Compatibility and Support Matrix¶
This page records the current source versions, runtime support, and the one-time migration rule for historical candidate entrypoints. Package manifests, the Contracts registry, and the capability catalog are the machine authorities.
Current Versions¶
| Package | Current source version | Role |
|---|---|---|
skill-family-contracts |
0.28.0 | Local Contracts 1.21.0 machine contracts |
skill-family-harness-node |
0.28.0 | Node implementation of Contracts mechanisms |
skill-family-engineering-kit |
0.28.0 | Four engineering commands and build-time projection |
| Private parent workspace | 0.28.0 | Sole development source of truth |
The three leaf packages release in lockstep and must not be mixed. The Contracts specification and npm packages use separate version lines.
Two-Generation Maturity Rule¶
Historical candidate APIs migrate once to canonical entrypoints. Legacy entrypoints continue to resolve to the same module during the compatibility window. Removing one requires a published deprecation, zero references in known real consumers, at least one release cycle, and a separate major-version decision.
APIs introduced from 0.10.0 onward use their final canonical identity from the first candidate release. An active candidate upgrade can still require adaptation. Candidate-to-stable promotion, however, may change only the provider's compatibility promise. It cannot change the entrypoint, capability ID, Schema $id, operation, request, result, or error semantics. A consumer must still update all three exact package pins to obtain the newly published stable promise. Existing package-identity, source-digest, and provenance bindings determine whether a Bundle rebuild is required; the maturity label adds no separate rebuild condition. FND-ADR-016 and CANDIDATE_PROMOTION_POLICY define the machine rule.
Historical Candidate Migration Matrix¶
| Historical coordinate or capability | 0.10.0 migration target | Current treatment |
|---|---|---|
skill-family-contracts/candidate/quickstart-profile |
skill-family-contracts/quickstart-profile |
Same source module; migrate once |
skill-family-harness-node/candidate/quickstart-profile |
skill-family-harness-node/quickstart-profile |
Same source module; operations unchanged |
skill-family-harness-node/candidate/rename-directory-no-replace |
skill-family-harness-node/rename-directory-no-replace |
Same source module; distinct from high-level fixed-set publication |
skill-family-engineering-kit/candidate/quickstart-profile |
skill-family-engineering-kit/quickstart-profile |
One-time Quickstart builder migration |
| Adoption from the old Quickstart namespace | skill-family-engineering-kit/adoption |
Responsibility-specific canonical entrypoint backed by the same source |
| Package-local or projected skill-naming candidate | skill-family-engineering-kit/skill-naming |
Canonical package entrypoint; no fifth Kit command |
| 0.4.0 fixed-set candidate schemas and primitive | 0.9.0 stable Schema $id values and skill-family-harness-node/fixed-set-publication |
Legacy schemas remain packaged while consumers migrate to the high-level API |
0.9.0 validate-many-by-schema-id candidate schemas |
/foundation-mechanisms/v1/schema-validation-batch-{request,result}.json |
One canonical Schema copy; legacy and canonical IDs dispatch to the same compiled validator, with no operation or echoed-result change |
The six Quickstart v2 identities for Resource, Task, Result, consumer inventory, and Harness surface inventory/detectors also migrate once from /candidate/quickstart-profile/v2/ to /quickstart-profile/v2/. Contracts loaders return only canonical $id values. During the compatibility window, Bundles accept both old and new IDs without a second Schema set or a general alias registry.
Quickstart v1 had already been replaced by v2 before 0.3.0. Consumers that still require v1 must remain pinned to 0.2.1. Version 0.10.0 neither rewrites historical artifacts nor repackages v1.
R05 and legacy platform-manifest migration¶
The R05 request/result Schemas are the sole structural owners of logicalMappings. A consumer keeps only fields that belong to its own domain, then removes duplicated closure, digest, and file-list structures after real-directory verification. It does not maintain permanent dual writes.
| Legacy field | Migration decision |
|---|---|
familyId |
Map to skillFamilyId. |
platformId |
Map to canonical hostId only after a registered Descriptor proves the identity. A request declaration is not proof. |
version |
Keep as the consumer package version. |
sourceDigest |
Map to commonSourceClosure.digest. |
projectionDigest |
No automatic equivalence; manifest.digest must not stand in for it. |
fileCount / files |
Derive from the standard manifest. The peer root's skills/ does not include a legacy manifest in its parent directory; remove the old list after migration. |
logicalMappings |
Owned only by request/result. |
lifecycleStatus / blocked / blockingReasons / advisories |
Remain in the consumer domain. |
verified |
Does not derive product, Audit, or release state. |
Node and Toolchain¶
- Node:
>=22.22.2 <23;.node-versionfixes the exact floor at22.22.2. - pnpm:
10.30.0. - projen:
0.101.23, the sole generator for managed engineering files. - Schema validator: Ajv
8.20.0, supporting draft-07 and 2020-12.
Results from Node below the floor or above the locked major cannot replace authoritative gate results.
Contracts and Engineering Boundaries¶
- The Contracts registry contains 56 locally registered schemas and is the sole authority for that set.
- The stable kernel protocol is
skill-family.kernel.operation; the local Contracts specification is 1.21.0, while the kernel document remains byte-pinned at its 1.8.0 lifecycle coordinate. - Error codes are append-only and are never reassigned.
- Kit top-level commands remain
scaffold,adopt-plan,projection, andcheck. - Host apply, install/update/uninstall, a full Qoder driver, remote publication, business state machines, model orchestration, and domain-audit semantics are outside the stable support surface. Local install/update remain within the 0.10.0 unstable plan-API boundary; an unsupported host receives no automatic lifecycle capability and no remote-publication guarantee.
Current host support comes from the capability catalog, Profile descriptors, and real drivers. A directory convention or CLI identity alone does not establish a supported lifecycle.
Windows compatibility and qualification boundaries¶
Foundation 0.28.0 is the package coordinate for this Windows contract surface, corresponding to Contracts 1.21.0 and 56 objects. Windows v2 and POSIX v1 branches coexist, the root binding retains four fields, and the three fixed-set-generation v1 objects remain candidate. Other API maturity levels remain as originally registered. Windows support is limited to Windows 11 x64, local NTFS, and ordinary users; the old two-directory exchange is unsupported.
The official skill-family-contracts@0.27.1 retains Contracts 1.20.0, 53 objects, and its existing POSIX guarantees; this version does not grant new capabilities to older published artifacts. The file-set logical naming rules in both v1 and Windows v2 are enforced during pre-checks at request submission: paths must be UTF-8 NFC-normalized, and any case or Unicode normalization alias within a single request results in rejection without any business writes. This restriction applies only at the logical naming level and is not relaxed due to NTFS's actual case sensitivity—e.g., even if A and a can coexist in a real NTFS directory, a group apply is still rejected under the logical contract.
Safe access, tree traversal, and fixed-set scanning follow actual NTFS case rules, with path matching based on filesystem semantics, not logical naming. Package version, API maturity, platform validation and remote availability are distinct. Real-host business qualification requires corresponding driver, version, authentication and business evidence. Remote release availability must be verified via formal release credentials and cannot be inferred from directory structure, local pre-builds, or self-testing.
See compatibility matrix for details.