跳转至

简体中文

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-version fixes the exact floor at 22.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, and check.
  • 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.