@cleocode/contracts 2026.9.8 → 2026.9.10

package/src/memory/observe.ts

@@ -117,8 +117,10 @@ export interface ObserveBrainParams {
   provenanceChain?: string[] | null;
   /**
    * T992: Internal flag — when true, bypasses the verifyAndStore gate.
-   * Set only by storeVerifiedCandidate in extraction-gate.ts to avoid
-   * infinite recursion (gate → storeVerifiedCandidate → observeBrain → gate).
+   * Set by storeVerifiedCandidate in extraction-gate.ts to avoid recursion,
+   * or by the prepared docs projection executor after authentic canonical
+   * source validation. That executor requires its persisted proposal and a
+   * current job fence at the actual observation transaction boundary.
    * External callers MUST NOT set this flag.
    */
   _skipGate?: boolean;

package/src/memory/search.ts

@@ -30,6 +30,8 @@
  * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
  */
 export interface BrainCompactHit {
+  /** Obsolete decision IDs matching the query whose explicit supersededBy chain resolves to this current hit. */
+  matchedHistoricalIds?: string[];
   /** Entry identifier (e.g. `D-arch-001`, `P-feat-042`). */
   id: string;
   /** Source BRAIN table that produced the hit. */
@@ -70,6 +72,8 @@ export interface BrainCompactHit {
  * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
  */
 export interface SearchBrainCompactParams {
+  /** Explicitly include superseded and invalidated records for historical retrieval. */
+  includeHistory?: boolean;
   /** Free-text query (FTS5 + optional vector recall). */
   query: string;
   /** Maximum number of hits to return (caller-bounded). */

package/src/nexus-living-brain-ops.ts

@@ -12,6 +12,13 @@
  * @epic T1042
  */
 
+import type {
+  KnowledgeAuthorityStatus,
+  KnowledgeCoverage,
+  KnowledgeEvidenceRef,
+  KnowledgeRepairFinding,
+} from './knowledge-health.js';
+
 // ---------------------------------------------------------------------------
 // Sub-interfaces — each substrate's projection
 // ---------------------------------------------------------------------------
@@ -59,6 +66,8 @@ export interface NexusContext {
  * references a code symbol via one of the cross-substrate edge types.
  */
 export interface BrainMemoryRef {
+  /** Canonical source authority; missing legacy source records remain unverified. */
+  authority?: KnowledgeAuthorityStatus;
   /** Brain page node ID (e.g., 'observation:abc123'). */
   nodeId: string;
   /** Node type. */
@@ -135,6 +144,8 @@ export interface PlasticityMeasure {
  * Returned by {@link getSymbolFullContext}.
  */
 export interface SymbolFullContext {
+  /** Evidence coverage; omitted only by legacy producers that have not assessed it. */
+  coverage?: KnowledgeCoverage;
   /** Symbol identifier (nexus node ID or name). */
   symbolId: string;
   /** Nexus code graph context: callers, callees, community, process. */
@@ -157,11 +168,15 @@ export interface SymbolFullContext {
  * Returned by {@link getTaskCodeImpact}.
  */
 export interface TaskCodeImpact {
+  /** Unresolved evidence and path interpretations that require caller action. */
+  findings?: KnowledgeRepairFinding[];
+  /** Evidence coverage, independent of risk; absent legacy coverage is not current. */
+  coverage?: KnowledgeCoverage;
   /** Task ID. */
   taskId: string;
-  /** Files listed in the task's files_json array. */
+  /** Files associated by task metadata, verification, commits, or canonical attachments. */
   files: string[];
-  /** Symbols in those files (from NEXUS). */
+  /** Symbols in those files; file-level evidence does not prove each symbol changed. */
   symbols: SymbolImpactEntry[];
   /** Aggregate blast radius across all symbols. */
   blastRadius: BlastRadiusSummary;
@@ -177,6 +192,10 @@ export interface TaskCodeImpact {
  * Impact entry for a single symbol in a task's footprint.
  */
 export interface SymbolImpactEntry {
+  /** Precision of the task association, independent of graph impact. */
+  precision?: 'file' | 'symbol';
+  /** Historical evidence supporting the task association. */
+  evidence?: KnowledgeEvidenceRef[];
   /** Nexus node ID. */
   nexusNodeId: string;
   /** Display label. */
@@ -219,8 +238,12 @@ export interface DecisionRef {
 
 /**
  * Risk tier for a symbol's impact analysis.
+ *
+ * UNKNOWN means missing coverage prevents assessment. NONE is reserved for an
+ * assessed graph with no detected impact; static analysis cannot prove that all
+ * runtime callers have been discovered. UNKNOWN is not an ordinal severity.
  */
-export type RiskTier = 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+export type RiskTier = 'UNKNOWN' | 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
 
 // ---------------------------------------------------------------------------
 // T1069 — Extended Code Reasoning types
@@ -230,6 +253,8 @@ export type RiskTier = 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
  * A single step in a code reasoning trace chain.
  */
 export interface ReasonTraceStep {
+  /** Authority of the underlying memory source when this is a memory step. */
+  authority?: KnowledgeAuthorityStatus;
   /** Step type discriminant. */
   type: 'decision' | 'observation' | 'task' | 'symbol';
   /** ID of this entry (brain ID, task ID, or nexus node ID). */
@@ -246,6 +271,8 @@ export interface ReasonTraceStep {
  * Returned by {@link reasonWhySymbol}.
  */
 export interface CodeReasonTrace {
+  /** Evidence coverage; missing reasoning is distinct from an assessed absence. */
+  coverage?: KnowledgeCoverage;
   /** The nexus symbol ID queried. */
   symbolId: string;
   /** Human-readable narrative summarizing the trace. */
@@ -258,6 +285,8 @@ export interface CodeReasonTrace {
  * A brain risk note associated with a symbol change.
  */
 export interface BrainRiskNote {
+  /** Canonical source authority, independent of graph proximity. */
+  authority?: KnowledgeAuthorityStatus;
   /** Brain node ID. */
   nodeId: string;
   /** Node type (observation, decision, etc.). */
@@ -276,6 +305,8 @@ export interface BrainRiskNote {
  * Returned by {@link reasonImpactOfChange}.
  */
 export interface ImpactFullReport {
+  /** Evidence coverage, independent of merged risk. */
+  coverage?: KnowledgeCoverage;
   /** The nexus symbol ID analyzed. */
   symbolId: string;
   /** Structural blast radius from analyzeImpact BFS. */

package/src/nexus-tasks-bridge-ops.ts

@@ -8,11 +8,15 @@
  * @epic T1042
  */
 
+import type { KnowledgeEvidenceRef } from './knowledge-health.js';
+
 /**
  * A single task reference in a symbol context.
  * Used by getTasksForSymbol() reverse-lookup queries.
  */
 export interface TaskReference {
+  /** File association does not prove that this individual symbol changed. */
+  precision?: 'file' | 'symbol';
   /** Task ID (e.g., 'T001'). */
   taskId: string;
   /** Display label for the task. */
@@ -28,6 +32,10 @@ export interface TaskReference {
  * Used by getSymbolsForTask() forward-lookup queries.
  */
 export interface SymbolReference {
+  /** File scope means association only, not proof that this symbol changed. */
+  precision?: 'file' | 'symbol';
+  /** Explicit sources supporting this relationship. */
+  evidence?: KnowledgeEvidenceRef[];
   /** Nexus node ID (format: '<filePath>::<name>' or '<filePath>'). */
   nexusNodeId: string;
   /** Display label for the symbol (file path or function name). */
@@ -46,6 +54,10 @@ export interface SymbolReference {
  * Result from linkTaskToSymbols() operation.
  */
 export interface LinkTaskResult {
+  /** Explicit failure state; omitted on successful legacy results. */
+  status?: 'complete' | 'failed';
+  /** Observable persistence or input failure, when present. */
+  reason?: string;
   /** Number of task_touches_symbol edges created or found. */
   linked: number;
   /** Task ID that was linked. */

package/src/operations/admin.ts

@@ -24,6 +24,9 @@
  * @see packages/cleo/src/dispatch/domains/admin.ts
  */
 
+import type { BackgroundJobStatus } from '../jobs.js';
+import type { AcceptanceItem } from '../task.js';
+
 // ============================================================================
 // Shared primitive types
 // ============================================================================
@@ -759,8 +762,8 @@ export interface AdminContextPullResult {
     title: string;
     /** Current status. */
     status: string;
-    /** Acceptance criteria array. */
-    acceptance: string[];
+    /** Canonical literal criteria and typed requirements, without projection loss. */
+    acceptance: AcceptanceItem[];
   };
   /** Relevant brain memory hits (up to 5). */
   relevantMemory: AdminContextPullMemoryHit[];
@@ -1759,10 +1762,14 @@ export interface AdminJobCancelParams {
 
 /** Result of `admin.job.cancel`. */
 export interface AdminJobCancelResult {
-  /** The job ID that was cancelled. */
+  /** The inspected job identity. */
   jobId: string;
-  /** Whether the cancellation succeeded. */
+  /** Whether this call recorded or reaffirmed a request for running work. */
+  cancellationRequested: boolean;
+  /** Whether the executor has acknowledged terminal cancellation. */
   cancelled: boolean;
+  /** Persisted lifecycle state observed after the request. */
+  status: BackgroundJobStatus;
 }
 
 // ---------------------------------------------------------------------------

package/src/operations/docs.ts

@@ -30,8 +30,15 @@
  * @see packages/contracts/src/operations/index.ts
  */
 
+import { z } from 'zod';
 import type { AttachmentKind } from '../attachment.js';
 import { BUILTIN_DOC_KIND_VALUES, type BuiltinDocKind } from '../docs-taxonomy.js';
+import type {
+  BackgroundJobStatus,
+  OperationExecutionContext,
+  OperationExecutionIdentity,
+} from '../jobs.js';
+import type { DocAttachmentObservationPayload } from '../memory/observe.js';
 
 // ============================================================================
 // Shared Attachment Types (API wire format)
@@ -464,10 +471,156 @@ export interface DocsAddParams {
   strict?: boolean;
 }
 
+/** Canonical attachment and owner whose optional projections may be prepared. */
+export interface DocsProjectionSource {
+  /** Canonical attachment identity, never synthesized from a missing record. */
+  readonly attachmentId: string;
+  /** Expected canonical SHA-256; a changed source refuses preparation. */
+  readonly sha256: string;
+  /** Exact existing owner reference. */
+  readonly ownerId: string;
+  /** Kind of the referenced owner. */
+  readonly ownerType: AttachmentOwnerType;
+  /** Human-readable graph label captured before asynchronous work. */
+  readonly label: string;
+}
+
+/** Authentic domain inputs stored before any optional document projection executes. */
+export interface DocsProjectionProposal {
+  /** Version of the supported deterministic proposal shape. */
+  readonly version: 1;
+  /** Exact domain operation, independent of the caller's foreground operation. */
+  readonly operation: 'docs.projection';
+  /** Captured project, root and actor provenance. */
+  readonly identity: OperationExecutionIdentity;
+  /** Verified canonical source and owner. */
+  readonly source: DocsProjectionSource;
+  /** Sourced observation payload; preparation does not call a model. */
+  readonly observation: DocAttachmentObservationPayload;
+}
+
+/** Strict persisted input validator for the one supported document projection operation. */
+export const DOCS_PROJECTION_PROPOSAL_SCHEMA = z
+  .object({
+    version: z.literal(1),
+    operation: z.literal('docs.projection'),
+    identity: z
+      .object({
+        projectId: z.string().min(1),
+        projectRoot: z.string().min(1),
+        actor: z.string().min(1),
+        operation: z.literal('docs.projection'),
+        idempotencyKey: z.string().min(1),
+      })
+      .strict(),
+    source: z
+      .object({
+        attachmentId: z.string().min(1),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/),
+        ownerId: z.string().min(1),
+        ownerType: z.enum(['task', 'session', 'observation', 'decision', 'learning', 'pattern']),
+        label: z.string().min(1),
+      })
+      .strict(),
+    observation: z
+      .object({
+        kind: z.literal('doc-attachment'),
+        attachmentId: z.string().min(1),
+        ownerId: z.string().min(1),
+        addedAt: z.string().min(1),
+        slug: z.string().optional(),
+        type: z.string().optional(),
+      })
+      .strict(),
+  })
+  .strict() satisfies z.ZodType<DocsProjectionProposal>;
+
+/** Verifiable result retained in the existing durable job result column. */
+export const DOCS_PROJECTION_RECEIPT_SCHEMA = z
+  .object({
+    version: z.literal(1),
+    sourceHash: z.string().regex(/^[a-f0-9]{64}$/),
+    graph: z.enum(['completed', 'disabled']),
+    observationId: z.string().min(1),
+    verifiedAt: z.string().min(1),
+    actor: z.string().min(1),
+  })
+  .strict();
+
+/** Domain verification record; this is not a cross-database atomic repair receipt. */
+export type DocsProjectionReceipt = z.infer<typeof DOCS_PROJECTION_RECEIPT_SCHEMA>;
+
+/** Truthful bounded observation of optional work following an accepted canonical attachment. */
+export interface DocsProjectionOutcome {
+  /** Captured project identity, or null when canonical identity could not be read. */
+  projectId: string | null;
+  /** Captured explicit repository root. */
+  projectRoot: string;
+  /** Completed verification, resumable pending work, or an observed failure. */
+  status: 'completed' | 'pending' | 'failed';
+  /** Current proof, incomplete proof, missing preparation or an observed diagnostic failure. */
+  coverage: 'current' | 'partial' | 'missing' | 'failed';
+  /** Durable pending/claimed job when preparation committed. */
+  jobId?: string;
+  /** Actual verified receipt when available. */
+  receipt?: DocsProjectionReceipt;
+  /** Explicit failures or unresolved-outcome details. */
+  diagnostics: string[];
+  /** Original shared deadline. */
+  deadlineAt: number;
+  /** True when foreground observation crossed the deadline; no preemption is implied. */
+  deadlineExceeded: boolean;
+}
+
+/** Captured maintenance lifetime or an explicit unavailable identity diagnostic. */
+export type DocsProjectionCapture =
+  | {
+      /** A canonical stable project identity was read successfully. */
+      status: 'ready';
+      /** Original deadline and cancellation shared by every optional stage. */
+      context: OperationExecutionContext;
+    }
+  | {
+      /** No optional work may be admitted under a guessed identity. */
+      status: 'unavailable';
+      /** Diagnostic returned alongside accepted canonical bytes. */
+      outcome: DocsProjectionOutcome;
+    };
+
+/** Durable preparation result; does not assert that optional projections completed. */
+export interface DocsProjectionPreparation {
+  /** Existing durable job identity for explicit inspection and later execution. */
+  jobId: string;
+  /** Hash of the exact persisted proposal JSON bytes. */
+  proposalHash: string;
+  /** Owning project identity captured before asynchronous work. */
+  projectId: string;
+  /** Captured root used for canonical validation and pending storage. */
+  projectRoot: string;
+  /** Observed persisted lifecycle; preparation never schedules an executor. */
+  jobStatus: BackgroundJobStatus;
+  /** Absolute caller deadline, shared rather than reset by this stage. */
+  deadlineAt: number;
+  /** True if synchronous persistence returned after its admission deadline. */
+  deadlineExceeded: boolean;
+}
+
+/** Successful or policy-disabled optional graph projection of a canonical document. */
+export interface DocsGraphProjectionResult {
+  /** Explicit policy outcome; failures are not represented as successful completion. */
+  status: 'completed' | 'disabled';
+  /** Captured project identity owning the graph. */
+  projectId: string;
+  /** Captured absolute repository root used for all graph writes. */
+  projectRoot: string;
+}
+
 /**
  * Result of `docs.add`.
  */
 export interface DocsAddResult {
+  /** Optional projection coverage; canonical attachment acceptance remains independent. */
+  projection?: DocsProjectionOutcome;
   /** Newly-created or existing attachment ID. */
   attachmentId: string;
   /** SHA-256 hash of the attached content. */

package/src/operations/focus.ts

@@ -12,6 +12,11 @@
  * @epic T9964 E-ORIENT-V2
  */
 
+import type {
+  KnowledgeCoverage,
+  KnowledgeDiagnostic,
+  KnowledgeHealth,
+} from '../knowledge-health.js';
 import type { MviDigest } from '../mvi.js';
 import type { AttentionScopeKind } from './attention.js';
 import type { MemoryCompactHit } from './memory.js';
@@ -188,6 +193,12 @@ export interface FocusBrainContext {
  * @epic T9964
  */
 export interface FocusShowResult {
+  /** Assessed graph coverage; absence on legacy responses is not healthy coverage. */
+  coverage?: KnowledgeCoverage;
+  /** Bounded deterministic maintenance and sourced repair findings for the foreground caller. */
+  knowledgeHealth?: KnowledgeHealth;
+  /** Failed auxiliary reads are distinct from successfully empty sources. */
+  sourceDiagnostics?: Record<string, KnowledgeDiagnostic>;
   /** Core identity of the focused entity. */
   identity: FocusIdentity;
   /** Scope hierarchy (saga → epic → task) derived from ancestry. */

package/src/operations/nexus.ts

@@ -20,12 +20,14 @@
  */
 
 // API contract result types (T1065)
+import type { KnowledgeCoverage } from '../knowledge-health.js';
 import type { ContractCompatibilityMatrix } from '../nexus-contract-ops.js';
 // Living-brain result types (T1068)
 import type {
   CodeAnchorResult,
   CodeReasonTrace,
   ImpactFullReport,
+  RiskTier,
   SymbolFullContext,
   TaskCodeImpact,
 } from '../nexus-living-brain-ops.js';
@@ -860,6 +862,8 @@ export interface NexusImpactAffectedNode {
 }
 /** Result of `nexus.impact`. */
 export interface NexusImpactResult {
+  /** Evidence coverage assessed independently of impact severity. */
+  coverage?: KnowledgeCoverage;
   /** Original symbol query string. */
   query: string;
   /** Project ID the analysis ran against. */
@@ -871,7 +875,7 @@ export interface NexusImpactResult {
   /** Whether `why` reasons were requested and populated. */
   why: boolean;
   /** Risk tier based on totalImpact count. */
-  riskLevel: 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+  riskLevel: RiskTier;
   /** Total affected symbols across all depths (excludes the target itself). */
   totalImpact: number;
   /** Maximum traversal depth applied. */
@@ -1038,6 +1042,8 @@ export interface NexusTaskSymbolsParams {
 }
 /** Result of `nexus.task-symbols`. */
 export interface NexusTaskSymbolsResult {
+  /** Coverage and unresolved evidence, independent of the number of matches. */
+  coverage?: KnowledgeCoverage;
   /** Task ID that was queried. */
   taskId: string;
   /** Count of symbols found. */

package/src/operations/output-contracts-data.ts

@@ -144,12 +144,28 @@ const tasksShowOutputContract: OperationOutputContract = {
  *
  * Grounded in {@link TasksListResult}: `{ tasks: TaskOp[], total, filtered }`.
  */
+const taskPopulationSchema = {
+  type: 'object',
+  required: ['matched', 'returned', 'truncated', 'archive', 'limit', 'offset'],
+  properties: {
+    matched: { type: 'number', description: 'All rows matching the query before pagination.' },
+    returned: {
+      type: 'number',
+      description: 'Rows present in this response; also --output count.',
+    },
+    truncated: { type: 'boolean', description: 'Matching rows are omitted by this page.' },
+    archive: { type: 'string', enum: ['included', 'excluded', 'only'] },
+    limit: { type: ['number', 'null'] },
+    offset: { type: 'number' },
+  },
+} as const;
+
 const tasksListOutputContract: OperationOutputContract = {
   operation: 'tasks.list',
   shapeNote: 'Rows are under /data/tasks (an array); counts are /data/total and /data/filtered.',
   dataSchema: {
     type: 'object',
-    required: ['tasks', 'total', 'filtered'],
+    required: ['tasks', 'total', 'filtered', 'population'],
     additionalProperties: true,
     properties: {
       tasks: {
@@ -166,6 +182,7 @@ const tasksListOutputContract: OperationOutputContract = {
       },
       total: { type: 'number', description: 'Total tasks before filtering.' },
       filtered: { type: 'number', description: 'Number of tasks after filters applied.' },
+      population: taskPopulationSchema,
     },
   },
   fieldPointers: [
@@ -174,6 +191,9 @@ const tasksListOutputContract: OperationOutputContract = {
     '/data/tasks/0/status',
     '/data/total',
     '/data/filtered',
+    '/data/population/matched',
+    '/data/population/returned',
+    '/data/population/archive',
   ],
 };
 
@@ -198,7 +218,7 @@ const tasksFindOutputContract: OperationOutputContract = {
     'Use /data/results/0/id — NOT /data/0/id.',
   dataSchema: {
     type: 'object',
-    required: ['results', 'total'],
+    required: ['results', 'total', 'population'],
     additionalProperties: true,
     properties: {
       results: {
@@ -215,15 +235,25 @@ const tasksFindOutputContract: OperationOutputContract = {
         },
       },
       total: { type: 'number', description: 'Total matching tasks.' },
+      population: taskPopulationSchema,
       query: { type: 'string', description: 'The query string that was searched.' },
-      searchType: { type: 'string', description: 'Kind of search performed (fts, semantic, ...).' },
+      searchType: {
+        type: 'string',
+        description:
+          'Requested matching mode: lexical (default), fuzzy (explicit opt-in), exact, id, or filter.',
+      },
     },
   },
   fieldPointers: [
     '/data/results/0/id',
     '/data/results/0/title',
     '/data/results/0/status',
+    '/data/results/0/match',
+    '/data/searchType',
     '/data/total',
+    '/data/population/matched',
+    '/data/population/returned',
+    '/data/population/archive',
   ],
 };
 

package/src/operations/research.ts

@@ -154,3 +154,39 @@ export interface ResearchManifestArchiveResult {
   entryIds: string[];
   filesMovedCount?: number;
 }
+
+/** Physical manifest table contributing authentic stored evidence.
+ * @remarks Table identity does not imply scientific or decision authority.
+ * @example
+ * ```ts
+ * const table: ManifestStorageTable = 'docs_pipeline_manifest';
+ * ```
+ */
+export type ManifestStorageTable = 'docs_pipeline_manifest' | 'pipeline_manifest';
+
+/** Physical provenance of a manifest read; multiple tables imply identical stored payloads.
+ * @remarks Database identity is observed on the captured project binding; tables are not inferred from recency.
+ * @example
+ * ```ts
+ * const source: ManifestStorageProvenance = { databasePath: '/project/.cleo/cleo.db', tables: ['docs_pipeline_manifest'] };
+ * ```
+ */
+export interface ManifestStorageProvenance {
+  /** Absolute path of the canonical project database actually read. */
+  databasePath: string;
+  /** Tables containing byte-equivalent persisted rows, modern first. */
+  tables: ManifestStorageTable[];
+}
+
+/** Existing manifest data augmented with its storage provenance.
+ * @typeParam T - Existing row or public entry contract.
+ * @remarks Adds provenance without replacing the existing manifest result fields.
+ * @example
+ * ```ts
+ * type SourcedEntry = ManifestWithProvenance<ManifestEntry>;
+ * ```
+ */
+export type ManifestWithProvenance<T> = T & {
+  /** Observed physical storage sources; never an authority ranking. */
+  provenance: ManifestStorageProvenance;
+};