@ornexus/neocortex 4.60.22 → 4.60.24

package/packages/shared/dist/invocation/public-diagnostics.d.ts

@@ -0,0 +1,87 @@
+import type { InvokeInputEvidenceV1 } from './input-envelope.js';
+import type { InvocationShapeV2 } from './state-projection.js';
+export declare const INVOCATION_PUBLIC_DIAGNOSTIC_VERSION: 1;
+export declare const INVOCATION_DIGEST_PREFIX_LENGTH = 12;
+export type InvocationPublicDiagnosticV1 = {
+    readonly version: 1;
+    readonly event: 'invoke.input';
+    readonly source: InvokeInputEvidenceV1['source'];
+    readonly bytesBucket: string;
+    readonly newlineStyle: InvokeInputEvidenceV1['newlineStyle'];
+    readonly digestPrefix: string;
+    readonly outcome: 'accepted' | 'rejected';
+    readonly reasonCode?: string;
+    readonly publicSafe: true;
+} | {
+    readonly version: 1;
+    readonly event: 'invoke.projection';
+    readonly shape: InvocationShapeV2;
+    readonly bytesBucket: string;
+    readonly includedEpics: number;
+    readonly includedStories: number;
+    readonly omittedEpics: number;
+    readonly omittedStories: number;
+    readonly nodes: number;
+    readonly edges: number;
+    readonly cycles: number;
+    readonly outcome: 'accepted' | 'rejected';
+    readonly reasonCode?: string;
+    readonly publicSafe: true;
+} | {
+    readonly version: 1;
+    readonly event: 'invoke.project-identity';
+    readonly phase: 'prepare' | 'seed' | 'remote-acknowledged' | 'finalize' | 'reconcile';
+    readonly outcome: 'prepared' | 'seeded' | 'already-seeded' | 'finalized' | 'rejected' | 'retry';
+    readonly floorBucket: string;
+    readonly scopeDigestPrefix: string;
+    readonly capability: 'project-identity-migration-v1';
+    readonly publicSafe: true;
+} | {
+    readonly version: 1;
+    readonly event: 'invoke.diagnose';
+    readonly authority: 'strict-read-only';
+    readonly receiptStatus: 'verified' | 'rejected';
+    readonly attemptedEffectCount: number;
+    readonly suppressedEffectCount: number;
+    readonly publicSafe: true;
+} | {
+    readonly version: 1;
+    readonly event: 'invoke.trace';
+    readonly stages: readonly ('admission' | 'input' | 'shape' | 'projection' | 'size-guard' | 'send')[];
+    readonly outcome: 'accepted' | 'rejected';
+    readonly reasonCode?: string;
+    readonly publicSafe: true;
+};
+export declare function invocationByteBucket(bytes: number): string;
+export declare function invocationFloorBucket(floor: number): string;
+export declare function invocationDigestPrefix(domain: string, value: string): string;
+export declare function buildInputPublicDiagnostic(evidence: InvokeInputEvidenceV1, outcome?: 'accepted' | 'rejected', reasonCode?: string): InvocationPublicDiagnosticV1;
+export declare function buildProjectionPublicDiagnostic(input: {
+    readonly shape: InvocationShapeV2;
+    readonly bytes: number;
+    readonly includedEpics: number;
+    readonly includedStories: number;
+    readonly omittedEpics: number;
+    readonly omittedStories: number;
+    readonly nodes?: number;
+    readonly edges?: number;
+    readonly cycles?: number;
+    readonly outcome?: 'accepted' | 'rejected';
+    readonly reasonCode?: string;
+}): InvocationPublicDiagnosticV1;
+export declare function buildProjectIdentityPublicDiagnostic(input: {
+    readonly phase: Extract<InvocationPublicDiagnosticV1, {
+        event: 'invoke.project-identity';
+    }>['phase'];
+    readonly outcome: Extract<InvocationPublicDiagnosticV1, {
+        event: 'invoke.project-identity';
+    }>['outcome'];
+    readonly floor: number;
+    readonly licenseId: string;
+    readonly projectId: string;
+}): InvocationPublicDiagnosticV1;
+export declare function buildDiagnosePublicDiagnostic(receiptStatus: 'verified' | 'rejected', attemptedEffectCount: number, suppressedEffectCount: number): InvocationPublicDiagnosticV1;
+export declare function buildInvokeTracePublicDiagnostic(stages: Extract<InvocationPublicDiagnosticV1, {
+    event: 'invoke.trace';
+}>['stages'], outcome: 'accepted' | 'rejected', reasonCode?: string): InvocationPublicDiagnosticV1;
+export declare function assertInvocationPublicDiagnosticV1(value: unknown): asserts value is InvocationPublicDiagnosticV1;

