@neuraloom/contracts 0.0.0-stage → 0.1.23

package/dist/schemas/workflow/engineering-context.schema.js

@@ -0,0 +1,566 @@
+"use strict";
+/**
+ * Engineering Context — durable, revision-aware task context that survives agent resets.
+ *
+ * Connects the existing mechanisms (task capsule → context bundle → durable execution
+ * spine → workflow artifacts) into one task-specific workflow:
+ *
+ *   capsule (intake)  →  engineering brief (evidence assembly, bounded)
+ *                     →  task checkpoint (durable milestones, provider-independent)
+ *                     →  verification result (what was genuinely tested)
+ *                     →  resume (invalidate stale evidence, rebuild brief, continue)
+ *
+ * Canonical storage: workflow_artifacts rows with artifact_type in
+ *   'engineeringBrief' | 'taskCheckpoint' | 'verificationResult'.
+ * Execution linkage: execution_runs / execution_tasks (CAN-021) — never a second spine.
+ *
+ * Source facts, accepted decisions and hypotheses are separate fields by design:
+ * an agent's plausible interpretation must never become an authoritative fact
+ * merely because it was saved.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EngineeringContextTraceSchema = exports.EngineeringContextMissingReasonSchema = exports.CheckpointMissReasonSchema = exports.ENGINEERING_BRIEF_PREPARATION_STAGE_ID = exports.ENGINEERING_CHECKPOINT_STAGE_METADATA_KEY = exports.CheckpointResumeResponseSchema = exports.CheckpointResumeOutcomeSchema = exports.CheckpointResumeRequestSchema = exports.StaleRevisionSchema = exports.InvalidatedEvidenceSchema = exports.EvidenceInvalidationReasonSchema = exports.TaskCheckpointPayloadSchema = exports.CheckpointProviderSchema = exports.EngineeringBriefPayloadSchema = exports.EngineeringBriefBudgetSchema = exports.CompletedInvestigationSchema = exports.InvestigationMethodSchema = exports.VerificationResultPayloadSchema = exports.ToolchainIdentitySchema = exports.VerificationStatusSchema = exports.PatchRefSchema = exports.KnownFailureSchema = exports.KnownFailureStatusSchema = exports.HypothesisSchema = exports.HypothesisStatusSchema = exports.DecisionSchema = exports.DecisionSourceSchema = exports.MandatoryRuleSchema = exports.MandatoryRuleSourceSchema = exports.EvidenceOmissionSchema = exports.EvidenceRelationshipSchema = exports.EvidenceRefSchema = exports.EvidenceRelevanceSchema = exports.EvidenceKindSchema = exports.RevisionMapSchema = exports.RevisionMapEntrySchema = exports.RevisionRoleSchema = exports.CommitShaSchema = exports.VERIFICATION_ERROR_EXCERPT_MAX_CHARS = exports.ENGINEERING_BRIEF_MAX_RELATIONSHIPS = exports.ENGINEERING_BRIEF_MAX_EVIDENCE_REFS = exports.ENGINEERING_BRIEF_DEFAULT_MAX_CHARS = exports.ENGINEERING_CONTEXT_SCHEMA_VERSION = void 0;
+exports.computeEvidenceInvalidation = computeEvidenceInvalidation;
+exports.serializeRevisionMap = serializeRevisionMap;
+exports.buildEngineeringContextCacheMaterial = buildEngineeringContextCacheMaterial;
+exports.estimateTokensFromChars = estimateTokensFromChars;
+exports.readTaskCheckpointFromStageMetadata = readTaskCheckpointFromStageMetadata;
+exports.mergeTaskCheckpointIntoStageMetadata = mergeTaskCheckpointIntoStageMetadata;
+exports.computeContractChangeInvalidation = computeContractChangeInvalidation;
+exports.diagnoseEngineeringContext = diagnoseEngineeringContext;
+const zod_1 = require("zod");
+exports.ENGINEERING_CONTEXT_SCHEMA_VERSION = '1.0.0';
+/** Starting budget for a worker brief (chars ≈ tokens × 4). Tunable, not a universal limit. */
+exports.ENGINEERING_BRIEF_DEFAULT_MAX_CHARS = 24_000;
+exports.ENGINEERING_BRIEF_MAX_EVIDENCE_REFS = 200;
+exports.ENGINEERING_BRIEF_MAX_RELATIONSHIPS = 400;
+exports.VERIFICATION_ERROR_EXCERPT_MAX_CHARS = 4_000;
+// ─── Revision map ─────────────────────────────────────────────────────────────
+exports.CommitShaSchema = zod_1.z.string().regex(/^[a-f0-9]{7,64}$/i, 'commit must be a 7–64 char hex sha');
+exports.RevisionRoleSchema = zod_1.z.enum(['primary', 'dependency', 'consumer']);
+/**
+ * One participating repository at an exact revision. A task across connected
+ * codebases needs one entry per repo — a single commit SHA is insufficient.
+ * `installedVersions` records what a consuming app actually has installed of a
+ * shared package so an agent cannot assume a new producer API is available.
+ */
+exports.RevisionMapEntrySchema = zod_1.z.object({
+    repo: zod_1.z.string().min(1),
+    branch: zod_1.z.string().min(1).nullable(),
+    commit: exports.CommitShaSchema,
+    dirty: zod_1.z.boolean().default(false),
+    uncommittedFiles: zod_1.z.array(zod_1.z.string()).default([]),
+    role: exports.RevisionRoleSchema.default('primary'),
+    installedVersions: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+});
+exports.RevisionMapSchema = zod_1.z.array(exports.RevisionMapEntrySchema).min(1);
+// ─── Evidence ─────────────────────────────────────────────────────────────────
+exports.EvidenceKindSchema = zod_1.z.enum([
+    'node',
+    'edge',
+    'file',
+    'symbol',
+    'route',
+    'contract',
+    'drift_finding',
+    'decision',
+    'test',
+    'verification',
+    'log',
+    'artifact',
+    'knowledge',
+]);
+/** How an evidence item was selected — exact resolution ranks above keyword hits. */
+exports.EvidenceRelevanceSchema = zod_1.z.enum(['exact', 'dependency', 'reference', 'governance', 'keyword']);
+exports.EvidenceRefSchema = zod_1.z.object({
+    /** Stable evidence id, e.g. `node:<uuid>`, `file:<path>`, `drift:<finding-id>`. */
+    id: zod_1.z.string().min(1),
+    kind: exports.EvidenceKindSchema,
+    /** Path, stable key, artifact uuid, route path or finding id the id points at. */
+    ref: zod_1.z.string().min(1),
+    label: zod_1.z.string().optional(),
+    repo: zod_1.z.string().optional(),
+    /** Commit the evidence was observed at; null when not revision-bound. */
+    revision: zod_1.z.string().nullable().default(null),
+    /** Content hash (sha256) when the evidence body was hashed; null otherwise. */
+    contentHash: zod_1.z.string().nullable().default(null),
+    relevance: exports.EvidenceRelevanceSchema,
+    /** Resolver that selected this item (symbol_index, dependency_traversal, …). */
+    selectedBy: zod_1.z.string().optional(),
+});
+exports.EvidenceRelationshipSchema = zod_1.z.object({
+    sourceId: zod_1.z.string().min(1),
+    targetId: zod_1.z.string().min(1),
+    relation: zod_1.z.string().min(1),
+});
+/** Explicit, expandable truncation: what was left out and how to fetch more. */
+exports.EvidenceOmissionSchema = zod_1.z.object({
+    kind: exports.EvidenceKindSchema,
+    totalCount: zod_1.z.number().int().min(0),
+    omittedCount: zod_1.z.number().int().min(0),
+    continuationToken: zod_1.z.string().nullable().default(null),
+});
+exports.MandatoryRuleSourceSchema = zod_1.z.enum([
+    'constitution',
+    'repo_policy',
+    'tombstone',
+    'ownership',
+    'capsule',
+    'agent_rules',
+]);
+/** Governing requirements that context reduction must never drop. */
+exports.MandatoryRuleSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1),
+    source: exports.MandatoryRuleSourceSchema,
+    text: zod_1.z.string().min(1),
+});
+exports.DecisionSourceSchema = zod_1.z.enum(['human', 'agent']);
+exports.DecisionSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1),
+    decision: zod_1.z.string().min(1),
+    rationale: zod_1.z.string().default(''),
+    evidenceIds: zod_1.z.array(zod_1.z.string()).default([]),
+    source: exports.DecisionSourceSchema,
+    decidedAt: zod_1.z.string().datetime(),
+});
+exports.HypothesisStatusSchema = zod_1.z.enum(['open', 'confirmed', 'rejected']);
+exports.HypothesisSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1),
+    statement: zod_1.z.string().min(1),
+    status: exports.HypothesisStatusSchema,
+    evidenceIds: zod_1.z.array(zod_1.z.string()).default([]),
+    note: zod_1.z.string().optional(),
+});
+exports.KnownFailureStatusSchema = zod_1.z.enum(['open', 'resolved', 'rejected']);
+exports.KnownFailureSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1),
+    summary: zod_1.z.string().min(1),
+    evidenceIds: zod_1.z.array(zod_1.z.string()).default([]),
+    status: exports.KnownFailureStatusSchema.default('open'),
+});
+// ─── Patch / verification ─────────────────────────────────────────────────────
+exports.PatchRefSchema = zod_1.z.object({
+    repo: zod_1.z.string().min(1),
+    branch: zod_1.z.string().min(1).nullable(),
+    worktree: zod_1.z.string().nullable().default(null),
+    headSha: exports.CommitShaSchema.nullable(),
+    dirty: zod_1.z.boolean().default(false),
+    /** sha256 of the current diff, so a resumed agent can detect a changed patch. */
+    diffHash: zod_1.z.string().nullable().default(null),
+    patchArtifactId: zod_1.z.string().uuid().nullable().default(null),
+});
+exports.VerificationStatusSchema = zod_1.z.enum(['passed', 'failed', 'blocked', 'not_run']);
+exports.ToolchainIdentitySchema = zod_1.z.object({
+    node: zod_1.z.string().optional(),
+    pnpm: zod_1.z.string().optional(),
+    os: zod_1.z.string().optional(),
+    environment: zod_1.z.string().optional(),
+});
+/**
+ * One verification result: exact revision + patch tested, command identity,
+ * failure excerpt first, full log on demand. Producer tests passing does not
+ * prove the consumer still works — `contractSides` records both.
+ */
+exports.VerificationResultPayloadSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(exports.ENGINEERING_CONTEXT_SCHEMA_VERSION),
+    taskId: zod_1.z.string().min(1),
+    checkpointSequence: zod_1.z.number().int().min(0).nullable().default(null),
+    revision: zod_1.z.object({ repo: zod_1.z.string().min(1), commit: exports.CommitShaSchema }),
+    patchRef: exports.PatchRefSchema.nullable().default(null),
+    command: zod_1.z.string().min(1),
+    cwd: zod_1.z.string().min(1),
+    toolchain: exports.ToolchainIdentitySchema.default({}),
+    exitCode: zod_1.z.number().int().nullable(),
+    status: exports.VerificationStatusSchema,
+    failingTests: zod_1.z.array(zod_1.z.string()).default([]),
+    errorExcerpt: zod_1.z.string().max(exports.VERIFICATION_ERROR_EXCERPT_MAX_CHARS).nullable().default(null),
+    logArtifactRef: zod_1.z.string().nullable().default(null),
+    /** True when the same failure reproduces without the patch; null when unknown. */
+    preExistingFailure: zod_1.z.boolean().nullable().default(null),
+    affectedSymbols: zod_1.z.array(zod_1.z.string()).default([]),
+    contractSides: zod_1.z
+        .object({
+        producer: exports.VerificationStatusSchema.optional(),
+        consumer: exports.VerificationStatusSchema.optional(),
+    })
+        .optional(),
+    durationMs: zod_1.z.number().int().min(0).nullable().default(null),
+    recordedAt: zod_1.z.string().datetime(),
+});
+// ─── Investigation ────────────────────────────────────────────────────────────
+exports.InvestigationMethodSchema = zod_1.z.enum([
+    'symbol_index',
+    'dependency_traversal',
+    'route_trace',
+    'knowledge_retrieval',
+    'git_diff',
+    'test_mapping',
+    'manual',
+]);
+exports.CompletedInvestigationSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1),
+    query: zod_1.z.string().min(1),
+    method: exports.InvestigationMethodSchema,
+    summary: zod_1.z.string().default(''),
+    evidenceIds: zod_1.z.array(zod_1.z.string()).default([]),
+});
+// ─── Engineering brief ────────────────────────────────────────────────────────
+exports.EngineeringBriefBudgetSchema = zod_1.z.object({
+    maxChars: zod_1.z.number().int().min(1),
+    usedChars: zod_1.z.number().int().min(0),
+    estimatedTokens: zod_1.z.number().int().min(0),
+});
+/**
+ * The compact worker brief. Objective → rules → relevant implementation →
+ * relationships → known failures → acceptance criteria → next action.
+ */
+exports.EngineeringBriefPayloadSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(exports.ENGINEERING_CONTEXT_SCHEMA_VERSION),
+    taskId: zod_1.z.string().min(1),
+    capsuleArtifactId: zod_1.z.string().uuid().nullable().default(null),
+    /** Execution task (execution_tasks.id) whose checkpoint this brief was built from. */
+    executionTaskId: zod_1.z.string().uuid().nullable().default(null),
+    executionRunId: zod_1.z.string().uuid().nullable().default(null),
+    compiledAt: zod_1.z.string().datetime(),
+    objective: zod_1.z.string().min(1),
+    acceptanceCriteria: zod_1.z.array(zod_1.z.string()),
+    mandatoryRules: zod_1.z.array(exports.MandatoryRuleSchema),
+    revisionMap: exports.RevisionMapSchema,
+    policyVersion: zod_1.z.string().nullable().default(null),
+    selectedEvidence: zod_1.z.array(exports.EvidenceRefSchema).max(exports.ENGINEERING_BRIEF_MAX_EVIDENCE_REFS),
+    relationships: zod_1.z.array(exports.EvidenceRelationshipSchema).max(exports.ENGINEERING_BRIEF_MAX_RELATIONSHIPS),
+    omissions: zod_1.z.array(exports.EvidenceOmissionSchema),
+    knownFailures: zod_1.z.array(exports.KnownFailureSchema),
+    priorDecisions: zod_1.z.array(exports.DecisionSchema),
+    nextAction: zod_1.z.string().min(1),
+    budget: exports.EngineeringBriefBudgetSchema,
+    /** Content-addressed identity: repos + revisions + policy + scope + task. */
+    cacheKey: zod_1.z.string().min(1),
+    /** Hash of the access scope (never raw scope identifiers). */
+    scopeKey: zod_1.z.string().min(1),
+    promptMarkdown: zod_1.z.string().min(1),
+});
+// ─── Task checkpoint ──────────────────────────────────────────────────────────
+exports.CheckpointProviderSchema = zod_1.z.object({
+    conversationId: zod_1.z.string().nullable().default(null),
+    responseId: zod_1.z.string().nullable().default(null),
+    model: zod_1.z.string().nullable().default(null),
+});
+/**
+ * Durable milestone. Sufficient to resume in a fresh conversation with a
+ * different model; a provider conversation id is an optional convenience.
+ * Stores concise conclusions and evidence — never private reasoning.
+ */
+exports.TaskCheckpointPayloadSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(exports.ENGINEERING_CONTEXT_SCHEMA_VERSION),
+    taskId: zod_1.z.string().min(1),
+    executionRunId: zod_1.z.string().uuid().nullable().default(null),
+    executionTaskId: zod_1.z.string().uuid().nullable().default(null),
+    cortexTaskId: zod_1.z.string().nullable().default(null),
+    sequence: zod_1.z.number().int().min(0),
+    milestone: zod_1.z.string().min(1),
+    createdAt: zod_1.z.string().datetime(),
+    revisionMap: exports.RevisionMapSchema,
+    policyVersion: zod_1.z.string().nullable().default(null),
+    completedInvestigation: zod_1.z.array(exports.CompletedInvestigationSchema).default([]),
+    evidence: zod_1.z.array(exports.EvidenceRefSchema).default([]),
+    decisions: zod_1.z.array(exports.DecisionSchema).default([]),
+    hypotheses: zod_1.z.array(exports.HypothesisSchema).default([]),
+    patchRef: exports.PatchRefSchema.nullable().default(null),
+    verification: zod_1.z.array(exports.VerificationResultPayloadSchema).default([]),
+    remainingWork: zod_1.z.array(zod_1.z.string()).default([]),
+    nextAction: zod_1.z.string().min(1),
+    provider: exports.CheckpointProviderSchema.default({}),
+});
+// ─── Resume ───────────────────────────────────────────────────────────────────
+exports.EvidenceInvalidationReasonSchema = zod_1.z.enum([
+    'revision_changed',
+    'file_changed',
+    'repo_missing',
+    'policy_changed',
+    'hash_mismatch',
+]);
+exports.InvalidatedEvidenceSchema = zod_1.z.object({
+    evidenceId: zod_1.z.string().min(1),
+    reason: exports.EvidenceInvalidationReasonSchema,
+});
+exports.StaleRevisionSchema = zod_1.z.object({
+    repo: zod_1.z.string().min(1),
+    checkpointCommit: zod_1.z.string().nullable(),
+    currentCommit: zod_1.z.string().nullable(),
+});
+exports.CheckpointResumeRequestSchema = zod_1.z.object({
+    taskId: zod_1.z.string().min(1),
+    currentRevisionMap: exports.RevisionMapSchema,
+    /** Repo-relative paths changed since the checkpoint (git diff + graph diff). */
+    changedFiles: zod_1.z.array(zod_1.z.string()).default([]),
+    policyVersion: zod_1.z.string().nullable().default(null),
+});
+exports.CheckpointResumeOutcomeSchema = zod_1.z.enum(['resumed', 'no_checkpoint']);
+exports.CheckpointResumeResponseSchema = zod_1.z.object({
+    taskId: zod_1.z.string().min(1),
+    outcome: exports.CheckpointResumeOutcomeSchema,
+    /** Execution task the resumed checkpoint lives on (single persistence path). */
+    executionTaskId: zod_1.z.string().uuid().nullable(),
+    sequence: zod_1.z.number().int().min(0).nullable(),
+    staleRevisions: zod_1.z.array(exports.StaleRevisionSchema),
+    validEvidence: zod_1.z.array(exports.EvidenceRefSchema),
+    invalidatedEvidence: zod_1.z.array(exports.InvalidatedEvidenceSchema),
+    /** Hypotheses whose supporting evidence was invalidated are re-opened, not deleted. */
+    reopenedHypothesisIds: zod_1.z.array(zod_1.z.string()),
+    /** Verification results that no longer describe the current revision/patch. */
+    staleVerificationCount: zod_1.z.number().int().min(0),
+    completedInvestigation: zod_1.z.array(exports.CompletedInvestigationSchema),
+    decisions: zod_1.z.array(exports.DecisionSchema),
+    remainingWork: zod_1.z.array(zod_1.z.string()),
+    nextAction: zod_1.z.string().nullable(),
+    brief: exports.EngineeringBriefPayloadSchema.nullable(),
+});
+function normalizePath(p) {
+    return p.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+}
+function evidencePathCandidates(ref) {
+    const out = [];
+    if (ref.kind === 'file' || ref.kind === 'symbol' || ref.kind === 'test' || ref.kind === 'contract' || ref.kind === 'route' || ref.kind === 'node') {
+        out.push(normalizePath(ref.ref));
+    }
+    const fromId = ref.id.split(':').slice(1).join(':');
+    if (fromId.length > 0) {
+        out.push(normalizePath(fromId.replace(/@[a-f0-9]{7,64}$/i, '')));
+    }
+    return out;
+}
+/**
+ * Compare a checkpoint against the current revision map and changed files.
+ * Evidence bound to a repo whose commit moved is invalidated only when its file
+ * is in `changedFiles` (git diff + graph diff) or when it is revision-bound to
+ * the old commit and no changed-file list was supplied. Evidence whose repo is
+ * no longer present is invalidated. A policy version change invalidates
+ * governance evidence. Everything else stays valid — refresh what changed,
+ * retain what remains valid.
+ */
+function computeEvidenceInvalidation(input) {
+    const current = new Map(input.currentRevisionMap.map((e) => [e.repo, e]));
+    const previous = new Map(input.checkpoint.revisionMap.map((e) => [e.repo, e]));
+    const changed = new Set((input.changedFiles ?? []).map(normalizePath));
+    const changedListSupplied = (input.changedFiles ?? []).length > 0;
+    const policyChanged = input.policyVersion !== undefined &&
+        input.checkpoint.policyVersion !== null &&
+        input.policyVersion !== null &&
+        input.policyVersion !== input.checkpoint.policyVersion;
+    const staleRevisions = [];
+    const movedRepos = new Set();
+    const missingRepos = new Set();
+    for (const [repo, prev] of previous) {
+        const cur = current.get(repo);
+        if (cur === undefined) {
+            missingRepos.add(repo);
+            staleRevisions.push({ repo, checkpointCommit: prev.commit, currentCommit: null });
+            continue;
+        }
+        if (cur.commit.toLowerCase() !== prev.commit.toLowerCase() || cur.dirty !== prev.dirty) {
+            movedRepos.add(repo);
+            staleRevisions.push({ repo, checkpointCommit: prev.commit, currentCommit: cur.commit });
+        }
+    }
+    const primaryRepo = input.checkpoint.revisionMap.find((e) => e.role === 'primary')?.repo ?? input.checkpoint.revisionMap[0]?.repo;
+    const validEvidence = [];
+    const invalidatedEvidence = [];
+    for (const ref of input.checkpoint.evidence) {
+        const repo = ref.repo ?? primaryRepo;
+        if (repo !== undefined && missingRepos.has(repo)) {
+            invalidatedEvidence.push({ evidenceId: ref.id, reason: 'repo_missing' });
+            continue;
+        }
+        if (policyChanged && ref.relevance === 'governance') {
+            invalidatedEvidence.push({ evidenceId: ref.id, reason: 'policy_changed' });
+            continue;
+        }
+        const candidates = evidencePathCandidates(ref);
+        if (candidates.some((c) => changed.has(c) || [...changed].some((f) => c.length > 0 && (f.startsWith(`${c}/`) || c.startsWith(`${f}:`))))) {
+            invalidatedEvidence.push({ evidenceId: ref.id, reason: 'file_changed' });
+            continue;
+        }
+        if (repo !== undefined && movedRepos.has(repo)) {
+            const cur = current.get(repo);
+            const boundToOldRevision = ref.revision !== null && cur !== undefined && ref.revision.toLowerCase() !== cur.commit.toLowerCase();
+            if (boundToOldRevision && !changedListSupplied) {
+                invalidatedEvidence.push({ evidenceId: ref.id, reason: 'revision_changed' });
+                continue;
+            }
+        }
+        validEvidence.push(ref);
+    }
+    const invalidIds = new Set(invalidatedEvidence.map((e) => e.evidenceId));
+    const reopenedHypothesisIds = input.checkpoint.hypotheses
+        .filter((h) => h.status !== 'open' && h.evidenceIds.some((id) => invalidIds.has(id)))
+        .map((h) => h.id);
+    const staleVerificationCount = input.checkpoint.verification.filter((v) => {
+        const cur = current.get(v.revision.repo);
+        if (cur === undefined)
+            return true;
+        if (cur.commit.toLowerCase() !== v.revision.commit.toLowerCase())
+            return true;
+        if (v.patchRef !== null && input.checkpoint.patchRef !== null && v.patchRef.diffHash !== null && input.checkpoint.patchRef.diffHash !== null) {
+            return v.patchRef.diffHash !== input.checkpoint.patchRef.diffHash;
+        }
+        return false;
+    }).length;
+    return {
+        staleRevisions,
+        validEvidence,
+        invalidatedEvidence,
+        reopenedHypothesisIds,
+        staleVerificationCount,
+        policyChanged,
+    };
+}
+/** Stable, order-independent serialization for cache keys. */
+function serializeRevisionMap(map) {
+    return [...map]
+        .sort((a, b) => a.repo.localeCompare(b.repo))
+        .map((e) => `${e.repo}@${e.commit.toLowerCase()}${e.dirty ? `+dirty(${[...e.uncommittedFiles].sort().join(',')})` : ''}`)
+        .join(';');
+}
+/**
+ * Cache key material: task + repos/revisions/worktree state + policy + scope.
+ * Callers hash this (sha256) — hashing is left to the runtime so contracts stay
+ * dependency-free. The task text alone is never a sufficient key.
+ */
+function buildEngineeringContextCacheMaterial(input) {
+    return [
+        `task=${input.taskId}`,
+        `rev=${serializeRevisionMap(input.revisionMap)}`,
+        `policy=${input.policyVersion ?? 'none'}`,
+        `scope=${input.scopeKey}`,
+        `step=${input.step ?? 'none'}`,
+    ].join('|');
+}
+/** Rough token estimate for budget accounting (4 chars ≈ 1 token). */
+function estimateTokensFromChars(chars) {
+    return Math.ceil(Math.max(0, chars) / 4);
+}
+// ─── Single persistence path: execution_tasks.metadata.stage_metadata ─────────
+/**
+ * The ONLY place a task checkpoint is stored. It rides the existing durable
+ * execution spine (CAN-021) as `execution_tasks.metadata.stage_metadata[KEY]`;
+ * there is no artifact table, no second store, no history table. Sequence and
+ * verification history live inside the payload.
+ */
+exports.ENGINEERING_CHECKPOINT_STAGE_METADATA_KEY = 'engineeringCheckpoint';
+/** Stage id that routes brief preparation through the cheaper model policy in executeStage. */
+exports.ENGINEERING_BRIEF_PREPARATION_STAGE_ID = 'engineering_brief_preparation';
+exports.CheckpointMissReasonSchema = zod_1.z.enum([
+    'stage_metadata_missing',
+    'checkpoint_absent',
+    'checkpoint_invalid',
+]);
+/** Defensive reader for stage metadata; never throws. */
+function readTaskCheckpointFromStageMetadata(stageMetadata) {
+    if (stageMetadata === null || typeof stageMetadata !== 'object' || Array.isArray(stageMetadata)) {
+        return { checkpoint: null, missReason: 'stage_metadata_missing' };
+    }
+    const nested = stageMetadata[exports.ENGINEERING_CHECKPOINT_STAGE_METADATA_KEY];
+    if (nested === undefined) {
+        return { checkpoint: null, missReason: 'checkpoint_absent' };
+    }
+    const parsed = exports.TaskCheckpointPayloadSchema.safeParse(nested);
+    if (!parsed.success) {
+        return { checkpoint: null, missReason: 'checkpoint_invalid' };
+    }
+    return { checkpoint: parsed.data, missReason: null };
+}
+/** Merge a checkpoint into stage metadata (pure). */
+function mergeTaskCheckpointIntoStageMetadata(stageMetadata, checkpoint) {
+    return { ...(stageMetadata ?? {}), [exports.ENGINEERING_CHECKPOINT_STAGE_METADATA_KEY]: checkpoint };
+}
+/**
+ * A shared contract changed at exactly (repo, previousRevision → nextRevision).
+ * Only evidence observed at that producer revision is invalidated; everything
+ * else is preserved. Producer tests passing never proves a consumer: every
+ * consumer entry whose installed version of `packageName` is unknown or still
+ * the previous one receives its own verification command.
+ */
+function computeContractChangeInvalidation(input) {
+    const prev = input.changed.previousRevision.toLowerCase();
+    const invalidatedEvidenceIds = input.evidence
+        .filter((item) => item.repo === input.changed.repo && item.revision !== null && item.revision.toLowerCase() === prev)
+        .map((item) => item.id);
+    const invalidated = new Set(invalidatedEvidenceIds);
+    const preservedEvidenceIds = input.evidence.filter((item) => !invalidated.has(item.id)).map((item) => item.id);
+    const consumerChecks = input.revisionMap
+        .filter((entry) => {
+        if (entry.role !== 'consumer')
+            return false;
+        const installed = entry.installedVersions?.[input.changed.packageName];
+        if (installed === undefined)
+            return true;
+        return input.changed.previousVersion === undefined || input.changed.previousVersion === null
+            ? true
+            : installed === input.changed.previousVersion;
+    })
+        .map((entry) => ({
+        repo: entry.repo,
+        command: `pnpm test -- ${input.changed.packageName}`,
+        cwd: entry.repo,
+        reason: 'consumer must be verified against the new producer revision',
+    }));
+    return { invalidatedEvidenceIds, preservedEvidenceIds, consumerChecks };
+}
+// ─── Trace / diagnostics (why can or cannot a fresh agent resume) ──────────────
+exports.EngineeringContextMissingReasonSchema = zod_1.z.enum([
+    'no_matches',
+    'source_unavailable',
+    'not_approved',
+    'retrieval_failed',
+    'stale_revision',
+]);
+exports.EngineeringContextTraceSchema = zod_1.z.object({
+    taskReachedNeuraLoom: zod_1.z.boolean(),
+    cortexTaskId: zod_1.z.string().nullable(),
+    executionRunId: zod_1.z.string().uuid().nullable(),
+    executionTaskId: zod_1.z.string().uuid().nullable(),
+    requestedRevision: zod_1.z.string().nullable(),
+    indexedRevision: zod_1.z.string().nullable(),
+    indexedRevisionMatches: zod_1.z.boolean().nullable(),
+    missingContextReason: exports.EngineeringContextMissingReasonSchema.nullable(),
+    checkpointMissReason: exports.CheckpointMissReasonSchema.nullable(),
+    sequence: zod_1.z.number().int().min(0).nullable(),
+    verificationTestedPatch: zod_1.z.boolean(),
+    canResume: zod_1.z.boolean(),
+    nextAction: zod_1.z.string().nullable(),
+});
+function revisionsMatch(a, b) {
+    if (a === null || b === null)
+        return null;
+    const x = a.toLowerCase();
+    const y = b.toLowerCase();
+    return x.length >= 7 && y.length >= 7 && (x.startsWith(y) || y.startsWith(x));
+}
+function diagnoseEngineeringContext(input) {
+    const cp = input.checkpoint;
+    const primary = cp?.revisionMap.find((e) => e.role === 'primary') ?? cp?.revisionMap[0] ?? null;
+    const requestedRevision = primary?.commit ?? null;
+    const indexedRevisionMatches = revisionsMatch(requestedRevision, input.indexedRevision);
+    const verificationTestedPatch = cp !== null &&
+        cp.patchRef !== null &&
+        cp.verification.some((v) => v.status !== 'not_run' &&
+            v.patchRef !== null &&
+            ((v.patchRef.diffHash !== null && v.patchRef.diffHash === cp.patchRef?.diffHash) ||
+                (v.patchRef.headSha !== null && v.patchRef.headSha === cp.patchRef?.headSha)));
+    return exports.EngineeringContextTraceSchema.parse({
+        taskReachedNeuraLoom: cp !== null,
+        cortexTaskId: cp?.cortexTaskId ?? null,
+        executionRunId: cp?.executionRunId ?? null,
+        executionTaskId: cp?.executionTaskId ?? null,
+        requestedRevision,
+        indexedRevision: input.indexedRevision,
+        indexedRevisionMatches,
+        missingContextReason: indexedRevisionMatches === false ? 'stale_revision' : input.missingContextReason,
+        checkpointMissReason: cp === null ? input.checkpointMissReason : null,
+        sequence: cp?.sequence ?? null,
+        verificationTestedPatch,
+        canResume: cp !== null && cp.nextAction.length > 0,
+        nextAction: cp?.nextAction ?? null,
+    });
+}

