@cleocode/contracts 2026.5.96 → 2026.5.98

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (116) hide show
  1. package/dist/__tests__/enums.test.d.ts +14 -0
  2. package/dist/__tests__/enums.test.d.ts.map +1 -0
  3. package/dist/__tests__/enums.test.js +75 -0
  4. package/dist/__tests__/enums.test.js.map +1 -0
  5. package/dist/__tests__/jobs.test.d.ts +11 -0
  6. package/dist/__tests__/jobs.test.d.ts.map +1 -0
  7. package/dist/__tests__/jobs.test.js +48 -0
  8. package/dist/__tests__/jobs.test.js.map +1 -0
  9. package/dist/__tests__/memory-wire-shapes.test.d.ts +19 -0
  10. package/dist/__tests__/memory-wire-shapes.test.d.ts.map +1 -0
  11. package/dist/__tests__/memory-wire-shapes.test.js +119 -0
  12. package/dist/__tests__/memory-wire-shapes.test.js.map +1 -0
  13. package/dist/__tests__/operation-def.test.d.ts +20 -0
  14. package/dist/__tests__/operation-def.test.d.ts.map +1 -0
  15. package/dist/__tests__/operation-def.test.js +111 -0
  16. package/dist/__tests__/operation-def.test.js.map +1 -0
  17. package/dist/__tests__/provenance.test.d.ts +18 -0
  18. package/dist/__tests__/provenance.test.d.ts.map +1 -0
  19. package/dist/__tests__/provenance.test.js +142 -0
  20. package/dist/__tests__/provenance.test.js.map +1 -0
  21. package/dist/__tests__/scaffold-diagnostics.test.d.ts +19 -0
  22. package/dist/__tests__/scaffold-diagnostics.test.d.ts.map +1 -0
  23. package/dist/__tests__/scaffold-diagnostics.test.js +70 -0
  24. package/dist/__tests__/scaffold-diagnostics.test.js.map +1 -0
  25. package/dist/dispatch/identity.d.ts +72 -0
  26. package/dist/dispatch/identity.d.ts.map +1 -0
  27. package/dist/dispatch/identity.js +72 -0
  28. package/dist/dispatch/identity.js.map +1 -0
  29. package/dist/dispatch/operation-def.d.ts +92 -0
  30. package/dist/dispatch/operation-def.d.ts.map +1 -0
  31. package/dist/dispatch/operation-def.js +31 -0
  32. package/dist/dispatch/operation-def.js.map +1 -0
  33. package/dist/doctor.d.ts +43 -0
  34. package/dist/doctor.d.ts.map +1 -1
  35. package/dist/enums.d.ts +123 -0
  36. package/dist/enums.d.ts.map +1 -0
  37. package/dist/enums.js +139 -0
  38. package/dist/enums.js.map +1 -0
  39. package/dist/index.d.ts +15 -2
  40. package/dist/index.d.ts.map +1 -1
  41. package/dist/index.js +4 -0
  42. package/dist/index.js.map +1 -1
  43. package/dist/jobs.d.ts +39 -0
  44. package/dist/jobs.d.ts.map +1 -0
  45. package/dist/jobs.js +19 -0
  46. package/dist/jobs.js.map +1 -0
  47. package/dist/memory/budgeted.d.ts +67 -0
  48. package/dist/memory/budgeted.d.ts.map +1 -0
  49. package/dist/memory/budgeted.js +17 -0
  50. package/dist/memory/budgeted.js.map +1 -0
  51. package/dist/memory/fetch.d.ts +58 -0
  52. package/dist/memory/fetch.d.ts.map +1 -0
  53. package/dist/memory/fetch.js +19 -0
  54. package/dist/memory/fetch.js.map +1 -0
  55. package/dist/memory/observe.d.ts +158 -0
  56. package/dist/memory/observe.d.ts.map +1 -0
  57. package/dist/memory/observe.js +46 -0
  58. package/dist/memory/observe.js.map +1 -0
  59. package/dist/memory/search.d.ts +137 -0
  60. package/dist/memory/search.d.ts.map +1 -0
  61. package/dist/memory/search.js +22 -0
  62. package/dist/memory/search.js.map +1 -0
  63. package/dist/memory/timeline.d.ts +89 -0
  64. package/dist/memory/timeline.d.ts.map +1 -0
  65. package/dist/memory/timeline.js +22 -0
  66. package/dist/memory/timeline.js.map +1 -0
  67. package/dist/operations/focus.d.ts +199 -0
  68. package/dist/operations/focus.d.ts.map +1 -0
  69. package/dist/operations/focus.js +15 -0
  70. package/dist/operations/focus.js.map +1 -0
  71. package/dist/operations/index.d.ts +1 -0
  72. package/dist/operations/index.d.ts.map +1 -1
  73. package/dist/operations/index.js +1 -0
  74. package/dist/operations/index.js.map +1 -1
  75. package/dist/operations/session.d.ts +65 -0
  76. package/dist/operations/session.d.ts.map +1 -1
  77. package/dist/operations/tasks.d.ts +38 -0
  78. package/dist/operations/tasks.d.ts.map +1 -1
  79. package/dist/provenance.d.ts +257 -0
  80. package/dist/provenance.d.ts.map +1 -0
  81. package/dist/provenance.js +42 -0
  82. package/dist/provenance.js.map +1 -0
  83. package/dist/release/plan.d.ts +7 -7
  84. package/dist/scaffold-diagnostics.d.ts +110 -0
  85. package/dist/scaffold-diagnostics.d.ts.map +1 -0
  86. package/dist/scaffold-diagnostics.js +28 -0
  87. package/dist/scaffold-diagnostics.js.map +1 -0
  88. package/dist/session.d.ts +37 -0
  89. package/dist/session.d.ts.map +1 -1
  90. package/dist/session.js.map +1 -1
  91. package/dist/tasks/archive.d.ts +3 -3
  92. package/package.json +42 -2
  93. package/src/__tests__/enums.test.ts +114 -0
  94. package/src/__tests__/jobs.test.ts +76 -0
  95. package/src/__tests__/memory-wire-shapes.test.ts +371 -0
  96. package/src/__tests__/operation-def.test.ts +185 -0
  97. package/src/__tests__/provenance.test.ts +259 -0
  98. package/src/__tests__/scaffold-diagnostics.test.ts +137 -0
  99. package/src/dispatch/identity.ts +109 -0
  100. package/src/dispatch/operation-def.ts +102 -0
  101. package/src/doctor.ts +44 -0
  102. package/src/enums.ts +144 -0
  103. package/src/index.ts +79 -1
  104. package/src/jobs.ts +45 -0
  105. package/src/memory/budgeted.ts +75 -0
  106. package/src/memory/fetch.ts +66 -0
  107. package/src/memory/observe.ts +176 -0
  108. package/src/memory/search.ts +145 -0
  109. package/src/memory/timeline.ts +100 -0
  110. package/src/operations/focus.ts +226 -0
  111. package/src/operations/index.ts +1 -0
  112. package/src/operations/session.ts +67 -0
  113. package/src/operations/tasks.ts +40 -0
  114. package/src/provenance.ts +335 -0
  115. package/src/scaffold-diagnostics.ts +119 -0
  116. package/src/session.ts +37 -0