package/packages/shared/dist/invocation/public-diagnostics.js

@@ -0,0 +1,181 @@
+import { createHash } from 'node:crypto';
+export const INVOCATION_PUBLIC_DIAGNOSTIC_VERSION = 1;
+export const INVOCATION_DIGEST_PREFIX_LENGTH = 12;
+const SAFE_REASON = /^[a-z0-9][a-z0-9._-]{0,79}$/;
+const BYTE_BUCKETS = new Set(['0', '1-1023', '1k-16k', '16k-64k', '64k-128k', '128k-192k', '192k-256k', '256k+']);
+const FLOOR_BUCKETS = new Set(['0-9', '10-99', '100-999', '1k-10k', '10k+']);
+const INVOCATION_SHAPES = new Set([
+    'yolo-story', 'yolo-inline', 'yoloop-target', 'yoloop-session', 'yoloop-discovery',
+]);
+const TRACE_STAGES = new Set(['admission', 'input', 'shape', 'projection', 'size-guard', 'send']);
+function boundedCount(value) {
+    return Number.isSafeInteger(value) && value >= 0 ? Math.min(value, 1_000_000) : 0;
+}
+export function invocationByteBucket(bytes) {
+    const safe = boundedCount(bytes);
+    if (safe === 0)
+        return '0';
+    if (safe < 1024)
+        return '1-1023';
+    if (safe < 16 * 1024)
+        return '1k-16k';
+    if (safe < 64 * 1024)
+        return '16k-64k';
+    if (safe < 128 * 1024)
+        return '64k-128k';
+    if (safe < 192 * 1024)
+        return '128k-192k';
+    if (safe < 256 * 1024)
+        return '192k-256k';
+    return '256k+';
+}
+export function invocationFloorBucket(floor) {
+    const safe = boundedCount(floor);
+    if (safe < 10)
+        return '0-9';
+    if (safe < 100)
+        return '10-99';
+    if (safe < 1_000)
+        return '100-999';
+    if (safe < 10_000)
+        return '1k-10k';
+    return '10k+';
+}
+export function invocationDigestPrefix(domain, value) {
+    return createHash('sha256').update(`${domain}\0${value}`, 'utf8').digest('hex').slice(0, INVOCATION_DIGEST_PREFIX_LENGTH);
+}
+export function buildInputPublicDiagnostic(evidence, outcome = 'accepted', reasonCode) {
+    return Object.freeze({
+        version: 1,
+        event: 'invoke.input',
+        source: evidence.source,
+        bytesBucket: invocationByteBucket(evidence.byteLength),
+        newlineStyle: evidence.newlineStyle,
+        digestPrefix: evidence.sha256.slice(0, INVOCATION_DIGEST_PREFIX_LENGTH),
+        outcome,
+        ...(reasonCode && SAFE_REASON.test(reasonCode) ? { reasonCode } : {}),
+        publicSafe: true,
+    });
+}
+export function buildProjectionPublicDiagnostic(input) {
+    return Object.freeze({
+        version: 1,
+        event: 'invoke.projection',
+        shape: input.shape,
+        bytesBucket: invocationByteBucket(input.bytes),
+        includedEpics: boundedCount(input.includedEpics),
+        includedStories: boundedCount(input.includedStories),
+        omittedEpics: boundedCount(input.omittedEpics),
+        omittedStories: boundedCount(input.omittedStories),
+        nodes: boundedCount(input.nodes ?? input.includedStories),
+        edges: boundedCount(input.edges ?? 0),
+        cycles: boundedCount(input.cycles ?? 0),
+        outcome: input.outcome ?? 'accepted',
+        ...(input.reasonCode && SAFE_REASON.test(input.reasonCode) ? { reasonCode: input.reasonCode } : {}),
+        publicSafe: true,
+    });
+}
+export function buildProjectIdentityPublicDiagnostic(input) {
+    return Object.freeze({
+        version: 1,
+        event: 'invoke.project-identity',
+        phase: input.phase,
+        outcome: input.outcome,
+        floorBucket: invocationFloorBucket(input.floor),
+        scopeDigestPrefix: invocationDigestPrefix('nx-project-scope-v1', `${input.licenseId}\0${input.projectId}`),
+        capability: 'project-identity-migration-v1',
+        publicSafe: true,
+    });
+}
+export function buildDiagnosePublicDiagnostic(receiptStatus, attemptedEffectCount, suppressedEffectCount) {
+    return Object.freeze({
+        version: 1,
+        event: 'invoke.diagnose',
+        authority: 'strict-read-only',
+        receiptStatus,
+        attemptedEffectCount: boundedCount(attemptedEffectCount),
+        suppressedEffectCount: boundedCount(suppressedEffectCount),
+        publicSafe: true,
+    });
+}
+export function buildInvokeTracePublicDiagnostic(stages, outcome, reasonCode) {
+    const allowed = new Set(['admission', 'input', 'shape', 'projection', 'size-guard', 'send']);
+    return Object.freeze({
+        version: 1,
+        event: 'invoke.trace',
+        stages: Object.freeze([...new Set(stages.filter((stage) => allowed.has(stage)))]),
+        outcome,
+        ...(reasonCode && SAFE_REASON.test(reasonCode) ? { reasonCode } : {}),
+        publicSafe: true,
+    });
+}
+export function assertInvocationPublicDiagnosticV1(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('INVOCATION_PUBLIC_DIAGNOSTIC_INVALID');
+    const record = value;
+    const serialized = JSON.stringify(value);
+    if (record.version !== 1 || record.publicSafe !== true || serialized.length > 4096
+        || /(rawArgs|stateSnapshot|projectRoot|licenseId|projectId|payload|preview|secret|password|privateUrl)/i.test(serialized)) {
+        throw new Error('INVOCATION_PUBLIC_DIAGNOSTIC_INVALID');
+    }
+    const exactKeys = (required, optional = []) => {
+        const allowed = new Set([...required, ...optional]);
+        const keys = Object.keys(record);
+        return required.every((key) => keys.includes(key)) && keys.every((key) => allowed.has(key));
+    };
+    const validReason = record.reasonCode === undefined
+        || (typeof record.reasonCode === 'string' && SAFE_REASON.test(record.reasonCode));
+    const validCount = (candidate) => Number.isSafeInteger(candidate)
+        && candidate >= 0 && candidate <= 1_000_000;
+    const validOutcome = record.outcome === 'accepted' || record.outcome === 'rejected';
+    let valid = false;
+    if (record.event === 'invoke.input') {
+        valid = exactKeys(['version', 'event', 'source', 'bytesBucket', 'newlineStyle', 'digestPrefix', 'outcome', 'publicSafe'], ['reasonCode'])
+            && ['args', 'stdin', 'args-file'].includes(String(record.source))
+            && BYTE_BUCKETS.has(String(record.bytesBucket))
+            && ['none', 'lf', 'crlf', 'mixed'].includes(String(record.newlineStyle))
+            && typeof record.digestPrefix === 'string' && /^[a-f0-9]{12}$/.test(record.digestPrefix)
+            && validOutcome && validReason;
+    }
+    else if (record.event === 'invoke.projection') {
+        valid = exactKeys([
+            'version', 'event', 'shape', 'bytesBucket', 'includedEpics', 'includedStories',
+            'omittedEpics', 'omittedStories', 'nodes', 'edges', 'cycles', 'outcome', 'publicSafe',
+        ], ['reasonCode'])
+            && INVOCATION_SHAPES.has(record.shape)
+            && BYTE_BUCKETS.has(String(record.bytesBucket))
+            && ['includedEpics', 'includedStories', 'omittedEpics', 'omittedStories', 'nodes', 'edges', 'cycles']
+                .every((key) => validCount(record[key]))
+            && validOutcome && validReason;
+    }
+    else if (record.event === 'invoke.project-identity') {
+        valid = exactKeys([
+            'version', 'event', 'phase', 'outcome', 'floorBucket', 'scopeDigestPrefix', 'capability', 'publicSafe',
+        ])
+            && ['prepare', 'seed', 'remote-acknowledged', 'finalize', 'reconcile'].includes(String(record.phase))
+            && ['prepared', 'seeded', 'already-seeded', 'finalized', 'rejected', 'retry'].includes(String(record.outcome))
+            && FLOOR_BUCKETS.has(String(record.floorBucket))
+            && typeof record.scopeDigestPrefix === 'string' && /^[a-f0-9]{12}$/.test(record.scopeDigestPrefix)
+            && record.capability === 'project-identity-migration-v1';
+    }
+    else if (record.event === 'invoke.diagnose') {
+        valid = exactKeys([
+            'version', 'event', 'authority', 'receiptStatus', 'attemptedEffectCount',
+            'suppressedEffectCount', 'publicSafe',
+        ])
+            && record.authority === 'strict-read-only'
+            && (record.receiptStatus === 'verified' || record.receiptStatus === 'rejected')
+            && validCount(record.attemptedEffectCount)
+            && validCount(record.suppressedEffectCount);
+    }
+    else if (record.event === 'invoke.trace') {
+        valid = exactKeys(['version', 'event', 'stages', 'outcome', 'publicSafe'], ['reasonCode'])
+            && Array.isArray(record.stages)
+            && record.stages.length <= TRACE_STAGES.size
+            && new Set(record.stages).size === record.stages.length
+            && record.stages.every((stage) => typeof stage === 'string' && TRACE_STAGES.has(stage))
+            && validOutcome && validReason;
+    }
+    if (!valid)
+        throw new Error('INVOCATION_PUBLIC_DIAGNOSTIC_INVALID');
+}

