@synapsor/spec 0.1.0

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,4 @@
+import type { SynapsorContract, ValidationResult } from "./types.js";
+export declare function validateContract(input: unknown): ValidationResult;
+export declare function assertValidContract(input: unknown): asserts input is SynapsorContract;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAmB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA2DtF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAiCjE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,gBAAgB,CAGrF"}

package/dist/validate.js

@@ -0,0 +1,522 @@
+import { SPEC_VERSION } from "./version.js";
+import { SynapsorSpecValidationError } from "./errors.js";
+const TOP_LEVEL_KEYS = new Set([
+    "spec_version",
+    "kind",
+    "metadata",
+    "resources",
+    "contexts",
+    "capabilities",
+    "workflows",
+    "policies",
+    "evidence",
+    "proposals",
+    "receipts",
+    "replay",
+    "external_actions",
+]);
+const METADATA_KEYS = new Set(["name", "description", "version", "tags"]);
+const RESOURCE_KEYS = new Set(["name", "engine", "schema", "table", "type", "primary_key", "tenant_key", "conflict_key", "single_tenant_dev"]);
+const CONTEXT_KEYS = new Set(["name", "description", "bindings", "tenant_binding", "principal_binding"]);
+const BINDING_KEYS = new Set(["name", "source", "key", "required"]);
+const CAPABILITY_KEYS = new Set(["name", "description", "kind", "context", "source", "subject", "args", "lookup", "visible_fields", "kept_out_fields", "evidence", "max_rows", "proposal"]);
+const SUBJECT_KEYS = new Set(["resource", "schema", "table", "primary_key", "tenant_key", "conflict_key", "single_tenant_dev"]);
+const ARG_KEYS = new Set(["type", "description", "required", "max_length", "minimum", "maximum", "enum"]);
+const LOOKUP_KEYS = new Set(["id_from_arg"]);
+const EVIDENCE_KEYS = new Set(["required", "sources", "query_audit", "handle_prefix"]);
+const PROPOSAL_KEYS = new Set(["action", "allowed_fields", "patch", "conflict_guard", "approval", "writeback"]);
+const PATCH_KEYS = new Set(["fixed", "from_arg"]);
+const CONFLICT_GUARD_KEYS = new Set(["column", "weak_guard_ack"]);
+const APPROVAL_KEYS = new Set(["mode", "required_role"]);
+const WRITEBACK_KEYS = new Set(["mode", "executor", "idempotency_key"]);
+const WORKFLOW_KEYS = new Set(["name", "description", "context", "allowed_capabilities", "required_evidence", "approval", "settlement", "replay"]);
+const POLICY_KEYS = new Set(["name", "kind", "mode", "rules"]);
+const EVIDENCE_RECORD_KEYS = new Set(["handle", "capability", "query_fingerprint", "items"]);
+const PROPOSAL_RECORD_KEYS = new Set(["id", "capability", "subject", "status", "diff", "evidence_handle"]);
+const RECEIPT_KEYS = new Set(["id", "proposal_id", "status", "idempotency_key", "source_database_mutated", "rows_affected"]);
+const REPLAY_KEYS = new Set(["id", "proposal_id", "run_id", "events"]);
+const EXTERNAL_ACTION_KEYS = new Set(["id", "action", "handler", "idempotency_key", "receipt"]);
+const TRUSTED_ARG_NAMES = new Set([
+    "tenant_id",
+    "tenantId",
+    "principal",
+    "principal_id",
+    "principalId",
+    "schema",
+    "table",
+    "column",
+    "columns",
+    "database_url",
+    "write_url",
+    "read_url",
+    "expected_version",
+    "row_version",
+]);
+export function validateContract(input) {
+    const errors = [];
+    const warnings = [];
+    if (!isRecord(input)) {
+        return {
+            ok: false,
+            errors: [{ path: "$", code: "CONTRACT_NOT_OBJECT", message: "Contract must be a JSON object." }],
+            warnings,
+        };
+    }
+    checkUnknownKeys(input, TOP_LEVEL_KEYS, "$", errors);
+    if (input.spec_version !== SPEC_VERSION) {
+        errors.push({ path: "$.spec_version", code: "UNSUPPORTED_SPEC_VERSION", message: `spec_version must be ${SPEC_VERSION}.` });
+    }
+    if (input.kind !== "SynapsorContract") {
+        errors.push({ path: "$.kind", code: "INVALID_KIND", message: "kind must be SynapsorContract." });
+    }
+    validateMetadata(input.metadata, "$.metadata", errors);
+    const resourceNames = validateResources(input.resources, errors, warnings);
+    const contextNames = validateContexts(input.contexts, errors, warnings);
+    const capabilityNames = validateCapabilities(input.capabilities, contextNames, resourceNames, errors, warnings);
+    validateWorkflows(input.workflows, contextNames, capabilityNames, errors);
+    validatePolicies(input.policies, errors);
+    validateEvidenceRecords(input.evidence, errors);
+    validateProposalRecords(input.proposals, capabilityNames, errors);
+    validateReceiptRecords(input.receipts, errors);
+    validateReplay(input.replay, errors);
+    validateExternalActions(input.external_actions, errors);
+    scanForInlineSecrets(input, "$", errors);
+    return { ok: errors.length === 0, errors, warnings };
+}
+export function assertValidContract(input) {
+    const result = validateContract(input);
+    if (!result.ok)
+        throw new SynapsorSpecValidationError(result.errors);
+}
+function validateMetadata(value, path, errors) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value)) {
+        errors.push({ path, code: "METADATA_NOT_OBJECT", message: "metadata must be an object." });
+        return;
+    }
+    checkUnknownKeys(value, METADATA_KEYS, path, errors);
+    if (value.name !== undefined && !isNonEmptyString(value.name))
+        errors.push({ path: `${path}.name`, code: "INVALID_METADATA_NAME", message: "metadata.name must be a non-empty string." });
+    if (value.tags !== undefined && (!Array.isArray(value.tags) || value.tags.some((tag) => !isNonEmptyString(tag)))) {
+        errors.push({ path: `${path}.tags`, code: "INVALID_METADATA_TAGS", message: "metadata.tags must be an array of non-empty strings." });
+    }
+}
+function validateResources(value, errors, warnings) {
+    const names = new Set();
+    if (value === undefined)
+        return names;
+    if (!Array.isArray(value)) {
+        errors.push({ path: "$.resources", code: "RESOURCES_NOT_ARRAY", message: "resources must be an array." });
+        return names;
+    }
+    value.forEach((resource, index) => {
+        const path = `$.resources[${index}]`;
+        if (!isRecord(resource)) {
+            errors.push({ path, code: "RESOURCE_NOT_OBJECT", message: "resource must be an object." });
+            return;
+        }
+        checkUnknownKeys(resource, RESOURCE_KEYS, path, errors);
+        if (!isQualifiedOrSafeName(resource.name))
+            errors.push({ path: `${path}.name`, code: "INVALID_RESOURCE_NAME", message: "resource name must be a safe identifier or qualified name." });
+        else
+            addUnique(names, resource.name, `${path}.name`, "DUPLICATE_RESOURCE_NAME", errors);
+        if (!["postgres", "mysql", "synapsor"].includes(String(resource.engine)))
+            errors.push({ path: `${path}.engine`, code: "INVALID_RESOURCE_ENGINE", message: "engine must be postgres, mysql, or synapsor." });
+        for (const key of ["schema", "table", "primary_key"]) {
+            if (!isSafeIdentifier(resource[key]))
+                errors.push({ path: `${path}.${key}`, code: "INVALID_RESOURCE_IDENTIFIER", message: `${key} must be a fixed safe identifier.` });
+        }
+        if (resource.tenant_key !== undefined && !isSafeIdentifier(resource.tenant_key))
+            errors.push({ path: `${path}.tenant_key`, code: "INVALID_TENANT_KEY", message: "tenant_key must be a fixed safe identifier." });
+        if (!isSafeIdentifier(resource.tenant_key) && resource.single_tenant_dev !== true) {
+            errors.push({ path: `${path}.tenant_key`, code: "TENANT_KEY_REQUIRED", message: "tenant_key is required unless single_tenant_dev is explicitly true." });
+        }
+        if (resource.single_tenant_dev === true)
+            warnings.push({ path: `${path}.single_tenant_dev`, code: "SINGLE_TENANT_DEV", message: "single_tenant_dev is only for local demos and must not be used for shared tenant data." });
+        if (resource.conflict_key !== undefined && !isSafeIdentifier(resource.conflict_key))
+            errors.push({ path: `${path}.conflict_key`, code: "INVALID_CONFLICT_KEY", message: "conflict_key must be a fixed safe identifier." });
+    });
+    return names;
+}
+function validateContexts(value, errors, warnings) {
+    const names = new Set();
+    if (!Array.isArray(value) || value.length === 0) {
+        errors.push({ path: "$.contexts", code: "CONTEXTS_REQUIRED", message: "At least one context is required." });
+        return names;
+    }
+    value.forEach((context, index) => {
+        const path = `$.contexts[${index}]`;
+        if (!isRecord(context)) {
+            errors.push({ path, code: "CONTEXT_NOT_OBJECT", message: "context must be an object." });
+            return;
+        }
+        checkUnknownKeys(context, CONTEXT_KEYS, path, errors);
+        if (!isQualifiedOrSafeName(context.name))
+            errors.push({ path: `${path}.name`, code: "INVALID_CONTEXT_NAME", message: "context name must be a safe identifier or qualified name." });
+        else
+            addUnique(names, context.name, `${path}.name`, "DUPLICATE_CONTEXT_NAME", errors);
+        if (!Array.isArray(context.bindings) || context.bindings.length === 0) {
+            errors.push({ path: `${path}.bindings`, code: "BINDINGS_REQUIRED", message: "context.bindings must contain trusted/session bindings." });
+            return;
+        }
+        const bindingNames = new Set();
+        context.bindings.forEach((binding, bindingIndex) => {
+            const bindingPath = `${path}.bindings[${bindingIndex}]`;
+            if (!isRecord(binding)) {
+                errors.push({ path: bindingPath, code: "BINDING_NOT_OBJECT", message: "binding must be an object." });
+                return;
+            }
+            checkUnknownKeys(binding, BINDING_KEYS, bindingPath, errors);
+            if (!isSafeIdentifier(binding.name))
+                errors.push({ path: `${bindingPath}.name`, code: "INVALID_BINDING_NAME", message: "binding name must be a safe identifier." });
+            else
+                addUnique(bindingNames, binding.name, `${bindingPath}.name`, "DUPLICATE_BINDING_NAME", errors);
+            if (!["session", "environment", "cloud_session", "static_dev", "http_claim"].includes(String(binding.source)))
+                errors.push({ path: `${bindingPath}.source`, code: "INVALID_BINDING_SOURCE", message: "binding source must be session, environment, cloud_session, static_dev, or http_claim." });
+            if (!isNonEmptyString(binding.key))
+                errors.push({ path: `${bindingPath}.key`, code: "INVALID_BINDING_KEY", message: "binding key must be a non-empty string." });
+            if (binding.source === "static_dev")
+                warnings.push({ path: `${bindingPath}.source`, code: "STATIC_DEV_BINDING", message: "static_dev bindings are for local demos only." });
+        });
+        for (const key of ["tenant_binding", "principal_binding"]) {
+            if (context[key] !== undefined && (!isSafeIdentifier(context[key]) || !bindingNames.has(String(context[key])))) {
+                errors.push({ path: `${path}.${key}`, code: "UNKNOWN_CONTEXT_BINDING", message: `${key} must reference a binding name.` });
+            }
+        }
+    });
+    return names;
+}
+function validateCapabilities(value, contextNames, resourceNames, errors, warnings) {
+    const names = new Set();
+    if (!Array.isArray(value) || value.length === 0) {
+        errors.push({ path: "$.capabilities", code: "CAPABILITIES_REQUIRED", message: "At least one capability is required." });
+        return names;
+    }
+    value.forEach((capability, index) => {
+        const path = `$.capabilities[${index}]`;
+        if (!isRecord(capability)) {
+            errors.push({ path, code: "CAPABILITY_NOT_OBJECT", message: "capability must be an object." });
+            return;
+        }
+        checkUnknownKeys(capability, CAPABILITY_KEYS, path, errors);
+        if (!isQualifiedName(capability.name))
+            errors.push({ path: `${path}.name`, code: "INVALID_CAPABILITY_NAME", message: "capability name must be namespace.name." });
+        else
+            addUnique(names, capability.name, `${path}.name`, "DUPLICATE_CAPABILITY_NAME", errors);
+        if (!["read", "proposal", "external_action", "answer_with_evidence"].includes(String(capability.kind)))
+            errors.push({ path: `${path}.kind`, code: "INVALID_CAPABILITY_KIND", message: "kind must be read, proposal, external_action, or answer_with_evidence." });
+        if (!isNonEmptyString(capability.context) || !contextNames.has(capability.context))
+            errors.push({ path: `${path}.context`, code: "UNKNOWN_CONTEXT", message: "capability.context must reference a declared context." });
+        validateSubject(capability.subject, `${path}.subject`, resourceNames, errors, warnings);
+        validateArgs(capability.args, `${path}.args`, errors);
+        if (capability.lookup !== undefined)
+            validateLookup(capability.lookup, `${path}.lookup`, capability.args, errors);
+        validateFieldList(capability.visible_fields, `${path}.visible_fields`, "VISIBLE_FIELDS_REQUIRED", errors);
+        if (capability.kept_out_fields !== undefined)
+            validateFieldList(capability.kept_out_fields, `${path}.kept_out_fields`, "INVALID_KEPT_OUT_FIELDS", errors, true);
+        validateKeptOutExclusion(capability.visible_fields, capability.kept_out_fields, path, errors);
+        if (capability.evidence !== undefined)
+            validateEvidenceRequirement(capability.evidence, `${path}.evidence`, errors);
+        if (capability.max_rows !== undefined && !isPositiveInteger(capability.max_rows))
+            errors.push({ path: `${path}.max_rows`, code: "INVALID_MAX_ROWS", message: "max_rows must be a positive integer." });
+        if (capability.kind === "proposal")
+            validateProposalAction(capability.proposal, `${path}.proposal`, errors);
+        if (capability.kind !== "proposal" && capability.proposal !== undefined)
+            errors.push({ path: `${path}.proposal`, code: "PROPOSAL_ONLY_FOR_PROPOSAL_KIND", message: "proposal is only valid for proposal capabilities." });
+    });
+    return names;
+}
+function validateSubject(value, path, resourceNames, errors, warnings) {
+    if (!isRecord(value)) {
+        errors.push({ path, code: "SUBJECT_REQUIRED", message: "subject must be an object." });
+        return;
+    }
+    checkUnknownKeys(value, SUBJECT_KEYS, path, errors);
+    if (value.resource !== undefined && (!isQualifiedOrSafeName(value.resource) || (resourceNames.size > 0 && !resourceNames.has(String(value.resource))))) {
+        errors.push({ path: `${path}.resource`, code: "UNKNOWN_RESOURCE", message: "subject.resource must reference a declared resource." });
+    }
+    if (value.resource === undefined) {
+        for (const key of ["schema", "table", "primary_key"]) {
+            if (!isSafeIdentifier(value[key]))
+                errors.push({ path: `${path}.${key}`, code: "INVALID_SUBJECT_IDENTIFIER", message: `${key} must be provided as a fixed safe identifier when resource is omitted.` });
+        }
+        if (!isSafeIdentifier(value.tenant_key) && value.single_tenant_dev !== true) {
+            errors.push({ path: `${path}.tenant_key`, code: "TENANT_KEY_REQUIRED", message: "tenant_key is required unless single_tenant_dev is explicitly true." });
+        }
+    }
+    if (value.single_tenant_dev === true)
+        warnings.push({ path: `${path}.single_tenant_dev`, code: "SINGLE_TENANT_DEV", message: "single_tenant_dev is only for local demos and must not be used for shared tenant data." });
+}
+function validateArgs(value, path, errors) {
+    if (!isRecord(value) || Object.keys(value).length === 0) {
+        errors.push({ path, code: "ARGS_REQUIRED", message: "args must define at least one model-facing business argument." });
+        return;
+    }
+    for (const [name, arg] of Object.entries(value)) {
+        const argPath = `${path}.${name}`;
+        if (!isSafeIdentifier(name))
+            errors.push({ path: argPath, code: "INVALID_ARG_NAME", message: "arg names must be safe identifiers." });
+        if (TRUSTED_ARG_NAMES.has(name))
+            errors.push({ path: argPath, code: "MODEL_CONTROLLED_TRUST_ARG", message: "model-facing args cannot include trust scope, dynamic identifiers, or version authority." });
+        if (!isRecord(arg)) {
+            errors.push({ path: argPath, code: "ARG_NOT_OBJECT", message: "arg definition must be an object." });
+            continue;
+        }
+        checkUnknownKeys(arg, ARG_KEYS, argPath, errors);
+        if (!["string", "number", "boolean"].includes(String(arg.type)))
+            errors.push({ path: `${argPath}.type`, code: "INVALID_ARG_TYPE", message: "arg type must be string, number, or boolean." });
+    }
+}
+function validateLookup(value, path, args, errors) {
+    if (!isRecord(value)) {
+        errors.push({ path, code: "LOOKUP_NOT_OBJECT", message: "lookup must be an object." });
+        return;
+    }
+    checkUnknownKeys(value, LOOKUP_KEYS, path, errors);
+    if (!isSafeIdentifier(value.id_from_arg) || !isRecord(args) || !Object.prototype.hasOwnProperty.call(args, String(value.id_from_arg))) {
+        errors.push({ path: `${path}.id_from_arg`, code: "UNKNOWN_LOOKUP_ARG", message: "lookup.id_from_arg must reference a model-facing arg." });
+    }
+}
+function validateEvidenceRequirement(value, path, errors) {
+    if (!isRecord(value)) {
+        errors.push({ path, code: "EVIDENCE_NOT_OBJECT", message: "evidence must be an object." });
+        return;
+    }
+    checkUnknownKeys(value, EVIDENCE_KEYS, path, errors);
+    if (typeof value.required !== "boolean")
+        errors.push({ path: `${path}.required`, code: "INVALID_EVIDENCE_REQUIRED", message: "evidence.required must be boolean." });
+    if (value.sources !== undefined && (!Array.isArray(value.sources) || value.sources.some((source) => !isNonEmptyString(source))))
+        errors.push({ path: `${path}.sources`, code: "INVALID_EVIDENCE_SOURCES", message: "evidence.sources must be non-empty strings." });
+}
+function validateProposalAction(value, path, errors) {
+    if (!isRecord(value)) {
+        errors.push({ path, code: "PROPOSAL_REQUIRED", message: "proposal capabilities must define proposal action semantics." });
+        return;
+    }
+    checkUnknownKeys(value, PROPOSAL_KEYS, path, errors);
+    if (!isQualifiedOrSafeName(value.action))
+        errors.push({ path: `${path}.action`, code: "INVALID_PROPOSAL_ACTION", message: "proposal.action must be a safe action name." });
+    validateFieldList(value.allowed_fields, `${path}.allowed_fields`, "ALLOWED_FIELDS_REQUIRED", errors);
+    if (!isRecord(value.patch) || Object.keys(value.patch).length === 0) {
+        errors.push({ path: `${path}.patch`, code: "PATCH_REQUIRED", message: "proposal.patch must map allowed fields to fixed or arg values." });
+    }
+    else {
+        for (const [field, patch] of Object.entries(value.patch)) {
+            const patchPath = `${path}.patch.${field}`;
+            if (!isSafeIdentifier(field))
+                errors.push({ path: patchPath, code: "INVALID_PATCH_FIELD", message: "patch field must be a safe identifier." });
+            if (Array.isArray(value.allowed_fields) && !value.allowed_fields.includes(field))
+                errors.push({ path: patchPath, code: "PATCH_FIELD_NOT_ALLOWED", message: "patch field must be listed in allowed_fields." });
+            if (!isRecord(patch)) {
+                errors.push({ path: patchPath, code: "PATCH_BINDING_NOT_OBJECT", message: "patch binding must be an object." });
+                continue;
+            }
+            checkUnknownKeys(patch, PATCH_KEYS, patchPath, errors);
+            if (patch.fixed === undefined && !isSafeIdentifier(patch.from_arg))
+                errors.push({ path: patchPath, code: "PATCH_BINDING_REQUIRED", message: "patch binding must include fixed or from_arg." });
+        }
+    }
+    if (value.conflict_guard !== undefined) {
+        if (!isRecord(value.conflict_guard))
+            errors.push({ path: `${path}.conflict_guard`, code: "CONFLICT_GUARD_NOT_OBJECT", message: "conflict_guard must be an object." });
+        else {
+            checkUnknownKeys(value.conflict_guard, CONFLICT_GUARD_KEYS, `${path}.conflict_guard`, errors);
+            if (value.conflict_guard.column !== undefined && !isSafeIdentifier(value.conflict_guard.column))
+                errors.push({ path: `${path}.conflict_guard.column`, code: "INVALID_CONFLICT_COLUMN", message: "conflict_guard.column must be a safe identifier." });
+            if (value.conflict_guard.column === undefined && value.conflict_guard.weak_guard_ack !== true)
+                errors.push({ path: `${path}.conflict_guard`, code: "CONFLICT_GUARD_REQUIRED", message: "proposal needs conflict_guard.column unless weak_guard_ack is explicit." });
+        }
+    }
+    if (value.approval !== undefined)
+        validateNestedObject(value.approval, APPROVAL_KEYS, `${path}.approval`, errors);
+    if (value.writeback !== undefined) {
+        validateNestedObject(value.writeback, WRITEBACK_KEYS, `${path}.writeback`, errors);
+        if (isRecord(value.writeback) && !["direct_sql", "app_handler", "cloud_worker", "none"].includes(String(value.writeback.mode)))
+            errors.push({ path: `${path}.writeback.mode`, code: "INVALID_WRITEBACK_MODE", message: "writeback.mode must be direct_sql, app_handler, cloud_worker, or none." });
+    }
+}
+function validateWorkflows(value, contextNames, capabilityNames, errors) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value)) {
+        errors.push({ path: "$.workflows", code: "WORKFLOWS_NOT_ARRAY", message: "workflows must be an array." });
+        return;
+    }
+    const names = new Set();
+    value.forEach((workflow, index) => {
+        const path = `$.workflows[${index}]`;
+        if (!isRecord(workflow)) {
+            errors.push({ path, code: "WORKFLOW_NOT_OBJECT", message: "workflow must be an object." });
+            return;
+        }
+        checkUnknownKeys(workflow, WORKFLOW_KEYS, path, errors);
+        if (!isQualifiedName(workflow.name))
+            errors.push({ path: `${path}.name`, code: "INVALID_WORKFLOW_NAME", message: "workflow name must be namespace.name." });
+        else
+            addUnique(names, workflow.name, `${path}.name`, "DUPLICATE_WORKFLOW_NAME", errors);
+        if (!isNonEmptyString(workflow.context) || !contextNames.has(workflow.context))
+            errors.push({ path: `${path}.context`, code: "UNKNOWN_CONTEXT", message: "workflow.context must reference a declared context." });
+        if (!Array.isArray(workflow.allowed_capabilities) || workflow.allowed_capabilities.length === 0) {
+            errors.push({ path: `${path}.allowed_capabilities`, code: "WORKFLOW_CAPABILITIES_REQUIRED", message: "workflow.allowed_capabilities must list allowed capabilities." });
+        }
+        else {
+            workflow.allowed_capabilities.forEach((name, allowedIndex) => {
+                if (!isNonEmptyString(name) || !capabilityNames.has(name))
+                    errors.push({ path: `${path}.allowed_capabilities[${allowedIndex}]`, code: "UNKNOWN_CAPABILITY", message: "workflow allowed capability must reference a declared capability." });
+            });
+        }
+    });
+}
+function validatePolicies(value, errors) {
+    if (value === undefined)
+        return;
+    validateArrayRecords(value, "$.policies", POLICY_KEYS, "POLICY", errors);
+}
+function validateEvidenceRecords(value, errors) {
+    if (value === undefined)
+        return;
+    validateArrayRecords(value, "$.evidence", EVIDENCE_RECORD_KEYS, "EVIDENCE", errors);
+}
+function validateProposalRecords(value, capabilityNames, errors) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value)) {
+        errors.push({ path: "$.proposals", code: "PROPOSALS_NOT_ARRAY", message: "proposals must be an array." });
+        return;
+    }
+    value.forEach((proposal, index) => {
+        const path = `$.proposals[${index}]`;
+        if (!isRecord(proposal)) {
+            errors.push({ path, code: "PROPOSAL_NOT_OBJECT", message: "proposal must be an object." });
+            return;
+        }
+        checkUnknownKeys(proposal, PROPOSAL_RECORD_KEYS, path, errors);
+        if (!isNonEmptyString(proposal.id))
+            errors.push({ path: `${path}.id`, code: "INVALID_PROPOSAL_ID", message: "proposal.id must be non-empty." });
+        if (!isNonEmptyString(proposal.capability) || (capabilityNames.size > 0 && !capabilityNames.has(String(proposal.capability))))
+            errors.push({ path: `${path}.capability`, code: "UNKNOWN_CAPABILITY", message: "proposal.capability must reference a declared capability." });
+    });
+}
+function validateReceiptRecords(value, errors) {
+    if (value === undefined)
+        return;
+    validateArrayRecords(value, "$.receipts", RECEIPT_KEYS, "RECEIPT", errors);
+}
+function validateReplay(value, errors) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value)) {
+        errors.push({ path: "$.replay", code: "REPLAY_NOT_ARRAY", message: "replay must be an array." });
+        return;
+    }
+    value.forEach((record, index) => {
+        const path = `$.replay[${index}]`;
+        if (!isRecord(record)) {
+            errors.push({ path, code: "REPLAY_RECORD_NOT_OBJECT", message: "replay record must be an object." });
+            return;
+        }
+        checkUnknownKeys(record, REPLAY_KEYS, path, errors);
+        if (!isNonEmptyString(record.id))
+            errors.push({ path: `${path}.id`, code: "INVALID_REPLAY_ID", message: "replay id must be non-empty." });
+        if (!Array.isArray(record.events))
+            errors.push({ path: `${path}.events`, code: "REPLAY_EVENTS_REQUIRED", message: "replay.events must be an array." });
+    });
+}
+function validateExternalActions(value, errors) {
+    if (value === undefined)
+        return;
+    validateArrayRecords(value, "$.external_actions", EXTERNAL_ACTION_KEYS, "EXTERNAL_ACTION", errors);
+}
+function validateArrayRecords(value, path, keys, label, errors) {
+    if (!Array.isArray(value)) {
+        errors.push({ path, code: `${label}_NOT_ARRAY`, message: `${path} must be an array.` });
+        return;
+    }
+    value.forEach((record, index) => {
+        const itemPath = `${path}[${index}]`;
+        if (!isRecord(record)) {
+            errors.push({ path: itemPath, code: `${label}_NOT_OBJECT`, message: `${label.toLowerCase()} entry must be an object.` });
+            return;
+        }
+        checkUnknownKeys(record, keys, itemPath, errors);
+    });
+}
+function validateFieldList(value, path, code, errors, allowEmpty = false) {
+    if (!Array.isArray(value) || (!allowEmpty && value.length === 0)) {
+        errors.push({ path, code, message: "field list must be a non-empty array of safe identifiers." });
+        return;
+    }
+    const seen = new Set();
+    value.forEach((field, index) => {
+        if (!isSafeIdentifier(field))
+            errors.push({ path: `${path}[${index}]`, code: "INVALID_FIELD_IDENTIFIER", message: "field names must be fixed safe identifiers." });
+        else
+            addUnique(seen, field, `${path}[${index}]`, "DUPLICATE_FIELD", errors);
+    });
+}
+function validateKeptOutExclusion(visible, keptOut, path, errors) {
+    if (!Array.isArray(visible) || !Array.isArray(keptOut))
+        return;
+    const visibleSet = new Set(visible);
+    for (const field of keptOut) {
+        if (visibleSet.has(field))
+            errors.push({ path: `${path}.kept_out_fields`, code: "KEPT_OUT_FIELD_VISIBLE", message: `kept-out field must not also be visible: ${String(field)}` });
+    }
+}
+function validateNestedObject(value, keys, path, errors) {
+    if (!isRecord(value)) {
+        errors.push({ path, code: "NESTED_VALUE_NOT_OBJECT", message: "nested value must be an object." });
+        return;
+    }
+    checkUnknownKeys(value, keys, path, errors);
+}
+function scanForInlineSecrets(value, path, errors) {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => scanForInlineSecrets(item, `${path}[${index}]`, errors));
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        const childPath = `${path}.${key}`;
+        if (/database_url|read_url|write_url|connection_string|password|secret|token/i.test(key) && typeof child === "string" && /(postgres(?:ql)?:\/\/|mysql:\/\/|Bearer\s+|[A-Za-z0-9+/=]{24,})/i.test(child)) {
+            errors.push({ path: childPath, code: "INLINE_SECRET_OR_URL", message: "Contracts must not contain database URLs, passwords, bearer tokens, or secrets. Put runtime wiring in runner config/env vars." });
+        }
+        scanForInlineSecrets(child, childPath, errors);
+    }
+}
+function checkUnknownKeys(value, allowed, path, errors) {
+    for (const key of Object.keys(value)) {
+        if (allowed.has(key) || isExtensionKey(key))
+            continue;
+        errors.push({ path: `${path}.${key}`, code: "UNKNOWN_CORE_FIELD", message: `Unknown core field ${key}. Use x-cloud-*, x-runner-*, or x-experimental-* for extensions.` });
+    }
+}
+function addUnique(seen, name, path, code, errors) {
+    const value = String(name);
+    if (seen.has(value))
+        errors.push({ path, code, message: `Duplicate name: ${value}` });
+    seen.add(value);
+}
+function isExtensionKey(key) {
+    return /^x-(cloud|runner|experimental)-[A-Za-z0-9_.-]+$/.test(key);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isSafeIdentifier(value) {
+    return typeof value === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function isQualifiedName(value) {
+    return typeof value === "string" && /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function isQualifiedOrSafeName(value) {
+    return isSafeIdentifier(value) || isQualifiedName(value);
+}
+function isPositiveInteger(value) {
+    return Number.isInteger(value) && Number(value) > 0;
+}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+export declare const SPEC_VERSION: "0.1";
+export declare const SUPPORTED_SPEC_VERSIONS: readonly ["0.1"];
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;AAC3C,eAAO,MAAM,uBAAuB,kBAA0B,CAAC"}

package/dist/version.js

@@ -0,0 +1,2 @@
+export const SPEC_VERSION = "0.1";
+export const SUPPORTED_SPEC_VERSIONS = [SPEC_VERSION];