sdd-agent-platform 0.3.0 → 0.4.1

package/node_modules/@sdd-agent-platform/core/src/context/evidence-summary.ts

@@ -0,0 +1,144 @@
+import {
+  ACCEPTANCE_POLICY_RULESET_VERSION,
+  EVIDENCE_SUMMARY_CONTRACT_VERSION,
+  SDD_EVIDENCE_CONTRACT,
+  SDD_EVIDENCE_VERSION
+} from '../contracts.js';
+import { branchToSafePartition } from '../path-safety.js';
+import { listInvocationLedgerEntries } from '../run-state/invocation-ledger.js';
+import { readRunEvents } from '../run-state/events.js';
+import { readRunState } from '../run-state/run-state.js';
+import { recordRuntimeProjection, withRuntimeStore } from '../storage/runtime-store.js';
+import { contextSourceRefForProjectPath, uniqueContextSourceRefs } from './source-refs.js';
+import type { ContextSourceRef } from './source-refs.js';
+
+type EvidenceCoverageStatus = 'PASS' | 'FAIL' | 'BLOCKED' | 'REFERENCED_ONLY' | 'MISSING';
+export type EvidenceQualityIssue = 'EMPTY_EVIDENCE' | 'TODO_PLACEHOLDER' | 'TEMPLATE_TEXT' | 'MENTION_ONLY' | 'UNSOURCED_PASS' | 'MISSING_COMMAND_OUTPUT' | 'MISSING_ARTIFACT_REFERENCE' | 'MISSING_MATERIAL_REFERENCE' | 'PROVENANCE_GAP' | 'POLICY_RULE_FAILED' | 'DERIVED_SOURCE_EVIDENCE' | 'PARTITION_SCOPE_VIOLATION';
+
+interface ContractValidationIssue {
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+interface EvidenceItem {
+  kind: string;
+  ref: string;
+  summary: string | null;
+}
+
+export interface EvidenceClaim {
+  contract: typeof SDD_EVIDENCE_CONTRACT;
+  version: typeof SDD_EVIDENCE_VERSION;
+  task: string;
+  acceptance: string;
+  status: EvidenceCoverageStatus;
+  claim: string;
+  sourceArtifact: string;
+  evidence: EvidenceItem[];
+  provenance: string[];
+  policy: string[];
+  rawMetadata: Record<string, string | string[]>;
+}
+
+export interface EvidenceSummaryProjection {
+  contract: typeof EVIDENCE_SUMMARY_CONTRACT_VERSION;
+  authoritative: false;
+  usableForPass: false;
+  runId: string;
+  taskId: string | null;
+  sources: ContextSourceRef[];
+  passCount: number;
+  blockedCount: number;
+  failCount: number;
+  issueCodes: EvidenceQualityIssue[];
+  policyRefs: string[];
+  highlights: string[];
+}
+
+export interface EvidenceSummaryOptions {
+  runId: string;
+  taskId?: string;
+}
+
+export async function buildEvidenceSummaryProjection(projectRoot: string, options: EvidenceSummaryOptions): Promise<EvidenceSummaryProjection> {
+  const state = await readRunState(projectRoot, options.runId);
+  const [events, invocationLedger] = await Promise.all([
+    readRunEvents(projectRoot, options.runId),
+    listInvocationLedgerEntries(projectRoot, options.runId)
+  ]);
+  const taskId = options.taskId ?? state.currentTask ?? state.taskId;
+  const admittedClaims = await readRuntimeEvidenceClaims(projectRoot, state.runId, taskId ?? null);
+  const artifactIngestions = Object.values(state.artifactIngestions ?? {}).filter((record) => !taskId || record.task === taskId);
+  const artifacts = state.artifacts.filter((artifact) => !taskId || artifact.task === taskId);
+  const ledgerArtifactRefs = invocationLedger
+    .filter((entry) => entry.kind === 'artifact_hash' && entry.artifactPath)
+    .map((entry) => ({ path: entry.artifactPath as string, kind: 'artifact' as const }));
+  const branchEvidenceRoot = `.sdd/runs/${branchToSafePartition(state.gitBranch ?? state.partition ?? 'unscoped')}/evidence`;
+  const artifactSourceRefs = [
+    ...artifacts.map((artifact) => ({ path: `${branchEvidenceRoot}/${artifact.path}`, kind: 'artifact' as const })),
+    ...ledgerArtifactRefs.map((artifact) => ({ path: `${branchEvidenceRoot}/${artifact.path}`, kind: artifact.kind }))
+  ];
+  const sources = await uniqueContextSourceRefs([
+    await contextSourceRefForProjectPath(projectRoot, `.sdd/runtime.sqlite`, 'run_state'),
+    await contextSourceRefForProjectPath(projectRoot, `.sdd/runtime.sqlite`, 'command_output'),
+    await contextSourceRefForProjectPath(projectRoot, `.sdd/runtime.sqlite`, 'ledger'),
+    ...(await Promise.all(artifactSourceRefs.map((artifact) => contextSourceRefForProjectPath(projectRoot, artifact.path, artifact.kind))))
+  ]);
+  const issueCodes = uniqueEvidenceIssueCodes(artifactIngestions.flatMap((record) => record.issues));
+  const passCount = Math.max(admittedClaims.filter((claim) => claim.status === 'PASS').length, artifactIngestions.filter((record) => record.status === 'accepted' && (record.resultStatus === 'PASS' || record.resultStatus === 'PASS_WITH_GAPS')).length);
+  const failCount = Math.max(admittedClaims.filter((claim) => claim.status === 'FAIL').length, artifactIngestions.filter((record) => record.status === 'rejected' || record.resultStatus === 'FAIL').length);
+  const blockedCount = Math.max(admittedClaims.filter((claim) => claim.status === 'BLOCKED').length, artifactIngestions.filter((record) => record.resultStatus === 'BLOCKED' || record.resultStatus === 'TIMED_OUT' || record.resultStatus === 'CANCELLED' || record.gaps.length > 0).length);
+  const highlights = [
+    `run=${state.runId} status=${state.status} phase=${state.phase ?? 'none'}`,
+    `task=${taskId ?? 'none'} validation=${state.validation.status} sync_back=${state.syncBack.status}`,
+    `artifacts=${artifacts.length} ingestions=${artifactIngestions.length} admitted_claims=${admittedClaims.length} events=${events.length} ledger=${invocationLedger.length}`,
+    `pass=${passCount} blocked=${blockedCount} fail=${failCount}`
+  ];
+  if (issueCodes.length > 0) {
+    highlights.push(`issues=${issueCodes.join(',')}`);
+  }
+  const projection: EvidenceSummaryProjection = {
+    contract: EVIDENCE_SUMMARY_CONTRACT_VERSION,
+    authoritative: false,
+    usableForPass: false,
+    runId: state.runId,
+    taskId: taskId ?? null,
+    sources,
+    passCount,
+    blockedCount,
+    failCount,
+    issueCodes,
+    policyRefs: [
+      `${ACCEPTANCE_POLICY_RULESET_VERSION}:require-source-evidence`,
+      `${ACCEPTANCE_POLICY_RULESET_VERSION}:require-provenance`,
+      `${ACCEPTANCE_POLICY_RULESET_VERSION}:reject-derived-source-evidence`
+    ],
+    highlights
+  };
+  await recordRuntimeProjection(projectRoot, 'evidence_summary', `${state.runId}:${taskId ?? 'all'}`, projection);
+  return projection;
+}
+
+export async function readRuntimeEvidenceClaims(projectRoot: string, runId: string, taskId: string | null): Promise<EvidenceClaim[]> {
+  return withRuntimeStore(projectRoot, ({ db }) => {
+    const rows = taskId
+      ? db.prepare('SELECT c.payload_json FROM evidence_claims c JOIN runs r ON r.run_id = c.run_id WHERE c.run_id = ? AND c.task_id = ? AND (c.partition IS NULL OR r.partition IS NULL OR c.partition = r.partition) ORDER BY c.created_at ASC, c.claim_id ASC').all(runId, taskId)
+      : db.prepare('SELECT c.payload_json FROM evidence_claims c JOIN runs r ON r.run_id = c.run_id WHERE c.run_id = ? AND (c.partition IS NULL OR r.partition IS NULL OR c.partition = r.partition) ORDER BY c.created_at ASC, c.claim_id ASC').all(runId);
+    return (rows as Array<{ payload_json: string }>).map((row) => JSON.parse(row.payload_json) as EvidenceClaim);
+  });
+}
+
+export async function hasRuntimeEvidenceScopeViolation(projectRoot: string, runId: string, taskId: string | null): Promise<boolean> {
+  return withRuntimeStore(projectRoot, ({ db }) => {
+    const row = taskId
+      ? db.prepare('SELECT COUNT(*) AS count FROM evidence_claims c JOIN runs r ON r.run_id = c.run_id WHERE c.run_id = ? AND c.task_id = ? AND c.partition IS NOT NULL AND r.partition IS NOT NULL AND c.partition <> r.partition').get(runId, taskId)
+      : db.prepare('SELECT COUNT(*) AS count FROM evidence_claims c JOIN runs r ON r.run_id = c.run_id WHERE c.run_id = ? AND c.partition IS NOT NULL AND r.partition IS NOT NULL AND c.partition <> r.partition').get(runId);
+    return ((row as { count?: number } | undefined)?.count ?? 0) > 0;
+  });
+}
+
+export function uniqueEvidenceIssueCodes(issues: ContractValidationIssue[]): EvidenceQualityIssue[] {
+  const known: EvidenceQualityIssue[] = ['EMPTY_EVIDENCE', 'TODO_PLACEHOLDER', 'TEMPLATE_TEXT', 'MENTION_ONLY', 'UNSOURCED_PASS', 'MISSING_COMMAND_OUTPUT', 'MISSING_ARTIFACT_REFERENCE', 'MISSING_MATERIAL_REFERENCE', 'PROVENANCE_GAP', 'POLICY_RULE_FAILED', 'DERIVED_SOURCE_EVIDENCE', 'PARTITION_SCOPE_VIOLATION'];
+  return known.filter((code) => issues.some((issue) => issue.message.includes(code)));
+}

package/node_modules/@sdd-agent-platform/core/src/context/log-worker.ts

@@ -0,0 +1,48 @@
+import { LOG_WORKER_SUMMARY_CONTRACT_VERSION } from '../contracts.js';
+import type { ContractValidationIssue } from '../delegation/state-machine.js';
+import type { ContextSourceRef } from './source-refs.js';
+
+export interface LogWorkerSummary {
+  contract: typeof LOG_WORKER_SUMMARY_CONTRACT_VERSION;
+  authoritative: false;
+  usableForPass: false;
+  runId: string;
+  taskId: string | null;
+  workerId: string;
+  sources: ContextSourceRef[];
+  highlights: string[];
+  forbiddenAuthority: string[];
+}
+
+export interface LogWorkerSummaryValidation {
+  valid: boolean;
+  issues: ContractValidationIssue[];
+}
+
+export function validateLogWorkerSummary(summary: LogWorkerSummary): LogWorkerSummaryValidation {
+  const issues: ContractValidationIssue[] = [];
+  const candidate = summary as LogWorkerSummary & Record<string, unknown>;
+  if (candidate.contract !== LOG_WORKER_SUMMARY_CONTRACT_VERSION) {
+    issues.push(contractIssue('contract', 'Log worker summary contract is invalid.', `Use ${LOG_WORKER_SUMMARY_CONTRACT_VERSION}.`));
+  }
+  if (candidate.authoritative !== false) {
+    issues.push(contractIssue('authoritative', 'Log worker summary must be non-authoritative.', 'Set authoritative=false and keep workflow decisions in core runtime.'));
+  }
+  if (candidate.usableForPass !== false) {
+    issues.push(contractIssue('usableForPass', 'Log worker summary cannot be used for PASS evidence.', 'Set usableForPass=false and reference source artifacts for PASS evidence.'));
+  }
+  const forbiddenAuthority = Array.isArray(candidate.forbiddenAuthority) ? candidate.forbiddenAuthority.filter((item) => typeof item === 'string') : [];
+  if (forbiddenAuthority.length > 0) {
+    issues.push(contractIssue('forbiddenAuthority', `Log worker summary claims forbidden workflow authority: ${forbiddenAuthority.join(', ')}.`, 'Remove PASS/BLOCKED/route/doctor/sync-back decisions from worker summaries.'));
+  }
+  for (const field of ['status', 'verdict', 'routeDecision', 'doctorVerdict', 'syncBackReady']) {
+    if (field in candidate) {
+      issues.push(contractIssue(field, `Log worker summary must not expose workflow decision field ${field}.`, 'Keep decision fields in core runtime outputs only.'));
+    }
+  }
+  return { valid: issues.length === 0, issues };
+}
+
+function contractIssue(field: string, message: string, recommendation: string): ContractValidationIssue {
+  return { field, message, recommendation };
+}

package/node_modules/@sdd-agent-platform/core/src/context/source-refs.ts

@@ -0,0 +1,41 @@
+import { createHash } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { exists } from '../storage/json-io.js';
+import { normalizePortablePath } from '../path-safety.js';
+
+export type ContextSourceKind = 'artifact' | 'run_state' | 'ledger' | 'document' | 'command_output' | 'derived';
+
+export interface ContextSourceRef {
+  path: string;
+  hash: string;
+  kind: ContextSourceKind;
+}
+
+export async function contextSourceRefForProjectPath(projectRoot: string, relativePath: string, kind: ContextSourceKind): Promise<ContextSourceRef> {
+  const normalized = normalizePortablePath(relativePath);
+  return contextSourceRefForAbsolutePath(projectRoot, path.join(projectRoot, normalized), kind, normalized);
+}
+
+export async function contextSourceRefForAbsolutePath(projectRoot: string, absolutePath: string, kind: ContextSourceKind, displayPath?: string): Promise<ContextSourceRef> {
+  const relativePath = displayPath ?? normalizePortablePath(path.relative(projectRoot, absolutePath));
+  if (!relativePath || relativePath.startsWith('../') || path.isAbsolute(relativePath)) {
+    return { path: normalizePortablePath(absolutePath), hash: hashDocumentContent(`external:${absolutePath}`), kind };
+  }
+  if (!await exists(absolutePath)) {
+    return { path: relativePath, hash: hashDocumentContent(`missing:${relativePath}`), kind };
+  }
+  const fileStat = await stat(absolutePath);
+  if (fileStat.isDirectory()) {
+    return { path: relativePath, hash: hashDocumentContent(`directory:${relativePath}`), kind };
+  }
+  return { path: relativePath, hash: hashDocumentContent(await readFile(absolutePath, 'utf8')), kind };
+}
+
+export function uniqueContextSourceRefs(refs: ContextSourceRef[]): ContextSourceRef[] {
+  return [...new Map(refs.map((ref) => [`${ref.kind}:${ref.path}`, ref])).values()];
+}
+
+function hashDocumentContent(raw: string): string {
+  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+}

package/node_modules/@sdd-agent-platform/core/src/context-offload/contracts.ts

@@ -0,0 +1,47 @@
+import type { RuntimeConfidence, RuntimeRef, RuntimeScope } from '../contracts.js';
+import { CONTEXT_LOAD_SIGNAL_CONTRACT_VERSION, CONTEXT_OFFLOAD_DECISION_CONTRACT_VERSION, SCOPED_CONTEXT_HANDOFF_CONTRACT_VERSION } from '../contracts.js';
+
+export type ContextLoadLevel = 'normal' | 'elevated' | 'high' | 'overloaded';
+export type ContextOffloadAction = 'inline' | 'summarize' | 'dispatch-subagent' | 'block-for-curation';
+
+export interface ContextLoadSignal {
+  contract: typeof CONTEXT_LOAD_SIGNAL_CONTRACT_VERSION;
+  scope: RuntimeScope;
+  level: ContextLoadLevel;
+  score: number;
+  fileCountScore: number;
+  artifactSizeScore: number;
+  dependencyFanoutScore: number;
+  unknownImpactScore: number;
+  staleEvidenceScore: number;
+  logVolumeScore: number;
+  confidence: RuntimeConfidence;
+  inputRefs: RuntimeRef[];
+  reasons: string[];
+  generatedAt: string;
+}
+
+export interface ContextOffloadDecision {
+  contract: typeof CONTEXT_OFFLOAD_DECISION_CONTRACT_VERSION;
+  scope: RuntimeScope;
+  action: ContextOffloadAction;
+  loadSignalRef: RuntimeRef;
+  requiredBefore: 'stage-output' | 'handoff' | 'sync-back' | 'ship' | 'never';
+  inlineRefs: RuntimeRef[];
+  summarizeRefs: RuntimeRef[];
+  dispatchRefs: RuntimeRef[];
+  blockingReasons: string[];
+  generatedAt: string;
+}
+
+export interface ScopedContextHandoff {
+  contract: typeof SCOPED_CONTEXT_HANDOFF_CONTRACT_VERSION;
+  id: string;
+  scope: RuntimeScope;
+  purpose: string;
+  mustReadRefs: RuntimeRef[];
+  summaryRefs: RuntimeRef[];
+  doNotReadUnlessNeededRefs: RuntimeRef[];
+  producedFor: 'main-agent' | 'co-main-agent' | 'subagent';
+  generatedAt: string;
+}

package/node_modules/@sdd-agent-platform/core/src/context-offload/runtime.test.ts

@@ -0,0 +1,71 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { initProject } from '../config/init-project.js';
+import type { RuntimeRef, RuntimeScope } from '../contracts.js';
+import { decideContextOffload, evaluateContextLoadSignal, inspectContextOffloadRuntime, recordContextLoadSignalProjection, recordContextOffloadDecisionProjection, readContextLoadSignalProjection } from './runtime.js';
+
+const scope: RuntimeScope = { branch: 'master', taskId: 'PHASE8-9', runId: 'run-1' };
+const sourceRef: RuntimeRef = { kind: 'document', ref: 'specs/master/tasks.md' };
+const summaryRef: RuntimeRef = { kind: 'artifact', ref: 'artifacts/context-summary.md' };
+const dispatchRef: RuntimeRef = { kind: 'projection', ref: 'phase8_subagent_dispatch:master:PHASE8-9:run-1:none:dispatch-1' };
+
+test('context load signal scoring maps load dimensions to levels', () => {
+  const normal = evaluateContextLoadSignal({ scope });
+  const elevated = evaluateContextLoadSignal({ scope, fileCount: 8, dependencyFanout: 5, staleEvidenceRefs: 1 });
+  const high = evaluateContextLoadSignal({ scope, fileCount: 20, artifactBytes: 200_000, dependencyFanout: 12, unknownImpact: true });
+  const overloaded = evaluateContextLoadSignal({ scope, fileCount: 40, artifactBytes: 500_000, dependencyFanout: 25, staleEvidenceRefs: 6 });
+
+  assert.equal(normal.level, 'normal');
+  assert.equal(normal.confidence, 'high');
+  assert.equal(elevated.level, 'elevated');
+  assert.equal(elevated.score, 3);
+  assert.equal(high.level, 'high');
+  assert.equal(high.confidence, 'medium');
+  assert.equal(overloaded.level, 'overloaded');
+  assert.equal(overloaded.score, 12);
+});
+
+test('context offload decision maps load levels to inline summarize dispatch and curation actions', () => {
+  const inline = decideContextOffload(evaluateContextLoadSignal({ scope, refs: [sourceRef] }));
+  const summarize = decideContextOffload(evaluateContextLoadSignal({ scope, refs: [sourceRef], fileCount: 8, dependencyFanout: 5, staleEvidenceRefs: 1 }), { summarizeRefs: [summaryRef] });
+  const dispatch = decideContextOffload(evaluateContextLoadSignal({ scope, refs: [sourceRef], fileCount: 20, artifactBytes: 200_000, dependencyFanout: 12, unknownImpact: true }), { dispatchRefs: [dispatchRef] });
+  const curation = decideContextOffload(evaluateContextLoadSignal({ scope, refs: [sourceRef], fileCount: 40, artifactBytes: 500_000, dependencyFanout: 25, staleEvidenceRefs: 6 }));
+
+  assert.equal(inline.action, 'inline');
+  assert.deepEqual(inline.inlineRefs, [sourceRef]);
+  assert.equal(summarize.action, 'summarize');
+  assert.deepEqual(summarize.summarizeRefs, [summaryRef]);
+  assert.equal(dispatch.action, 'dispatch-subagent');
+  assert.equal(dispatch.requiredBefore, 'handoff');
+  assert.deepEqual(dispatch.dispatchRefs, [dispatchRef]);
+  assert.equal(curation.action, 'block-for-curation');
+  assert.equal(curation.requiredBefore, 'stage-output');
+  assert.equal(curation.blockingReasons.length > 0, true);
+});
+
+test('context load and offload projections can be written read and inspected', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-context-offload-runtime-'));
+  try {
+    await initProject(root);
+    const signal = evaluateContextLoadSignal({ scope, refs: [sourceRef], fileCount: 20, artifactBytes: 200_000, dependencyFanout: 12, unknownImpact: true, generatedAt: '2026-05-18T00:00:00.000Z' });
+    const decision = decideContextOffload(signal, { dispatchRefs: [dispatchRef] });
+
+    const signalWrite = await recordContextLoadSignalProjection(root, signal);
+    const decisionWrite = await recordContextOffloadDecisionProjection(root, decision);
+    const restoredSignal = await readContextLoadSignalProjection(root, scope);
+    const diagnostic = await inspectContextOffloadRuntime(root, 'master');
+
+    assert.equal(signalWrite.status, 'created');
+    assert.equal(decisionWrite.status, 'created');
+    assert.equal(restoredSignal?.payload.level, 'high');
+    assert.equal(diagnostic.level, 'high');
+    assert.equal(diagnostic.action, 'dispatch-subagent');
+    assert.equal(diagnostic.dispatchRefs, 1);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/node_modules/@sdd-agent-platform/core/src/context-offload/runtime.ts

@@ -0,0 +1,178 @@
+import { createHash } from 'node:crypto';
+
+import { CONTEXT_LOAD_SIGNAL_CONTRACT_VERSION, CONTEXT_OFFLOAD_DECISION_CONTRACT_VERSION } from '../contracts.js';
+import type { RuntimeProjectionEnvelope, RuntimeRef, RuntimeScope } from '../contracts.js';
+import { listRuntimeProjections, readRuntimeProjectionEnvelope, recordRuntimeProjectionEnvelope, type RuntimeProjectionEnvelopeWriteResult } from '../storage/runtime-store.js';
+import type { ContextLoadLevel, ContextLoadSignal, ContextOffloadDecision } from './contracts.js';
+
+export const CONTEXT_OFFLOAD_RUNTIME_PRODUCER_VERSION = 'phase8-context-offload-runtime-v1';
+export const CONTEXT_LOAD_SIGNAL_PROJECTION_TYPE = 'phase8_context_load_signal';
+export const CONTEXT_OFFLOAD_DECISION_PROJECTION_TYPE = 'phase8_context_offload_decision';
+
+export interface ContextLoadInput {
+  scope: RuntimeScope;
+  refs?: RuntimeRef[];
+  fileCount?: number;
+  artifactBytes?: number;
+  dependencyFanout?: number;
+  unknownImpact?: boolean;
+  staleEvidenceRefs?: number;
+  logBytes?: number;
+  generatedAt?: string;
+}
+
+export interface ContextRuntimeDiagnostic {
+  level: ContextLoadLevel | 'unknown';
+  action: ContextOffloadDecision['action'] | 'none';
+  loadSignals: number;
+  offloadDecisions: number;
+  dispatchRefs: number;
+  blockingReasons: string[];
+}
+
+export function evaluateContextLoadSignal(input: ContextLoadInput): ContextLoadSignal {
+  const fileCountScore = scoreByThreshold(input.fileCount ?? 0, [8, 20, 40]);
+  const artifactSizeScore = scoreByThreshold(input.artifactBytes ?? 0, [50_000, 200_000, 500_000]);
+  const dependencyFanoutScore = scoreByThreshold(input.dependencyFanout ?? 0, [5, 12, 25]);
+  const unknownImpactScore = input.unknownImpact ? 2 : 0;
+  const staleEvidenceScore = scoreByThreshold(input.staleEvidenceRefs ?? 0, [1, 3, 6]);
+  const logVolumeScore = scoreByThreshold(input.logBytes ?? 0, [30_000, 120_000, 300_000]);
+  const score = fileCountScore + artifactSizeScore + dependencyFanoutScore + unknownImpactScore + staleEvidenceScore + logVolumeScore;
+  return {
+    contract: CONTEXT_LOAD_SIGNAL_CONTRACT_VERSION,
+    scope: input.scope,
+    level: contextLevelForScore(score),
+    score,
+    fileCountScore,
+    artifactSizeScore,
+    dependencyFanoutScore,
+    unknownImpactScore,
+    staleEvidenceScore,
+    logVolumeScore,
+    confidence: input.unknownImpact ? 'medium' : 'high',
+    inputRefs: input.refs ?? [],
+    reasons: contextLoadReasons(fileCountScore, artifactSizeScore, dependencyFanoutScore, unknownImpactScore, staleEvidenceScore, logVolumeScore),
+    generatedAt: input.generatedAt ?? new Date().toISOString()
+  };
+}
+
+export function decideContextOffload(signal: ContextLoadSignal, refs: { inlineRefs?: RuntimeRef[]; summarizeRefs?: RuntimeRef[]; dispatchRefs?: RuntimeRef[] } = {}): ContextOffloadDecision {
+  const action = signal.level === 'overloaded'
+    ? 'block-for-curation'
+    : signal.level === 'high'
+      ? 'dispatch-subagent'
+      : signal.level === 'elevated'
+        ? 'summarize'
+        : 'inline';
+  return {
+    contract: CONTEXT_OFFLOAD_DECISION_CONTRACT_VERSION,
+    scope: signal.scope,
+    action,
+    loadSignalRef: { kind: 'projection', ref: `${CONTEXT_LOAD_SIGNAL_PROJECTION_TYPE}:${contextLoadSignalScopeKey(signal.scope)}` },
+    requiredBefore: action === 'block-for-curation' ? 'stage-output' : action === 'dispatch-subagent' ? 'handoff' : 'never',
+    inlineRefs: action === 'inline' ? refs.inlineRefs ?? signal.inputRefs : [],
+    summarizeRefs: action === 'summarize' ? refs.summarizeRefs ?? signal.inputRefs : [],
+    dispatchRefs: action === 'dispatch-subagent' ? refs.dispatchRefs ?? signal.inputRefs : [],
+    blockingReasons: action === 'block-for-curation' ? signal.reasons : [],
+    generatedAt: signal.generatedAt
+  };
+}
+
+export function contextLoadSignalScopeKey(scope: RuntimeScope): string {
+  return [scope.branch, scope.taskId ?? 'all', scope.runId ?? 'none', scope.changeRef ?? 'none'].join(':');
+}
+
+export async function recordContextLoadSignalProjection(projectRoot: string, signal: ContextLoadSignal): Promise<RuntimeProjectionEnvelopeWriteResult<ContextLoadSignal>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: CONTEXT_LOAD_SIGNAL_PROJECTION_TYPE,
+    scopeKey: contextLoadSignalScopeKey(signal.scope),
+    inputHash: stableHash(JSON.stringify(signal)),
+    producer: 'phase8-context-offload-runtime',
+    producerVersion: CONTEXT_OFFLOAD_RUNTIME_PRODUCER_VERSION,
+    generatedAt: signal.generatedAt,
+    payload: signal
+  });
+}
+
+export async function readContextLoadSignalProjection(projectRoot: string, scope: RuntimeScope): Promise<RuntimeProjectionEnvelope<ContextLoadSignal> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, CONTEXT_LOAD_SIGNAL_PROJECTION_TYPE, contextLoadSignalScopeKey(scope));
+}
+
+export async function recordContextOffloadDecisionProjection(projectRoot: string, decision: ContextOffloadDecision): Promise<RuntimeProjectionEnvelopeWriteResult<ContextOffloadDecision>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: CONTEXT_OFFLOAD_DECISION_PROJECTION_TYPE,
+    scopeKey: contextLoadSignalScopeKey(decision.scope),
+    inputHash: stableHash(JSON.stringify(decision)),
+    producer: 'phase8-context-offload-runtime',
+    producerVersion: CONTEXT_OFFLOAD_RUNTIME_PRODUCER_VERSION,
+    generatedAt: decision.generatedAt,
+    payload: decision
+  });
+}
+
+export async function inspectContextOffloadRuntime(projectRoot: string, branch: string): Promise<ContextRuntimeDiagnostic> {
+  const projections = await listRuntimeProjections(projectRoot, [CONTEXT_LOAD_SIGNAL_PROJECTION_TYPE, CONTEXT_OFFLOAD_DECISION_PROJECTION_TYPE]);
+  const signalEnvelopes = projections
+    .filter((projection) => projection.projectionType === CONTEXT_LOAD_SIGNAL_PROJECTION_TYPE)
+    .map((projection) => projection.payload as RuntimeProjectionEnvelope<ContextLoadSignal>)
+    .filter((envelope) => envelope?.payload?.scope?.branch === branch);
+  const decisionEnvelopes = projections
+    .filter((projection) => projection.projectionType === CONTEXT_OFFLOAD_DECISION_PROJECTION_TYPE)
+    .map((projection) => projection.payload as RuntimeProjectionEnvelope<ContextOffloadDecision>)
+    .filter((envelope) => envelope?.payload?.scope?.branch === branch);
+  const latestSignal = latestEnvelope(signalEnvelopes)?.payload ?? null;
+  const latestDecision = latestEnvelope(decisionEnvelopes)?.payload ?? null;
+  return {
+    level: latestSignal?.level ?? 'unknown',
+    action: latestDecision?.action ?? 'none',
+    loadSignals: signalEnvelopes.length,
+    offloadDecisions: decisionEnvelopes.length,
+    dispatchRefs: latestDecision?.dispatchRefs.length ?? 0,
+    blockingReasons: latestDecision?.blockingReasons ?? []
+  };
+}
+
+function latestEnvelope<TPayload>(envelopes: Array<RuntimeProjectionEnvelope<TPayload>>): RuntimeProjectionEnvelope<TPayload> | null {
+  return [...envelopes].sort((left, right) => right.generatedAt.localeCompare(left.generatedAt))[0] ?? null;
+}
+
+function contextLevelForScore(score: number): ContextLoadLevel {
+  if (score >= 10) {
+    return 'overloaded';
+  }
+  if (score >= 7) {
+    return 'high';
+  }
+  if (score >= 3) {
+    return 'elevated';
+  }
+  return 'normal';
+}
+
+function scoreByThreshold(value: number, thresholds: [number, number, number]): number {
+  if (value >= thresholds[2]) {
+    return 3;
+  }
+  if (value >= thresholds[1]) {
+    return 2;
+  }
+  if (value >= thresholds[0]) {
+    return 1;
+  }
+  return 0;
+}
+
+function contextLoadReasons(fileCountScore: number, artifactSizeScore: number, dependencyFanoutScore: number, unknownImpactScore: number, staleEvidenceScore: number, logVolumeScore: number): string[] {
+  return [
+    fileCountScore > 0 ? `file-count score=${fileCountScore}` : null,
+    artifactSizeScore > 0 ? `artifact-size score=${artifactSizeScore}` : null,
+    dependencyFanoutScore > 0 ? `dependency-fanout score=${dependencyFanoutScore}` : null,
+    unknownImpactScore > 0 ? `unknown-impact score=${unknownImpactScore}` : null,
+    staleEvidenceScore > 0 ? `stale-evidence score=${staleEvidenceScore}` : null,
+    logVolumeScore > 0 ? `log-volume score=${logVolumeScore}` : null
+  ].filter((reason): reason is string => reason !== null);
+}
+
+function stableHash(value: string): string {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}