package/packages/shared/dist/invocation/state-projection.d.ts

@@ -0,0 +1,21 @@
+export declare const STATE_PROJECTION_VERSION: 2;
+export type InvocationShapeV2 = 'yolo-story' | 'yolo-inline' | 'yoloop-target' | 'yoloop-session' | 'yoloop-discovery';
+export type StructuralProjectionErrorCodeV2 = 'STRUCTURAL_TARGET_NOT_FOUND' | 'STRUCTURAL_DEPENDENCY_MISSING' | 'STRUCTURAL_DEPENDENCY_CYCLE' | 'STRUCTURAL_CONTEXT_TOO_LARGE';
+export interface StateProjectionCountsV2 {
+    readonly epics: number;
+    readonly stories: number;
+    readonly edges: number;
+}
+export type StateProjectionResultV2<TSnapshot> = {
+    readonly ok: true;
+    readonly version: typeof STATE_PROJECTION_VERSION;
+    readonly shape: InvocationShapeV2;
+    readonly snapshot: TSnapshot;
+    readonly included: StateProjectionCountsV2;
+    readonly omitted: Omit<StateProjectionCountsV2, 'edges'>;
+    readonly cycleCount: number;
+} | {
+    readonly ok: false;
+    readonly code: StructuralProjectionErrorCodeV2;
+    readonly publicDetails: Readonly<Record<string, string | number>>;
+};

