@ornexus/neocortex 4.60.65 → 4.60.67

package/packages/shared/dist/compatibility/index.js

@@ -0,0 +1,476 @@
+/**
+ * Public compatibility and release-lifecycle contracts.
+ *
+ * This module is deliberately pure. It accepts only bounded public metadata and
+ * never reads protected response fields, project state, clocks, or environment.
+ */
+import { createHash } from 'node:crypto';
+export const COMPATIBILITY_OFFER_SCHEMA = 'CompatibilityOffer/1.0';
+export const COMPATIBILITY_RESULT_SCHEMA = 'CompatibilityResult/1.0';
+export const RELEASE_LIFECYCLE_SCHEMA = 'ReleaseLifecycle/1.0';
+export const RELEASE_LIFECYCLE_CONTEXT_SCHEMA = 'ReleaseLifecycleContext/1.0';
+export const INVOKE_PROTOCOL_VERSION = 'invoke/1';
+export const COMPATIBILITY_CAPABILITIES = Object.freeze({
+    INVOKE_CORE: 'invoke-core-v1',
+    PUBLIC_SAFE_DIAGNOSTICS: 'public-safe-diagnostics-v1',
+    PROTECTED_RESPONSE_GUARD: 'protected-response-guard-v1',
+    RELEASE_LIFECYCLE: 'release-lifecycle-v1',
+    RELEASE_BLOCKED_TERMINAL: 'release-blocked-terminal-v1',
+    REVIEW_RECONCILIATION: 'review-reconciliation-v1',
+});
+export const COMPATIBILITY_SCHEMAS = Object.freeze({
+    INVOKE_REQUEST: 'invoke-request/1',
+    INVOKE_RESPONSE: 'invoke-response/1',
+    RELEASE_LIFECYCLE: RELEASE_LIFECYCLE_SCHEMA,
+    RELEASE_BLOCKED: 'ReleaseBlockedResult/1.0',
+    REVIEW_RECONCILIATION: 'ReviewReconciliation/1',
+});
+export const COMPATIBILITY_REASON_CODES = Object.freeze({
+    COMPATIBLE: 'compatibility-compatible',
+    OPTIONAL_PROJECTION_OMITTED: 'compatibility-optional-projection-omitted',
+    LEGACY_OFFER_MISSING: 'compatibility-legacy-offer-missing',
+    SERVER_NEGOTIATION_MISSING: 'compatibility-server-negotiation-missing',
+    OFFER_MALFORMED: 'compatibility-offer-malformed',
+    CLIENT_VERSION_UNKNOWN: 'compatibility-client-version-unknown',
+    SERVER_VERSION_UNKNOWN: 'compatibility-server-version-unknown',
+    PROTOCOL_MISMATCH: 'compatibility-protocol-mismatch',
+    REQUIRED_SCHEMA_MISSING: 'compatibility-required-schema-missing',
+    REQUIRED_CAPABILITY_MISSING: 'compatibility-required-capability-missing',
+    SECURITY_CAPABILITY_MISSING: 'compatibility-security-capability-missing',
+    REGISTRY_VERSION_MISMATCH: 'compatibility-registry-version-mismatch',
+    REGISTRY_CHECKSUM_MISMATCH: 'compatibility-registry-checksum-mismatch',
+    RESULT_MALFORMED: 'compatibility-result-malformed',
+    UNNEGOTIATED_PROTECTED_FIELD: 'compatibility-unnegotiated-protected-field',
+});
+const VERSION = /^\d{1,6}\.\d{1,6}\.\d{1,6}(?:[-+][A-Za-z0-9.-]{1,40})?$/u;
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,79}$/u;
+const REGISTRY_VERSION = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/u;
+const SHA256 = /^[a-f0-9]{64}$/u;
+const PROJECT_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{15,127}$/u;
+const MAX_NEGOTIATED_ITEMS = 32;
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function hasOnlyKeys(value, allowed) {
+    const keys = Object.keys(value);
+    return keys.length <= allowed.length && keys.every((key) => allowed.includes(key));
+}
+function isBoundedIdentifiers(value) {
+    return Array.isArray(value)
+        && value.length <= MAX_NEGOTIATED_ITEMS
+        && value.every((entry) => typeof entry === 'string' && IDENTIFIER.test(entry));
+}
+export function isCompatibilityOfferV1(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const offer = value;
+    const registry = offer.commandRegistry;
+    return hasOnlyKeys(offer, ['schemaVersion', 'clientVersion', 'protocolVersions', 'schemaVersions', 'capabilityIds', 'commandRegistry', 'publicSafe'])
+        && offer.schemaVersion === COMPATIBILITY_OFFER_SCHEMA
+        && typeof offer.clientVersion === 'string' && VERSION.test(offer.clientVersion)
+        && isBoundedIdentifiers(offer.protocolVersions) && offer.protocolVersions.length > 0
+        && isBoundedIdentifiers(offer.schemaVersions) && offer.schemaVersions.length > 0
+        && isBoundedIdentifiers(offer.capabilityIds) && offer.capabilityIds.length > 0
+        && !!registry && typeof registry === 'object' && !Array.isArray(registry)
+        && hasOnlyKeys(registry, ['version', 'checksum'])
+        && typeof registry.version === 'string' && REGISTRY_VERSION.test(registry.version)
+        && typeof registry.checksum === 'string' && SHA256.test(registry.checksum)
+        && offer.publicSafe === true;
+}
+export function createCompatibilityOffer(input) {
+    const offer = {
+        schemaVersion: COMPATIBILITY_OFFER_SCHEMA,
+        clientVersion: input.clientVersion,
+        protocolVersions: uniqueSorted(input.protocolVersions ?? [INVOKE_PROTOCOL_VERSION]),
+        schemaVersions: uniqueSorted(input.schemaVersions ?? Object.values(COMPATIBILITY_SCHEMAS)),
+        capabilityIds: uniqueSorted(input.capabilityIds ?? Object.values(COMPATIBILITY_CAPABILITIES)),
+        commandRegistry: { version: input.registryVersion, checksum: input.registryChecksum },
+        publicSafe: true,
+    };
+    if (!isCompatibilityOfferV1(offer))
+        throw new Error('compatibility-offer-invalid');
+    return Object.freeze({
+        ...offer,
+        protocolVersions: Object.freeze([...offer.protocolVersions]),
+        schemaVersions: Object.freeze([...offer.schemaVersions]),
+        capabilityIds: Object.freeze([...offer.capabilityIds]),
+        commandRegistry: Object.freeze({ ...offer.commandRegistry }),
+    });
+}
+function result(input) {
+    return Object.freeze({
+        schemaVersion: COMPATIBILITY_RESULT_SCHEMA,
+        ...input,
+        schemaVersions: Object.freeze([...input.schemaVersions]),
+        capabilityIds: Object.freeze([...input.capabilityIds]),
+        commandRegistry: Object.freeze({ ...input.commandRegistry }),
+        projection: Object.freeze({ ...input.projection, omittedFields: Object.freeze([...input.projection.omittedFields]) }),
+        reasonCodes: Object.freeze([...input.reasonCodes]),
+        publicSafe: true,
+    });
+}
+export function negotiateCompatibility(rawOffer, policy) {
+    const serverVersionValid = VERSION.test(policy.serverVersion);
+    const safeServerVersion = serverVersionValid ? policy.serverVersion : '0.0.0';
+    if (!isCompatibilityOfferV1(rawOffer)) {
+        const unknownClientVersion = !!rawOffer && typeof rawOffer === 'object' && !Array.isArray(rawOffer)
+            && rawOffer.schemaVersion === COMPATIBILITY_OFFER_SCHEMA
+            && (typeof rawOffer.clientVersion !== 'string'
+                || !VERSION.test(rawOffer.clientVersion));
+        return result({
+            status: 'incompatible', clientVersion: '0.0.0', serverVersion: safeServerVersion,
+            protocolVersion: null, schemaVersions: [], capabilityIds: [],
+            commandRegistry: { version: policy.commandRegistry.version, checksum: policy.commandRegistry.checksum, status: 'unknown' },
+            projection: { status: 'none', omittedFields: ['releaseBlocked', 'releaseLifecycle', 'reviewReconciliation'] },
+            reasonCodes: [unknownClientVersion
+                    ? COMPATIBILITY_REASON_CODES.CLIENT_VERSION_UNKNOWN
+                    : COMPATIBILITY_REASON_CODES.OFFER_MALFORMED], remediationHint: 'upgrade-client',
+        });
+    }
+    const offer = rawOffer;
+    const reasons = [];
+    const has = (values, expected) => values.includes(expected);
+    if (!serverVersionValid)
+        reasons.push(COMPATIBILITY_REASON_CODES.SERVER_VERSION_UNKNOWN);
+    if (!has(offer.protocolVersions, policy.protocolVersion))
+        reasons.push(COMPATIBILITY_REASON_CODES.PROTOCOL_MISMATCH);
+    if (policy.requiredSchemaVersions.some((schema) => !has(offer.schemaVersions, schema))) {
+        reasons.push(COMPATIBILITY_REASON_CODES.REQUIRED_SCHEMA_MISSING);
+    }
+    const missingRequiredCapabilities = policy.requiredCapabilityIds.filter((capability) => !has(offer.capabilityIds, capability));
+    if (missingRequiredCapabilities.length > 0)
+        reasons.push(COMPATIBILITY_REASON_CODES.REQUIRED_CAPABILITY_MISSING);
+    if (policy.securityCapabilityIds.some((capability) => !has(offer.capabilityIds, capability))) {
+        reasons.push(COMPATIBILITY_REASON_CODES.SECURITY_CAPABILITY_MISSING);
+    }
+    if (offer.commandRegistry.version !== policy.commandRegistry.version) {
+        reasons.push(COMPATIBILITY_REASON_CODES.REGISTRY_VERSION_MISMATCH);
+    }
+    if (offer.commandRegistry.checksum !== policy.commandRegistry.checksum) {
+        reasons.push(COMPATIBILITY_REASON_CODES.REGISTRY_CHECKSUM_MISMATCH);
+    }
+    const incompatible = reasons.length > 0;
+    const supportedSchemas = uniqueSorted(policy.requiredSchemaVersions.concat(policy.optionalSchemaVersions.filter((schema) => has(offer.schemaVersions, schema))));
+    const supportedCapabilities = uniqueSorted(policy.requiredCapabilityIds.concat(policy.optionalCapabilityIds.filter((capability) => has(offer.capabilityIds, capability))));
+    const omittedFields = [];
+    if (!has(offer.capabilityIds, COMPATIBILITY_CAPABILITIES.RELEASE_LIFECYCLE)
+        || !has(offer.schemaVersions, COMPATIBILITY_SCHEMAS.RELEASE_LIFECYCLE))
+        omittedFields.push('releaseLifecycle');
+    if (!has(offer.capabilityIds, COMPATIBILITY_CAPABILITIES.RELEASE_BLOCKED_TERMINAL)
+        || !has(offer.schemaVersions, COMPATIBILITY_SCHEMAS.RELEASE_BLOCKED))
+        omittedFields.push('releaseBlocked');
+    if (!has(offer.capabilityIds, COMPATIBILITY_CAPABILITIES.REVIEW_RECONCILIATION)
+        || !has(offer.schemaVersions, COMPATIBILITY_SCHEMAS.REVIEW_RECONCILIATION))
+        omittedFields.push('reviewReconciliation');
+    if (incompatible) {
+        const registryMismatch = reasons.includes(COMPATIBILITY_REASON_CODES.REGISTRY_VERSION_MISMATCH)
+            || reasons.includes(COMPATIBILITY_REASON_CODES.REGISTRY_CHECKSUM_MISMATCH);
+        return result({
+            status: 'incompatible', clientVersion: offer.clientVersion, serverVersion: safeServerVersion,
+            protocolVersion: null, schemaVersions: supportedSchemas, capabilityIds: supportedCapabilities,
+            commandRegistry: {
+                version: policy.commandRegistry.version, checksum: policy.commandRegistry.checksum,
+                status: registryMismatch ? 'mismatched' : 'matched',
+            },
+            projection: { status: 'none', omittedFields: ['releaseBlocked', 'releaseLifecycle', 'reviewReconciliation'] },
+            reasonCodes: uniqueSorted(reasons),
+            remediationHint: registryMismatch ? 'align-command-registry' : 'upgrade-client',
+        });
+    }
+    const degraded = omittedFields.length > 0;
+    return result({
+        status: degraded ? 'degraded' : 'compatible',
+        clientVersion: offer.clientVersion, serverVersion: safeServerVersion,
+        protocolVersion: policy.protocolVersion, schemaVersions: supportedSchemas,
+        capabilityIds: supportedCapabilities,
+        commandRegistry: { version: policy.commandRegistry.version, checksum: policy.commandRegistry.checksum, status: 'matched' },
+        projection: { status: degraded ? 'reduced' : 'full', omittedFields: uniqueSorted(omittedFields) },
+        reasonCodes: degraded
+            ? [COMPATIBILITY_REASON_CODES.OPTIONAL_PROJECTION_OMITTED]
+            : [COMPATIBILITY_REASON_CODES.COMPATIBLE],
+        remediationHint: degraded ? 'retry-supported-projection' : 'none',
+    });
+}
+export function createLegacyCompatibilityResult(input) {
+    return result({
+        status: 'degraded',
+        clientVersion: input.clientVersion && VERSION.test(input.clientVersion) ? input.clientVersion : '0.0.0',
+        serverVersion: VERSION.test(input.serverVersion) ? input.serverVersion : '0.0.0',
+        protocolVersion: INVOKE_PROTOCOL_VERSION,
+        schemaVersions: [COMPATIBILITY_SCHEMAS.INVOKE_REQUEST, COMPATIBILITY_SCHEMAS.INVOKE_RESPONSE],
+        capabilityIds: [COMPATIBILITY_CAPABILITIES.INVOKE_CORE, COMPATIBILITY_CAPABILITIES.PUBLIC_SAFE_DIAGNOSTICS],
+        commandRegistry: { version: input.registryVersion, checksum: input.registryChecksum, status: 'unknown' },
+        projection: { status: 'reduced', omittedFields: ['releaseBlocked', 'releaseLifecycle', 'reviewReconciliation'] },
+        reasonCodes: [input.reason ?? COMPATIBILITY_REASON_CODES.LEGACY_OFFER_MISSING],
+        remediationHint: 'retry-supported-projection',
+    });
+}
+const COMPATIBILITY_STATUSES = new Set(['compatible', 'degraded', 'incompatible']);
+const PROJECTION_STATUSES = new Set(['full', 'reduced', 'none']);
+const REMEDIATIONS = new Set(['none', 'upgrade-client', 'retry-supported-projection', 'align-command-registry', 'contact-support']);
+const REASONS = new Set(Object.values(COMPATIBILITY_REASON_CODES));
+const OPTIONAL_FIELDS = new Set(['releaseBlocked', 'releaseLifecycle', 'reviewReconciliation']);
+export function isCompatibilityResultV1(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const candidate = value;
+    const registry = candidate.commandRegistry;
+    const projection = candidate.projection;
+    const status = candidate.status;
+    const projectionStatus = projection?.status;
+    const remediation = candidate.remediationHint;
+    return hasOnlyKeys(candidate, ['schemaVersion', 'status', 'clientVersion', 'serverVersion', 'protocolVersion', 'schemaVersions', 'capabilityIds', 'commandRegistry', 'projection', 'reasonCodes', 'remediationHint', 'publicSafe'])
+        && candidate.schemaVersion === COMPATIBILITY_RESULT_SCHEMA
+        && COMPATIBILITY_STATUSES.has(candidate.status)
+        && typeof candidate.clientVersion === 'string' && VERSION.test(candidate.clientVersion)
+        && typeof candidate.serverVersion === 'string' && VERSION.test(candidate.serverVersion)
+        && (candidate.protocolVersion === null || typeof candidate.protocolVersion === 'string' && IDENTIFIER.test(candidate.protocolVersion))
+        && isBoundedIdentifiers(candidate.schemaVersions) && isBoundedIdentifiers(candidate.capabilityIds)
+        && !!registry && hasOnlyKeys(registry, ['version', 'checksum', 'status'])
+        && typeof registry.version === 'string' && REGISTRY_VERSION.test(registry.version)
+        && typeof registry.checksum === 'string' && SHA256.test(registry.checksum)
+        && ['matched', 'mismatched', 'unknown'].includes(String(registry.status))
+        && !!projection && hasOnlyKeys(projection, ['status', 'omittedFields'])
+        && PROJECTION_STATUSES.has(projectionStatus)
+        && Array.isArray(projection.omittedFields) && projection.omittedFields.length <= 3
+        && projection.omittedFields.every((field) => OPTIONAL_FIELDS.has(field))
+        && Array.isArray(candidate.reasonCodes) && candidate.reasonCodes.length > 0 && candidate.reasonCodes.length <= 12
+        && candidate.reasonCodes.every((reason) => typeof reason === 'string' && REASONS.has(reason))
+        && REMEDIATIONS.has(remediation)
+        && (status !== 'compatible' || projectionStatus === 'full' && remediation === 'none')
+        && (status !== 'degraded' || projectionStatus === 'reduced')
+        && (status !== 'incompatible' || projectionStatus === 'none')
+        && candidate.publicSafe === true;
+}
+/** Omit only explicitly optional fields. Required/security fields are never downgraded. */
+export function projectInvokePayloadForCompatibility(payload, decision) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload) || decision.status === 'incompatible')
+        return payload;
+    const root = { ...payload };
+    if (root.metadata && typeof root.metadata === 'object' && !Array.isArray(root.metadata)) {
+        const metadata = { ...root.metadata };
+        for (const field of decision.projection.omittedFields) {
+            delete metadata[field];
+            if (field === 'releaseLifecycle')
+                delete metadata.release_lifecycle;
+            if (field === 'releaseBlocked') {
+                delete metadata.release_blocked;
+                delete metadata.yoloopReleaseBlocked;
+                delete metadata.releaseBlockedReason;
+                delete metadata.releaseBlockedResume;
+            }
+            if (field === 'reviewReconciliation') {
+                delete metadata.review_reconciliation;
+                delete metadata.reconciliationMetadata;
+            }
+        }
+        root.metadata = metadata;
+    }
+    for (const field of decision.projection.omittedFields) {
+        delete root[field];
+        if (field === 'releaseLifecycle')
+            delete root.release_lifecycle;
+        if (field === 'releaseBlocked')
+            delete root.release_blocked;
+        if (field === 'reviewReconciliation') {
+            delete root.review_reconciliation;
+            delete root.reconciliationMetadata;
+        }
+    }
+    return root;
+}
+function releaseLifecycleContextDigest(input) {
+    return createHash('sha256')
+        .update('release-lifecycle-context-v1\0')
+        .update(input.projectId)
+        .update('\0')
+        .update(input.candidateId)
+        .update('\0')
+        .update(input.lineageSha256)
+        .digest('hex');
+}
+export function createReleaseLifecycleContext(input) {
+    const context = {
+        schemaVersion: RELEASE_LIFECYCLE_CONTEXT_SCHEMA,
+        projectId: input.projectId,
+        candidateId: input.candidateId,
+        lineageSha256: input.lineageSha256,
+        contextDigestSha256: releaseLifecycleContextDigest(input),
+        publicSafe: true,
+    };
+    if (!isReleaseLifecycleContextV1(context))
+        throw new Error('release-lifecycle-context-invalid');
+    return Object.freeze(context);
+}
+export function isReleaseLifecycleContextV1(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const context = value;
+    if (!hasOnlyKeys(context, [
+        'schemaVersion', 'projectId', 'candidateId', 'lineageSha256', 'contextDigestSha256', 'publicSafe',
+    ])
+        || context.schemaVersion !== RELEASE_LIFECYCLE_CONTEXT_SCHEMA
+        || typeof context.projectId !== 'string' || !PROJECT_ID.test(context.projectId)
+        || typeof context.candidateId !== 'string' || !CANDIDATE_ID.test(context.candidateId)
+        || typeof context.lineageSha256 !== 'string' || !SHA256.test(context.lineageSha256)
+        || typeof context.contextDigestSha256 !== 'string' || !SHA256.test(context.contextDigestSha256)
+        || context.publicSafe !== true)
+        return false;
+    return context.contextDigestSha256 === releaseLifecycleContextDigest({
+        projectId: context.projectId,
+        candidateId: context.candidateId,
+        lineageSha256: context.lineageSha256,
+    });
+}
+export const RELEASE_LIFECYCLE_REASON_CODES = Object.freeze({
+    VERIFIED: 'release-evidence-verified',
+    NOT_SATISFIED: 'release-gate-not-satisfied',
+    EVIDENCE_UNAVAILABLE: 'release-evidence-unavailable',
+    MALFORMED: 'release-lifecycle-malformed',
+    CANDIDATE_MISMATCH: 'release-candidate-mismatch',
+    LINEAGE_MISMATCH: 'release-lineage-mismatch',
+    FRESHNESS_STALE: 'release-evidence-stale',
+    FRESHNESS_UNKNOWN: 'release-evidence-freshness-unknown',
+    FUTURE_OBSERVATION: 'release-evidence-future-observation',
+    EVIDENCE_REF_INVALID: 'release-evidence-ref-invalid',
+    EVIDENCE_REPLAYED: 'release-evidence-replayed',
+    IMPLEMENTATION_RECEIPT_MISSING: 'release-implementation-receipt-missing',
+    BETA_RECEIPT_MISSING: 'release-beta-receipt-missing',
+    RELEASE_GATE_RECEIPT_MISSING: 'release-gate-receipt-missing',
+    PROMOTION_RECEIPT_MISSING: 'release-promotion-receipt-missing',
+    RELEASE_READY_PREREQUISITE_MISSING: 'release-ready-prerequisite-missing',
+    PRODUCTION_PREREQUISITE_MISSING: 'release-production-prerequisite-missing',
+});
+const CANDIDATE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+const EVIDENCE_REF = /^(?:local-gate|beta-receipt|release-gate|promotion-receipt|sha256):[a-f0-9]{64}$/u;
+const RELEASE_REASONS = new Set(Object.values(RELEASE_LIFECYCLE_REASON_CODES));
+const DIMENSIONS = Object.freeze([
+    'implementationComplete', 'betaOperable', 'releaseReady', 'productionPromoted',
+]);
+function validIso(value) {
+    return typeof value === 'string' && value.length >= 20 && value.length <= 40
+        && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+function dimensionShape(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const dimension = value;
+    return hasOnlyKeys(dimension, ['value', 'reasonCodes', 'evidenceRefs', 'candidateId', 'lineageSha256', 'observedAt', 'maxAgeSeconds', 'freshness'])
+        && (typeof dimension.value === 'boolean' || dimension.value === 'unknown')
+        && Array.isArray(dimension.reasonCodes) && dimension.reasonCodes.length > 0 && dimension.reasonCodes.length <= 8
+        && dimension.reasonCodes.every((reason) => typeof reason === 'string' && RELEASE_REASONS.has(reason))
+        && Array.isArray(dimension.evidenceRefs) && dimension.evidenceRefs.length <= 8
+        && dimension.evidenceRefs.every((ref) => typeof ref === 'string' && ref.length <= 96)
+        && typeof dimension.candidateId === 'string' && CANDIDATE_ID.test(dimension.candidateId)
+        && typeof dimension.lineageSha256 === 'string' && SHA256.test(dimension.lineageSha256)
+        && (dimension.observedAt === undefined || validIso(dimension.observedAt))
+        && (dimension.maxAgeSeconds === undefined
+            || Number.isSafeInteger(dimension.maxAgeSeconds) && dimension.maxAgeSeconds >= 1
+                && dimension.maxAgeSeconds <= 31_536_000)
+        && (dimension.freshness === undefined || ['fresh', 'stale', 'unknown'].includes(String(dimension.freshness)));
+}
+function freshness(dimension, evaluatedAtMs) {
+    if (!dimension.observedAt || !dimension.maxAgeSeconds)
+        return 'unknown';
+    const observedAtMs = Date.parse(dimension.observedAt);
+    if (observedAtMs > evaluatedAtMs)
+        return 'unknown';
+    return evaluatedAtMs - observedAtMs <= dimension.maxAgeSeconds * 1_000 ? 'fresh' : 'stale';
+}
+function hasEvidencePrefix(dimension, prefix) {
+    return dimension.evidenceRefs.some((ref) => ref.startsWith(`${prefix}:`));
+}
+/**
+ * Validate exact-candidate monotonic release truth without inferring any higher
+ * dimension. Invalid true claims are rejected rather than normalized to false.
+ */
+export function validateReleaseLifecycle(input) {
+    const fail = (reasons) => Object.freeze({
+        accepted: false,
+        reasonCodes: Object.freeze(uniqueSorted(reasons)),
+        publicSafe: true,
+    });
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return fail([RELEASE_LIFECYCLE_REASON_CODES.MALFORMED]);
+    const lifecycle = input;
+    if (!hasOnlyKeys(lifecycle, ['schemaVersion', 'candidateId', 'lineageSha256', 'evaluatedAt', ...DIMENSIONS, 'publicSafe'])
+        || lifecycle.schemaVersion !== RELEASE_LIFECYCLE_SCHEMA
+        || typeof lifecycle.candidateId !== 'string' || !CANDIDATE_ID.test(lifecycle.candidateId)
+        || typeof lifecycle.lineageSha256 !== 'string' || !SHA256.test(lifecycle.lineageSha256)
+        || !validIso(lifecycle.evaluatedAt) || lifecycle.publicSafe !== true
+        || DIMENSIONS.some((name) => !dimensionShape(lifecycle[name]))) {
+        return fail([RELEASE_LIFECYCLE_REASON_CODES.MALFORMED]);
+    }
+    const typed = lifecycle;
+    const evaluatedAtMs = Date.parse(typed.evaluatedAt);
+    const reasons = [];
+    const seenEvidence = new Set();
+    const projected = {};
+    for (const name of DIMENSIONS) {
+        const dimension = typed[name];
+        if (dimension.candidateId !== typed.candidateId)
+            reasons.push(RELEASE_LIFECYCLE_REASON_CODES.CANDIDATE_MISMATCH);
+        if (dimension.lineageSha256 !== typed.lineageSha256)
+            reasons.push(RELEASE_LIFECYCLE_REASON_CODES.LINEAGE_MISMATCH);
+        if (dimension.evidenceRefs.some((ref) => !EVIDENCE_REF.test(ref)))
+            reasons.push(RELEASE_LIFECYCLE_REASON_CODES.EVIDENCE_REF_INVALID);
+        for (const ref of dimension.evidenceRefs) {
+            if (seenEvidence.has(ref))
+                reasons.push(RELEASE_LIFECYCLE_REASON_CODES.EVIDENCE_REPLAYED);
+            seenEvidence.add(ref);
+        }
+        const evidenceFreshness = freshness(dimension, evaluatedAtMs);
+        const suppliedFreshness = dimension.freshness;
+        if (suppliedFreshness !== undefined && suppliedFreshness !== evidenceFreshness) {
+            reasons.push(RELEASE_LIFECYCLE_REASON_CODES.MALFORMED);
+        }
+        if (dimension.observedAt && Date.parse(dimension.observedAt) > evaluatedAtMs) {
+            reasons.push(RELEASE_LIFECYCLE_REASON_CODES.FUTURE_OBSERVATION);
+        }
+        if (dimension.value === true && evidenceFreshness === 'stale')
+            reasons.push(RELEASE_LIFECYCLE_REASON_CODES.FRESHNESS_STALE);
+        if (dimension.value === true && evidenceFreshness === 'unknown')
+            reasons.push(RELEASE_LIFECYCLE_REASON_CODES.FRESHNESS_UNKNOWN);
+        projected[name] = Object.freeze({
+            ...dimension,
+            reasonCodes: Object.freeze([...dimension.reasonCodes]),
+            evidenceRefs: Object.freeze([...dimension.evidenceRefs]),
+            freshness: evidenceFreshness,
+        });
+    }
+    if (typed.implementationComplete.value === true && !hasEvidencePrefix(typed.implementationComplete, 'local-gate')) {
+        reasons.push(RELEASE_LIFECYCLE_REASON_CODES.IMPLEMENTATION_RECEIPT_MISSING);
+    }
+    if (typed.betaOperable.value === true && !hasEvidencePrefix(typed.betaOperable, 'beta-receipt')) {
+        reasons.push(RELEASE_LIFECYCLE_REASON_CODES.BETA_RECEIPT_MISSING);
+    }
+    if (typed.releaseReady.value === true) {
+        if (typed.implementationComplete.value !== true || typed.betaOperable.value !== true) {
+            reasons.push(RELEASE_LIFECYCLE_REASON_CODES.RELEASE_READY_PREREQUISITE_MISSING);
+        }
+        if (!hasEvidencePrefix(typed.releaseReady, 'release-gate')) {
+            reasons.push(RELEASE_LIFECYCLE_REASON_CODES.RELEASE_GATE_RECEIPT_MISSING);
+        }
+    }
+    if (typed.productionPromoted.value === true) {
+        if (typed.releaseReady.value !== true)
+            reasons.push(RELEASE_LIFECYCLE_REASON_CODES.PRODUCTION_PREREQUISITE_MISSING);
+        if (!hasEvidencePrefix(typed.productionPromoted, 'promotion-receipt')) {
+            reasons.push(RELEASE_LIFECYCLE_REASON_CODES.PROMOTION_RECEIPT_MISSING);
+        }
+    }
+    if (reasons.length > 0)
+        return fail(reasons);
+    const projection = Object.freeze({
+        schemaVersion: RELEASE_LIFECYCLE_SCHEMA,
+        candidateId: typed.candidateId,
+        lineageSha256: typed.lineageSha256,
+        evaluatedAt: typed.evaluatedAt,
+        implementationComplete: projected.implementationComplete,
+        betaOperable: projected.betaOperable,
+        releaseReady: projected.releaseReady,
+        productionPromoted: projected.productionPromoted,
+        publicSafe: true,
+    });
+    return Object.freeze({ accepted: true, reasonCodes: Object.freeze([]), projection, publicSafe: true });
+}

package/packages/shared/dist/invocation/index.js

@@ -177,10 +177,12 @@ export function lexInvocationEnvelope(input) {
         if (escaped) {
             const allowed = char === '\\' || char === ' ' || char === '\t' || char === '\r' || char === '\n'
                 || (quote === 'single' && char === "'") || (quote === 'double' && char === '"');
-            if (!allowed)
+            // A quoted Windows path such as src\win\async.c is literal user text.
+            // Keep unquoted shell-shaped escapes fail-closed.
+            if (!allowed && !quote)
                 return { ok: false, reason: 'unsupported_escape', tokenCount: tokens.length };
             startSegment(i - 1, quote);
-            value += char;
+            value += allowed ? char : `\\${char}`;
             escaped = false;
             continue;
         }

package/packages/shared/dist/private-qa-structural-admission.js

@@ -0,0 +1,14 @@
+export function isPrivateQaStructuralAdmission(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const r = value, checks = r.checks;
+    return Object.keys(r).sort().join('|') === ['schemaVersion', 'kind', 'stepId', 'generationId', 'graphRevision', 'topologyGenerationId', 'tier', 'checks', 'publicSafe'].sort().join('|')
+        && r.schemaVersion === 1 && r.kind === 'server-private-qa-structural-admission' && r.stepId === 'step-8721319d'
+        && typeof r.generationId === 'string' && /^sha256:[a-f0-9]{64}$/.test(r.generationId)
+        && typeof r.graphRevision === 'string' && /^[a-f0-9]{64}$/.test(r.graphRevision)
+        && typeof r.topologyGenerationId === 'string' && /^sha256:[a-f0-9]{64}$/.test(r.topologyGenerationId)
+        && ['free', 'pro', 'enterprise'].includes(String(r.tier)) && r.publicSafe === true
+        && !!checks && typeof checks === 'object' && !Array.isArray(checks)
+        && Object.keys(checks).sort().join('|') === ['classifiedAssetDelivery', 'licensedCommandAdmission', 'registeredStatusMapping', 'prerequisiteStateAdmitted'].sort().join('|')
+        && Object.values(checks).every(result => result === true);
+}

package/packages/shared/dist/private-yolo-predecessor-decision.js

@@ -0,0 +1,32 @@
+export function isPrivateQaSkippedPredecessors(value) {
+    if (!Array.isArray(value) || value.length > 2)
+        return false;
+    const ids = [];
+    for (const item of value) {
+        if (isPrivateYoloSkippedPredecessors([item])) {
+            ids.push(item.stepId);
+            continue;
+        }
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            return false;
+        const r = item;
+        if (Object.keys(r).sort().join('|') !== ['stepId', 'featureGate', 'reason', 'tier', 'publicSafe'].sort().join('|')
+            || r.stepId !== 'step-b2fe7cb5' || r.featureGate !== 'validate-tests'
+            || r.reason !== 'subscription-tier' || r.tier !== 'free' || r.publicSafe !== true)
+            return false;
+        ids.push(r.stepId);
+    }
+    return new Set(ids).size === ids.length && (value.length < 2
+        || ids[0] === 'step-a8ce5c64' && ids[1] === 'step-b2fe7cb5' && value[0].tier === 'free');
+}
+export function isPrivateYoloSkippedPredecessors(value) {
+    return Array.isArray(value) && value.length <= 1 && value.every(item => {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            return false;
+        const r = item;
+        return Object.keys(r).sort().join('|') === ['stepId', 'featureFlagId', 'enabled', 'tier', 'publicSafe'].sort().join('|')
+            && r.stepId === 'step-a8ce5c64' && r.featureFlagId === 'property-testing'
+            && typeof r.enabled === 'boolean' && ['free', 'pro', 'enterprise'].includes(String(r.tier))
+            && (r.enabled === false || r.tier === 'free') && r.publicSafe === true;
+    });
+}

package/packages/shared/dist/project-validation-commands.js

@@ -0,0 +1,74 @@
+/** Bounded project command declarations from the submitted story/spec artifacts.
+ * These are planning data, never permission to execute or independent QA.
+ */
+export const PROJECT_VALIDATION_KINDS = ['unit', 'integration', 'contract', 'bdd-example', 'e2e'];
+export function readProjectValidationCommands(storyId, sources) {
+    const byKind = new Map();
+    let declared = false, invalid = false;
+    const allowedPaths = new Set(['story', 'spec', 'tasks'].map(suffix => `docs/stories/${storyId}.${suffix}.md`));
+    if (sources.length > 3 || new Set(sources.map(source => source.path)).size !== sources.length) {
+        return { declared: true, invalid: true, commands: [] };
+    }
+    for (const source of sources) {
+        if (!allowedPaths.has(source.path) || Buffer.byteLength(source.content) > 131072) {
+            invalid = true;
+            declared = true;
+            continue;
+        }
+        let active = false, fenced = false, headings = 0, entries = 0;
+        for (const raw of source.content.split(/\r?\n/)) {
+            const line = raw.trim();
+            if (/^(?:```|~~~)/.test(line)) {
+                fenced = !fenced;
+                continue;
+            }
+            if (fenced)
+                continue;
+            if (/^##\s+/.test(line)) {
+                if (active && entries === 0)
+                    invalid = true;
+                active = line === '## Validation Commands';
+                if (active) {
+                    declared = true;
+                    headings++;
+                    entries = 0;
+                    if (headings > 1)
+                        invalid = true;
+                }
+                continue;
+            }
+            if (!active || !line)
+                continue;
+            const match = /^- (unit|integration|contract|bdd-example|e2e): `([^`]{1,220})`$/.exec(line);
+            if (!match) {
+                invalid = true;
+                continue;
+            }
+            const kind = match[1], command = match[2];
+            // No shell language, quoted substitutions, inline secrets or private URLs.
+            // A command stays a literal argv-shaped string throughout this planner.
+            if (!/^[A-Za-z0-9_./-]+(?: [A-Za-z0-9_./:@%+=,-]+)*$/.test(command)
+                || /(?:token|password|license_key|secret|credential)=|(?:https?|ssh):\/\/|@[^ /]+\.[A-Za-z]/i.test(command)
+                || command.split(' ').some(arg => arg.split('/').includes('..'))) {
+                invalid = true;
+                continue;
+            }
+            entries++;
+            const prior = byKind.get(kind);
+            if (prior && prior.command !== command) {
+                invalid = true;
+                continue;
+            }
+            if (prior?.sourcePaths.includes(source.path)) {
+                invalid = true;
+                continue;
+            }
+            byKind.set(kind, { kind, command, sourcePaths: [...(prior?.sourcePaths ?? []), source.path] });
+        }
+        if (active && entries === 0)
+            invalid = true;
+    }
+    if (declared && !byKind.has('unit'))
+        invalid = true;
+    return { declared, invalid, commands: [...byKind.values()] };
+}

package/packages/shared/dist/yolo/spec-envelope.js

@@ -6,6 +6,8 @@ export const YOLO_SPEC_TOTAL_LIMIT_BYTES = 128 * 1024;
 export const YOLO_SPEC_MAX_ARTIFACTS = 12;
 export const YOLO_SPEC_MAX_AGE_MS = 120_000;
 export const YOLO_SPEC_FUTURE_SKEW_MS = 30_000;
+/** Public server capability for both mandatory top-level YOLO invoke fields. */
+export const YOLO_INVOKE_ENVELOPE_CAPABILITY = 'yolo-invoke-envelope-v1';
 const HASH = /^[a-f0-9]{64}$/;
 const HEAD = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
 const STORY_ID = /^[A-Za-z0-9]+(?:\.[A-Za-z0-9]+)+$/;