package/dist/schemas/workflow/existing-capability-classification.schema.d.ts

@@ -0,0 +1,79 @@
+/**
+ * ExistingCapabilityClassification — payload schema for workflow_artifacts rows with
+ * artifact_type='existingCapabilityClassification'.
+ */
+import { z } from 'zod';
+export declare const CapabilityStatusSchema: z.ZodEnum<["present", "partial", "missing", "unknown"]>;
+export type CapabilityStatus = z.infer<typeof CapabilityStatusSchema>;
+export declare const CapabilityEntrySchema: z.ZodObject<{
+    capabilityId: z.ZodString;
+    label: z.ZodString;
+    status: z.ZodEnum<["present", "partial", "missing", "unknown"]>;
+    evidence_refs: z.ZodArray<z.ZodString, "many">;
+    notes: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "unknown" | "partial" | "missing" | "present";
+    label: string;
+    evidence_refs: string[];
+    capabilityId: string;
+    notes?: string | undefined;
+}, {
+    status: "unknown" | "partial" | "missing" | "present";
+    label: string;
+    evidence_refs: string[];
+    capabilityId: string;
+    notes?: string | undefined;
+}>;
+export type CapabilityEntry = z.infer<typeof CapabilityEntrySchema>;
+export declare const ExistingCapabilityPostureSchema: z.ZodEnum<["repair_required", "incremental_improvement", "maintain"]>;
+export type ExistingCapabilityPosture = z.infer<typeof ExistingCapabilityPostureSchema>;
+export declare const ExistingCapabilityClassificationPayloadSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"1.0.0">;
+    generatedAt: z.ZodString;
+    sourceFindingsRegisterId: z.ZodString;
+    capabilities: z.ZodArray<z.ZodObject<{
+        capabilityId: z.ZodString;
+        label: z.ZodString;
+        status: z.ZodEnum<["present", "partial", "missing", "unknown"]>;
+        evidence_refs: z.ZodArray<z.ZodString, "many">;
+        notes: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "unknown" | "partial" | "missing" | "present";
+        label: string;
+        evidence_refs: string[];
+        capabilityId: string;
+        notes?: string | undefined;
+    }, {
+        status: "unknown" | "partial" | "missing" | "present";
+        label: string;
+        evidence_refs: string[];
+        capabilityId: string;
+        notes?: string | undefined;
+    }>, "many">;
+    overallPosture: z.ZodEnum<["repair_required", "incremental_improvement", "maintain"]>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: "1.0.0";
+    capabilities: {
+        status: "unknown" | "partial" | "missing" | "present";
+        label: string;
+        evidence_refs: string[];
+        capabilityId: string;
+        notes?: string | undefined;
+    }[];
+    generatedAt: string;
+    sourceFindingsRegisterId: string;
+    overallPosture: "maintain" | "repair_required" | "incremental_improvement";
+}, {
+    schemaVersion: "1.0.0";
+    capabilities: {
+        status: "unknown" | "partial" | "missing" | "present";
+        label: string;
+        evidence_refs: string[];
+        capabilityId: string;
+        notes?: string | undefined;
+    }[];
+    generatedAt: string;
+    sourceFindingsRegisterId: string;
+    overallPosture: "maintain" | "repair_required" | "incremental_improvement";
+}>;
+export type ExistingCapabilityClassificationPayload = z.infer<typeof ExistingCapabilityClassificationPayloadSchema>;