package/node_modules/@sdd-agent-platform/core/src/context-offload.ts

@@ -0,0 +1,2 @@
+export * from './context-offload/contracts.js';
+export * from './context-offload/runtime.js';

package/node_modules/@sdd-agent-platform/core/src/context.ts

@@ -0,0 +1,6 @@
+export * from './context/budget.js';
+export * from './context/build-package.js';
+export * from './context/command-summary.js';
+export * from './context/evidence-summary.js';
+export * from './context/log-worker.js';
+export * from './context/source-refs.js';

package/node_modules/@sdd-agent-platform/core/src/contracts/issues.ts

@@ -0,0 +1,13 @@
+export interface ContractValidationIssue {
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export function contractIssue(field: string, message: string, recommendation: string): ContractValidationIssue {
+  return { field, message, recommendation };
+}
+
+export function messageFromError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/node_modules/@sdd-agent-platform/core/src/contracts.test.ts

@@ -0,0 +1,9 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { CODING_FACT_SET_CONTRACT_VERSION, LIFECYCLE_RISK_DECISION_CONTRACT_VERSION, RUNTIME_PROJECTION_ENVELOPE_CONTRACT_VERSION } from './contracts.js';
+
+test('Phase 8 contract constants are versioned', () => {
+  assert.equal(CODING_FACT_SET_CONTRACT_VERSION, 'sdd-coding-fact-set-v1');
+  assert.equal(LIFECYCLE_RISK_DECISION_CONTRACT_VERSION, 'sdd-lifecycle-risk-decision-v1');
+  assert.equal(RUNTIME_PROJECTION_ENVELOPE_CONTRACT_VERSION, 'sdd-runtime-projection-envelope-v1');
+});