@@ -0,0 +1,176 @@
1
+ /**
2
+ * BRAIN observation-write wire shapes.
3
+ *
4
+ * Canonical home for the parameters and result types of the public
5
+ * `observeBrain` operation — the unified BRAIN write path that persists
6
+ * agent observations into `brain_observations`. Companion to the
7
+ * read-side trio in {@link ./search.ts}, {@link ./timeline.ts}, and
8
+ * {@link ./fetch.ts}.
9
+ *
10
+ * The `BRAIN_OBSERVATION_SOURCE_TYPES` const is co-located here so the
11
+ * derived `BrainObservationSourceType` union has a single source of truth.
12
+ * `packages/core/src/store/memory-schema.ts` re-exports the const for
13
+ * Drizzle's `enum: [...]` column constraint, which requires the runtime
14
+ * tuple literal.
15
+ *
16
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
17
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
18
+ * (E-CONTRACTS-FOUNDATION).
19
+ *
20
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
21
+ */
22
+
23
+ import type { BrainSourceConfidence } from '../brain.js';
24
+ import type { BrainObservationType } from '../facade.js';
25
+
26
+ // ── BRAIN_OBSERVATION_SOURCE_TYPES + BrainObservationSourceType ─────
27
+
28
+ /**
29
+ * Source-type tuple for `brain_observations.source_type` — how the
30
+ * observation was created.
31
+ *
32
+ * Originally defined in `packages/core/src/store/memory-schema.ts:134`.
33
+ * Promoted here so the derived {@link BrainObservationSourceType} union
34
+ * lives alongside its source. `memory-schema.ts` re-exports the const
35
+ * because Drizzle's `{ enum: ... }` column constraint requires the runtime
36
+ * tuple literal.
37
+ *
38
+ * - `agent` — produced by a spawned agent at task time.
39
+ * - `session-debrief` — synthesized at session end by the debrief pipeline.
40
+ * - `claude-mem` — imported from a claude-mem migration batch.
41
+ * - `manual` — typed directly by the owner via `cleo memory observe`.
42
+ *
43
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
44
+ */
45
+ export const BRAIN_OBSERVATION_SOURCE_TYPES = [
46
+ 'agent',
47
+ 'session-debrief',
48
+ 'claude-mem',
49
+ 'manual',
50
+ ] as const;
51
+
52
+ /**
53
+ * Derived string-literal union of valid `source_type` values.
54
+ *
55
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
56
+ */
57
+ export type BrainObservationSourceType = (typeof BRAIN_OBSERVATION_SOURCE_TYPES)[number];
58
+
59
+ // ── ObserveBrainParams ──────────────────────────────────────────────
60
+
61
+ /**
62
+ * Parameters for `observeBrain`.
63
+ *
64
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
65
+ */
66
+ export interface ObserveBrainParams {
67
+ /** Observation narrative — the free-form text persisted to `brain_observations.narrative`. */
68
+ text: string;
69
+ /** Optional display title; auto-derived from `text` when omitted. */
70
+ title?: string;
71
+ /** Optional cognitive observation type (`feature`, `bugfix`, `decision`, …). */
72
+ type?: BrainObservationType;
73
+ /** Optional project scope ID; defaults to the current project root. */
74
+ project?: string;
75
+ /** Session ID that produced the observation (provenance). */
76
+ sourceSessionId?: string;
77
+ /** How the observation was created (default `agent`). */
78
+ sourceType?: BrainObservationSourceType;
79
+ /** T417: agent provenance — the name of the spawned agent producing this observation. */
80
+ agent?: string;
81
+ /**
82
+ * T549 Wave 1-A: source reliability level.
83
+ * Overrides the default routing. If omitted, routing is determined automatically:
84
+ * - sourceType 'manual' → 'owner'
85
+ * - sourceType 'session-debrief' → 'task-outcome'
86
+ * - otherwise → 'agent'
87
+ */
88
+ sourceConfidence?: BrainSourceConfidence;
89
+ /**
90
+ * T794 BRAIN-05: cross-references to other memory entries or external IDs.
91
+ * When this array has ≥1 entry, the observation is auto-promoted from
92
+ * 'short' to 'medium' tier at write time to protect it from soft-eviction.
93
+ */
94
+ crossRef?: string[];
95
+ /**
96
+ * T799: SHA-256 refs of attachments to link to this observation.
97
+ *
98
+ * Stored as a JSON-encoded string in the `attachments_json` column.
99
+ * Each entry must be a 64-char hex SHA-256 from the tasks.db attachment store.
100
+ */
101
+ attachmentRefs?: string[];
102
+ /**
103
+ * T1897: Producer pipeline that created this observation.
104
+ * - `manual` — typed directly by owner
105
+ * - `auto-extract` — from fulfillPromotionLog / LLM extraction
106
+ * - `transcript-ingest`— imported from raw session transcript
107
+ * - `session-debrief` — synthesized at session end
108
+ * - `test` — inserted by test code
109
+ *
110
+ * Null on legacy rows and when not specified.
111
+ */
112
+ origin?: string | null;
113
+ /**
114
+ * T1897: JSON array of source brain_observations.id values this row was derived from.
115
+ * Null for directly-observed rows.
116
+ */
117
+ provenanceChain?: string[] | null;
118
+ /**
119
+ * T992: Internal flag — when true, bypasses the verifyAndStore gate.
120
+ * Set only by storeVerifiedCandidate in extraction-gate.ts to avoid
121
+ * infinite recursion (gate → storeVerifiedCandidate → observeBrain → gate).
122
+ * External callers MUST NOT set this flag.
123
+ */
124
+ _skipGate?: boolean;
125
+ }
126
+
127
+ // ── ObserveBrainResult ──────────────────────────────────────────────
128
+
129
+ /**
130
+ * Result envelope returned by `observeBrain`.
131
+ *
132
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
133
+ */
134
+ export interface ObserveBrainResult {
135
+ /** Identifier of the newly-persisted observation row. */
136
+ id: string;
137
+ /** Resolved BRAIN table name (always `observation` for `observeBrain`). */
138
+ type: string;
139
+ /** ISO 8601 creation timestamp. */
140
+ createdAt: string;
141
+ }
142
+
143
+ // ── DocAttachmentObservationPayload ─────────────────────────────────
144
+
145
+ /**
146
+ * Structured payload stored in the `narrative` of a doc-attachment memory
147
+ * observation emitted by `cleo docs add` (T9976).
148
+ *
149
+ * The observation title is `"Doc attached: <slug>"` (or
150
+ * `"Doc attached: <attachmentId>"` when no slug is set) so
151
+ * `cleo memory find '<slug>'` reliably surfaces the entry via FTS.
152
+ *
153
+ * The payload is serialised as JSON and embedded in the observation
154
+ * `narrative` field so it can be recovered by `cleo memory verify`
155
+ * for round-trip attachment-existence checks.
156
+ *
157
+ * @task T9976
158
+ */
159
+ export interface DocAttachmentObservationPayload {
160
+ /** Slug recorded for this attachment (optional — omitted when none set). */
161
+ slug?: string;
162
+ /** Owner entity ID (task, session, observation, …). */
163
+ ownerId: string;
164
+ /** Taxonomy type classification (optional). */
165
+ type?: string;
166
+ /** Attachment ID assigned by the store. */
167
+ attachmentId: string;
168
+ /** ISO 8601 timestamp when the attachment was added. */
169
+ addedAt: string;
170
+ /**
171
+ * Observation kind discriminator — always `"doc-attachment"`.
172
+ * Used by `cleo memory verify` to identify doc-attachment observations
173
+ * and perform round-trip checks against the docs store.
174
+ */
175
+ kind: 'doc-attachment';
176
+ }
@@ -0,0 +1,145 @@
1
+ /**
2
+ * BRAIN compact-search wire shapes.
3
+ *
4
+ * Canonical home for the parameters and result types of the public
5
+ * `searchBrainCompact` operation — Layer 1 of CLEO's 3-layer BRAIN retrieval
6
+ * pattern (search → timeline → fetch). Returns index-level hits (~50 tokens
7
+ * per result) so agents can scan a wide candidate set cheaply before drilling
8
+ * into a specific entry.
9
+ *
10
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
11
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
12
+ * (E-CONTRACTS-FOUNDATION) so the Studio + CLI + downstream consumers can
13
+ * depend on the shape without importing core. Unblocks the
14
+ * `brain-retrieval.ts` god-module split tracked under E-CORE-DECOMP
15
+ * (T9834).
16
+ *
17
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
18
+ * @see Layer 2: {@link ./timeline.ts}
19
+ * @see Layer 3: {@link ./fetch.ts}
20
+ */
21
+
22
+ // ── BrainCompactHit ─────────────────────────────────────────────────
23
+
24
+ /**
25
+ * Single compact hit returned by `searchBrainCompact`.
26
+ *
27
+ * Minimal projection of a BRAIN table row designed for cheap scanning —
28
+ * the full payload is fetched on demand via `fetchBrainEntries` (Layer 3).
29
+ *
30
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
31
+ */
32
+ export interface BrainCompactHit {
33
+ /** Entry identifier (e.g. `D-arch-001`, `P-feat-042`). */
34
+ id: string;
35
+ /** Source BRAIN table that produced the hit. */
36
+ type: 'decision' | 'pattern' | 'learning' | 'observation';
37
+ /** Display title for the entry. */
38
+ title: string;
39
+ /** ISO 8601 creation date. */
40
+ date: string;
41
+ /** Legacy relevance score (BM25-only path); omit when `rrfScore` is set. */
42
+ relevance?: number;
43
+ /**
44
+ * RRF-fused score: sum of 1/(rank+60) across all retrieval sources.
45
+ * Present only when the RRF path is used (`useRRF=true`, default).
46
+ * Higher = stronger match. Comparable across results in the same query.
47
+ */
48
+ rrfScore?: number;
49
+ /**
50
+ * BM25-derived score, min-max normalized to [0, 1] across the result set.
51
+ * 1.0 = best BM25 rank in this query, 0.0 = worst (or not found via FTS).
52
+ * Present only when the RRF path is used and at least one FTS result exists.
53
+ */
54
+ bm25Score?: number;
55
+ /**
56
+ * Progressive-disclosure directives for follow-up operations.
57
+ *
58
+ * Maps follow-up keys (e.g. `fetch`, `timeline`) to suggested CLI commands.
59
+ * `Record<string, string>` mirrors the runtime `NextDirectives` alias used
60
+ * by `@cleocode/core`'s `mvi-helpers`.
61
+ */
62
+ _next?: Record<string, string>;
63
+ }
64
+
65
+ // ── SearchBrainCompactParams ────────────────────────────────────────
66
+
67
+ /**
68
+ * Parameters for `searchBrainCompact`.
69
+ *
70
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
71
+ */
72
+ export interface SearchBrainCompactParams {
73
+ /** Free-text query (FTS5 + optional vector recall). */
74
+ query: string;
75
+ /** Maximum number of hits to return (caller-bounded). */
76
+ limit?: number;
77
+ /** Restrict the search to a subset of BRAIN tables. */
78
+ tables?: Array<'decisions' | 'patterns' | 'learnings' | 'observations'>;
79
+ /** ISO 8601 lower-bound date filter (inclusive). */
80
+ dateStart?: string;
81
+ /** ISO 8601 upper-bound date filter (inclusive). */
82
+ dateEnd?: string;
83
+ /** T418: filter results to observations produced by a specific agent (Wave 8 mental models). */
84
+ agent?: string;
85
+ /**
86
+ * When true (default), use Reciprocal Rank Fusion to combine FTS5 and
87
+ * vector search results for higher recall and better ranking.
88
+ * When false, fall back to FTS5-only search (faster, no embeddings needed).
89
+ */
90
+ useRRF?: boolean;
91
+ /**
92
+ * T1085: Peer ID filter for CANT agent memory isolation (PSYCHE Wave 2).
93
+ *
94
+ * When provided, search results are scoped to entries where:
95
+ * `peer_id = peerId OR peer_id = 'global'`
96
+ *
97
+ * When omitted, all entries are returned — backward-compatible behavior.
98
+ */
99
+ peerId?: string;
100
+ /**
101
+ * T1085: When true (default when peerId is provided), include entries with
102
+ * `peer_id = 'global'` alongside the peer-specific entries.
103
+ *
104
+ * Set to false for strict per-peer isolation (no global pool bleed-through).
105
+ */
106
+ includeGlobal?: boolean;
107
+ /**
108
+ * T1900: ranking mode.
109
+ *
110
+ * - `recency` — ORDER BY created_at DESC, no BM25/RRF contribution.
111
+ * Use for recentObservations / recentLearnings where
112
+ * chronological freshness matters more than textual match.
113
+ * - `lexical` — FTS5 BM25 only (useRRF=false legacy path).
114
+ * - `hybrid` — Reciprocal Rank Fusion (default, useRRF=true path).
115
+ *
116
+ * @default 'hybrid'
117
+ */
118
+ mode?: 'recency' | 'lexical' | 'hybrid';
119
+ /**
120
+ * T1900: ISO 8601 timestamp lower-bound filter (inclusive).
121
+ *
122
+ * When provided, only rows with `created_at >= since` are returned.
123
+ * Applies to all modes including recency. Useful with `mode=hybrid`
124
+ * (e.g., `since=<30d>`) to limit pattern staleness.
125
+ *
126
+ * When omitted, no lower-bound date filter is applied.
127
+ */
128
+ since?: string;
129
+ }
130
+
131
+ // ── SearchBrainCompactResult ────────────────────────────────────────
132
+
133
+ /**
134
+ * Result envelope returned by `searchBrainCompact`.
135
+ *
136
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
137
+ */
138
+ export interface SearchBrainCompactResult {
139
+ /** Ordered compact hits (best match first). */
140
+ results: BrainCompactHit[];
141
+ /** Total number of matches before `limit` truncation. */
142
+ total: number;
143
+ /** Approximate token cost of the returned payload (~chars/4). */
144
+ tokensEstimated: number;
145
+ }
@@ -0,0 +1,100 @@
1
+ /**
2
+ * BRAIN timeline wire shapes.
3
+ *
4
+ * Canonical home for the parameters and result types of the public
5
+ * `timelineBrain` operation — Layer 2 of CLEO's 3-layer BRAIN retrieval
6
+ * pattern (search → timeline → fetch). Surfaces chronological neighbors
7
+ * around an anchor entry so an agent can reconstruct the surrounding
8
+ * memory context cheaply.
9
+ *
10
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
11
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
12
+ * (E-CONTRACTS-FOUNDATION). `BrainAnchor` is co-located here because it
13
+ * is the only `brain-row-types.ts` shape that escapes the core boundary
14
+ * via `TimelineBrainResult`; `packages/core/src/memory/brain-row-types.ts`
15
+ * continues to re-export it for internal callers.
16
+ *
17
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
18
+ * @see Layer 1: {@link ./search.ts}
19
+ * @see Layer 3: {@link ./fetch.ts}
20
+ */
21
+
22
+ // ── BrainAnchor ─────────────────────────────────────────────────────
23
+
24
+ /**
25
+ * Anchor entry around which a timeline is built.
26
+ *
27
+ * Carries the entry identifier, its source table (`type`), and the full
28
+ * payload (`data`) so the caller can render the anchor inline with the
29
+ * neighbor list without an additional `fetchBrainEntries` round trip.
30
+ *
31
+ * Originally defined in `packages/core/src/memory/brain-row-types.ts:46`.
32
+ *
33
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
34
+ */
35
+ export interface BrainAnchor {
36
+ /** Entry identifier (e.g. `O-abc123`, `D-arch-001`). */
37
+ id: string;
38
+ /** Source BRAIN table (e.g. `observation`, `decision`, `pattern`, `learning`). */
39
+ type: string;
40
+ /**
41
+ * Raw row payload as returned by the underlying SQL query.
42
+ *
43
+ * Typed as `unknown` because the shape varies by `type`. Callers narrow
44
+ * via a discriminated read or pass the value through to a renderer that
45
+ * already understands every BRAIN table shape.
46
+ */
47
+ data: unknown;
48
+ }
49
+
50
+ // ── TimelineBrainParams ─────────────────────────────────────────────
51
+
52
+ /**
53
+ * Parameters for `timelineBrain`.
54
+ *
55
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
56
+ */
57
+ export interface TimelineBrainParams {
58
+ /** Anchor entry ID to build the timeline around. */
59
+ anchor: string;
60
+ /** Number of chronologically-earlier neighbors to include. */
61
+ depthBefore?: number;
62
+ /** Number of chronologically-later neighbors to include. */
63
+ depthAfter?: number;
64
+ }
65
+
66
+ // ── TimelineNeighbor ────────────────────────────────────────────────
67
+
68
+ /**
69
+ * Compact neighbor projection used in timeline results.
70
+ *
71
+ * Each neighbor is reduced to an `{id, type, date}` triple so callers can
72
+ * cheaply scan a large window before drilling into specific entries via
73
+ * `fetchBrainEntries`.
74
+ *
75
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
76
+ */
77
+ export interface TimelineNeighbor {
78
+ /** Entry identifier. */
79
+ id: string;
80
+ /** Source BRAIN table (e.g. `observation`, `decision`). */
81
+ type: string;
82
+ /** ISO 8601 creation date. */
83
+ date: string;
84
+ }
85
+
86
+ // ── TimelineBrainResult ─────────────────────────────────────────────
87
+
88
+ /**
89
+ * Result envelope returned by `timelineBrain`.
90
+ *
91
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
92
+ */
93
+ export interface TimelineBrainResult {
94
+ /** The anchor entry, or `null` when the requested ID does not resolve. */
95
+ anchor: BrainAnchor | null;
96
+ /** Chronologically-earlier neighbors, oldest first. */
97
+ before: TimelineNeighbor[];
98
+ /** Chronologically-later neighbors, newest last. */
99
+ after: TimelineNeighbor[];
100
+ }
@@ -0,0 +1,226 @@
1
+ /**
2
+ * Focus Domain Operations — single-envelope task orientation.
3
+ *
4
+ * `cleo focus <id>` aggregates 8 separate orientation calls into one
5
+ * wire-format envelope covering identity, scope, members, blockers,
6
+ * the next parallel-safe wave, attached docs, recent git activity, and
7
+ * scope-filtered brain context.
8
+ *
9
+ * Token budget: ≤ 1 500 tokens for a typical task orientation request.
10
+ *
11
+ * @task T9973
12
+ * @epic T9964 E-ORIENT-V2
13
+ */
14
+
15
+ import type { MemoryCompactHit } from './memory.js';
16
+
17
+ // ---------------------------------------------------------------------------
18
+ // Params
19
+ // ---------------------------------------------------------------------------
20
+
21
+ /**
22
+ * Parameters for `focus.show`.
23
+ *
24
+ * @task T9973
25
+ */
26
+ export interface FocusShowParams {
27
+ /** Task, Epic, or Saga ID to orient on (e.g. `T9973`, `T9831`). Required. */
28
+ id: string;
29
+ }
30
+
31
+ // ---------------------------------------------------------------------------
32
+ // Result sub-types
33
+ // ---------------------------------------------------------------------------
34
+
35
+ /**
36
+ * Minimal identity block surfaced for the focused entity.
37
+ *
38
+ * @task T9973
39
+ */
40
+ export interface FocusIdentity {
41
+ /** Task / Epic / Saga identifier. */
42
+ id: string;
43
+ /** Human-readable title. */
44
+ title: string;
45
+ /** Entity tier — `'task'`, `'epic'`, or `'saga'`. */
46
+ type: string;
47
+ /** Current lifecycle status. */
48
+ status: string;
49
+ /** Parent task / Epic identifier, if any. */
50
+ parentId?: string | null;
51
+ }
52
+
53
+ /**
54
+ * Scope hierarchy resolved from the focused entity's ancestry.
55
+ *
56
+ * @task T9973
57
+ */
58
+ export interface FocusScope {
59
+ /** Saga ID, when the entity belongs to a Saga. */
60
+ sagaId?: string;
61
+ /** Epic ID when the entity is a task or the focused entity itself is an Epic. */
62
+ epicId?: string;
63
+ /** Task ID when the focused entity is a task. */
64
+ taskId?: string;
65
+ }
66
+
67
+ /**
68
+ * One member Epic of a Saga, with a rollup status.
69
+ *
70
+ * Populated only when `focus.show` is called on a Saga ID.
71
+ *
72
+ * @task T9973
73
+ */
74
+ export interface FocusSagaMember {
75
+ /** Epic task identifier. */
76
+ epicId: string;
77
+ /** Rollup status for the Epic (e.g. `'active'`, `'done'`). */
78
+ status: string;
79
+ /** Epic title. */
80
+ title: string;
81
+ }
82
+
83
+ /**
84
+ * One task blocking the focused entity.
85
+ *
86
+ * @task T9973
87
+ */
88
+ export interface FocusBlocker {
89
+ /** ID of the task that is blocking. */
90
+ id: string;
91
+ /** Title of the blocking task. */
92
+ title: string;
93
+ /** Human-readable reason the dependency is unresolved. */
94
+ reason: string;
95
+ }
96
+
97
+ /**
98
+ * One ready task from the next parallel-safe wave of the parent Epic.
99
+ *
100
+ * @task T9973
101
+ */
102
+ export interface FocusReadyTask {
103
+ /** Task identifier. */
104
+ id: string;
105
+ /** Task title. */
106
+ title: string;
107
+ /** Engine-rolled priority. */
108
+ priority: string;
109
+ /** Dependency IDs (already satisfied for ready tasks). */
110
+ depends: string[];
111
+ }
112
+
113
+ /**
114
+ * One doc attachment linked to the focused entity.
115
+ *
116
+ * @task T9973
117
+ */
118
+ export interface FocusAttachedDoc {
119
+ /** Attachment identifier (att_* or UUID). */
120
+ attachmentId: string;
121
+ /** Human-friendly slug, when assigned. */
122
+ slug?: string;
123
+ /** Taxonomy classification, when assigned. */
124
+ type?: string;
125
+ /** Storage kind (e.g. `'local-file'`, `'url'`, `'blob'`). */
126
+ kind: string;
127
+ }
128
+
129
+ /**
130
+ * One recent git commit mentioning the focused task ID.
131
+ *
132
+ * @task T9973
133
+ */
134
+ export interface FocusRecentCommit {
135
+ /** Full 40-character commit SHA. */
136
+ commitSha: string;
137
+ /** Commit subject line (first line of the commit message). */
138
+ message: string;
139
+ /** ISO 8601 author date. */
140
+ date: string;
141
+ }
142
+
143
+ /**
144
+ * Brain context scoped to the focused entity (≤ 3 entries per category).
145
+ *
146
+ * @task T9973
147
+ */
148
+ export interface FocusBrainContext {
149
+ /** Recent observations relevant to the focused entity. */
150
+ observations: MemoryCompactHit[];
151
+ /** Learnings relevant to the focused entity. */
152
+ learnings: MemoryCompactHit[];
153
+ /** Decisions relevant to the focused entity. */
154
+ decisions: MemoryCompactHit[];
155
+ }
156
+
157
+ // ---------------------------------------------------------------------------
158
+ // Result
159
+ // ---------------------------------------------------------------------------
160
+
161
+ /**
162
+ * Result of `focus.show` — the single-envelope task orientation response.
163
+ *
164
+ * All fields except `identity` and `scope` are omitted when the
165
+ * underlying data source returns nothing (empty arrays, unavailable stores,
166
+ * git not in repo). Consumers MUST handle optional fields gracefully.
167
+ *
168
+ * Token budget: ≤ 1 500 tokens for typical task orientation.
169
+ *
170
+ * @task T9973
171
+ * @epic T9964
172
+ */
173
+ export interface FocusShowResult {
174
+ /** Core identity of the focused entity. */
175
+ identity: FocusIdentity;
176
+ /** Scope hierarchy (saga → epic → task) derived from ancestry. */
177
+ scope: FocusScope;
178
+ /**
179
+ * Saga member Epics with rollup statuses.
180
+ * Populated only when `id` resolves to a Saga (`label='saga'`).
181
+ */
182
+ members?: FocusSagaMember[];
183
+ /**
184
+ * Tasks that are blocking the focused entity.
185
+ * Empty array when the entity is not blocked.
186
+ */
187
+ blockers: FocusBlocker[];
188
+ /**
189
+ * Next parallel-safe wave of tasks from the parent Epic.
190
+ * Omitted when the entity has no parent Epic or the ready-set is empty.
191
+ */
192
+ readyWave?: FocusReadyTask[];
193
+ /**
194
+ * Docs attached to the focused task/epic.
195
+ * Omitted when the docs store is unavailable or no attachments exist.
196
+ */
197
+ attachedDocs?: FocusAttachedDoc[];
198
+ /**
199
+ * Up to 5 most-recent git commits mentioning the focused task ID.
200
+ * Omitted when git is unavailable or no matching commits are found.
201
+ */
202
+ recentActivity?: FocusRecentCommit[];
203
+ /**
204
+ * Scope-filtered brain context — up to 3 entries per category.
205
+ * Omitted when the BRAIN store is unavailable.
206
+ */
207
+ brainContext?: FocusBrainContext;
208
+ /** Estimated token weight of this envelope. */
209
+ tokensEstimated: number;
210
+ }
211
+
212
+ // ---------------------------------------------------------------------------
213
+ // Typed op record
214
+ // ---------------------------------------------------------------------------
215
+
216
+ /**
217
+ * Typed operation record for the focus domain.
218
+ *
219
+ * Maps each operation name to its `[Params, Result]` tuple for compile-time
220
+ * narrowing in the dispatch layer.
221
+ *
222
+ * @task T9973
223
+ */
224
+ export type FocusOps = {
225
+ readonly show: readonly [FocusShowParams, FocusShowResult];
226
+ };
@@ -10,6 +10,7 @@ export * from './brain.js';
10
10
  export * from './conduit.js';
11
11
  export * from './dialectic.js';
12
12
  export * from './docs.js';
13
+ export * from './focus.js';
13
14
  export * from './intelligence.js';
14
15
  export * from './issues.js';
15
16
  export * from './lifecycle.js';