package/dist/schemas/workflow/existing-capability-classification.schema.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * ExistingCapabilityClassification — payload schema for workflow_artifacts rows with
+ * artifact_type='existingCapabilityClassification'.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExistingCapabilityClassificationPayloadSchema = exports.ExistingCapabilityPostureSchema = exports.CapabilityEntrySchema = exports.CapabilityStatusSchema = void 0;
+const zod_1 = require("zod");
+exports.CapabilityStatusSchema = zod_1.z.enum(['present', 'partial', 'missing', 'unknown']);
+exports.CapabilityEntrySchema = zod_1.z.object({
+    capabilityId: zod_1.z.string().min(1),
+    label: zod_1.z.string().min(1),
+    status: exports.CapabilityStatusSchema,
+    evidence_refs: zod_1.z.array(zod_1.z.string().min(1)),
+    notes: zod_1.z.string().optional(),
+});
+exports.ExistingCapabilityPostureSchema = zod_1.z.enum([
+    'repair_required',
+    'incremental_improvement',
+    'maintain',
+]);
+exports.ExistingCapabilityClassificationPayloadSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal('1.0.0'),
+    generatedAt: zod_1.z.string().datetime(),
+    sourceFindingsRegisterId: zod_1.z.string().uuid(),
+    capabilities: zod_1.z.array(exports.CapabilityEntrySchema).min(1),
+    overallPosture: exports.ExistingCapabilityPostureSchema,
+});