package/packages/shared/dist/invocation/state-projection.js

@@ -0,0 +1 @@
+export const STATE_PROJECTION_VERSION = 2;

package/packages/shared/dist/invocation/strict-effect-receipt.d.ts

@@ -0,0 +1,12 @@
+export declare const STRICT_DIAGNOSE_RECEIPT_VERSION: 1;
+export interface StrictDiagnoseReceiptV1 {
+    readonly version: typeof STRICT_DIAGNOSE_RECEIPT_VERSION;
+    readonly authority: 'strict-read-only';
+    readonly projectBusinessMutation: false;
+    readonly attemptedEffects: readonly string[];
+    readonly suppressedEffects: readonly string[];
+    readonly inputDigest: string;
+    readonly responseDigest: string;
+}
+export declare function assertStrictDiagnoseReceiptV1(value: unknown): asserts value is StrictDiagnoseReceiptV1;
+export declare function verifyStrictDiagnoseReceiptV1(value: unknown, rawArgs: string, responseInstructions: string): asserts value is StrictDiagnoseReceiptV1;

package/packages/shared/dist/invocation/strict-effect-receipt.js

@@ -0,0 +1,43 @@
+import { SHA256_HEX_PATTERN } from './project-identity-migration.js';
+import { invokeInputSha256 } from './input-envelope.js';
+export const STRICT_DIAGNOSE_RECEIPT_VERSION = 1;
+const validEffects = (value) => Array.isArray(value)
+    && value.length <= 128
+    && value.every((entry) => typeof entry === 'string' && entry.length > 0 && entry.length <= 128);
+export function assertStrictDiagnoseReceiptV1(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('STRICT_DIAGNOSE_RECEIPT_INVALID');
+    }
+    const candidate = value;
+    if (candidate.version !== STRICT_DIAGNOSE_RECEIPT_VERSION) {
+        throw new Error('STRICT_DIAGNOSE_RECEIPT_VERSION_UNSUPPORTED');
+    }
+    if (candidate.projectBusinessMutation !== false) {
+        throw new Error('STRICT_DIAGNOSE_RECEIPT_MUTATION_CONFLICT');
+    }
+    const expectedKeys = [
+        'attemptedEffects', 'authority', 'inputDigest', 'projectBusinessMutation',
+        'responseDigest', 'suppressedEffects', 'version',
+    ];
+    const actualKeys = Object.keys(candidate).sort();
+    if (actualKeys.length !== expectedKeys.length
+        || actualKeys.some((key, index) => key !== expectedKeys[index])
+        || candidate.authority !== 'strict-read-only'
+        || !validEffects(candidate.attemptedEffects)
+        || !validEffects(candidate.suppressedEffects)
+        || typeof candidate.inputDigest !== 'string'
+        || !SHA256_HEX_PATTERN.test(candidate.inputDigest)
+        || typeof candidate.responseDigest !== 'string'
+        || !SHA256_HEX_PATTERN.test(candidate.responseDigest)) {
+        throw new Error('STRICT_DIAGNOSE_RECEIPT_INVALID');
+    }
+}
+export function verifyStrictDiagnoseReceiptV1(value, rawArgs, responseInstructions) {
+    assertStrictDiagnoseReceiptV1(value);
+    const receipt = value;
+    if (receipt.inputDigest !== invokeInputSha256(rawArgs)
+        || receipt.responseDigest !== invokeInputSha256(responseInstructions)
+        || JSON.stringify(receipt.attemptedEffects) !== JSON.stringify(receipt.suppressedEffects)) {
+        throw new Error('STRICT_DIAGNOSE_RECEIPT_BINDING_CONFLICT');
+    }
+}

