commandmate 0.11.4 → 0.12.0

package/dist/server/src/lib/skills/schema.js

@@ -0,0 +1,1248 @@
+"use strict";
+/**
+ * Schema validation for the Agent Skills distribution contract (Issue #1228)
+ *
+ * Pure functions over already-parsed values: no filesystem, no network, no YAML
+ * parser. The caller parses `commandmate.skill.yaml` under
+ * {@link SKILL_YAML_SAFE_PROFILE} and hands the resulting `unknown` here.
+ *
+ * Every validator is fail-closed and total: it returns a
+ * {@link SkillValidationResult} rather than throwing, and on success returns a
+ * freshly constructed object so no unvalidated property from the input
+ * survives.
+ *
+ * @module lib/skills/schema
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_OPTIONAL_FIELDS = exports.SKILL_DOCUMENT_FIELDS = void 0;
+exports.foldSkillIdForCollision = foldSkillIdForCollision;
+exports.validateSkillId = validateSkillId;
+exports.detectSkillIdCollision = detectSkillIdCollision;
+exports.validateSkillIdentityConsistency = validateSkillIdentityConsistency;
+exports.validateSkillPayloadPath = validateSkillPayloadPath;
+exports.validateSkillManifest = validateSkillManifest;
+exports.validateSkillCatalog = validateSkillCatalog;
+exports.validateSkillInstallReceipt = validateSkillInstallReceipt;
+exports.validateManifestFileSet = validateManifestFileSet;
+exports.resolveEffectiveSkillRisk = resolveEffectiveSkillRisk;
+exports.computeSkillRisk = computeSkillRisk;
+exports.canonicalizeSkillReceipt = canonicalizeSkillReceipt;
+const types_1 = require("../../lib/cli-tools/types");
+const constants_1 = require("../../lib/skills/constants");
+const errors_1 = require("../../lib/skills/errors");
+const semver_1 = require("../../lib/skills/semver");
+// =============================================================================
+// Allowed field sets (schema_version 1 is closed: unknown fields are rejected)
+// =============================================================================
+const MANIFEST_FIELDS = [
+    'schema_version',
+    'id',
+    'name',
+    'version',
+    'summary',
+    'description',
+    'capabilities',
+    'expected_outcomes',
+    'provider',
+    'license',
+    'homepage',
+    'keywords',
+    'compatibility',
+    'requirements',
+    'declared_permissions',
+    'declared_risk',
+    'risk_rationale',
+    'files',
+];
+const CATALOG_FIELDS = ['schema_version', 'entries'];
+const CATALOG_ENTRY_FIELDS = [
+    'id',
+    'name',
+    'summary',
+    'provider',
+    'license',
+    'homepage',
+    'keywords',
+    'latest',
+    'versions',
+];
+const CATALOG_VERSION_FIELDS = [
+    'version',
+    'changelog',
+    'published_at',
+    'source',
+    'artifact',
+    'compatibility',
+    'declared_risk',
+];
+const RECEIPT_FIELDS = [
+    'schema_version',
+    'skill_id',
+    'version',
+    'install_root',
+    'install_roots',
+    'source',
+    'artifact',
+    'files',
+    'declared_risk',
+    'computed_risk',
+    'effective_risk',
+    'declared_permissions',
+    'agent_compatibility',
+];
+const PROVIDER_FIELDS = ['name', 'url', 'contact'];
+const COMPATIBILITY_FIELDS = ['commandmate', 'agents'];
+const AGENT_COMPAT_FIELDS = ['agent', 'support', 'evidence'];
+const REQUIREMENTS_FIELDS = ['commands', 'network_hosts'];
+const COMMAND_FIELDS = ['name', 'version_range'];
+const FILE_ENTRY_FIELDS = ['path', 'sha256', 'size', 'kind', 'executable', 'script'];
+const SOURCE_FIELDS = ['repository', 'ref', 'commit'];
+const ARTIFACT_FIELDS = ['asset_name', 'url', 'sha256', 'size', 'content_type', 'format'];
+const RECEIPT_ARTIFACT_FIELDS = ['asset_name', 'sha256', 'size', 'format'];
+const INSTALLED_FILE_FIELDS = ['path', 'sha256', 'size', 'executable'];
+/** Field name lists, exposed so schema-parity tests can compare them to the JSON Schema. */
+exports.SKILL_DOCUMENT_FIELDS = {
+    manifest: MANIFEST_FIELDS,
+    catalog: CATALOG_FIELDS,
+    catalogEntry: CATALOG_ENTRY_FIELDS,
+    catalogVersion: CATALOG_VERSION_FIELDS,
+    receipt: RECEIPT_FIELDS,
+    provider: PROVIDER_FIELDS,
+    compatibility: COMPATIBILITY_FIELDS,
+    agentCompatibility: AGENT_COMPAT_FIELDS,
+    requirements: REQUIREMENTS_FIELDS,
+    requirementCommand: COMMAND_FIELDS,
+    fileEntry: FILE_ENTRY_FIELDS,
+    source: SOURCE_FIELDS,
+    artifact: ARTIFACT_FIELDS,
+    receiptArtifact: RECEIPT_ARTIFACT_FIELDS,
+    installedFile: INSTALLED_FILE_FIELDS,
+};
+/** Optional fields per document, exposed for the same parity check. */
+exports.SKILL_OPTIONAL_FIELDS = {
+    manifest: ['homepage', 'keywords'],
+    catalog: [],
+    catalogEntry: ['homepage', 'keywords'],
+    catalogVersion: [],
+    receipt: ['install_roots'],
+    provider: ['url', 'contact'],
+    compatibility: [],
+    agentCompatibility: [],
+    requirements: [],
+    requirementCommand: ['version_range'],
+    fileEntry: [],
+    source: [],
+    artifact: [],
+    receiptArtifact: [],
+    installedFile: [],
+};
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function has(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+function readObject(value, path, errors) {
+    if (!isPlainObject(value)) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.NOT_AN_OBJECT, path, `${path || '/'} must be an object`));
+        return null;
+    }
+    return value;
+}
+function checkUnknownFields(obj, allowed, path, errors) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.includes(key)) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.UNKNOWN_FIELD, (0, errors_1.joinPath)(path, key), `unknown field is not allowed in schema_version ${constants_1.SKILL_SCHEMA_VERSION}`));
+        }
+    }
+}
+function readString(obj, key, parent, errors, options = {}) {
+    const path = (0, errors_1.joinPath)(parent, key);
+    if (!has(obj, key) || obj[key] === undefined) {
+        if (!options.optional) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, path, `${key} is required`));
+        }
+        return undefined;
+    }
+    const value = obj[key];
+    if (typeof value !== 'string') {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INVALID_TYPE, path, `${key} must be a string`));
+        return undefined;
+    }
+    // A field with a domain-specific error code reports that code for every
+    // violation, so a truncated digest reads as "invalid digest" rather than as a
+    // generic length problem.
+    const lengthCode = options.formatCode ?? errors_1.SkillContractErrorCode.LIMIT_EXCEEDED;
+    const min = options.minLength ?? 1;
+    if (value.length < min) {
+        errors.push((0, errors_1.skillError)(lengthCode, path, `${key} is shorter than the minimum`, { minLength: min }));
+        return undefined;
+    }
+    if (options.maxLength !== undefined && value.length > options.maxLength) {
+        errors.push((0, errors_1.skillError)(lengthCode, path, `${key} exceeds the maximum length`, {
+            maxLength: options.maxLength,
+        }));
+        return undefined;
+    }
+    if (options.pattern && !options.pattern.test(value)) {
+        errors.push((0, errors_1.skillError)(options.formatCode ?? errors_1.SkillContractErrorCode.INVALID_FORMAT, path, `${key} does not match the required format`, options.patternName ? { format: options.patternName } : undefined));
+        return undefined;
+    }
+    return value;
+}
+function readInteger(obj, key, parent, errors, bounds) {
+    const path = (0, errors_1.joinPath)(parent, key);
+    if (!has(obj, key) || obj[key] === undefined) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, path, `${key} is required`));
+        return undefined;
+    }
+    const value = obj[key];
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INVALID_TYPE, path, `${key} must be an integer`));
+        return undefined;
+    }
+    if (value < bounds.min || value > bounds.max) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.LIMIT_EXCEEDED, path, `${key} is out of range`, bounds));
+        return undefined;
+    }
+    return value;
+}
+function readBoolean(obj, key, parent, errors) {
+    const path = (0, errors_1.joinPath)(parent, key);
+    if (!has(obj, key) || obj[key] === undefined) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, path, `${key} is required`));
+        return undefined;
+    }
+    const value = obj[key];
+    if (typeof value !== 'boolean') {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INVALID_TYPE, path, `${key} must be a boolean`));
+        return undefined;
+    }
+    return value;
+}
+function readArray(obj, key, parent, errors, options) {
+    const path = (0, errors_1.joinPath)(parent, key);
+    if (!has(obj, key) || obj[key] === undefined) {
+        if (!options.optional) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, path, `${key} is required`));
+        }
+        return undefined;
+    }
+    const value = obj[key];
+    if (!Array.isArray(value)) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INVALID_TYPE, path, `${key} must be an array`));
+        return undefined;
+    }
+    if (value.length > options.maxItems) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.LIMIT_EXCEEDED, path, `${key} has too many items`, {
+            maxItems: options.maxItems,
+        }));
+        return undefined;
+    }
+    return value;
+}
+function readEnum(obj, key, parent, errors, allowed) {
+    const path = (0, errors_1.joinPath)(parent, key);
+    if (!has(obj, key) || obj[key] === undefined) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, path, `${key} is required`));
+        return undefined;
+    }
+    const value = obj[key];
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INVALID_ENUM, path, `${key} is not an allowed value`, {
+            allowed: allowed.join('|'),
+        }));
+        return undefined;
+    }
+    return value;
+}
+function readStringList(obj, key, parent, errors, options) {
+    const raw = readArray(obj, key, parent, errors, {
+        maxItems: options.maxItems,
+        optional: options.optional,
+    });
+    if (raw === undefined)
+        return undefined;
+    const out = [];
+    let failed = false;
+    raw.forEach((item, index) => {
+        const path = (0, errors_1.joinPath)((0, errors_1.joinPath)(parent, key), index);
+        if (typeof item !== 'string' || item.length === 0 || item.length > options.maxLength) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INVALID_TYPE, path, 'item must be a bounded string', {
+                maxLength: options.maxLength,
+            }));
+            failed = true;
+            return;
+        }
+        if (options.pattern && !options.pattern.test(item)) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INVALID_FORMAT, path, 'item does not match the required format'));
+            failed = true;
+            return;
+        }
+        out.push(item);
+    });
+    return failed ? undefined : out;
+}
+function readHttpsUrl(obj, key, parent, errors, options = {}) {
+    const value = readString(obj, key, parent, errors, { optional: options.optional, maxLength: 512 });
+    if (value === undefined)
+        return undefined;
+    if (!value.startsWith(constants_1.HTTPS_URL_PREFIX)) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INVALID_FORMAT, (0, errors_1.joinPath)(parent, key), `${key} must be an https URL`));
+        return undefined;
+    }
+    return value;
+}
+function readSchemaVersion(obj, errors) {
+    const path = '/schema_version';
+    const value = obj['schema_version'];
+    if (value === undefined) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.SCHEMA_VERSION_UNSUPPORTED, path, 'schema_version is required'));
+        return undefined;
+    }
+    if (value !== constants_1.SKILL_SCHEMA_VERSION) {
+        // Fail closed: a future schema_version is rejected, never best-effort parsed.
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.SCHEMA_VERSION_UNSUPPORTED, path, 'schema_version is not supported by this build', { supported: constants_1.SKILL_SCHEMA_VERSION }));
+        return undefined;
+    }
+    return constants_1.SKILL_SCHEMA_VERSION;
+}
+// =============================================================================
+// Skill ID
+// =============================================================================
+/**
+ * Fold a name for collision detection.
+ *
+ * Case folding plus NFKC catches directory names that differ only by case or by
+ * a compatibility-equivalent Unicode form but collide on a case-insensitive or
+ * normalizing filesystem.
+ */
+function foldSkillIdForCollision(name) {
+    return name.normalize('NFKC').toLowerCase();
+}
+/** Validate a Skill ID against the slug grammar and the reserved list. */
+function validateSkillId(id, path = '/id') {
+    if (typeof id !== 'string' || id.length === 0) {
+        return (0, errors_1.skillFail)([(0, errors_1.skillError)(errors_1.SkillContractErrorCode.ID_INVALID, path, 'id must be a non-empty string')]);
+    }
+    if (id.length > constants_1.SKILL_ID_MAX_LENGTH) {
+        return (0, errors_1.skillFail)([
+            (0, errors_1.skillError)(errors_1.SkillContractErrorCode.ID_INVALID, path, 'id exceeds the maximum length', {
+                maxLength: constants_1.SKILL_ID_MAX_LENGTH,
+            }),
+        ]);
+    }
+    if (!constants_1.SKILL_ID_PATTERN.test(id)) {
+        return (0, errors_1.skillFail)([
+            (0, errors_1.skillError)(errors_1.SkillContractErrorCode.ID_INVALID, path, 'id must be a lowercase ASCII slug', {
+                format: 'lowercase-slug',
+            }),
+        ]);
+    }
+    if (constants_1.RESERVED_SKILL_IDS.includes(id)) {
+        return (0, errors_1.skillFail)([(0, errors_1.skillError)(errors_1.SkillContractErrorCode.ID_RESERVED, path, 'id is reserved')]);
+    }
+    return (0, errors_1.skillOk)(id);
+}
+/**
+ * Detect a case/Unicode collision between a new ID and existing directory names.
+ *
+ * @returns the colliding existing name, or null when the ID is free.
+ */
+function detectSkillIdCollision(id, existingNames) {
+    const folded = foldSkillIdForCollision(id);
+    for (const name of existingNames) {
+        if (name === id)
+            continue;
+        if (foldSkillIdForCollision(name) === folded)
+            return name;
+    }
+    return null;
+}
+/**
+ * Check that the directory name, the SKILL.md frontmatter name and the manifest
+ * agree, which is what stops a package from installing under a name the user
+ * never reviewed.
+ */
+function validateSkillIdentityConsistency(input) {
+    const idResult = validateSkillId(input.manifestId);
+    if (!idResult.ok)
+        return idResult;
+    const errors = [];
+    if (input.directoryName !== input.manifestId) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.ID_MISMATCH, '/id', 'directory name does not match the manifest id'));
+    }
+    if (input.skillMdName !== input.manifestName) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.ID_MISMATCH, '/name', 'SKILL.md name does not match the manifest name'));
+    }
+    return errors.length > 0 ? (0, errors_1.skillFail)(errors) : (0, errors_1.skillOk)(input.manifestId);
+}
+// =============================================================================
+// Payload paths
+// =============================================================================
+const WINDOWS_DRIVE_PATH = /^[A-Za-z]:/;
+/** NUL and other control bytes are rejected by code point, not by a control regex. */
+function hasControlCharOrBackslash(value) {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f || code === 0x5c)
+            return true;
+    }
+    return false;
+}
+/**
+ * Validate a payload path declared in a manifest or receipt.
+ *
+ * String-level only: it rejects everything that could escape the Skill root
+ * before any filesystem call happens. Real-path/symlink checks stay with the
+ * installer (#1231), which owns the filesystem.
+ */
+function validateSkillPayloadPath(value, path) {
+    const fail = (message, detail) => (0, errors_1.skillFail)([(0, errors_1.skillError)(errors_1.SkillContractErrorCode.FILE_PATH_UNSAFE, path, message, detail)]);
+    if (typeof value !== 'string' || value.length === 0)
+        return fail('path must be a non-empty string');
+    if (value.length > constants_1.SKILL_PATH_MAX_LENGTH) {
+        return fail('path exceeds the maximum length', { maxLength: constants_1.SKILL_PATH_MAX_LENGTH });
+    }
+    if (hasControlCharOrBackslash(value))
+        return fail('path contains a control character or a backslash');
+    if (value.startsWith('/') || WINDOWS_DRIVE_PATH.test(value))
+        return fail('path must be relative');
+    if (value !== value.normalize('NFC'))
+        return fail('path must be NFC-normalized');
+    if (value.includes('//'))
+        return fail('path must not contain empty segments');
+    if (value.endsWith('/'))
+        return fail('path must not be a directory entry');
+    const segments = value.split('/');
+    if (segments.length > constants_1.SKILL_PATH_MAX_DEPTH) {
+        return fail('path is nested too deeply', { maxDepth: constants_1.SKILL_PATH_MAX_DEPTH });
+    }
+    for (const segment of segments) {
+        if (segment === '.' || segment === '..')
+            return fail('path must not contain "." or ".." segments');
+        if (segment.length > constants_1.SKILL_PATH_SEGMENT_MAX_LENGTH) {
+            return fail('path segment is too long', { maxLength: constants_1.SKILL_PATH_SEGMENT_MAX_LENGTH });
+        }
+        if (segment !== segment.trim())
+            return fail('path segment must not be padded with whitespace');
+    }
+    return (0, errors_1.skillOk)(value);
+}
+// =============================================================================
+// Shared sub-object validators
+// =============================================================================
+function readProvider(parentObj, parent, errors) {
+    const path = (0, errors_1.joinPath)(parent, 'provider');
+    const raw = parentObj['provider'];
+    if (raw === undefined) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, path, 'provider is required'));
+        return undefined;
+    }
+    const obj = readObject(raw, path, errors);
+    if (!obj)
+        return undefined;
+    checkUnknownFields(obj, PROVIDER_FIELDS, path, errors);
+    const name = readString(obj, 'name', path, errors, { maxLength: constants_1.SKILL_NAME_MAX_LENGTH });
+    const url = readHttpsUrl(obj, 'url', path, errors, { optional: true });
+    const contact = readString(obj, 'contact', path, errors, { optional: true, maxLength: 200 });
+    if (name === undefined)
+        return undefined;
+    return { name, ...(url !== undefined ? { url } : {}), ...(contact !== undefined ? { contact } : {}) };
+}
+function readAgentCompatibility(raw, path, errors) {
+    const obj = readObject(raw, path, errors);
+    if (!obj)
+        return undefined;
+    checkUnknownFields(obj, AGENT_COMPAT_FIELDS, path, errors);
+    const agent = readString(obj, 'agent', path, errors, { maxLength: 40 });
+    if (agent !== undefined && !(0, types_1.isCliToolType)(agent)) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INVALID_ENUM, (0, errors_1.joinPath)(path, 'agent'), 'agent is not a known CLI tool'));
+        return undefined;
+    }
+    const support = readEnum(obj, 'support', path, errors, constants_1.SKILL_AGENT_SUPPORT_VALUES);
+    const evidence = readString(obj, 'evidence', path, errors, { maxLength: constants_1.SKILL_EVIDENCE_MAX_LENGTH });
+    if (agent === undefined || support === undefined || evidence === undefined)
+        return undefined;
+    return { agent, support, evidence };
+}
+function readCompatibility(parentObj, parent, errors) {
+    const path = (0, errors_1.joinPath)(parent, 'compatibility');
+    const raw = parentObj['compatibility'];
+    if (raw === undefined) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, path, 'compatibility is required'));
+        return undefined;
+    }
+    const obj = readObject(raw, path, errors);
+    if (!obj)
+        return undefined;
+    checkUnknownFields(obj, COMPATIBILITY_FIELDS, path, errors);
+    const commandmate = readString(obj, 'commandmate', path, errors, { maxLength: 100 });
+    if (commandmate !== undefined && !(0, semver_1.isValidSkillVersionRange)(commandmate)) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.VERSION_RANGE_INVALID, (0, errors_1.joinPath)(path, 'commandmate'), 'commandmate is not a supported version range'));
+        return undefined;
+    }
+    const rawAgents = readArray(obj, 'agents', path, errors, { maxItems: 20 });
+    if (commandmate === undefined || rawAgents === undefined)
+        return undefined;
+    const agents = [];
+    const seen = new Set();
+    let failed = false;
+    rawAgents.forEach((item, index) => {
+        const itemPath = (0, errors_1.joinPath)((0, errors_1.joinPath)(path, 'agents'), index);
+        const parsed = readAgentCompatibility(item, itemPath, errors);
+        if (!parsed) {
+            failed = true;
+            return;
+        }
+        if (seen.has(parsed.agent)) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.DUPLICATE_ENTRY, itemPath, 'agent is declared more than once'));
+            failed = true;
+            return;
+        }
+        seen.add(parsed.agent);
+        agents.push(parsed);
+    });
+    return failed ? undefined : { commandmate, agents };
+}
+function readRequirements(parentObj, parent, errors) {
+    const path = (0, errors_1.joinPath)(parent, 'requirements');
+    const raw = parentObj['requirements'];
+    if (raw === undefined) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, path, 'requirements is required'));
+        return undefined;
+    }
+    const obj = readObject(raw, path, errors);
+    if (!obj)
+        return undefined;
+    checkUnknownFields(obj, REQUIREMENTS_FIELDS, path, errors);
+    const rawCommands = readArray(obj, 'commands', path, errors, { maxItems: constants_1.SKILL_COMMANDS_MAX_COUNT });
+    const networkHosts = readStringList(obj, 'network_hosts', path, errors, {
+        maxItems: constants_1.SKILL_NETWORK_HOSTS_MAX_COUNT,
+        maxLength: 253,
+        pattern: constants_1.NETWORK_HOST_PATTERN,
+    });
+    if (rawCommands === undefined || networkHosts === undefined)
+        return undefined;
+    const commands = [];
+    let failed = false;
+    rawCommands.forEach((item, index) => {
+        const itemPath = (0, errors_1.joinPath)((0, errors_1.joinPath)(path, 'commands'), index);
+        const cmdObj = readObject(item, itemPath, errors);
+        if (!cmdObj) {
+            failed = true;
+            return;
+        }
+        checkUnknownFields(cmdObj, COMMAND_FIELDS, itemPath, errors);
+        const name = readString(cmdObj, 'name', itemPath, errors, {
+            maxLength: 64,
+            pattern: constants_1.COMMAND_NAME_PATTERN,
+            patternName: 'command-name',
+        });
+        const range = readString(cmdObj, 'version_range', itemPath, errors, {
+            optional: true,
+            maxLength: 100,
+        });
+        if (range !== undefined && !(0, semver_1.isValidSkillVersionRange)(range)) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.VERSION_RANGE_INVALID, (0, errors_1.joinPath)(itemPath, 'version_range'), 'version_range is not a supported version range'));
+            failed = true;
+            return;
+        }
+        if (name === undefined) {
+            failed = true;
+            return;
+        }
+        commands.push({ name, ...(range !== undefined ? { version_range: range } : {}) });
+    });
+    return failed ? undefined : { commands, network_hosts: networkHosts };
+}
+function readSource(parentObj, parent, errors) {
+    const path = (0, errors_1.joinPath)(parent, 'source');
+    const raw = parentObj['source'];
+    if (raw === undefined) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, path, 'source is required'));
+        return undefined;
+    }
+    const obj = readObject(raw, path, errors);
+    if (!obj)
+        return undefined;
+    checkUnknownFields(obj, SOURCE_FIELDS, path, errors);
+    const repository = readString(obj, 'repository', path, errors, {
+        maxLength: 140,
+        pattern: constants_1.REPOSITORY_SLUG_PATTERN,
+        patternName: 'owner/name',
+    });
+    const ref = readString(obj, 'ref', path, errors, {
+        maxLength: 100,
+        pattern: constants_1.GIT_REF_PATTERN,
+        patternName: 'git-ref',
+    });
+    if (ref !== undefined && ref.includes('..')) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INVALID_FORMAT, (0, errors_1.joinPath)(path, 'ref'), 'ref must not contain ".."'));
+        return undefined;
+    }
+    const commit = readString(obj, 'commit', path, errors, {
+        maxLength: 40,
+        minLength: 40,
+        pattern: constants_1.GIT_COMMIT_SHA_PATTERN,
+        patternName: 'sha1-40-hex',
+        formatCode: errors_1.SkillContractErrorCode.SOURCE_COMMIT_INVALID,
+    });
+    if (repository === undefined || ref === undefined || commit === undefined)
+        return undefined;
+    return { repository, ref, commit };
+}
+function readArtifact(parentObj, parent, errors) {
+    const path = (0, errors_1.joinPath)(parent, 'artifact');
+    const raw = parentObj['artifact'];
+    if (raw === undefined) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, path, 'artifact is required'));
+        return undefined;
+    }
+    const obj = readObject(raw, path, errors);
+    if (!obj)
+        return undefined;
+    checkUnknownFields(obj, ARTIFACT_FIELDS, path, errors);
+    const assetName = readString(obj, 'asset_name', path, errors, { maxLength: 200 });
+    const url = readHttpsUrl(obj, 'url', path, errors);
+    const sha256 = readString(obj, 'sha256', path, errors, {
+        minLength: 64,
+        maxLength: 64,
+        pattern: constants_1.SHA256_HEX_PATTERN,
+        patternName: 'sha256-lowercase-hex',
+        formatCode: errors_1.SkillContractErrorCode.DIGEST_INVALID,
+    });
+    const size = readInteger(obj, 'size', path, errors, { min: 1, max: constants_1.SKILL_ARTIFACT_MAX_SIZE });
+    const contentType = readString(obj, 'content_type', path, errors, { maxLength: 100 });
+    const format = readEnum(obj, 'format', path, errors, [constants_1.SKILL_ARTIFACT_FORMAT]);
+    if (contentType !== undefined && contentType !== constants_1.SKILL_ARTIFACT_CONTENT_TYPE) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.ARTIFACT_INVALID, (0, errors_1.joinPath)(path, 'content_type'), 'content_type must be the fixed artifact media type', { expected: constants_1.SKILL_ARTIFACT_CONTENT_TYPE }));
+        return undefined;
+    }
+    if (assetName === undefined ||
+        url === undefined ||
+        sha256 === undefined ||
+        size === undefined ||
+        contentType === undefined ||
+        format === undefined) {
+        return undefined;
+    }
+    return { asset_name: assetName, url, sha256, size, content_type: contentType, format };
+}
+// =============================================================================
+// Manifest
+// =============================================================================
+function readFileEntries(parentObj, parent, errors) {
+    const path = (0, errors_1.joinPath)(parent, 'files');
+    const raw = readArray(parentObj, 'files', parent, errors, { maxItems: constants_1.SKILL_FILES_MAX_COUNT });
+    if (raw === undefined)
+        return undefined;
+    const entries = [];
+    const seenFolded = new Set();
+    let failed = false;
+    raw.forEach((item, index) => {
+        const itemPath = (0, errors_1.joinPath)(path, index);
+        const obj = readObject(item, itemPath, errors);
+        if (!obj) {
+            failed = true;
+            return;
+        }
+        checkUnknownFields(obj, FILE_ENTRY_FIELDS, itemPath, errors);
+        const pathResult = validateSkillPayloadPath(obj['path'], (0, errors_1.joinPath)(itemPath, 'path'));
+        const sha256 = readString(obj, 'sha256', itemPath, errors, {
+            minLength: 64,
+            maxLength: 64,
+            pattern: constants_1.SHA256_HEX_PATTERN,
+            patternName: 'sha256-lowercase-hex',
+            formatCode: errors_1.SkillContractErrorCode.DIGEST_INVALID,
+        });
+        const size = readInteger(obj, 'size', itemPath, errors, { min: 0, max: constants_1.SKILL_FILE_MAX_SIZE });
+        const kind = readEnum(obj, 'kind', itemPath, errors, constants_1.SKILL_FILE_KINDS);
+        const executable = readBoolean(obj, 'executable', itemPath, errors);
+        const script = readBoolean(obj, 'script', itemPath, errors);
+        if (!pathResult.ok) {
+            errors.push(...pathResult.errors);
+            failed = true;
+            return;
+        }
+        if (sha256 === undefined ||
+            size === undefined ||
+            kind === undefined ||
+            executable === undefined ||
+            script === undefined) {
+            failed = true;
+            return;
+        }
+        const filePath = pathResult.value;
+        if (filePath === constants_1.SKILL_MANIFEST_FILENAME) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.FILE_SET_MISMATCH, (0, errors_1.joinPath)(itemPath, 'path'), 'the manifest must not declare a digest for itself'));
+            failed = true;
+            return;
+        }
+        const folded = foldSkillIdForCollision(filePath);
+        if (seenFolded.has(folded)) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.FILE_PATH_DUPLICATE, (0, errors_1.joinPath)(itemPath, 'path'), 'path collides with another declared file'));
+            failed = true;
+            return;
+        }
+        seenFolded.add(folded);
+        entries.push({ path: filePath, sha256, size, kind, executable, script });
+    });
+    if (failed)
+        return undefined;
+    const skillMd = entries.filter((e) => e.path === constants_1.SKILL_MD_FILENAME);
+    if (skillMd.length !== 1) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.FILE_SET_MISMATCH, path, `files must declare exactly one ${constants_1.SKILL_MD_FILENAME}`));
+        return undefined;
+    }
+    if (skillMd[0].kind !== 'skill_md') {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INCONSISTENT_VALUE, path, `${constants_1.SKILL_MD_FILENAME} must be declared with kind "skill_md"`));
+        return undefined;
+    }
+    return entries;
+}
+/** Validate a parsed `commandmate.skill.yaml` document. */
+function validateSkillManifest(input) {
+    const errors = [];
+    const obj = readObject(input, '', errors);
+    if (!obj)
+        return (0, errors_1.skillFail)(errors);
+    const schemaVersion = readSchemaVersion(obj, errors);
+    if (schemaVersion === undefined)
+        return (0, errors_1.skillFail)(errors);
+    checkUnknownFields(obj, MANIFEST_FIELDS, '', errors);
+    const idResult = validateSkillId(obj['id']);
+    if (!idResult.ok)
+        errors.push(...idResult.errors);
+    const name = readString(obj, 'name', '', errors, { maxLength: constants_1.SKILL_NAME_MAX_LENGTH });
+    const version = readString(obj, 'version', '', errors, { maxLength: 64 });
+    if (version !== undefined && !(0, semver_1.isValidSemVer)(version)) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.VERSION_INVALID, '/version', 'version must be SemVer 2.0 without a "v" prefix'));
+    }
+    const summary = readString(obj, 'summary', '', errors, { maxLength: constants_1.SKILL_SUMMARY_MAX_LENGTH });
+    const description = readString(obj, 'description', '', errors, {
+        maxLength: constants_1.SKILL_DESCRIPTION_MAX_LENGTH,
+    });
+    const capabilities = readStringList(obj, 'capabilities', '', errors, {
+        maxItems: constants_1.SKILL_BULLET_MAX_COUNT,
+        maxLength: constants_1.SKILL_BULLET_MAX_LENGTH,
+    });
+    const expectedOutcomes = readStringList(obj, 'expected_outcomes', '', errors, {
+        maxItems: constants_1.SKILL_BULLET_MAX_COUNT,
+        maxLength: constants_1.SKILL_BULLET_MAX_LENGTH,
+    });
+    const provider = readProvider(obj, '', errors);
+    const license = readString(obj, 'license', '', errors, {
+        maxLength: 64,
+        pattern: constants_1.SPDX_LICENSE_PATTERN,
+        patternName: 'spdx-license-id',
+    });
+    const homepage = readHttpsUrl(obj, 'homepage', '', errors, { optional: true });
+    const keywords = readStringList(obj, 'keywords', '', errors, {
+        maxItems: constants_1.SKILL_KEYWORDS_MAX_COUNT,
+        maxLength: constants_1.SKILL_KEYWORD_MAX_LENGTH,
+        optional: true,
+    });
+    const compatibility = readCompatibility(obj, '', errors);
+    const requirements = readRequirements(obj, '', errors);
+    const declaredPermissions = readStringList(obj, 'declared_permissions', '', errors, {
+        maxItems: constants_1.SKILL_DECLARED_PERMISSIONS.length,
+        maxLength: 40,
+    });
+    if (declaredPermissions) {
+        for (const [index, permission] of declaredPermissions.entries()) {
+            if (!constants_1.SKILL_DECLARED_PERMISSIONS.includes(permission)) {
+                errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INVALID_ENUM, (0, errors_1.joinPath)('/declared_permissions', index), 'declared permission is not an allowed value'));
+            }
+        }
+    }
+    const declaredRisk = readEnum(obj, 'declared_risk', '', errors, constants_1.SKILL_RISK_LEVELS);
+    const riskRationale = readString(obj, 'risk_rationale', '', errors, {
+        maxLength: constants_1.SKILL_RATIONALE_MAX_LENGTH,
+    });
+    const files = readFileEntries(obj, '', errors);
+    // Capabilities and expected outcomes are what the install dialog shows (UX-01),
+    // so an empty list is a contract violation rather than an acceptable default.
+    if (capabilities && capabilities.length === 0) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, '/capabilities', 'capabilities must not be empty'));
+    }
+    if (expectedOutcomes && expectedOutcomes.length === 0) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, '/expected_outcomes', 'expected_outcomes must not be empty'));
+    }
+    if (errors.length > 0 ||
+        !idResult.ok ||
+        name === undefined ||
+        version === undefined ||
+        summary === undefined ||
+        description === undefined ||
+        capabilities === undefined ||
+        expectedOutcomes === undefined ||
+        provider === undefined ||
+        license === undefined ||
+        compatibility === undefined ||
+        requirements === undefined ||
+        declaredPermissions === undefined ||
+        declaredRisk === undefined ||
+        riskRationale === undefined ||
+        files === undefined) {
+        return (0, errors_1.skillFail)(errors.length > 0
+            ? errors
+            : [(0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, '', 'manifest is incomplete')]);
+    }
+    return (0, errors_1.skillOk)({
+        schema_version: schemaVersion,
+        id: idResult.value,
+        name,
+        version,
+        summary,
+        description,
+        capabilities,
+        expected_outcomes: expectedOutcomes,
+        provider,
+        license,
+        ...(homepage !== undefined ? { homepage } : {}),
+        ...(keywords !== undefined ? { keywords } : {}),
+        compatibility,
+        requirements,
+        declared_permissions: declaredPermissions,
+        declared_risk: declaredRisk,
+        risk_rationale: riskRationale,
+        files,
+    });
+}
+// =============================================================================
+// Catalog
+// =============================================================================
+function readCatalogVersion(raw, path, skillId, errors) {
+    const obj = readObject(raw, path, errors);
+    if (!obj)
+        return undefined;
+    checkUnknownFields(obj, CATALOG_VERSION_FIELDS, path, errors);
+    const version = readString(obj, 'version', path, errors, { maxLength: 64 });
+    if (version !== undefined && !(0, semver_1.isValidSemVer)(version)) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.VERSION_INVALID, (0, errors_1.joinPath)(path, 'version'), 'version must be SemVer 2.0'));
+        return undefined;
+    }
+    const changelog = readString(obj, 'changelog', path, errors, { maxLength: constants_1.SKILL_CHANGELOG_MAX_LENGTH });
+    const publishedAt = readString(obj, 'published_at', path, errors, {
+        maxLength: 30,
+        pattern: constants_1.RFC3339_UTC_PATTERN,
+        patternName: 'rfc3339-utc',
+    });
+    const source = readSource(obj, path, errors);
+    const artifact = readArtifact(obj, path, errors);
+    const compatibility = readCompatibility(obj, path, errors);
+    const declaredRisk = readEnum(obj, 'declared_risk', path, errors, constants_1.SKILL_RISK_LEVELS);
+    if (version === undefined ||
+        changelog === undefined ||
+        publishedAt === undefined ||
+        source === undefined ||
+        artifact === undefined ||
+        compatibility === undefined ||
+        declaredRisk === undefined) {
+        return undefined;
+    }
+    const expectedAsset = (0, constants_1.buildSkillAssetName)(skillId, version);
+    if (artifact.asset_name !== expectedAsset) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.ARTIFACT_INVALID, (0, errors_1.joinPath)((0, errors_1.joinPath)(path, 'artifact'), 'asset_name'), 'asset_name must follow the <skill-id>-<version>.tar.gz convention', { expected: expectedAsset }));
+        return undefined;
+    }
+    return {
+        version,
+        changelog,
+        published_at: publishedAt,
+        source,
+        artifact,
+        compatibility,
+        declared_risk: declaredRisk,
+    };
+}
+function readCatalogEntry(raw, path, errors) {
+    const obj = readObject(raw, path, errors);
+    if (!obj)
+        return undefined;
+    checkUnknownFields(obj, CATALOG_ENTRY_FIELDS, path, errors);
+    const idResult = validateSkillId(obj['id'], (0, errors_1.joinPath)(path, 'id'));
+    if (!idResult.ok) {
+        errors.push(...idResult.errors);
+        return undefined;
+    }
+    const id = idResult.value;
+    const name = readString(obj, 'name', path, errors, { maxLength: constants_1.SKILL_NAME_MAX_LENGTH });
+    const summary = readString(obj, 'summary', path, errors, { maxLength: constants_1.SKILL_SUMMARY_MAX_LENGTH });
+    const provider = readProvider(obj, path, errors);
+    const license = readString(obj, 'license', path, errors, {
+        maxLength: 64,
+        pattern: constants_1.SPDX_LICENSE_PATTERN,
+        patternName: 'spdx-license-id',
+    });
+    const homepage = readHttpsUrl(obj, 'homepage', path, errors, { optional: true });
+    const keywords = readStringList(obj, 'keywords', path, errors, {
+        maxItems: constants_1.SKILL_KEYWORDS_MAX_COUNT,
+        maxLength: constants_1.SKILL_KEYWORD_MAX_LENGTH,
+        optional: true,
+    });
+    const latest = readString(obj, 'latest', path, errors, { maxLength: 64 });
+    const rawVersions = readArray(obj, 'versions', path, errors, {
+        maxItems: constants_1.SKILL_CATALOG_VERSIONS_MAX_COUNT,
+    });
+    if (name === undefined ||
+        summary === undefined ||
+        provider === undefined ||
+        license === undefined ||
+        latest === undefined ||
+        rawVersions === undefined) {
+        return undefined;
+    }
+    if (rawVersions.length === 0) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, (0, errors_1.joinPath)(path, 'versions'), 'versions must not be empty'));
+        return undefined;
+    }
+    const versions = [];
+    const seenVersions = new Set();
+    let failed = false;
+    rawVersions.forEach((item, index) => {
+        const itemPath = (0, errors_1.joinPath)((0, errors_1.joinPath)(path, 'versions'), index);
+        const parsed = readCatalogVersion(item, itemPath, id, errors);
+        if (!parsed) {
+            failed = true;
+            return;
+        }
+        if (seenVersions.has(parsed.version)) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.DUPLICATE_ENTRY, itemPath, 'version is listed more than once'));
+            failed = true;
+            return;
+        }
+        seenVersions.add(parsed.version);
+        versions.push(parsed);
+    });
+    if (failed)
+        return undefined;
+    if (!seenVersions.has(latest)) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.CATALOG_LATEST_UNRESOLVED, (0, errors_1.joinPath)(path, 'latest'), 'latest must reference a listed version'));
+        return undefined;
+    }
+    return {
+        id,
+        name,
+        summary,
+        provider,
+        license,
+        ...(homepage !== undefined ? { homepage } : {}),
+        ...(keywords !== undefined ? { keywords } : {}),
+        latest,
+        versions,
+    };
+}
+/** Validate a parsed Catalog document. */
+function validateSkillCatalog(input) {
+    const errors = [];
+    const obj = readObject(input, '', errors);
+    if (!obj)
+        return (0, errors_1.skillFail)(errors);
+    const schemaVersion = readSchemaVersion(obj, errors);
+    if (schemaVersion === undefined)
+        return (0, errors_1.skillFail)(errors);
+    checkUnknownFields(obj, CATALOG_FIELDS, '', errors);
+    const rawEntries = readArray(obj, 'entries', '', errors, {
+        maxItems: constants_1.SKILL_CATALOG_ENTRIES_MAX_COUNT,
+    });
+    if (rawEntries === undefined)
+        return (0, errors_1.skillFail)(errors);
+    const entries = [];
+    const seenIds = new Set();
+    rawEntries.forEach((item, index) => {
+        const itemPath = (0, errors_1.joinPath)('/entries', index);
+        const parsed = readCatalogEntry(item, itemPath, errors);
+        if (!parsed)
+            return;
+        const folded = foldSkillIdForCollision(parsed.id);
+        if (seenIds.has(folded)) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.ID_COLLISION, itemPath, 'entry id collides with another entry'));
+            return;
+        }
+        seenIds.add(folded);
+        entries.push(parsed);
+    });
+    if (errors.length > 0)
+        return (0, errors_1.skillFail)(errors);
+    return (0, errors_1.skillOk)({ schema_version: schemaVersion, entries });
+}
+// =============================================================================
+// Receipt
+// =============================================================================
+function readReceiptArtifact(parentObj, parent, errors) {
+    const path = (0, errors_1.joinPath)(parent, 'artifact');
+    const raw = parentObj['artifact'];
+    if (raw === undefined) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, path, 'artifact is required'));
+        return undefined;
+    }
+    const obj = readObject(raw, path, errors);
+    if (!obj)
+        return undefined;
+    checkUnknownFields(obj, RECEIPT_ARTIFACT_FIELDS, path, errors);
+    const assetName = readString(obj, 'asset_name', path, errors, { maxLength: 200 });
+    const sha256 = readString(obj, 'sha256', path, errors, {
+        minLength: 64,
+        maxLength: 64,
+        pattern: constants_1.SHA256_HEX_PATTERN,
+        patternName: 'sha256-lowercase-hex',
+        formatCode: errors_1.SkillContractErrorCode.DIGEST_INVALID,
+    });
+    const size = readInteger(obj, 'size', path, errors, { min: 1, max: constants_1.SKILL_ARTIFACT_MAX_SIZE });
+    const format = readEnum(obj, 'format', path, errors, [constants_1.SKILL_ARTIFACT_FORMAT]);
+    if (assetName === undefined || sha256 === undefined || size === undefined || format === undefined) {
+        return undefined;
+    }
+    return { asset_name: assetName, sha256, size, format };
+}
+function readInstalledFiles(parentObj, parent, errors) {
+    const path = (0, errors_1.joinPath)(parent, 'files');
+    const raw = readArray(parentObj, 'files', parent, errors, { maxItems: constants_1.SKILL_FILES_MAX_COUNT });
+    if (raw === undefined)
+        return undefined;
+    const files = [];
+    let failed = false;
+    raw.forEach((item, index) => {
+        const itemPath = (0, errors_1.joinPath)(path, index);
+        const obj = readObject(item, itemPath, errors);
+        if (!obj) {
+            failed = true;
+            return;
+        }
+        checkUnknownFields(obj, INSTALLED_FILE_FIELDS, itemPath, errors);
+        const pathResult = validateSkillPayloadPath(obj['path'], (0, errors_1.joinPath)(itemPath, 'path'));
+        const sha256 = readString(obj, 'sha256', itemPath, errors, {
+            minLength: 64,
+            maxLength: 64,
+            pattern: constants_1.SHA256_HEX_PATTERN,
+            patternName: 'sha256-lowercase-hex',
+            formatCode: errors_1.SkillContractErrorCode.DIGEST_INVALID,
+        });
+        const size = readInteger(obj, 'size', itemPath, errors, { min: 0, max: constants_1.SKILL_FILE_MAX_SIZE });
+        const executable = readBoolean(obj, 'executable', itemPath, errors);
+        if (!pathResult.ok) {
+            errors.push(...pathResult.errors);
+            failed = true;
+            return;
+        }
+        if (sha256 === undefined || size === undefined || executable === undefined) {
+            failed = true;
+            return;
+        }
+        files.push({ path: pathResult.value, sha256, size, executable });
+    });
+    if (failed)
+        return undefined;
+    // Receipts must be byte-reproducible, so the file list has one canonical order.
+    for (let i = 1; i < files.length; i++) {
+        if (files[i - 1].path >= files[i].path) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INCONSISTENT_VALUE, path, 'files must be sorted by path in ascending order without duplicates'));
+            return undefined;
+        }
+    }
+    return files;
+}
+/** Validate a parsed install receipt. */
+function validateSkillInstallReceipt(input) {
+    const errors = [];
+    const obj = readObject(input, '', errors);
+    if (!obj)
+        return (0, errors_1.skillFail)(errors);
+    const schemaVersion = readSchemaVersion(obj, errors);
+    if (schemaVersion === undefined)
+        return (0, errors_1.skillFail)(errors);
+    checkUnknownFields(obj, RECEIPT_FIELDS, '', errors);
+    const idResult = validateSkillId(obj['skill_id'], '/skill_id');
+    if (!idResult.ok)
+        errors.push(...idResult.errors);
+    const version = readString(obj, 'version', '', errors, { maxLength: 64 });
+    if (version !== undefined && !(0, semver_1.isValidSemVer)(version)) {
+        errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.VERSION_INVALID, '/version', 'version must be SemVer 2.0'));
+    }
+    const installRoot = readString(obj, 'install_root', '', errors, { maxLength: 200 });
+    // Optional (#1460): absent means a single-root install rooted at install_root.
+    const installRootsPresent = obj['install_roots'] !== undefined;
+    const installRoots = installRootsPresent
+        ? readStringList(obj, 'install_roots', '', errors, {
+            maxItems: constants_1.SKILL_INSTALL_ROOT_PREFIXES.length,
+            maxLength: 200,
+        })
+        : undefined;
+    const source = readSource(obj, '', errors);
+    const artifact = readReceiptArtifact(obj, '', errors);
+    const files = readInstalledFiles(obj, '', errors);
+    const declaredRisk = readEnum(obj, 'declared_risk', '', errors, constants_1.SKILL_RISK_LEVELS);
+    const computedRisk = readEnum(obj, 'computed_risk', '', errors, constants_1.SKILL_RISK_LEVELS);
+    const effectiveRisk = readEnum(obj, 'effective_risk', '', errors, constants_1.SKILL_RISK_LEVELS);
+    const declaredPermissions = readStringList(obj, 'declared_permissions', '', errors, {
+        maxItems: constants_1.SKILL_DECLARED_PERMISSIONS.length,
+        maxLength: 40,
+    });
+    if (declaredPermissions) {
+        for (const [index, permission] of declaredPermissions.entries()) {
+            if (!constants_1.SKILL_DECLARED_PERMISSIONS.includes(permission)) {
+                errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INVALID_ENUM, (0, errors_1.joinPath)('/declared_permissions', index), 'declared permission is not an allowed value'));
+            }
+        }
+    }
+    const rawAgents = readArray(obj, 'agent_compatibility', '', errors, { maxItems: 20 });
+    const agentCompatibility = [];
+    if (rawAgents) {
+        rawAgents.forEach((item, index) => {
+            const parsed = readAgentCompatibility(item, (0, errors_1.joinPath)('/agent_compatibility', index), errors);
+            if (parsed)
+                agentCompatibility.push(parsed);
+        });
+    }
+    if (idResult.ok && installRoot !== undefined) {
+        const expectedRoot = `${constants_1.SKILL_INSTALL_ROOT_PREFIX}/${idResult.value}`;
+        if (installRoot !== expectedRoot) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INCONSISTENT_VALUE, '/install_root', 'install_root must be the repository-relative skill root', { expected: expectedRoot }));
+        }
+    }
+    // Multi-root receipt (#1460): if present, install_roots must be the ordered set
+    // of known-prefix roots for this skill, primary first and equal to install_root.
+    if (idResult.ok && installRoot !== undefined && installRoots !== undefined) {
+        const allowed = constants_1.SKILL_INSTALL_ROOT_PREFIXES.map((prefix) => `${prefix}/${idResult.value}`);
+        if (installRoots.length === 0) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INCONSISTENT_VALUE, '/install_roots', 'install_roots must not be empty'));
+        }
+        else if (installRoots[0] !== installRoot) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INCONSISTENT_VALUE, '/install_roots/0', 'install_roots[0] must equal install_root (the primary root)', { expected: installRoot }));
+        }
+        const seen = new Set();
+        installRoots.forEach((root, index) => {
+            if (!allowed.includes(root)) {
+                errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INCONSISTENT_VALUE, `/install_roots/${index}`, 'install_roots entry must be a known repository-relative skill root'));
+            }
+            if (seen.has(root)) {
+                errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INCONSISTENT_VALUE, `/install_roots/${index}`, 'install_roots must not repeat a root'));
+            }
+            seen.add(root);
+        });
+    }
+    if (idResult.ok && version !== undefined && artifact !== undefined) {
+        const expectedAsset = (0, constants_1.buildSkillAssetName)(idResult.value, version);
+        if (artifact.asset_name !== expectedAsset) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.ARTIFACT_INVALID, '/artifact/asset_name', 'asset_name must follow the <skill-id>-<version>.tar.gz convention', { expected: expectedAsset }));
+        }
+    }
+    if (declaredRisk !== undefined && computedRisk !== undefined && effectiveRisk !== undefined) {
+        const expected = resolveEffectiveSkillRisk(declaredRisk, computedRisk);
+        if (effectiveRisk !== expected) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.INCONSISTENT_VALUE, '/effective_risk', 'effective_risk must be the higher of declared_risk and computed_risk', { expected }));
+        }
+    }
+    if (errors.length > 0 ||
+        !idResult.ok ||
+        version === undefined ||
+        installRoot === undefined ||
+        source === undefined ||
+        artifact === undefined ||
+        files === undefined ||
+        declaredRisk === undefined ||
+        computedRisk === undefined ||
+        effectiveRisk === undefined ||
+        declaredPermissions === undefined ||
+        rawAgents === undefined) {
+        return (0, errors_1.skillFail)(errors.length > 0
+            ? errors
+            : [(0, errors_1.skillError)(errors_1.SkillContractErrorCode.MISSING_FIELD, '', 'receipt is incomplete')]);
+    }
+    return (0, errors_1.skillOk)({
+        schema_version: schemaVersion,
+        skill_id: idResult.value,
+        version,
+        install_root: installRoot,
+        ...(installRoots !== undefined ? { install_roots: installRoots } : {}),
+        source,
+        artifact,
+        files,
+        declared_risk: declaredRisk,
+        computed_risk: computedRisk,
+        effective_risk: effectiveRisk,
+        declared_permissions: declaredPermissions,
+        agent_compatibility: agentCompatibility,
+    });
+}
+// =============================================================================
+// Cross-document rules
+// =============================================================================
+/**
+ * Compare the manifest's declared file set with the package's payload set.
+ *
+ * The comparison set is every regular payload file in the archive minus the
+ * manifest itself and minus directory entries; the manifest's own integrity is
+ * covered by the Catalog artifact digest, so it declares no self-digest.
+ */
+function validateManifestFileSet(manifest, payloadPaths) {
+    const declared = new Set(manifest.files.map((f) => f.path));
+    const actual = new Set(payloadPaths.filter((p) => p !== constants_1.SKILL_MANIFEST_FILENAME));
+    const errors = [];
+    for (const path of declared) {
+        if (!actual.has(path)) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.FILE_SET_MISMATCH, '/files', 'declared file is absent from the package', {
+                path,
+            }));
+        }
+    }
+    for (const path of actual) {
+        if (!declared.has(path)) {
+            errors.push((0, errors_1.skillError)(errors_1.SkillContractErrorCode.FILE_SET_MISMATCH, '/files', 'package contains an undeclared file', {
+                path,
+            }));
+        }
+    }
+    return errors.length > 0 ? (0, errors_1.skillFail)(errors) : (0, errors_1.skillOk)([...declared].sort());
+}
+/** Resolve the effective risk shown to the user: the higher of the two inputs. */
+function resolveEffectiveSkillRisk(declared, computed) {
+    return constants_1.SKILL_RISK_ORDER[computed] > constants_1.SKILL_RISK_ORDER[declared] ? computed : declared;
+}
+/**
+ * Derive the risk level CommandMate computes from inspection facts.
+ *
+ * Deterministic and independent of the publisher's own claim, so a package
+ * cannot talk its way down to `low`.
+ */
+function computeSkillRisk(inspection) {
+    if (inspection.executable_paths.length > 0 ||
+        inspection.declared_permissions.includes('credential_access')) {
+        return 'high';
+    }
+    if (inspection.script_paths.length > 0 ||
+        inspection.network_hosts.length > 0 ||
+        inspection.declared_permissions.includes('process_execution') ||
+        inspection.declared_permissions.includes('filesystem_write')) {
+        return 'moderate';
+    }
+    return 'low';
+}
+// =============================================================================
+// Canonicalization
+// =============================================================================
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            if (value[key] === undefined)
+                continue;
+            out[key] = canonicalize(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Serialize a receipt deterministically: keys sorted, no insignificant
+ * whitespace, no undefined members. Two installs of the same version from the
+ * same commit produce byte-identical output, which is what makes a receipt
+ * diffable and hashable.
+ */
+function canonicalizeSkillReceipt(receipt) {
+    return JSON.stringify(canonicalize(receipt));
+}