release-skill 0.9.22 → 0.9.24

package/src/core/derived-artifact-gates.mjs

@@ -10,7 +10,10 @@
  * freshness gate:
  *
  * - adapter gate: runs `scripts/build-adapters.mjs --check` (drift list,
- *   exit 1 on drift — the same supported check the scripts surface offers);
+ *   exit 1 on drift — the same supported check the scripts surface offers).
+ *   Exit 2 and an explicit process start failure mean that check did not
+ *   finish, so freshness is unknown. Timeout stays timeout. Other gates
+ *   keep their existing numeric-exit mapping.
  * - platform manifest gate: runs
  *   `scripts/generate-platform-manifest.mjs --check`;
  * - fact-pin gate: runs the version fact pins of
@@ -193,13 +196,15 @@ export async function checkDerivedArtifactGate(kind, pkgRoot, options = {}) {
       durationMs: Date.now() - startedAt,
     };
   } catch (err) {
-    // Timeout / spawn failure fail closed too: an undecidable gate is drift.
+    // Timeout stays timeout. Adapter exit 2 and an explicit spawn failure
+    // mean the check did not finish. Every other non-zero result, including
+    // other gates' numeric exits, remains drift.
     const stdoutTail = boundedOutputTail(err?.stdout ?? '');
     const stderrTail = boundedOutputTail(err?.stderr ?? err?.message ?? '');
     return {
       applicable: true,
       fresh: false,
-      reason: err?.killed || err?.code === 'ETIMEDOUT' ? 'timeout' : 'drift',
+      reason: failureReason(kind, err),
       artifact: gate.artifact,
       exitCode: typeof err?.code === 'number' ? err.code : null,
       stdoutTail,
@@ -209,6 +214,25 @@ export async function checkDerivedArtifactGate(kind, pkgRoot, options = {}) {
   }
 }
 
+function failureReason(kind, err) {
+  if (err?.killed || err?.code === 'ETIMEDOUT') return 'timeout';
+  if (kind === 'adapters' && (isProcessStartFailure(err) || err?.code === 2)) {
+    return 'execution-failed';
+  }
+  return 'drift';
+}
+
+function isProcessStartFailure(err) {
+  const syscall = err?.syscall;
+  if (syscall === 'spawn' || syscall === 'spawnSync') return true;
+  const executable = err?.path;
+  // Node 22 execFile sets syscall to "spawn <executable>" when the file cannot be started.
+  return typeof syscall === 'string'
+    && typeof executable === 'string'
+    && executable.length > 0
+    && syscall === `spawn ${executable}`;
+}
+
 /** Adapter freshness decision (build-adapters --check). */
 export function checkAdapterFreshness(pkgRoot, options = {}) {
   return checkDerivedArtifactGate('adapters', pkgRoot, options);
@@ -230,14 +254,19 @@ async function assertGate(kind, pkgRoot, options = {}) {
     return result;
   }
   const gate = GATES[kind];
-  const subject = kind === 'adapters'
-    ? 'adapters/ is out of sync with its sources (build-adapters --check reported drift)'
-    : kind === 'platform-manifest'
-      ? 'platform-manifest.json is out of sync with the current package tree (generate-platform-manifest --check reported drift)'
-      : 'the release-docs-self-bootstrap fact pins are stale (the hermetic fact-pin check failed)';
+  const unfinishedAdapterCheck = kind === 'adapters'
+    && (result.reason === 'execution-failed' || result.reason === 'timeout');
+  const subject = unfinishedAdapterCheck
+    ? `adapter freshness cannot be determined because build-adapters --check did not finish (${result.reason})`
+    : kind === 'adapters'
+      ? 'adapters/ is out of sync with its sources (build-adapters --check reported drift)'
+      : kind === 'platform-manifest'
+        ? 'platform-manifest.json is out of sync with the current package tree (generate-platform-manifest --check reported drift)'
+        : 'the release-docs-self-bootstrap fact pins are stale (the hermetic fact-pin check failed)';
+  const remediation = unfinishedAdapterCheck ? '' : ` ${gate.remediation}`;
   throw new ReleaseError(
     DERIVED_ARTIFACT_STALE,
-    `${subject}. ${DERIVED_ARTIFACT_PREGATE_NOTE} ${gate.remediation}`,
+    `${subject}. ${DERIVED_ARTIFACT_PREGATE_NOTE}${remediation}`,
     {
       artifact: result.artifact,
       reason: result.reason,

package/src/core/redact.mjs

@@ -54,12 +54,19 @@ export const REDACTED_PATH_PLACEHOLDER = '<redacted-path>';
 // (b) UNC paths (\\server\share...);
 // (c) POSIX absolute paths: a '/' anchored at the start of the string or
 //     preceded by a delimiter (whitespace, quote, '=', ':', ',', '(', '[',
-//     '{', '<'), running until whitespace or a quote. The left boundary keeps
-//     redaction from firing inside relative fragments ('src/core/x.mjs'),
-//     fragment-anchored JSON pointers ('#/required'), or protocol-relative
-//     URLs ('https://x/y').
+//     '{', '<'). Non-final '/'-separated segments may contain spaces (a
+//     volume name such as /Volumes/Samsung 990 pro 4T/src/file), so the
+//     token continues across those spaces and stops before trailing prose
+//     ('plan.json rejected: ...'). The left boundary keeps redaction from
+//     firing inside relative fragments ('src/core/x.mjs'), fragment-anchored
+//     JSON pointers ('#/required'), or protocol-relative URLs ('https://x/y').
+//     Windows drive and UNC alternatives still stop at whitespace; only the
+//     POSIX alternative crosses spaces, and only in non-final segments.
+//     A segment starting with a space right after '/' (e.g. /Volumes/ 990/x)
+//     and Windows drive/UNC tokens still truncate at that whitespace (known
+//     limitation).
 const PATH_TOKEN_RE =
-  /(?<=^|[\s'"=:,([{<])(?:[A-Za-z]:[\\/][^\s'"]*|\\\\[^\s'"]+|\/[^\s'"]+)/g;
+  /(?<=^|[\s'"=:,([{<])(?:[A-Za-z]:[\\/][^\s'"]*|\\\\[^\s'"]+|\/(?:[^/\s'"]+(?:[ ]+[^/\s'"]+)*\/)*[^/\s'"]*)/g;
 
 // Trailing prose punctuation that may cling to a token and must survive.
 const TRAILING_PUNCT_RE = /^(.*?)([.!,;:)\]}>]*)$/;

package/src/core/source-authority.mjs

@@ -272,6 +272,21 @@ function normalizeLocalGitMode(mode) {
   return (mode & 0o111) === 0 ? '100644' : '100755';
 }
 
+function gitPathSegments(value) {
+  return String(value).replaceAll('\\', '/').replace(/\/+$/u, '').split('/').filter(Boolean);
+}
+
+function sharesDirectoryBoundary(recordPath, requestedPath) {
+  const recordSegments = gitPathSegments(recordPath);
+  const requestedSegments = gitPathSegments(requestedPath);
+  const limit = Math.min(recordSegments.length, requestedSegments.length);
+  if (limit === 0) return false;
+  for (let index = 0; index < limit; index += 1) {
+    if (recordSegments[index] !== requestedSegments[index]) return false;
+  }
+  return true;
+}
+
 /**
  * Check only frozen source-input paths for staged, unstaged or untracked
  * changes. Unrelated dirty files remain allowed.
@@ -310,11 +325,21 @@ export async function checkSourceInputDirty({ closure, root, execFn = execFile }
     if (record.length < 4) continue;
     const status = record.slice(0, 2);
     const recordPath = record.slice(3);
+    let renamedPath = '';
+    if (status.startsWith('R') || status.startsWith('C')) {
+      renamedPath = records[index + 1] ?? '';
+      index += 1;
+    }
     // Ignored inputs are still untracked inputs. A file explicitly selected
     // for publication must not escape the prepare gate merely because a
-    // .gitignore rule hides it from ordinary status output.
-    dirtyPaths.push(recordPath);
-    if (status.startsWith('R') || status.startsWith('C')) index += 1;
+    // .gitignore rule hides it from ordinary status output. A porcelain row
+    // counts only when its path shares a full directory segment with a
+    // requested closure path. A character prefix is not a selection.
+    for (const candidate of [recordPath, renamedPath]) {
+      if (candidate && paths.some((requested) => sharesDirectoryBoundary(candidate, requested))) {
+        dirtyPaths.push(candidate);
+      }
+    }
   }
   return {
     dirty: dirtyPaths.length > 0,

package/src/npm/npm-entry-closure.mjs

@@ -84,6 +84,37 @@ function checkTarget({ field, target, fileIndex, requireDotSlash = false }) {
   };
 }
 
+// Identity mapping whose only star is the final character, for example
+// "./schemas/*" -> "./schemas/*". Node replaces that star with any non-empty
+// string, including "/". Other shapes stay rejected.
+function isDirectTrailingStarMapping(key, value) {
+  return typeof value === 'string'
+    && key === value
+    && key.startsWith('./')
+    && key.indexOf('*') === key.length - 1;
+}
+
+function validateTrailingStarPrefix(pattern) {
+  const head = pattern.slice(0, -1);
+  if (head === './') return {};
+  const staticTarget = head.endsWith('/') ? head.slice(0, -1) : head;
+  const validated = validateRelativeTarget(staticTarget, 'exports', { requireDotSlash: true });
+  if (validated.error) return validated;
+  return {};
+}
+
+function matchingIndexPaths(pattern, fileIndex) {
+  const prefix = pattern.slice(0, -1);
+  const matched = [];
+  for (const path of fileIndex.keys()) {
+    if (typeof path !== 'string') continue;
+    const subpath = `./${path}`;
+    if (subpath.startsWith(prefix) && subpath.length >= pattern.length) matched.push(path);
+  }
+  matched.sort();
+  return matched;
+}
+
 function collectExports(value, location, result) {
   if (value === null) return;
   if (typeof value === 'string') {
@@ -117,14 +148,18 @@ function collectExports(value, location, result) {
   for (const [key, child] of Object.entries(value)) {
     const childLocation = `${location}.${key}`;
     if (key.includes('*')) {
-      result.errors.push(
-        entryError(
-          'exports',
-          key,
-          'unsupported_entry_shape',
-          `${childLocation} uses a wildcard subpath that the static gate cannot verify`,
-        ),
-      );
+      if (isDirectTrailingStarMapping(key, child)) {
+        result.patterns.push({ location: childLocation, pattern: key });
+      } else {
+        result.errors.push(
+          entryError(
+            'exports',
+            key,
+            'unsupported_entry_shape',
+            `${childLocation} uses a wildcard subpath that the static gate cannot verify`,
+          ),
+        );
+      }
       continue;
     }
     collectExports(child, childLocation, result);
@@ -166,7 +201,7 @@ export function checkNpmEntryClosure(manifest, fileIndex) {
   }
 
   if (manifest.exports !== undefined) {
-    const exportsResult = { targets: [], errors: [], diagnostics: [] };
+    const exportsResult = { targets: [], patterns: [], errors: [], diagnostics: [] };
     collectExports(manifest.exports, 'exports', exportsResult);
     result.errors.push(...exportsResult.errors);
     result.diagnostics.push(...exportsResult.diagnostics);
@@ -180,6 +215,33 @@ export function checkNpmEntryClosure(manifest, fileIndex) {
       result.entries.push(...checked.entries);
       result.errors.push(...checked.errors);
     }
+    for (const pattern of exportsResult.patterns) {
+      const validated = validateTrailingStarPrefix(pattern.pattern);
+      if (validated.error) {
+        result.errors.push(validated.error);
+        continue;
+      }
+      const matched = matchingIndexPaths(pattern.pattern, fileIndex);
+      if (matched.length === 0) {
+        result.errors.push(entryError(
+          'exports',
+          pattern.pattern,
+          'empty_pattern_match',
+          `${pattern.location} matched no files in the package file index`,
+        ));
+        continue;
+      }
+      for (const path of matched) {
+        const checked = checkTarget({
+          field: 'exports',
+          target: `./${path}`,
+          fileIndex,
+          requireDotSlash: true,
+        });
+        result.entries.push(...checked.entries);
+        result.errors.push(...checked.errors);
+      }
+    }
   }
 
   return result;

package/src/producers/build-adapters.mjs

@@ -22,6 +22,7 @@
 import { readdir, mkdir, lstat, realpath, open, rm } from 'node:fs/promises';
 import { constants as fsConstants } from 'node:fs';
 import { join, dirname, relative, isAbsolute, sep, resolve, posix as pathPosix } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { sha256Hex } from '../core/digest.mjs';
 import { digestDocument } from 'skill-family-contracts';
@@ -392,11 +393,23 @@ function renderSkillForPlatform(content, platformName) {
       '${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs',
       '$RELEASE_SKILL_ENTRY',
     );
-    const renderedPreamble = rendered.includes('$RELEASE_SKILL_LOCAL_FINISH_ENTRY')
-      ? preamble
+    const hasMainEntry = rendered.includes('$RELEASE_SKILL_ENTRY');
+    const hasFinishEntry = rendered.includes('$RELEASE_SKILL_LOCAL_FINISH_ENTRY');
+    const mainBindingLine = '> 令 `RELEASE_SKILL_ENTRY=PLUGIN_ROOT/bin/release-skill.mjs`，对入口执行 `realpath` containment、`lstat` 非符号链接且为普通文件校验。\n';
+    const finishBindingLine = '> 令 `RELEASE_SKILL_LOCAL_FINISH_ENTRY=PLUGIN_ROOT/bin/release-skill-local-finish.mjs`，对入口执行 `realpath` containment、`lstat` 非符号链接且为普通文件校验。\n';
+    const mainShellLine = '> 每一次 shell 工具调用都必须在同一个调用中用上述已验证绝对值设置 `RELEASE_SKILL_ENTRY`，然后执行 `node "$RELEASE_SKILL_ENTRY" ...`；不得依赖前一次 shell 的变量。\n';
+    const dualShellLine = '> 每一次 shell 工具调用都必须在同一个调用中用上述已验证绝对值设置 `RELEASE_SKILL_ENTRY` 与 `RELEASE_SKILL_LOCAL_FINISH_ENTRY`，然后执行 `node "$RELEASE_SKILL_ENTRY" ...` 或 `node "$RELEASE_SKILL_LOCAL_FINISH_ENTRY" ...`；不得依赖前一次 shell 的变量。\n';
+    let renderedPreamble = preamble;
+    if (hasFinishEntry && hasMainEntry) {
+      if (!preamble.includes(mainBindingLine) || !preamble.includes(mainShellLine)) {
+        throw new Error(`${hostLabel} dual-entry rendering requires the original main-entry protocol lines`);
+      }
+      renderedPreamble = preamble.replace(`${mainBindingLine}${mainShellLine}`, `${mainBindingLine}${finishBindingLine}${dualShellLine}`);
+    } else if (hasFinishEntry) {
+      renderedPreamble = preamble
         .replaceAll('RELEASE_SKILL_ENTRY', 'RELEASE_SKILL_LOCAL_FINISH_ENTRY')
-        .replaceAll('release-skill.mjs', 'release-skill-local-finish.mjs')
-      : preamble;
+        .replaceAll('release-skill.mjs', 'release-skill-local-finish.mjs');
+    }
     if (platformName === 'cursor' && /\$\{(?:CLAUDE|CURSOR|CODEBUDDY|KIMI)[A-Z_]*\}/u.test(rendered)) {
       throw new Error('Cursor rendering contains a residual host-specific placeholder');
     }
@@ -701,7 +714,7 @@ async function generateAdapterFiles(platform, skills, templateJson, root, market
  * @param {string} [options.platformFilter] - Only generate for this platform name.
  */
 export async function produceBuildAdapters({ inputs, output, outputRoots, platformFilter } = {}) {
-  const defaultRoot = new URL('../..', import.meta.url).pathname;
+  const defaultRoot = fileURLToPath(new URL('../..', import.meta.url));
   const requestedRoot = inputs ?? defaultRoot;
 
   // ── Phase 1: Validate input root is not a symlink ──

package/src/producers/foundation-resource-projection.mjs

@@ -55,9 +55,9 @@ import { digestBytes, publishFileOrReplace, readFileStrict, withTemporaryWorkspa
 import { canonicalJson } from '../core/digest.mjs';
 
 export const FOUNDATION_PACKAGES = Object.freeze({
-  'skill-family-contracts': '0.21.0',
-  'skill-family-engineering-kit': '0.21.0',
-  'skill-family-harness-node': '0.21.0',
+  'skill-family-contracts': '0.22.0',
+  'skill-family-engineering-kit': '0.22.0',
+  'skill-family-harness-node': '0.22.0',
 });
 
 export const BINDING_RECORD_PATH = 'bin/foundation-resource-binding.json';

package/src/producers/render-public-assets.mjs

@@ -13,6 +13,7 @@
 
 import { readFile, writeFile, readdir, stat, mkdir } from 'node:fs/promises';
 import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
 import { digestDocument } from 'skill-family-contracts';
@@ -111,7 +112,7 @@ async function renderDir(srcDir, outDir, pathPrefix) {
  * @returns {Promise<{outputs: Array, outputManifestDigest: string}>}
  */
 export async function produceRenderPublicAssets({ inputs, output } = {}) {
-  const defaultRoot = new URL('../../..', import.meta.url).pathname;
+  const defaultRoot = fileURLToPath(new URL('../../..', import.meta.url));
   const root = inputs ?? defaultRoot;
 
   const srcDirs = [

package/src/producers/sync-skills.mjs

@@ -11,6 +11,7 @@
 
 import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
 import { digestDocument } from 'skill-family-contracts';
@@ -44,7 +45,7 @@ export function computeSyncSkillsDigest(sourceBytes) {
  * @param {string} options.output - Output directory path.
  */
 export async function produceSyncSkills({ inputs, output } = {}) {
-  const defaultSrc = new URL('../../skills-src', import.meta.url).pathname;
+  const defaultSrc = fileURLToPath(new URL('../../skills-src', import.meta.url));
   const srcDir = inputs ?? defaultSrc;
 
   const skillDirs = [];

package/src/schemas/file-set-apply-request.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/file-set-apply-request.json",
+  "title": "File set apply request",
+  "description": "Frozen JSON projection. Runtime checks bind bytes, cumulative capacity, modes, canonical paths, filesystem identities and cooperative ownership before business writes.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "operationId", "root", "rootBinding", "recoveryRelPath", "allowAdjacentStaging", "environment", "validationTimeoutMs", "operations"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.file-set-apply-request" },
+    "operationId": { "$ref": "#/$defs/operationId" },
+    "root": { "$ref": "#/$defs/root" },
+    "rootBinding": { "$ref": "https://contracts.skill-family.example/v1/filesystem-root-binding.json" },
+    "recoveryRelPath": { "const": ".foundation-file-apply" },
+    "allowAdjacentStaging": { "const": true },
+    "environment": { "$ref": "#/$defs/environment" },
+    "validationTimeoutMs": { "type": "integer", "minimum": 1, "maximum": 2147483647 },
+    "operations": {
+      "type": "array", "minItems": 1, "maxItems": 1024, "uniqueItems": true,
+      "items": { "$ref": "#/$defs/operation" }
+    }
+  },
+  "$defs": {
+    "operationId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+    "root": { "type": "string", "pattern": "^/(?!.*(?:^|/)(?:\\.|\\.\\.)(?:/|$))(?!.*//)(?!.*[\\\\\\u0000])(?:[^/]+(?:/[^/]+)*)?$" },
+    "path": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)(?:\\.|\\.\\.|\\.git|\\.foundation-file-apply)(?:/|$))(?!.*[\\\\\\u0000])[^/]+(?:/[^/]+)*$" },
+    "environment": {
+      "type": "object", "additionalProperties": false,
+      "required": ["filesystem", "cooperativeWriters"],
+      "properties": {
+        "filesystem": { "enum": ["apfs", "ext4"] },
+        "cooperativeWriters": { "const": true }
+      }
+    },
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "size": { "type": "integer", "minimum": 0, "maximum": 268435456 },
+    "mode": { "type": "integer", "minimum": 256, "maximum": 511 },
+    "next": {
+      "type": "object", "additionalProperties": false,
+      "required": ["sha256", "size", "mode"],
+      "properties": {
+        "sha256": { "$ref": "#/$defs/sha256" },
+        "size": { "$ref": "#/$defs/size" },
+        "mode": { "$ref": "#/$defs/mode" }
+      }
+    },
+    "present": {
+      "type": "object", "additionalProperties": false,
+      "required": ["exists", "sha256", "size", "mode"],
+      "properties": {
+        "exists": { "const": true },
+        "sha256": { "$ref": "#/$defs/sha256" },
+        "size": { "$ref": "#/$defs/size" },
+        "mode": { "$ref": "#/$defs/mode" }
+      }
+    },
+    "absent": {
+      "type": "object", "additionalProperties": false,
+      "required": ["exists"], "properties": { "exists": { "const": false } }
+    },
+    "operation": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "action", "expected", "next"],
+      "properties": {
+        "path": { "$ref": "#/$defs/path" },
+        "action": { "enum": ["create", "replace", "delete"] },
+        "expected": { "oneOf": [{ "$ref": "#/$defs/absent" }, { "$ref": "#/$defs/present" }] },
+        "next": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/next" }] }
+      },
+      "allOf": [
+        { "if": { "properties": { "action": { "const": "create" } }, "required": ["action"] }, "then": { "properties": { "expected": { "$ref": "#/$defs/absent" }, "next": { "$ref": "#/$defs/next" } } } },
+        { "if": { "properties": { "action": { "const": "replace" } }, "required": ["action"] }, "then": { "properties": { "expected": { "$ref": "#/$defs/present" }, "next": { "$ref": "#/$defs/next" } } } },
+        { "if": { "properties": { "action": { "const": "delete" } }, "required": ["action"] }, "then": { "properties": { "expected": { "$ref": "#/$defs/present" }, "next": { "type": "null" } } } }
+      ]
+    }
+  }
+}

package/src/schemas/file-set-event-payload.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/file-set-event-payload.json",
+  "title": "File set event payload",
+  "description": "File recovery facts within the existing state-event envelope. Event order, request and path bindings are checked by Harness; no second sequence or hash chain is introduced.",
+  "type": "object", "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "operationId", "type"],
+  "properties": {
+    "schemaVersion": { "const": 1 }, "kind": { "const": "skill-family.file-set-event-payload" },
+    "operationId": { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json#/$defs/operationId" },
+    "type": { "enum": ["prepared", "apply-intent", "applied", "restore-intent", "restored", "validation-started", "validation-finished", "committed", "rolled-back", "recovery-required", "prune-intent", "pruned"] },
+    "request": { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json" },
+    "requestDigest": { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json#/$defs/sha256" },
+    "rootBinding": { "$ref": "https://contracts.skill-family.example/v1/filesystem-root-binding.json" },
+    "materialIdentity": { "$ref": "#/$defs/directoryIdentity" },
+    "entries": { "type": "array", "minItems": 1, "maxItems": 1024, "items": { "$ref": "#/$defs/materialEntry" } },
+    "index": { "type": "integer", "minimum": 0, "maximum": 1023 },
+    "current": { "enum": ["original", "expected-new"] },
+    "validation": { "$ref": "https://contracts.skill-family.example/v1/file-set-result.json#/$defs/validation" },
+    "paths": { "$ref": "https://contracts.skill-family.example/v1/file-set-result.json#/$defs/paths" },
+    "errorKinds": { "$ref": "https://contracts.skill-family.example/v1/file-set-result.json#/$defs/errorKinds" }
+  },
+  "allOf": [
+    { "if": { "properties": { "type": { "const": "prepared" } }, "required": ["type"] },
+      "then": { "properties": { "request": {}, "requestDigest": {}, "rootBinding": {}, "materialIdentity": {}, "entries": {} }, "required": ["request", "requestDigest", "rootBinding", "materialIdentity", "entries"] },
+      "else": { "properties": { "request": false, "requestDigest": false, "rootBinding": false, "materialIdentity": false, "entries": false } } },
+    { "if": { "properties": { "type": { "enum": ["apply-intent", "applied", "restore-intent", "restored"] } }, "required": ["type"] },
+      "then": { "properties": { "index": {} }, "required": ["index"] }, "else": { "properties": { "index": false } } },
+    { "if": { "properties": { "type": { "enum": ["applied", "restored"] } }, "required": ["type"] },
+      "then": { "properties": { "current": {} }, "required": ["current"] }, "else": { "properties": { "current": false } } },
+    { "if": { "properties": { "type": { "const": "applied" } }, "required": ["type"] },
+      "then": { "properties": { "current": { "const": "expected-new" } } } },
+    { "if": { "properties": { "type": { "const": "restored" } }, "required": ["type"] },
+      "then": { "properties": { "current": { "const": "original" } } } },
+    { "if": { "properties": { "type": { "const": "validation-finished" } }, "required": ["type"] },
+      "then": { "properties": { "validation": {} }, "required": ["validation"] }, "else": { "properties": { "validation": false } } },
+    { "if": { "properties": { "type": { "enum": ["committed", "rolled-back", "recovery-required"] } }, "required": ["type"] },
+      "then": { "properties": { "paths": {}, "errorKinds": {} }, "required": ["paths", "errorKinds"] }, "else": { "properties": { "paths": false, "errorKinds": false } } }
+  ],
+  "$defs": {
+    "directoryIdentity": {
+      "$ref": "https://contracts.skill-family.example/v1/state-store-recovery-observation.json#/$defs/identity",
+      "type": "object", "properties": { "type": { "const": "directory" } }
+    },
+    "materialEntry": {
+      "type": "object", "additionalProperties": false,
+      "required": ["before", "after", "parentIdentity"],
+      "properties": {
+        "before": { "anyOf": [{ "type": "null" }, { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json#/$defs/next" }] },
+        "after": { "anyOf": [{ "type": "null" }, { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json#/$defs/next" }] },
+        "parentIdentity": { "$ref": "#/$defs/directoryIdentity" }
+      }
+    }
+  }
+}

package/src/schemas/file-set-prune-request.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/file-set-prune-request.json",
+  "title": "File set prune request",
+  "type": "object", "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "operationId", "root", "rootBinding", "recoveryRelPath", "environment"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.file-set-prune-request" },
+    "operationId": { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json#/$defs/operationId" },
+    "root": { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json#/$defs/root" },
+    "rootBinding": { "$ref": "https://contracts.skill-family.example/v1/filesystem-root-binding.json" },
+    "recoveryRelPath": { "const": ".foundation-file-apply" },
+    "environment": { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json#/$defs/environment" },
+    "maintenance": { "$ref": "https://contracts.skill-family.example/v1/file-set-recovery-request.json#/$defs/maintenance" }
+  }
+}

package/src/schemas/file-set-recovery-request.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/file-set-recovery-request.json",
+  "title": "File set recovery request",
+  "type": "object", "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "operationId", "root", "rootBinding", "recoveryRelPath", "environment", "allowAdjacentStaging", "maintenance"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.file-set-recovery-request" },
+    "operationId": { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json#/$defs/operationId" },
+    "root": { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json#/$defs/root" },
+    "rootBinding": { "$ref": "https://contracts.skill-family.example/v1/filesystem-root-binding.json" },
+    "recoveryRelPath": { "const": ".foundation-file-apply" },
+    "environment": { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json#/$defs/environment" },
+    "allowAdjacentStaging": { "const": true },
+    "maintenance": { "$ref": "#/$defs/maintenance" }
+  },
+  "$defs": {
+    "maintenance": {
+      "type": "object", "additionalProperties": false,
+      "required": ["observation", "confirmAllParticipantsStopped", "confirmExclusiveMaintenance"],
+      "properties": {
+        "observation": { "$ref": "https://contracts.skill-family.example/v1/state-store-recovery-observation.json" },
+        "confirmAllParticipantsStopped": { "const": true },
+        "confirmExclusiveMaintenance": { "const": true }
+      }
+    }
+  }
+}

package/src/schemas/file-set-result.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/file-set-result.json",
+  "title": "File set result",
+  "type": "object", "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "operationId", "operation", "outcome", "preflight", "businessWrite", "validation", "recovery", "paths", "errors", "materials"],
+  "properties": {
+    "schemaVersion": { "const": 1 }, "kind": { "const": "skill-family.file-set-result" },
+    "operationId": { "anyOf": [{ "type": "null" }, { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json#/$defs/operationId" }] },
+    "operation": { "enum": ["apply", "recover", "prune"] },
+    "outcome": { "enum": ["committed", "commit-unconfirmed", "rejected", "rolled-back", "recovery-required", "already-committed", "already-rolled-back", "pruned", "already-pruned"] },
+    "preflight": { "enum": ["not-run", "failed", "passed"] },
+    "businessWrite": { "enum": ["none", "started", "unknown"] },
+    "validation": { "$ref": "#/$defs/validation" },
+    "recovery": {
+      "type": "object", "additionalProperties": false, "required": ["attempted", "status"],
+      "properties": { "attempted": { "type": "boolean" }, "status": { "enum": ["not-needed", "complete", "partial", "blocked"] } }
+    },
+    "paths": { "$ref": "#/$defs/paths" },
+    "errors": { "type": "array", "items": { "$ref": "#/$defs/error" } },
+    "materials": {
+      "type": "object", "additionalProperties": false,
+      "required": ["relPath", "status", "durable", "adjacentStaging"],
+      "properties": {
+        "relPath": { "const": ".foundation-file-apply" },
+        "status": { "enum": ["none", "retained", "partial", "pruned"] },
+        "durable": { "type": "boolean" },
+        "adjacentStaging": { "enum": ["none-observed", "possible-unknown"] }
+      }
+    }
+  },
+  "allOf": [{
+    "if": { "properties": { "operationId": { "type": "null" } }, "required": ["operationId"] },
+    "then": { "properties": { "paths": { "type": "array", "maxItems": 0 } } }
+  }],
+  "$defs": {
+    "errorKind": { "enum": ["invalid-request", "unsupported-environment", "unsafe-path", "precondition-mismatch", "locked", "unfinished-operation", "operation-id-reused", "commit-unconfirmed", "persistence-failed", "apply-failed", "validation-failed", "validation-incomplete", "restore-conflict", "restore-failed", "recovery-corrupt", "root-changed", "ownership-lost", "operation-not-found", "prune-refused", "lock-release-failed"] },
+    "errorKinds": { "type": "array", "items": { "$ref": "#/$defs/errorKind" } },
+    "error": {
+      "type": "object", "additionalProperties": false, "required": ["code", "message", "details"],
+      "properties": {
+        "code": { "const": "SFC2004" }, "message": { "type": "string", "minLength": 1 },
+        "details": {
+          "type": "object", "additionalProperties": false, "required": ["kind", "phase"],
+          "properties": {
+            "kind": { "$ref": "#/$defs/errorKind" },
+            "phase": { "enum": ["input", "preflight", "prepare", "apply", "validate", "restore", "finalize", "prune"] },
+            "path": { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json#/$defs/path" }
+          }
+        }
+      }
+    },
+    "validation": {
+      "type": "object", "additionalProperties": false, "required": ["status", "reason"],
+      "properties": {
+        "status": { "enum": ["not-run", "passed", "failed", "incomplete"] },
+        "reason": { "enum": [null, "returned-false", "exception", "timeout", "invalid-result", "interrupted"] }
+      },
+      "allOf": [
+        { "if": { "properties": { "status": { "enum": ["not-run", "passed"] } }, "required": ["status"] }, "then": { "properties": { "reason": { "type": "null" } } }, "else": { "properties": { "reason": { "type": "string" } } } },
+        { "if": { "properties": { "status": { "const": "failed" } }, "required": ["status"] }, "then": { "properties": { "reason": { "const": "returned-false" } } } },
+        { "if": { "properties": { "status": { "const": "incomplete" } }, "required": ["status"] }, "then": { "properties": { "reason": { "enum": ["exception", "timeout", "invalid-result", "interrupted"] } } } }
+      ]
+    },
+    "paths": { "type": "array", "maxItems": 1024, "items": { "$ref": "#/$defs/pathResult" } },
+    "pathResult": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "action", "apply", "restore", "current", "errorKinds"],
+      "properties": {
+        "path": { "$ref": "https://contracts.skill-family.example/v1/file-set-apply-request.json#/$defs/path" },
+        "action": { "enum": ["create", "replace", "delete"] },
+        "apply": { "enum": ["not-started", "intent-recorded", "applied", "unknown"] },
+        "restore": { "enum": ["not-needed", "restored", "already-original", "conflict", "failed", "unknown"] },
+        "current": { "enum": ["original", "expected-new", "other", "unknown"] },
+        "errorKinds": { "$ref": "#/$defs/errorKinds" }
+      }
+    }
+  }
+}