@cleocode/contracts 2026.4.100 → 2026.4.102

package/dist/operations/validate.d.ts

@@ -1,12 +1,10 @@
 /**
- * Validate Domain Operations (11 operations)
+ * Validate / Check Domain Operations
  *
- * Query operations: 9
- * Mutate operations: 2
- */
-/**
- * Common validation types
+ * T982 extension: Added new types for gate, archive, coherence, compliance-sync,
+ * chain, grade, canon, workflow-compliance, verify-explain, and all protocol subtypes.
  */
+import type { WarpChain } from '../warp-chain.js';
 export type ValidationSeverity = 'error' | 'warning' | 'info';
 export interface ValidationViolation {
     rule: string;
@@ -28,21 +26,51 @@ export interface ComplianceMetrics {
     }>;
     bySeverity: Record<ValidationSeverity, number>;
 }
-/**
- * Query Operations
- */
 export interface ValidateSchemaParams {
-    fileType: 'todo' | 'config' | 'archive' | 'log' | 'manifest';
+    fileType?: 'todo' | 'config' | 'archive' | 'log' | 'manifest';
     filePath?: string;
+    type?: string;
+    data?: unknown;
 }
 export interface ValidateSchemaResult {
     valid: boolean;
     schemaVersion: string;
     violations: ValidationViolation[];
 }
