apiVersion Policy

processkit uses a Kubernetes-style apiVersion field on every entity:

apiVersion: processkit.projectious.work/v2

The group

The group processkit.projectious.work is a reverse-DNS name anchored on the owning organization (projectious.work) with processkit as a subcomponent. This prevents name collisions if other organizations fork or publish compatible primitives under their own domains.

The form <reverse-dns-group>/<version> is the Kubernetes-idiomatic shape — exactly one slash. Tools that split on / expect exactly two parts.

Evolution rules

The processkit product version, entity API version, schema-source format, and per-kind schema versions are independent axes. In particular, processkit v1.x deliberately uses entity API v2.

Non-breaking entity changes

• Adding new optional fields to schemas
• Adding new primitive kinds
• Adding new states to a state machine
• Adding new skills
• Adding new packages

Breaking entity changes

• Removing or renaming existing fields
• Changing the type or meaning of existing fields
• Removing states from a state machine (stranding existing entities)
• Removing primitive kinds
• Changing the semantics of metadata.id, metadata.created, or other cross-cutting fields

Migration between versions

The SmoothTiger/SmoothRiver v2 direction is a no-shim contract: v2 schemas and index semantics become authoritative, and processkit does not add hidden dual-read or permissive validation paths for v1 data. Existing v1 contexts remain a migration source, not a long-term compatibility target.

For a v1 context moving to v2:

1. The installer or migration tool generates a diff between the old upstream reference templates and the new ones.
2. A Migration entity records the affected files, source and target apiVersion, source and target processkit versions, and the proposed plan.
3. The agent runs the migration through migration-management, using dry-run diagnostics before applying changes.
4. The user approves the project-specific plan before the migration reaches applied.
5. After migration, v2 validation rejects unknown kinds, stale primitive assumptions, and ad hoc event/type vocabulary that v1 tolerated.

No automatic in-place patching — migrations always go through an explicit review and approval step. See the v0.25.0 changelog for the public breaking-change summary.