artifact-chain-assistant 0.8.2 → 0.8.3

package/adapters/claude/scripts/lib/family-api-validator.mjs

@@ -0,0 +1,413 @@
+// @feature ACA18 @scenario S-65 @decision D-ACA-18
+// Family API validator: deterministic, fail-closed validation of Skill Family API definitions.
+// Executes the dependency-free validator compiled from the authoritative
+// family-api.schema.json. The generated module is checked for drift at build/test.
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import validateFamilyApiSchema, { schemaDigest as familyApiSchemaDigest } from './generated/family-api-validator.generated.mjs';
+import { canonicalStringify } from './generated/canonical-json-v1.generated.mjs';
+
+export { familyApiSchemaDigest, canonicalStringify };
+
+/**
+ * Load and parse a JSON file with fail-closed semantics.
+ * @param {string} filePath
+ * @returns {Promise<object>}
+ */
+export async function loadJson(filePath) {
+  const content = await readFile(filePath, 'utf8');
+  return JSON.parse(content);
+}
+
+/**
+ * Parse a JSON string safely.
+ * @param {string} text
+ * @returns {object}
+ */
+export function parseJson(text) {
+  return JSON.parse(text);
+}
+
+/**
+ * Compute the immutable revision digest of a Family API object.
+ * Removes the revisionDigest field, serializes with sorted keys, and hashes SHA-256.
+ * @param {object} apiObject - Parsed API YAML object
+ * @returns {string} - "sha256:<hex>"
+ */
+export function computeRevisionDigest(apiObject) {
+  const clone = structuredClone(apiObject);
+  if (clone.api && typeof clone.api === 'object') {
+    delete clone.api.revisionDigest;
+  }
+  const canonical = canonicalStringify(clone);
+  const hash = createHash('sha256').update(canonical).digest('hex');
+  return `sha256:${hash}`;
+}
+
+/**
+ * Deterministic JSON serialization with sorted keys at every level.
+ * Regular arrays preserve input order; set fields are sorted and deduplicated.
+ * @param {*} value
+ * @returns {string}
+ */
+export function stableStringify(value) {
+  return canonicalStringify(value);
+}
+
+/**
+ * Compute canonical hash compatible with Registry's computeContentHash.
+ * @param {*} value
+ * @returns {string} "sha256:<hex>"
+ */
+export function computeCanonicalHash(value) {
+  const canonical = canonicalStringify(value);
+  const hash = createHash('sha256').update(canonical).digest('hex');
+  return `sha256:${hash}`;
+}
+
+// Forbidden fields that must not appear in a Family API service definition
+const FORBIDDEN_SERVICE_FIELDS = new Set([
+  'stage', 'worker', 'prompt', 'template', 'provider', 'providers',
+  'installation', 'enablement', 'trust', 'resolution',
+  'locked', 'compatibility', 'selectionSource',
+  'bindings', 'sources',
+]);
+
+// Fields that must not appear at the top level of the API
+const FORBIDDEN_API_FIELDS = new Set([
+  'stage', 'worker', 'prompt', 'template', 'provider',
+  'installation', 'enablement', 'trust', 'resolution',
+  'locked', 'compatibility', 'selectionSource',
+  'providers', 'bindings', 'sources',
+]);
+
+// Canonical namespace pattern
+const CANONICAL_NAMESPACE_RE = /^artifact\.[a-z][a-z0-9-]*-family$/;
+const SERVICE_ID_RE = /^artifact\.[a-z][a-z0-9-]+\.[a-z][a-z0-9-]+$/;
+const CONTRACT_REF_RE = /^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*@[0-9]+$/;
+
+/**
+ * Validate a Family API definition against the authoritative JSON Schema and semantic constraints.
+ * @param {object} apiObj - Parsed API object
+ * @param {object} [opts] - Options
+ * @param {string} [opts.sourcePath] - Source file path for error messages
+ * @returns {Promise<{ ok: boolean, errors: Array<{code: string, path: string, message: string}>, warnings: string[] }>}
+ */
+export async function validateFamilyApi(apiObj, opts = {}) {
+  const errors = [];
+  const warnings = [];
+  const prefix = opts.sourcePath ? `${opts.sourcePath}: ` : '';
+
+  // 1. Run authoritative JSON Schema validation (includes additionalProperties: false)
+  try {
+    const schemaValid = validateFamilyApiSchema(apiObj);
+    if (!schemaValid) {
+      for (const err of validateFamilyApiSchema.errors || []) {
+        errors.push({
+          code: 'SCHEMA_VALIDATION',
+          path: err.instancePath || '/',
+          message: `${prefix}${err.message}${err.params ? ` (${JSON.stringify(err.params)})` : ''}`,
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({
+      code: 'SCHEMA_LOAD_ERROR',
+      path: '/schema',
+      message: `Failed to load or compile JSON Schema: ${err.message}`,
+    });
+    return { ok: false, errors, warnings };
+  }
+
+  // 2. Semantic validation beyond JSON Schema capabilities
+  if (!apiObj.api || typeof apiObj.api !== 'object') {
+    return { ok: false, errors, warnings };
+  }
+
+  const api = apiObj.api;
+
+  // 3. Canonical namespace
+  if (api.id && !CANONICAL_NAMESPACE_RE.test(api.id)) {
+    errors.push({
+      code: 'CANONICAL_NAMESPACE',
+      path: '/api/id',
+      message: `${prefix}api.id "${api.id}" does not match canonical namespace pattern artifact.<family>-family`,
+    });
+  }
+
+  // 4. Revision digest verification
+  if (api.revisionDigest && /^sha256:[a-f0-9]{64}$/.test(api.revisionDigest)) {
+    const computed = computeRevisionDigest(apiObj);
+    if (computed !== api.revisionDigest) {
+      errors.push({
+        code: 'DIGEST_MISMATCH',
+        path: '/api/revisionDigest',
+        message: `${prefix}api.revisionDigest mismatch: declared ${api.revisionDigest}, computed ${computed}`,
+      });
+    }
+  }
+
+  // 5. Forbidden fields (explicit semantic blocklist beyond schema)
+  for (const field of FORBIDDEN_API_FIELDS) {
+    if (field in apiObj) {
+      errors.push({
+        code: 'FORBIDDEN_FIELD',
+        path: `/${field}`,
+        message: `${prefix}forbidden top-level field "${field}" in Family API`,
+      });
+    }
+    if (field in api) {
+      errors.push({
+        code: 'FORBIDDEN_FIELD',
+        path: `/api/${field}`,
+        message: `${prefix}forbidden field "${field}" in api object`,
+      });
+    }
+  }
+
+  // 6. Services semantic validation
+  if (Array.isArray(apiObj.services)) {
+    const serviceIds = new Set();
+    for (let i = 0; i < apiObj.services.length; i++) {
+      const svc = apiObj.services[i];
+      const svcPath = `/services/${i}`;
+
+      // Service ID must belong to this API's family
+      if (api.id && svc.id) {
+        const familyPrefix = api.id.replace(/-family$/, '');
+        if (!svc.id.startsWith(familyPrefix + '.')) {
+          errors.push({
+            code: 'SERVICE_FAMILY_MISMATCH',
+            path: `${svcPath}/id`,
+            message: `${prefix}services[${i}] id "${svc.id}" does not belong to family "${api.id}"`,
+          });
+        }
+      }
+
+      // Uniqueness
+      if (serviceIds.has(svc.id)) {
+        errors.push({
+          code: 'DUPLICATE_SERVICE',
+          path: `${svcPath}/id`,
+          message: `${prefix}services[${i}] duplicate service id "${svc.id}"`,
+        });
+      }
+      serviceIds.add(svc.id);
+
+      // Forbidden service fields
+      for (const field of FORBIDDEN_SERVICE_FIELDS) {
+        if (field in svc) {
+          errors.push({
+            code: 'FORBIDDEN_SERVICE_FIELD',
+            path: `${svcPath}/${field}`,
+            message: `${prefix}services[${i}] forbidden field "${field}" in service definition`,
+          });
+        }
+      }
+
+      // accepts/produces references
+      validateRefs(svc.accepts, `${prefix}services[${i}]`, 'accepts', errors);
+      validateRefs(svc.produces, `${prefix}services[${i}]`, 'produces', errors);
+    }
+  }
+
+  // 7. At least one discoverable service (default or help)
+  if (Array.isArray(apiObj.services)) {
+    const hasDefault = apiObj.services.some(s => s.discoverable?.default);
+    const hasHelp = apiObj.services.some(s => s.discoverable?.help);
+    if (!hasDefault) {
+      warnings.push(`${prefix}no service declared as discoverable.default`);
+    }
+    if (!hasHelp) {
+      warnings.push(`${prefix}no service declared as discoverable.help`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Validate an array of contract/protocol references.
+ * @param {Array} refs
+ * @param {string} svcPrefix
+ * @param {string} field
+ * @param {Array} errors
+ */
+function validateRefs(refs, svcPrefix, field, errors) {
+  if (refs === undefined) return;
+  if (!Array.isArray(refs)) {
+    errors.push({
+      code: 'INVALID_REF_TYPE',
+      path: `${svcPrefix}/${field}`,
+      message: `${svcPrefix} ${field} must be an array`,
+    });
+    return;
+  }
+  for (let j = 0; j < refs.length; j++) {
+    const ref = refs[j];
+    const refPath = `${svcPrefix}/${field}[${j}]`;
+    if (typeof ref === 'string') {
+      if (ref.includes('@') && !CONTRACT_REF_RE.test(ref)) {
+        errors.push({
+          code: 'INVALID_CONTRACT_REF',
+          path: refPath,
+          message: `${refPath} "${ref}" looks like a contract reference but does not match pattern <authority>.<type>@<major>`,
+        });
+      }
+    } else if (typeof ref === 'object' && ref !== null) {
+      if (!ref.protocol || typeof ref.protocol !== 'string') {
+        errors.push({
+          code: 'MISSING_PROTOCOL',
+          path: refPath,
+          message: `${refPath} protocol reference must have a string "protocol" field`,
+        });
+      }
+      if (!ref.version || typeof ref.version !== 'string') {
+        errors.push({
+          code: 'MISSING_VERSION',
+          path: refPath,
+          message: `${refPath} protocol reference must have a string "version" field`,
+        });
+      }
+    } else {
+      errors.push({
+        code: 'INVALID_REF_TYPE',
+        path: refPath,
+        message: `${refPath} must be a string or protocol reference object`,
+      });
+    }
+  }
+}
+
+/**
+ * Validate that a catalog is consistent with its referenced API files.
+ * @param {object} catalog - Parsed catalog.yaml
+ * @param {Array<{id: string, major: number, content: object}>} apiFiles
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateCatalogConsistency(catalog, apiFiles) {
+  const errors = [];
+
+  if (!catalog || !Array.isArray(catalog.families)) {
+    errors.push('catalog.families must be an array');
+    return { ok: false, errors };
+  }
+
+  for (const entry of catalog.families) {
+    if (!entry.id || !entry.major) {
+      errors.push(`catalog family entry missing id or major`);
+      continue;
+    }
+
+    const apiFile = apiFiles.find(f => f.id === entry.id && f.major === entry.major);
+    if (!apiFile) {
+      errors.push(`catalog references ${entry.id}@${entry.major} but no matching API file found`);
+      continue;
+    }
+
+    if (entry.revisionDigest !== apiFile.content.api.revisionDigest) {
+      errors.push(
+        `catalog revisionDigest for ${entry.id}@${entry.major} (${entry.revisionDigest}) ` +
+        `does not match API file (${apiFile.content.api.revisionDigest})`
+      );
+    }
+  }
+
+  for (const apiFile of apiFiles) {
+    const inCatalog = catalog.families.some(
+      f => f.id === apiFile.id && f.major === apiFile.major
+    );
+    if (!inCatalog) {
+      errors.push(`API file ${apiFile.id}@${apiFile.major} exists but is not in catalog`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Side-effect ceiling ranking for comparison.
+ * Siblings (same rank) are NOT interchangeable — swapping between them is breaking.
+ */
+const CEILING_RANK = {
+  'none': 0,
+  'read-only': 1,
+  'write-authorized-artifacts': 2,
+  'write-review-result': 2,
+  'write-project-artifacts': 3,
+};
+
+/**
+ * Check API compatibility: adding optional service is compatible,
+ * removing required, changing required/optional flag, changing accepts/produces,
+ * swapping sibling side-effects, or expanding side effect is breaking.
+ * @param {object} previousApi - Previous API object
+ * @param {object} currentApi - Current API object
+ * @returns {{ compatible: boolean, breaking: string[] }}
+ */
+export function checkApiCompatibility(previousApi, currentApi) {
+  const breaking = [];
+  const prevServices = new Map((previousApi.services || []).map(s => [s.id, s]));
+  const currServices = new Map((currentApi.services || []).map(s => [s.id, s]));
+
+  // Check removed services
+  for (const [id, prev] of prevServices) {
+    if (!currServices.has(id)) {
+      if (prev.required) {
+        breaking.push(`required service "${id}" removed`);
+      }
+      // Removing optional service is compatible
+    }
+  }
+
+  // Check changed and new services
+  for (const [id, curr] of currServices) {
+    const prev = prevServices.get(id);
+    if (!prev) {
+      // New required service is breaking
+      if (curr.required) {
+        breaking.push(`new required service "${id}" added`);
+      }
+      // New optional service is compatible
+      continue;
+    }
+
+    // Check required flag changed
+    if (prev.required !== curr.required) {
+      breaking.push(`service "${id}" required flag changed from ${prev.required} to ${curr.required}`);
+    }
+
+    // Check accepts changed
+    const prevAccepts = stableStringify(prev.accepts || []);
+    const currAccepts = stableStringify(curr.accepts || []);
+    if (prevAccepts !== currAccepts) {
+      breaking.push(`service "${id}" accepts changed`);
+    }
+
+    // Check produces changed
+    const prevProduces = stableStringify(prev.produces || []);
+    const currProduces = stableStringify(curr.produces || []);
+    if (prevProduces !== currProduces) {
+      breaking.push(`service "${id}" produces changed`);
+    }
+
+    // Check side effect: expansion OR sibling swap is breaking
+    const prevCeiling = prev.sideEffectCeiling;
+    const currCeiling = curr.sideEffectCeiling;
+    if (prevCeiling !== currCeiling) {
+      const prevRank = CEILING_RANK[prevCeiling] ?? 0;
+      const currRank = CEILING_RANK[currCeiling] ?? 0;
+      // Expansion (higher rank) is breaking
+      if (currRank > prevRank) {
+        breaking.push(`service "${id}" sideEffectCeiling expanded from "${prevCeiling}" to "${currCeiling}"`);
+      }
+      // Sibling swap (same rank, different ceiling) is also breaking
+      // e.g., write-review-result ↔ write-authorized-artifacts
+      else if (currRank === prevRank) {
+        breaking.push(`service "${id}" sideEffectCeiling changed from "${prevCeiling}" to "${currCeiling}" (sibling swap)`);
+      }
+    }
+  }
+
+  return { compatible: breaking.length === 0, breaking };
+}

package/adapters/claude/scripts/lib/generated/canonical-json-v1-manifest.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "protocol": "canonical-json-v1",
+  "authorityDigest": "sha256:5f7d38cc2646d9b149f384f439870b7d71b9e6d8b5abfc0f2fee6f9f3b395e25",
+  "outputDigest": "sha256:5937d28fa9862399b654637ca130a51d0bad24350943e4e48ee7cab4c4c51350",
+  "vectorsDigest": "sha256:7b6ee3d871269e72cea6b79daac07bcd3ef57aae65c3cccd548e64dfa1298eef"
+}

package/adapters/claude/scripts/lib/generated/canonical-json-v1-vectors.generated.json

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": 1,
+  "protocol": "canonical-json-v1",
+  "legal": [
+    {
+      "name": "object-unicode-null",
+      "input": { "b": 1, "a": 2, "unicode": "你好", "nullValue": null },
+      "canonical": "{\"a\":2,\"b\":1,\"nullValue\":null,\"unicode\":\"你好\"}",
+      "digest": "sha256:e9da8640b06cbb0970d8072eff5b57498381aed127343d9f552916ea4564bd9f"
+    },
+    {
+      "name": "ordinary-array-order",
+      "input": { "items": [3, 1, 2] },
+      "canonical": "{\"items\":[3,1,2]}",
+      "digest": "sha256:de21aef9c6d6b65cfe6dc3c9159d9969659d1f5b854c6249d871036c57a26966"
+    },
+    {
+      "name": "set-like-names-remain-ordinary",
+      "input": {
+        "contextTargets": ["c", "a", "b"],
+        "domains": ["web", "api"],
+        "intents": ["build", "deploy"],
+        "artifactTypes": ["feature", "bugfix"]
+      },
+      "canonical": "{\"artifactTypes\":[\"feature\",\"bugfix\"],\"contextTargets\":[\"c\",\"a\",\"b\"],\"domains\":[\"web\",\"api\"],\"intents\":[\"build\",\"deploy\"]}",
+      "digest": "sha256:6cb73e462de926a9249a0d3fd92565d83096e6701383c4f5f33f809a013c2047"
+    },
+    {
+      "name": "canonical-project-facts-targets",
+      "input": {
+        "artifactGraphSummary": {
+          "artifactCount": 2,
+          "edgeCount": 3,
+          "contextTargets": ["ACA12", "ACA18"]
+        }
+      },
+      "canonical": "{\"artifactGraphSummary\":{\"artifactCount\":2,\"contextTargets\":[\"ACA12\",\"ACA18\"],\"edgeCount\":3}}",
+      "digest": "sha256:9e608eb56d99ccf1dc70eb2dba46efc9538f30b3d5481061cce02112692e8055"
+    }
+  ],
+  "orderDifferences": [
+    { "name": "ordinary-array", "left": { "items": [1, 2, 3] }, "right": { "items": [3, 2, 1] } },
+    { "name": "contextTargets-name-is-not-global-set", "left": { "contextTargets": ["a", "b"] }, "right": { "contextTargets": ["b", "a"] } }
+  ],
+  "invalidKinds": [
+    "undefined", "nan", "positive-infinity", "negative-infinity", "bigint", "symbol", "function",
+    "date", "regexp", "map", "set", "promise", "error", "custom-prototype", "circular",
+    "sparse-array", "hidden-field", "symbol-key", "accessor", "proxy"
+  ]
+}

package/adapters/claude/scripts/lib/generated/canonical-json-v1.generated.mjs

@@ -0,0 +1,130 @@
+// Generated by scripts/generate-canonical-json-protocol.mjs.
+// authority digest: sha256:5f7d38cc2646d9b149f384f439870b7d71b9e6d8b5abfc0f2fee6f9f3b395e25
+// Canonical JSON v1 — authoritative, dependency-free protocol implementation.
+// Consumers may import this public subpath or ship an exact generated snapshot.
+import { runInNewContext } from 'node:vm';
+import { types as utilTypes } from 'node:util';
+
+const primordials = runInNewContext(`({
+  getOwnPropertyDescriptor: Object.getOwnPropertyDescriptor,
+  getPrototypeOf: Object.getPrototypeOf,
+  ownKeys: Reflect.ownKeys,
+  isArray: Array.isArray,
+  isFinite: Number.isFinite,
+  isInteger: Number.isInteger
+})`);
+const objectPrototype = primordials.getPrototypeOf({});
+const arrayPrototype = primordials.getPrototypeOf([]);
+const bannedPrototypes = new Map([
+  [Date.prototype, 'Date'],
+  [RegExp.prototype, 'RegExp'],
+  [Map.prototype, 'Map'],
+  [Set.prototype, 'Set'],
+  [WeakMap.prototype, 'WeakMap'],
+  [WeakSet.prototype, 'WeakSet'],
+  [Promise.prototype, 'Promise'],
+  [Error.prototype, 'Error'],
+]);
+
+function nextAncestors(ancestors, value) {
+  const next = new Array(ancestors.length + 1);
+  for (let index = 0; index < ancestors.length; index += 1) next[index] = ancestors[index];
+  next[ancestors.length] = value;
+  return next;
+}
+
+function isArrayIndex(key, length) {
+  if (key === '') return false;
+  const numeric = Number(key);
+  return primordials.isInteger(numeric) && numeric >= 0 && numeric < length && String(numeric) === key;
+}
+
+export function cloneStrictJsonData(value, ancestors = []) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!primordials.isFinite(value)) throw new TypeError(`Canonical JSON rejects ${String(value)}`);
+    return value;
+  }
+  if (typeof value !== 'object') {
+    const label = typeof value === 'bigint' ? 'BigInt'
+      : typeof value === 'symbol' ? 'Symbol'
+        : typeof value === 'function' ? 'function'
+          : 'undefined';
+    throw new TypeError(`Canonical JSON rejects ${label}`);
+  }
+
+  if (utilTypes.isProxy(value)) throw new TypeError('Proxy value rejected');
+  for (let index = 0; index < ancestors.length; index += 1) {
+    if (ancestors[index] === value) throw new TypeError('circular reference rejected');
+  }
+
+  const isArray = primordials.isArray(value);
+  const prototype = primordials.getPrototypeOf(value);
+  if (prototype !== (isArray ? arrayPrototype : objectPrototype) && !(prototype === null && !isArray)) {
+    const banned = bannedPrototypes.get(prototype);
+    if (banned) throw new TypeError(`Canonical JSON rejects ${banned}`);
+    throw new TypeError('custom prototype rejected');
+  }
+
+  const keys = primordials.ownKeys(value);
+  for (const key of keys) {
+    if (typeof key === 'symbol') throw new TypeError('symbol-keyed property rejected');
+  }
+
+  const next = nextAncestors(ancestors, value);
+  if (isArray) {
+    const lengthDescriptor = primordials.getOwnPropertyDescriptor(value, 'length');
+    if (!lengthDescriptor || !('value' in lengthDescriptor) || !primordials.isInteger(lengthDescriptor.value)) {
+      throw new TypeError('invalid array length rejected');
+    }
+    const length = lengthDescriptor.value;
+    const output = new Array(length);
+    for (let index = 0; index < length; index += 1) {
+      const descriptor = primordials.getOwnPropertyDescriptor(value, String(index));
+      if (!descriptor || !('value' in descriptor) || descriptor.enumerable !== true) {
+        throw new TypeError('sparse array or accessor element rejected');
+      }
+      output[index] = cloneStrictJsonData(descriptor.value, next);
+    }
+    for (const key of keys) {
+      if (key !== 'length' && !isArrayIndex(key, length)) {
+        throw new TypeError('extra array property rejected');
+      }
+    }
+    return output;
+  }
+
+  const output = Object.create(null);
+  for (const key of keys) {
+    const descriptor = primordials.getOwnPropertyDescriptor(value, key);
+    if (!descriptor) throw new TypeError(`missing property descriptor "${key}" rejected`);
+    if (!('value' in descriptor)) {
+      throw new TypeError(`accessor property "${key}" rejected`);
+    }
+    if (descriptor.enumerable !== true) {
+      throw new TypeError(`non-enumerable field "${key}" rejected`);
+    }
+    output[key] = cloneStrictJsonData(descriptor.value, next);
+  }
+  return output;
+}
+
+export function validateJsonSafe(value) {
+  cloneStrictJsonData(value);
+}
+
+function sortObjectKeys(value) {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(sortObjectKeys);
+  const output = Object.create(null);
+  for (const key of Object.keys(value).sort()) output[key] = sortObjectKeys(value[key]);
+  return output;
+}
+
+export function canonicalizeJson(value) {
+  return sortObjectKeys(cloneStrictJsonData(value));
+}
+
+export function canonicalStringify(value) {
+  return JSON.stringify(canonicalizeJson(value));
+}