package/packages/shared/dist/yoloop/epic-terminal-git.js

@@ -0,0 +1,227 @@
+/** Public contracts and pure safety decisions for epic-owned terminal Git. */
+export const EPIC_TERMINAL_GIT_REASON_CODES = Object.freeze({
+    READY: 'epic-terminal-git-ready',
+    ALREADY_COMPLETE: 'epic-terminal-git-already-complete',
+    ORIGIN_MISSING: 'epic-origin-branch-missing',
+    EXECUTION_MISSING: 'epic-execution-branch-missing',
+    SAME_BRANCH: 'epic-origin-equals-execution',
+    LOCAL_GATES_REQUIRED: 'epic-local-gates-required',
+    STORY_CHECKPOINTS_REQUIRED: 'epic-story-checkpoints-required',
+    LEASE_ACTIVE: 'epic-writer-lease-active',
+    HEAD_MISMATCH: 'epic-execution-head-mismatch',
+    GRAPH_REVISION_MISMATCH: 'epic-graph-revision-mismatch',
+    MERGE_CONFLICT: 'epic-terminal-merge-conflict',
+    REMOTE_POLICY_DENIED: 'epic-terminal-remote-policy-denied',
+    RETRY_ELIGIBLE: 'epic-terminal-retry-eligible',
+    RECOVERED_PHYSICAL_PUSH: 'epic-terminal-recovered-physical-push',
+    OWNERSHIP_UNPROVEN: 'git-resource-ownership-unproven',
+    RESOURCE_ACTIVE: 'git-resource-active',
+    RESOURCE_ORIGIN: 'git-resource-is-origin',
+    RESOURCE_CURRENT: 'git-resource-is-current',
+    RESOURCE_PROTECTED: 'git-resource-protected',
+    UNIQUE_COMMITS: 'git-resource-has-unique-commits',
+    INTEGRATION_UNPROVEN: 'git-resource-integration-unproven',
+    SAFE_TO_RECONCILE: 'git-resource-safe-to-reconcile',
+    ALREADY_RECONCILED: 'git-resource-already-reconciled',
+    AGGREGATE_QA_REQUIRED: 'epic-aggregate-qa-receipt-required',
+    AGGREGATE_QA_STALE: 'epic-aggregate-qa-receipt-stale',
+    ORIGIN_BINDING_REQUIRED: 'epic-origin-binding-required',
+    PROVIDER_TRUTH_UNKNOWN: 'git-resource-provider-truth-unknown',
+    WORKTREE_ACTIVE: 'git-resource-worktree-active',
+    RESOURCE_RACED: 'git-resource-expected-oid-raced',
+    REMOTE_DELETE_CAS_UNAVAILABLE: 'git-resource-remote-delete-cas-unavailable',
+    ORIGIN_CAPTURE_WINDOW_MISSED: 'epic-origin-binding-capture-window-missed',
+    ORIGIN_PHYSICAL_DRIFT: 'epic-origin-binding-physical-drift',
+    PHYSICAL_REVALIDATION_REQUIRED: 'epic-terminal-physical-revalidation-required',
+    PHYSICAL_ANCESTRY_UNPROVEN: 'epic-terminal-physical-ancestry-unproven',
+    PR_STRICT_BASE_GUARD_REQUIRED: 'epic-terminal-pr-strict-base-guard-required',
+    PR_BASE_GUARD_UNVERIFIABLE: 'epic-terminal-pr-base-guard-unverifiable',
+    PR_MERGE_QUEUE_LOCAL_GATE_REQUIRED: 'epic-terminal-pr-merge-queue-local-gate-required',
+});
+export function validateEpicTerminalGitDirective(directive, actual) {
+    const reasons = [];
+    if (!nonEmpty(directive.originBranch))
+        reasons.push(EPIC_TERMINAL_GIT_REASON_CODES.ORIGIN_MISSING);
+    if (!nonEmpty(directive.executionBranch))
+        reasons.push(EPIC_TERMINAL_GIT_REASON_CODES.EXECUTION_MISSING);
+    if (directive.originBranch === directive.executionBranch)
+        reasons.push(EPIC_TERMINAL_GIT_REASON_CODES.SAME_BRANCH);
+    if (directive.localGates?.passed !== true || directive.localGates.receiptRefs.length === 0) {
+        reasons.push(EPIC_TERMINAL_GIT_REASON_CODES.LOCAL_GATES_REQUIRED);
+    }
+    const aggregate = actual.aggregateQaReceipt;
+    const directedAggregate = directive.localGates?.aggregateQaReceipt;
+    if (!aggregate
+        || aggregate.schemaVersion !== 1
+        || aggregate.evidenceVersion !== 'p205-execution-v2'
+        || aggregate.producer !== 'local-yolo-tdd'
+        || aggregate.contract !== 'P205-CI-02'
+        || aggregate.command !== 'node scripts/test-root.mjs --gate complete'
+        || aggregate.verdict !== 'passed'
+        || aggregate.executionHeadSha !== actual.executionHeadSha
+        || aggregate.executionHeadSha !== directive.expectedExecutionHeadSha
+        || aggregate.graphRevision !== directive.graphRevision
+        || aggregate.receiptRef.length === 0
+        || aggregate.gateIds.length === 0
+        || !isHash(aggregate.manifestDigest)
+        || !isHash(aggregate.resultDigest)
+        || !directedAggregate
+        || directedAggregate.executionHeadSha !== aggregate.executionHeadSha
+        || directedAggregate.graphRevision !== aggregate.graphRevision
+        || directedAggregate.checkedAt !== aggregate.checkedAt
+        || directedAggregate.receiptRef !== aggregate.receiptRef
+        || directedAggregate.manifestDigest !== aggregate.manifestDigest
+        || directedAggregate.resultDigest !== aggregate.resultDigest
+        || !sameSet(directedAggregate.gateIds, aggregate.gateIds)
+        || !directive.localGates.receiptRefs.includes(aggregate.receiptRef)) {
+        reasons.push(EPIC_TERMINAL_GIT_REASON_CODES.AGGREGATE_QA_REQUIRED);
+    }
+    else if (!Number.isFinite(Date.parse(aggregate.checkedAt)) || actual.nowIso && (Date.parse(actual.nowIso) - Date.parse(aggregate.checkedAt) > 30 * 60 * 1000
+        || Date.parse(aggregate.checkedAt) - Date.parse(actual.nowIso) > 5 * 60 * 1000)) {
+        reasons.push(EPIC_TERMINAL_GIT_REASON_CODES.AGGREGATE_QA_STALE);
+    }
+    const originBinding = actual.originBinding;
+    if (!originBinding
+        || originBinding.schemaVersion !== 1
+        || originBinding.capturedFromCurrentCheckout !== true
+        || originBinding.originBranch !== directive.originBranch
+        || originBinding.executionBranch !== directive.executionBranch
+        || !isSha(originBinding.originHeadSha)
+        || !Number.isFinite(Date.parse(originBinding.capturedAt))) {
+        reasons.push(EPIC_TERMINAL_GIT_REASON_CODES.ORIGIN_BINDING_REQUIRED);
+    }
+    if (actual.writerLeaseActive)
+        reasons.push(EPIC_TERMINAL_GIT_REASON_CODES.LEASE_ACTIVE);
+    if (!sameSet(directive.storyCheckpointIds, actual.acceptedCheckpointIds)) {
+        reasons.push(EPIC_TERMINAL_GIT_REASON_CODES.STORY_CHECKPOINTS_REQUIRED);
+    }
+    if (!isSha(directive.expectedExecutionHeadSha) || directive.expectedExecutionHeadSha !== actual.executionHeadSha) {
+        reasons.push(EPIC_TERMINAL_GIT_REASON_CODES.HEAD_MISMATCH);
+    }
+    if (directive.graphRevision && directive.graphRevision !== actual.graphRevision) {
+        reasons.push(EPIC_TERMINAL_GIT_REASON_CODES.GRAPH_REVISION_MISMATCH);
+    }
+    if (!/^[a-f0-9]{64}$/i.test(directive.graphRevision))
+        reasons.push(EPIC_TERMINAL_GIT_REASON_CODES.GRAPH_REVISION_MISMATCH);
+    if (actual.existingReceipt?.physicalStatus === 'pushed'
+        && actual.existingReceipt.idempotencyKey === directive.idempotencyKey
+        && actual.existingReceipt.executionHeadSha === directive.expectedExecutionHeadSha) {
+        return { ready: true, reasonCodes: [EPIC_TERMINAL_GIT_REASON_CODES.ALREADY_COMPLETE] };
+    }
+    return reasons.length === 0
+        ? { ready: true, reasonCodes: [EPIC_TERMINAL_GIT_REASON_CODES.READY] }
+        : { ready: false, reasonCodes: unique(reasons) };
+}
+/**
+ * Fail-closed ownership and integration classifier. A canonical-looking name is
+ * never sufficient: state/receipt proof plus convention and provider metadata
+ * or PR head/base evidence are required before any destructive action.
+ */
+export function classifyGitReconciliationCandidate(candidate) {
+    const evidence = unique(candidate.ownershipEvidence);
+    const hasDurableProof = evidence.includes('state_reference') || evidence.includes('terminal_receipt');
+    const hasConvention = evidence.includes('canonical_convention');
+    const hasCorroboration = candidate.kind === 'pull_request'
+        ? evidence.includes('pr_head_base_match')
+        : evidence.includes('managed_metadata');
+    const managed = hasDurableProof && hasConvention && hasCorroboration;
+    const preserve = (...reasonCodes) => Object.freeze({
+        schemaVersion: 1,
+        resourceId: candidate.resourceId,
+        action: 'preserve',
+        managed,
+        reasonCodes: Object.freeze(unique(reasonCodes)),
+        evidence: Object.freeze(evidence),
+        publicSafe: true,
+    });
+    if (candidate.lifecycle === 'already_absent' && candidate.providerVerified) {
+        return Object.freeze({ schemaVersion: 1, resourceId: candidate.resourceId, action: 'no_op', managed, reasonCodes: [EPIC_TERMINAL_GIT_REASON_CODES.ALREADY_RECONCILED], evidence, publicSafe: true });
+    }
+    if (!managed)
+        return preserve(EPIC_TERMINAL_GIT_REASON_CODES.OWNERSHIP_UNPROVEN);
+    if (!candidate.providerVerified)
+        return preserve(EPIC_TERMINAL_GIT_REASON_CODES.PROVIDER_TRUTH_UNKNOWN);
+    if (candidate.origin)
+        return preserve(EPIC_TERMINAL_GIT_REASON_CODES.RESOURCE_ORIGIN);
+    if (candidate.current)
+        return preserve(EPIC_TERMINAL_GIT_REASON_CODES.RESOURCE_CURRENT);
+    if (candidate.worktreeActive)
+        return preserve(EPIC_TERMINAL_GIT_REASON_CODES.WORKTREE_ACTIVE);
+    if (candidate.protected)
+        return preserve(EPIC_TERMINAL_GIT_REASON_CODES.RESOURCE_PROTECTED);
+    if (candidate.lifecycle === 'active')
+        return preserve(EPIC_TERMINAL_GIT_REASON_CODES.RESOURCE_ACTIVE);
+    if (candidate.hasExclusiveCommits)
+        return preserve(EPIC_TERMINAL_GIT_REASON_CODES.UNIQUE_COMMITS);
+    if (candidate.previouslyReconciled)
+        return preserve(EPIC_TERMINAL_GIT_REASON_CODES.RESOURCE_RACED);
+    if (!candidate.commitsReachable && !candidate.contentEquivalent) {
+        return preserve(EPIC_TERMINAL_GIT_REASON_CODES.INTEGRATION_UNPROVEN);
+    }
+    // Generic Git deletion has no safe expected-OID guard without force flags.
+    // The GitHub capability guards both target and integration origin atomically.
+    if (candidate.kind === 'remote_branch' && candidate.remoteDeletionCas !== 'github-update-refs-v1') {
+        return preserve(EPIC_TERMINAL_GIT_REASON_CODES.REMOTE_DELETE_CAS_UNAVAILABLE);
+    }
+    const action = candidate.kind === 'local_branch'
+        ? 'delete_local_branch'
+        : candidate.kind === 'remote_branch' ? 'delete_remote_branch' : 'close_pull_request';
+    return Object.freeze({
+        schemaVersion: 1,
+        resourceId: candidate.resourceId,
+        action,
+        managed: true,
+        reasonCodes: [EPIC_TERMINAL_GIT_REASON_CODES.SAFE_TO_RECONCILE],
+        evidence: Object.freeze(evidence),
+        publicSafe: true,
+    });
+}
+export function reconcileTerminalReceipt(current, requested) {
+    if (!current)
+        return { kind: 'accepted', receipt: requested };
+    if (current.idempotencyKey !== requested.idempotencyKey)
+        return { kind: 'accepted', receipt: requested };
+    if (current.epicId === requested.epicId
+        && current.executionBranch === requested.executionBranch
+        && current.originBranch === requested.originBranch
+        && current.baseSha === requested.baseSha
+        && current.executionHeadSha === requested.executionHeadSha
+        && current.mergeSha === requested.mergeSha
+        && current.pushedSha === requested.pushedSha
+        && current.physicalStatus === requested.physicalStatus) {
+        if (requested.candidateQa && JSON.stringify(current.candidateQa) !== JSON.stringify(requested.candidateQa)) {
+            return { kind: 'accepted', receipt: requested };
+        }
+        if (requested.providerGuard && JSON.stringify(current.providerGuard) !== JSON.stringify(requested.providerGuard)) {
+            return { kind: 'accepted', receipt: requested };
+        }
+        return { kind: 'reused', receipt: current };
+    }
+    // A failed/prepared attempt is not integrated physical truth. The root has to
+    // revalidate a new candidate, but its successful retry must replace that debt.
+    // Never rewrite a pushed/merged receipt or move an idempotency key to a new owner.
+    if (current.retryEligible && !current.pushedSha
+        && ['prepared', 'blocked_local_or_repo', 'denied_external_gate'].includes(current.physicalStatus)
+        && current.epicId === requested.epicId
+        && current.executionBranch === requested.executionBranch
+        && current.originBranch === requested.originBranch
+        && current.executionHeadSha === requested.executionHeadSha) {
+        return { kind: 'accepted', receipt: requested };
+    }
+    return { kind: 'blocked', reasonCode: 'epic-terminal-receipt-idempotency-conflict' };
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isSha(value) {
+    return /^[a-f0-9]{7,64}$/i.test(value);
+}
+function isHash(value) {
+    return typeof value === 'string' && /^[a-f0-9]{64}$/i.test(value);
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function sameSet(left, right) {
+    return left.length === right.length && [...left].sort().every((item, index) => item === [...right].sort()[index]);
+}