-export interface ValidateProtocolParams {
-    taskId: string;
-    protocolType: 'research' | 'consensus' | 'specification' | 'decomposition' | 'implementation' | 'contribution' | 'release';
+export interface ValidateProtocolBaseParams {
+    mode?: 'task' | 'manifest';
+    taskId?: string;
+    manifestFile?: string;
+    strict?: boolean;
+}
+export interface ValidateProtocolParams extends ValidateProtocolBaseParams {
+    protocolType?: string;
+    votingMatrixFile?: string;
+    epicId?: string;
+    specFile?: string;
+    hasCodeChanges?: boolean;
+    adrContent?: string;
+    status?: 'proposed' | 'accepted' | 'superseded' | 'deprecated';
+    hitlReviewed?: boolean;
+    downstreamFlagged?: boolean;
+    persistedInDb?: boolean;
+    specMatchConfirmed?: boolean;
+    testSuitePassed?: boolean;
+    protocolComplianceChecked?: boolean;
+    framework?: string;
+    testsRun?: number;
+    testsPassed?: number;
+    testsFailed?: number;
+    coveragePercent?: number;
+    coverageThreshold?: number;
+    ivtLoopConverged?: boolean;
+    ivtLoopIterations?: number;
+    version?: string;
+    hasChangelog?: boolean;
+    artifactType?: string;
+    buildPassed?: boolean;
+    hasAttestation?: boolean;
+    hasSbom?: boolean;
 }
 export interface ValidateProtocolResult {
     taskId: string;
@@ -58,7 +86,7 @@ export interface ValidateProtocolResult {
 }
 export interface ValidateTaskParams {
     taskId: string;
-    checkMode: 'basic' | 'strict' | 'anti-hallucination';
+    checkMode?: 'basic' | 'strict' | 'anti-hallucination';
 }
 export interface ValidateTaskResult {
     taskId: string;
@@ -86,7 +114,7 @@ export interface ValidateManifestResult {
     violations: ValidationViolation[];
 }
 export interface ValidateOutputParams {
-    taskId: string;
+    taskId?: string;
     filePath: string;
 }
 export interface ValidateOutputResult {
@@ -105,6 +133,12 @@ export interface ValidateOutputResult {
 export interface ValidateComplianceSummaryParams {
     scope?: string;
     since?: string;
+    detail?: boolean;
+    limit?: number;
+    type?: string;
+    taskId?: string;
+    days?: number;
+    global?: unknown;
 }
 export type ValidateComplianceSummaryResult = ComplianceMetrics;
 export interface ValidateComplianceViolationsParams {
@@ -121,6 +155,7 @@ export interface ValidateComplianceViolationsResult {
 }
 export interface ValidateTestStatusParams {
     taskId?: string;
+    format?: string;
 }
 export interface ValidateTestStatusResult {
     total: number;
@@ -144,12 +179,99 @@ export interface ValidateTestCoverageResult {
     threshold: number;
     meetsThreshold: boolean;
 }
-/**
- * Mutate Operations
- */
+export interface ValidateCoherenceParams {
+    taskId?: string;
+}
+export interface ValidateCoherenceResult {
+    passed: boolean;
+    issues: string[];
+    warnings: string[];
+}
+export interface ValidateGateParams {
+    taskId: string;
+    gate?: string;
+    value?: boolean;
+    agent?: string;
+    all?: boolean;
+    reset?: boolean;
+    evidence?: string;
+    sessionId?: string;
+}
+export interface ValidateGateResult {
+    taskId: string;
+    gates: Record<string, boolean>;
+    passed: boolean;
+    round: number;
+}
+export interface ValidateVerifyExplainParams {
+    taskId: string;
+}
+export interface ValidateVerifyExplainResult {
+    taskId: string;
+    title?: string;
+    status?: string;
+    passed: boolean;
+    round: number;
+    gates: Record<string, boolean>;
+    evidence: Record<string, unknown[]>;
+    requiredGates: string[];
+    missingGates: string[];
+    explanation: string;
+}
+export type ArchiveReportTypeAlias = 'summary' | 'by-phase' | 'by-label' | 'by-priority' | 'cycle-times' | 'trends';
+export interface ValidateArchiveStatsParams {
+    period?: number;
+    report?: ArchiveReportTypeAlias;
+    since?: string;
+    until?: string;
+}
+export type ValidateArchiveStatsResult = Record<string, unknown>;
+export interface ValidateChainParams {
+    chain: WarpChain;
+}
+export interface ValidateChainResult {
+    wellFormed: boolean;
+    gateSatisfiable: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export interface ValidateGradeParams {
+    sessionId: string;
+}
+export type ValidateGradeResult = Record<string, unknown>;
+export interface ValidateGradeListParams {
+    sessionId?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface ValidateGradeListResult {
+    grades: unknown[];
+    total: number;
+    filtered: number;
+}
+export interface ValidateCanonParams {
+    taskId?: string;
+}
+export interface ValidateCanonResult {
+    passed: boolean;
+    violations: unknown[];
+    assertions: Array<{
+        passed: boolean;
+    }>;
+}
+export interface ValidateWorkflowComplianceParams {
+    since?: string;
+}
+export type ValidateWorkflowComplianceResult = Record<string, unknown>;
 export interface ValidateComplianceRecordParams {
     taskId: string;
-    result: ValidateProtocolResult;
+    result: string;
+    protocol?: string;
+    violations?: Array<{
+        code: string;
+        message: string;
+        severity: 'error' | 'warning';
+    }>;
 }
 export interface ValidateComplianceRecordResult {
     taskId: string;
@@ -167,4 +289,8 @@ export interface ValidateTestRunResult {
     duration: string;
     output?: string;
 }
+export interface ValidateComplianceSyncParams {
+    force?: boolean;
+}
+export type ValidateComplianceSyncResult = Record<string, unknown>;
 //# sourceMappingURL=validate.d.ts.map

package/dist/operations/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/operations/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/D,UAAU,EAAE,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;CAChD;AAED;;GAEG;AAGH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,GAAG,UAAU,CAAC;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAGD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EACR,UAAU,GACV,WAAW,GACX,eAAe,GACf,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,SAAS,CAAC;CACf;AACD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,YAAY,EAAE;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAGD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,GAAG,QAAQ,GAAG,oBAAoB,CAAC;CACtD;AACD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,MAAM,EAAE;QACN,YAAY,EAAE,OAAO,CAAC;QACtB,yBAAyB,EAAE,OAAO,CAAC;QACnC,WAAW,EAAE,OAAO,CAAC;QACrB,kBAAkB,EAAE,OAAO,CAAC;QAC5B,sBAAsB,EAAE,OAAO,CAAC;KACjC,CAAC;CACH;AAGD,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE;QACL,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;IACF,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAGD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE;QACN,UAAU,EAAE,OAAO,CAAC;QACpB,aAAa,EAAE,OAAO,CAAC;QACvB,SAAS,EAAE,OAAO,CAAC;QACnB,UAAU,EAAE,OAAO,CAAC;QACpB,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;IACF,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAGD,MAAM,WAAW,+BAA+B;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,MAAM,+BAA+B,GAAG,iBAAiB,CAAC;AAGhE,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,kCAAkC;IACjD,UAAU,EAAE,KAAK,CACf,mBAAmB,GAAG;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,CACF,CAAC;IACF,KAAK,EAAE,MAAM,CAAC;CACf;AAGD,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7D;AAGD,MAAM,WAAW,0BAA0B;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AAGH,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,sBAAsB,CAAC;CAChC;AACD,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAGD,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AACD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,wBAAwB,CAAC;IACjC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/operations/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/D,UAAU,EAAE,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,GAAG,UAAU,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AACD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,sBAAuB,SAAQ,0BAA0B;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,CAAC;IAC/D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,YAAY,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,oBAAoB,CAAC;CACvD;AACD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,MAAM,EAAE;QACN,YAAY,EAAE,OAAO,CAAC;QACtB,yBAAyB,EAAE,OAAO,CAAC;QACnC,WAAW,EAAE,OAAO,CAAC;QACrB,kBAAkB,EAAE,OAAO,CAAC;QAC5B,sBAAsB,EAAE,OAAO,CAAC;KACjC,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IACrD,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE;QACN,UAAU,EAAE,OAAO,CAAC;QACpB,aAAa,EAAE,OAAO,CAAC;QACvB,SAAS,EAAE,OAAO,CAAC;QACnB,UAAU,EAAE,OAAO,CAAC;QACpB,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;IACF,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,+BAA+B;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AACD,MAAM,MAAM,+BAA+B,GAAG,iBAAiB,CAAC;AAEhE,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,kCAAkC;IACjD,UAAU,EAAE,KAAK,CAAC,mBAAmB,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjG,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AACD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACpC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,UAAU,GACV,UAAU,GACV,aAAa,GACb,aAAa,GACb,QAAQ,CAAC;AAEb,MAAM,WAAW,0BAA0B;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjE,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,SAAS,CAAC;CAClB;AACD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1D,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,EAAE,CAAC;IACtB,UAAU,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,gCAAgC;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,MAAM,gCAAgC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvE,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;KAAE,CAAC,CAAC;CACtF;AACD,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AACD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,wBAAwB,CAAC;IACjC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AACD,MAAM,MAAM,4BAA4B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC"}

package/dist/operations/validate.js

@@ -1,8 +1,8 @@
 /**
- * Validate Domain Operations (11 operations)
+ * Validate / Check Domain Operations
  *
- * Query operations: 9
- * Mutate operations: 2
+ * T982 extension: Added new types for gate, archive, coherence, compliance-sync,
+ * chain, grade, canon, workflow-compliance, verify-explain, and all protocol subtypes.
  */
 export {};
 //# sourceMappingURL=validate.js.map

package/dist/task-record.d.ts

@@ -57,6 +57,25 @@ export interface TaskRecord {
     cancellationReason?: string;
     /** RCASD-IVTR+C pipeline stage. @task T060 */
     pipelineStage?: string | null;
+    /**
+     * Task role axis — intent of work (string-widened from {@link TaskRole}).
+     * Values: work | research | experiment | bug | spike | release
+     * @task T944
+     */
+    role?: string | null;
+    /**
+     * Task scope axis — granularity of work (string-widened from {@link TaskScope}).
+     * Values: project | feature | unit
+     * @task T944
+     */
+    scope?: string | null;
+    /**
+     * Bug severity (string-widened from {@link TaskSeverity}).
+     * Only valid when role='bug'. OWNER-WRITE-ONLY.
+     * Values: P0 | P1 | P2 | P3
+     * @task T944
+     */
+    severity?: string | null;
 }
 /**
  * Minimal task representation for find results.

package/dist/task-record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-record.d.ts","sourceRoot":"","sources":["../src/task-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,6DAA6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,gCAAgC;AAChC,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,YAAY,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iBAAiB,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAC7C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"task-record.d.ts","sourceRoot":"","sources":["../src/task-record.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.4.100",
+  "version": "2026.4.102",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,46 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./nexus-contract-ops": {
+      "types": "./dist/nexus-contract-ops.d.ts",
+      "import": "./dist/nexus-contract-ops.js"
+    },
+    "./nexus-contract-ops.js": {
+      "types": "./dist/nexus-contract-ops.d.ts",
+      "import": "./dist/nexus-contract-ops.js"
+    },
+    "./nexus-living-brain-ops": {
+      "types": "./dist/nexus-living-brain-ops.d.ts",
+      "import": "./dist/nexus-living-brain-ops.js"
+    },
+    "./nexus-living-brain-ops.js": {
+      "types": "./dist/nexus-living-brain-ops.d.ts",
+      "import": "./dist/nexus-living-brain-ops.js"
+    },
+    "./nexus-query-ops": {
+      "types": "./dist/nexus-query-ops.d.ts",
+      "import": "./dist/nexus-query-ops.js"
+    },
+    "./nexus-query-ops.js": {
+      "types": "./dist/nexus-query-ops.d.ts",
+      "import": "./dist/nexus-query-ops.js"
+    },
+    "./nexus-route-ops": {
+      "types": "./dist/nexus-route-ops.d.ts",
+      "import": "./dist/nexus-route-ops.js"
+    },
+    "./nexus-route-ops.js": {
+      "types": "./dist/nexus-route-ops.d.ts",
+      "import": "./dist/nexus-route-ops.js"
+    },
+    "./nexus-tasks-bridge-ops": {
+      "types": "./dist/nexus-tasks-bridge-ops.d.ts",
+      "import": "./dist/nexus-tasks-bridge-ops.js"
+    },
+    "./nexus-tasks-bridge-ops.js": {
+      "types": "./dist/nexus-tasks-bridge-ops.d.ts",
+      "import": "./dist/nexus-tasks-bridge-ops.js"
     }
   },
   "engines": {

package/src/brain-graph.ts

@@ -0,0 +1,282 @@
+/**
+ * Canonical Brain unified-graph types.
+ *
+ * These are the **single source of truth** for `BrainNode`, `BrainEdge`,
+ * `BrainGraph`, and their supporting types across the entire CLEO monorepo.
+ *
+ * All other packages MUST import these types from `@cleocode/contracts`
+ * (or a relative path into this file) rather than defining their own copies.
+ * Runtime packages such as `@cleocode/brain` re-export these types directly
+ * so downstream consumers do not need to change their import path.
+ *
+ * ## Shape rationale
+ *
+ * The types here are the **runtime** shapes produced by the substrate
+ * adapters in `@cleocode/brain` and consumed by every graph renderer,
+ * SSE stream, and API route in `@cleocode/studio`. The wire-format
+ * operation contracts in `./operations/brain.ts` are intentionally distinct
+ * (they use `from`/`to`/`kind` field names and a separate `BrainSubstrateName`
+ * vocabulary) and are namespaced under `ops.*` to avoid collisions.
+ *
+ * @task T989 — canonical type unification (was split across packages/brain
+ *   and packages/contracts/operations/brain)
+ * @task T973 — LB* → Brain* rename
+ * @task T969 — `@cleocode/brain` package extraction
+ * @see packages/brain/src/types.ts (re-exports from here for backwards compat)
+ * @see packages/contracts/src/operations/brain.ts (wire-format / ops contracts)
+ * @see docs/plans/brain-synaptic-visualization-research.md §5.2
+ */
+
+// ---------------------------------------------------------------------------
+// Supporting enum types
+// ---------------------------------------------------------------------------
+
+/**
+ * All possible node kinds across the five CLEO substrates.
+ *
+ * - `observation` / `decision` / `pattern` / `learning` → BRAIN typed tables
+ * - `task` / `session` → TASKS
+ * - `symbol` / `file` → NEXUS
+ * - `agent` → SIGNALDOCK
+ * - `message` → CONDUIT
+ */
+export type BrainNodeKind =
+  | 'observation'
+  | 'decision'
+  | 'pattern'
+  | 'learning'
+  | 'task'
+  | 'session'
+  | 'symbol'
+  | 'file'
+  | 'agent'
+  | 'message';
+
+/**
+ * Which database a node or edge originates from.
+ *
+ * @remarks
+ * Uses the literal `'brain'` to match the on-disk `brain.db` filename.
+ * This differs from `BrainSubstrateName` in `./operations/brain.ts` which
+ * uses `'memory'` to align with the cognitive-memory domain rename. Callers
+ * that bridge runtime output to the wire format translate between the two
+ * naming planes at the adapter boundary.
+ */
+export type BrainSubstrate = 'brain' | 'nexus' | 'tasks' | 'conduit' | 'signaldock';
+
+// ---------------------------------------------------------------------------
+// Canonical graph node
+// ---------------------------------------------------------------------------
+
+/**
+ * A single node in the unified CLEO Brain graph.
+ *
+ * The `id` field is always substrate-prefixed so nodes from different
+ * substrates can be merged without collisions:
+ * - `"brain:O-abc"` — a brain observation
+ * - `"nexus:sym-123"` — a nexus code symbol
+ * - `"tasks:T949"` — a CLEO task
+ * - `"conduit:msg-7f3a2b1c"` — a conduit message
+ * - `"signaldock:agent-cleo-prime"` — a SignalDock agent
+ *
+ * @remarks
+ * This is the shape produced by all substrate adapters in `@cleocode/brain`
+ * and consumed by graph renderers and SSE streams. It differs from the
+ * `BrainNodeWire` wire-format type in `./operations/brain.ts` which uses
+ * `type`/`data` instead of `kind`/`meta`.
+ */
+export interface BrainNode {
+  /** Substrate-prefixed identifier, e.g. `"brain:O-abc"`, `"nexus:sym-123"`. */
+  id: string;
+  /** Semantic category of this node. */
+  kind: BrainNodeKind;
+  /** Source database. */
+  substrate: BrainSubstrate;
+  /** Human-readable display label. */
+  label: string;
+  /**
+   * Optional numeric weight in `[0, 1]`.
+   *
+   * - BRAIN: `quality_score` (0.0–1.0)
+   * - NEXUS: in-degree / caller count (normalised)
+   * - TASKS: priority rank (critical=4 → 1.0, low=1 → 0.25)
+   * - CONDUIT / SIGNALDOCK: omitted
+   */
+  weight?: number;
+  /**
+   * ISO-8601 creation timestamp, or `null` when the substrate does not
+   * expose a timestamp for this node type.
+   *
+   * - BRAIN: `brain_*` tables `created_at` column (ISO text)
+   * - NEXUS: `nexus_nodes.indexed_at` column (ISO text)
+   * - TASKS: `tasks.created_at` / `sessions.started_at` column (ISO text)
+   * - CONDUIT: `messages.created_at` converted from UNIX epoch (INTEGER)
+   * - SIGNALDOCK: `agents.created_at` converted from UNIX epoch (INTEGER), or null
+   */
+  createdAt: string | null;
+  /** Substrate-specific metadata (source row fields, opaque to super-graph callers). */
+  meta: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Canonical graph edge
+// ---------------------------------------------------------------------------
+
+/**
+ * A directed edge between two nodes in the unified CLEO Brain graph.
+ *
+ * Both `source` and `target` reference `BrainNode.id` values
+ * (substrate-prefixed). Cross-substrate edges use `substrate: 'cross'`.
+ *
+ * @remarks
+ * This type uses `source`/`target`/`type` field names (matching D3/Cosmograph
+ * conventions). The wire-format type `BrainEdgeWire` in `./operations/brain.ts`
+ * uses `from`/`to`/`kind` and is a separate concern.
+ */
+export interface BrainEdge {
+  /** Source node ID (substrate-prefixed, references {@link BrainNode.id}). */
+  source: string;
+  /** Target node ID (substrate-prefixed, references {@link BrainNode.id}). */
+  target: string;
+  /**
+   * Semantic edge type.
+   *
+   * In-substrate examples: `'supersedes'` | `'derived_from'` | `'calls'` | `'imports'`
+   * Cross-substrate examples: `'mentions'` | `'applies_to'` | `'authored_by'` | `'modified'`
+   */
+  type: string;
+  /**
+   * Edge weight in `[0, 1]`. Higher = stronger / more confident.
+   *
+   * - BRAIN: `brain_page_edges.weight` (Hebbian/STDP-trained)
+   * - NEXUS: relation `confidence`
+   * - Others: `0.5` default
+   */
+  weight: number;
+  /** Which substrate produced this edge, or `'cross'` for synthesized cross-substrate edges. */
+  substrate: BrainSubstrate | 'cross';
+}
+
+// ---------------------------------------------------------------------------
+// Canonical graph response
+// ---------------------------------------------------------------------------
+
+/**
+ * Unified graph response returned by the Brain unified-graph API and the
+ * `getAllSubstrates` adapter in `@cleocode/brain`.
+ *
+ * - `nodes` / `edges`: combined projection across all requested substrates.
+ * - `counts`: per-substrate contribution breakdown.
+ * - `truncated`: `true` when results were capped by the `limit` parameter.
+ */
+export interface BrainGraph {
+  /** Merged, deduplicated nodes across all requested substrates. */
+  nodes: BrainNode[];
+  /** Directed edges (may reference stub nodes for cross-substrate targets). */
+  edges: BrainEdge[];
+  /** Per-substrate node/edge contribution counts. */
+  counts: {
+    /** Nodes contributed per substrate. */
+    nodes: Record<BrainSubstrate, number>;
+    /** Edges contributed per substrate (including `'cross'`). */
+    edges: Record<BrainSubstrate | 'cross', number>;
+  };
+  /** `true` when the response was capped by the node limit. */
+  truncated: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Project context (minimal, used for path resolution in adapters)
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimum project context required by Brain substrate adapters to resolve
+ * per-project database paths.
+ *
+ * The studio's richer `ProjectContext` type carries additional fields
+ * (`projectId`, `name`, `brainDbExists`, etc.) and satisfies this interface
+ * via TypeScript structural typing.
+ *
+ * @remarks
+ * Defined here (rather than in `@cleocode/brain`) so that `BrainQueryOptions`
+ * can reference it without creating a circular dependency.
+ */
+export interface BrainProjectContext {
+  /** Absolute path to the project root. */
+  projectPath: string;
+  /** Absolute path to `brain.db` for this project. */
+  brainDbPath: string;
+  /** Absolute path to `tasks.db` for this project. */
+  tasksDbPath: string;
+}
+
+// ---------------------------------------------------------------------------
+// Query options
+// ---------------------------------------------------------------------------
+
+/**
+ * Query options forwarded from API route query parameters to substrate adapters.
+ *
+ * - `substrates`: filter to specific databases; omit for all five.
+ * - `limit`: cap on total node count (default 500, max 2000).
+ * - `minWeight`: excludes nodes/edges below this quality threshold.
+ * - `projectCtx`: resolves per-project DB paths; required for correct
+ *   multi-project routing.
+ */
+export interface BrainQueryOptions {
+  /** Which substrates to include. Defaults to all five. */
+  substrates?: BrainSubstrate[];
+  /** Maximum number of nodes to return across all substrates. Default `500`. */
+  limit?: number;
+  /** Minimum quality/weight threshold for nodes and edges (0.0–1.0). Default `0`. */
+  minWeight?: number;
+  /**
+   * Active project context from `event.locals.projectCtx`.
+   * Per-project substrates (brain, tasks, conduit) use this to resolve DB paths.
+   * When absent, adapters fall back to the process-default paths.
+   */
+  projectCtx?: BrainProjectContext;
+}
+
+// ---------------------------------------------------------------------------
+// SSE stream event union
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated union of all SSE event payloads emitted by
+ * `GET /api/brain/stream`.
+ *
+ * Every variant carries a top-level `ts` field (ISO-8601 timestamp) so
+ * clients can sequence events even when they arrive out-of-order.
+ *
+ * - `hello`            — sent immediately on connect; confirms the stream is live.
+ * - `heartbeat`        — sent every 30 s to prevent connection timeout.
+ * - `node.create`      — a new row was inserted into `brain_observations`.
+ * - `edge.strengthen`  — a `brain_page_edges` row had its `weight` updated.
+ * - `task.status`      — a `tasks` row changed its `status` column.
+ * - `message.send`     — a new row was inserted into conduit messages.
+ */
+export type BrainStreamEvent =
+  | { type: 'hello'; ts: string }
+  | { type: 'heartbeat'; ts: string }
+  | { type: 'node.create'; node: BrainNode; ts: string }
+  | {
+      type: 'edge.strengthen';
+      fromId: string;
+      toId: string;
+      edgeType: string;
+      weight: number;
+      ts: string;
+    }
+  | { type: 'task.status'; taskId: string; status: string; ts: string }
+  | {
+      type: 'message.send';
+      messageId: string;
+      fromAgentId: string;
+      toAgentId: string;
+      preview: string;
+      ts: string;
+    };
+
+/** Connection state for the SSE client subscription in the studio brain viewer. */
+export type BrainConnectionStatus = 'connecting' | 'connected' | 'error' | 'disconnected';