@mmnto/totem 1.113.1 → 1.115.0
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.
- package/dist/config-schema.d.ts +1 -1
- package/dist/config-schema.d.ts.map +1 -1
- package/dist/config-schema.js +1 -1
- package/dist/config-schema.js.map +1 -1
- package/dist/errors.d.ts +5 -1
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js.map +1 -1
- package/dist/fs-atomic.d.ts +63 -0
- package/dist/fs-atomic.d.ts.map +1 -0
- package/dist/fs-atomic.js +114 -0
- package/dist/fs-atomic.js.map +1 -0
- package/dist/fs-atomic.test.d.ts +2 -0
- package/dist/fs-atomic.test.d.ts.map +1 -0
- package/dist/fs-atomic.test.js +162 -0
- package/dist/fs-atomic.test.js.map +1 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -0
- package/dist/index.js.map +1 -1
- package/dist/ingest/pipeline.d.ts.map +1 -1
- package/dist/ingest/pipeline.js +5 -5
- package/dist/ingest/pipeline.js.map +1 -1
- package/dist/orchestration-resolver.d.ts +19 -0
- package/dist/orchestration-resolver.d.ts.map +1 -1
- package/dist/orchestration-resolver.js +5 -1
- package/dist/orchestration-resolver.js.map +1 -1
- package/dist/seat-lifecycle.d.ts +118 -0
- package/dist/seat-lifecycle.d.ts.map +1 -0
- package/dist/seat-lifecycle.js +197 -0
- package/dist/seat-lifecycle.js.map +1 -0
- package/dist/seat-lifecycle.test.d.ts +11 -0
- package/dist/seat-lifecycle.test.d.ts.map +1 -0
- package/dist/seat-lifecycle.test.js +210 -0
- package/dist/seat-lifecycle.test.js.map +1 -0
- package/dist/selection-manifest.d.ts +416 -0
- package/dist/selection-manifest.d.ts.map +1 -0
- package/dist/selection-manifest.js +444 -0
- package/dist/selection-manifest.js.map +1 -0
- package/dist/selection-manifest.test.d.ts +26 -0
- package/dist/selection-manifest.test.d.ts.map +1 -0
- package/dist/selection-manifest.test.js +331 -0
- package/dist/selection-manifest.test.js.map +1 -0
- package/dist/spine/ledgers.d.ts +12 -12
- package/dist/verification-outcomes.d.ts.map +1 -1
- package/dist/verification-outcomes.js +6 -12
- package/dist/verification-outcomes.js.map +1 -1
- package/dist/worktree-registry.d.ts.map +1 -1
- package/dist/worktree-registry.js +4 -4
- package/dist/worktree-registry.js.map +1 -1
- package/package.json +15 -11
|
@@ -0,0 +1,416 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Per-seat selection manifests — the Prop 308 / strategy#467 M1 instrument
|
|
3
|
+
* (mmnto-ai/totem#2468).
|
|
4
|
+
*
|
|
5
|
+
* A selection manifest is a read-only record of one selection event: which
|
|
6
|
+
* candidates a consumer (session-start hook, `search_knowledge`, `totem
|
|
7
|
+
* orient`) considered on a seat's behalf, which it selected or excluded, what
|
|
8
|
+
* each cost, and the policy's own stated reason. It is a record of what each
|
|
9
|
+
* policy did — never a ranker, and it never adjudicates between policies.
|
|
10
|
+
*
|
|
11
|
+
* ## Contract (binding, from the Prop 308 round + the armed #467 pre-registration)
|
|
12
|
+
*
|
|
13
|
+
* - **No shared relevance score, no common weights** (Prop 308 F1, unanimous;
|
|
14
|
+
* lc-codex refute condition). Both schema levels are `.strict()` so a shared
|
|
15
|
+
* score field cannot be added without failing parse of existing rows — the
|
|
16
|
+
* guard is structural, not a promise. Per-candidate `reason` strings carry
|
|
17
|
+
* each policy's OWN words (a floor value in a search reason is that policy's
|
|
18
|
+
* stated reason, not a common weight).
|
|
19
|
+
* - **Senses, never gates** (Tenet 13). Emission must never block, filter, or
|
|
20
|
+
* alter a selection. Command call sites use {@link senseSelectionManifest};
|
|
21
|
+
* the throwing writer exists so the contract is testable and a programming
|
|
22
|
+
* error is never silent (the `qbd/record.ts` posture, mirrored).
|
|
23
|
+
* - **Named cost basis** (#467 outcome 3's naming requirement): every figure
|
|
24
|
+
* names its aggregation — {@link SELECTION_COST_BASIS} is a fixed literal
|
|
25
|
+
* stamped on every row. What the manifest emits is a PAYLOAD-BYTE census
|
|
26
|
+
* with a declared token approximation; it is NOT the ruled `<total>` basis
|
|
27
|
+
* (measured cache-aware consumption), and whether it may substitute for a
|
|
28
|
+
* `<total>` surface is the pre-registration's call via versioned revision
|
|
29
|
+
* (#467 §9), never this module's claim.
|
|
30
|
+
* - **No fabricated measurement:** a manifest records only what the policy
|
|
31
|
+
* observed. Candidates the policy never read (recency-excluded journals,
|
|
32
|
+
* first-match-losing proposals) are recorded id-only — no fingerprint, no
|
|
33
|
+
* bytes. Emitters never over-fetch to manufacture exclusions, which would
|
|
34
|
+
* alter the thing being measured.
|
|
35
|
+
* - **Recorded absence, never silent skip** (the #2466 clause): the
|
|
36
|
+
* denominator lives in `events.ndjson` rows (`session_start`, `mcp_call`,
|
|
37
|
+
* `derive_action`) that ship independently of this instrument. A denominator
|
|
38
|
+
* row with no matching manifest row IS the recorded absence; a failed write
|
|
39
|
+
* additionally warns on the emitter's accounting channel.
|
|
40
|
+
*/
|
|
41
|
+
import { z } from 'zod';
|
|
42
|
+
/**
|
|
43
|
+
* Sidecar file, NOT rows in `events.ndjson` (ruled 2026-08-10, #2468 OQ1):
|
|
44
|
+
* per-candidate arrays are bulky, and the event stream's existing consumers
|
|
45
|
+
* (QBD scanner, stats) keep their scan economics. Same directory, same
|
|
46
|
+
* append-only + gitignored conventions; growth is bounded the same way
|
|
47
|
+
* `events.ndjson` is (janitorial rotation is a separate, pre-existing class).
|
|
48
|
+
*/
|
|
49
|
+
export declare const SELECTION_MANIFESTS_FILE = "selection-manifests.ndjson";
|
|
50
|
+
/**
|
|
51
|
+
* The named aggregation stamped on every row (#467 outcome-3 requirement:
|
|
52
|
+
* a measure without its basis reports NOT OBSERVED — so the basis rides the
|
|
53
|
+
* data). `bytes` is the UTF-8 byte length of the exact content the policy
|
|
54
|
+
* considered; `approxTokens` is declared as the chars/4 approximation, never
|
|
55
|
+
* presented as a measured token count.
|
|
56
|
+
*/
|
|
57
|
+
export declare const SELECTION_COST_BASIS: {
|
|
58
|
+
readonly bytes: "utf8-length";
|
|
59
|
+
readonly approxTokens: "ceil(bytes/4) approximation";
|
|
60
|
+
};
|
|
61
|
+
/** Emitting consumers — the three selection surfaces named by #2468. */
|
|
62
|
+
export declare const SELECTION_EMITTERS: readonly ["session-start", "search_knowledge", "orient"];
|
|
63
|
+
export type SelectionEmitter = (typeof SELECTION_EMITTERS)[number];
|
|
64
|
+
/**
|
|
65
|
+
* One candidate the policy observed. `.strict()` — see the module contract:
|
|
66
|
+
* no field can be added silently, which is the structural half of the Prop 308
|
|
67
|
+
* refute-condition guard.
|
|
68
|
+
*/
|
|
69
|
+
export declare const SelectionCandidateSchema: z.ZodEffects<z.ZodObject<{
|
|
70
|
+
/**
|
|
71
|
+
* Candidate identity: repo-relative path or logical id. The coarse join
|
|
72
|
+
* key for the overlap number — a whole-file fingerprint and a chunk
|
|
73
|
+
* fingerprint of the same source will not collide, so cross-emitter joins
|
|
74
|
+
* anchor on `id` first and use `fingerprint` for exactness. Join policy
|
|
75
|
+
* belongs to the measurement pass, declared here rather than solved.
|
|
76
|
+
*/
|
|
77
|
+
id: z.ZodString;
|
|
78
|
+
/** Linked-repo origin for federated hits; absent for primary/local. */
|
|
79
|
+
sourceRepo: z.ZodOptional<z.ZodString>;
|
|
80
|
+
/**
|
|
81
|
+
* sha256 hex, first 16 chars, over the EXACT bytes the policy considered.
|
|
82
|
+
* Absent when the policy never read the content (id-only exclusion) or
|
|
83
|
+
* when hashing failed (which also appends to `warnings` — an absent
|
|
84
|
+
* fingerprint is honest, a fabricated one never is).
|
|
85
|
+
*/
|
|
86
|
+
fingerprint: z.ZodOptional<z.ZodString>;
|
|
87
|
+
/** UTF-8 byte length of the considered content. Absent on id-only rows. */
|
|
88
|
+
bytes: z.ZodOptional<z.ZodNumber>;
|
|
89
|
+
/** ceil(bytes/4), under the declared approximation basis. */
|
|
90
|
+
approxTokens: z.ZodOptional<z.ZodNumber>;
|
|
91
|
+
/**
|
|
92
|
+
* What the policy did with this candidate. `truncated` = selected but
|
|
93
|
+
* partially delivered (`deliveredBytes` carries what actually shipped).
|
|
94
|
+
*/
|
|
95
|
+
disposition: z.ZodEnum<["selected", "truncated", "excluded"]>;
|
|
96
|
+
/**
|
|
97
|
+
* The policy's own stated reason — the why-selected / why-excluded half
|
|
98
|
+
* that is invisible today. Free text owned by the emitting policy.
|
|
99
|
+
*/
|
|
100
|
+
reason: z.ZodString;
|
|
101
|
+
/** For `truncated` rows: bytes actually delivered after the cut. */
|
|
102
|
+
deliveredBytes: z.ZodOptional<z.ZodNumber>;
|
|
103
|
+
}, "strict", z.ZodTypeAny, {
|
|
104
|
+
reason: string;
|
|
105
|
+
id: string;
|
|
106
|
+
disposition: "truncated" | "selected" | "excluded";
|
|
107
|
+
sourceRepo?: string | undefined;
|
|
108
|
+
fingerprint?: string | undefined;
|
|
109
|
+
bytes?: number | undefined;
|
|
110
|
+
approxTokens?: number | undefined;
|
|
111
|
+
deliveredBytes?: number | undefined;
|
|
112
|
+
}, {
|
|
113
|
+
reason: string;
|
|
114
|
+
id: string;
|
|
115
|
+
disposition: "truncated" | "selected" | "excluded";
|
|
116
|
+
sourceRepo?: string | undefined;
|
|
117
|
+
fingerprint?: string | undefined;
|
|
118
|
+
bytes?: number | undefined;
|
|
119
|
+
approxTokens?: number | undefined;
|
|
120
|
+
deliveredBytes?: number | undefined;
|
|
121
|
+
}>, {
|
|
122
|
+
reason: string;
|
|
123
|
+
id: string;
|
|
124
|
+
disposition: "truncated" | "selected" | "excluded";
|
|
125
|
+
sourceRepo?: string | undefined;
|
|
126
|
+
fingerprint?: string | undefined;
|
|
127
|
+
bytes?: number | undefined;
|
|
128
|
+
approxTokens?: number | undefined;
|
|
129
|
+
deliveredBytes?: number | undefined;
|
|
130
|
+
}, {
|
|
131
|
+
reason: string;
|
|
132
|
+
id: string;
|
|
133
|
+
disposition: "truncated" | "selected" | "excluded";
|
|
134
|
+
sourceRepo?: string | undefined;
|
|
135
|
+
fingerprint?: string | undefined;
|
|
136
|
+
bytes?: number | undefined;
|
|
137
|
+
approxTokens?: number | undefined;
|
|
138
|
+
deliveredBytes?: number | undefined;
|
|
139
|
+
}>;
|
|
140
|
+
export type SelectionCandidate = z.infer<typeof SelectionCandidateSchema>;
|
|
141
|
+
/**
|
|
142
|
+
* The CLOSED set of per-emitter context keys. Closing the key space is the
|
|
143
|
+
* context-layer half of the Prop 308 refute-condition guard (PR #2625 CR
|
|
144
|
+
* round): with an open record, `context.sharedRelevanceScore` would have
|
|
145
|
+
* parsed cleanly and the "no shared score without a schema change" claim held
|
|
146
|
+
* only at the row/candidate layers. Adding a context key is now a deliberate
|
|
147
|
+
* schema change, exactly like adding a field.
|
|
148
|
+
*/
|
|
149
|
+
export declare const SELECTION_CONTEXT_KEYS: readonly ["query", "boundary", "typeFilter", "floor", "finalLimit", "method", "status", "storesFailed", "storesUnavailable", "render", "branch", "ticket", "selfAgent", "template"];
|
|
150
|
+
export type SelectionContextKey = (typeof SELECTION_CONTEXT_KEYS)[number];
|
|
151
|
+
/** One selection event — one NDJSON row in `selection-manifests.ndjson`. */
|
|
152
|
+
export declare const SelectionManifestRowSchema: z.ZodObject<{
|
|
153
|
+
schemaVersion: z.ZodLiteral<1>;
|
|
154
|
+
/** ISO 8601 instant of the selection event. */
|
|
155
|
+
timestamp: z.ZodString;
|
|
156
|
+
emitter: z.ZodEnum<["session-start", "search_knowledge", "orient"]>;
|
|
157
|
+
/** Session UUID from `.totem/ledger/.session-id` — the denominator join key. */
|
|
158
|
+
session_id: z.ZodOptional<z.ZodString>;
|
|
159
|
+
/** Seat id from TOTEM_SELF_AGENT (ADR-078). Absent = stamped absence, never guessed. */
|
|
160
|
+
agent_source: z.ZodOptional<z.ZodString>;
|
|
161
|
+
/** Emitting package version, when the emitter can resolve it cheaply. */
|
|
162
|
+
cli_version: z.ZodOptional<z.ZodString>;
|
|
163
|
+
context: z.ZodRecord<z.ZodEnum<["query", "boundary", "typeFilter", "floor", "finalLimit", "method", "status", "storesFailed", "storesUnavailable", "render", "branch", "ticket", "selfAgent", "template"]>, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
|
|
164
|
+
/**
|
|
165
|
+
* Names the observable candidate pool (e.g. `store-returned-pool
|
|
166
|
+
* perStoreLimit=5`) — the honest boundary: exclusions are recorded only
|
|
167
|
+
* over candidates the emitter actually saw.
|
|
168
|
+
*/
|
|
169
|
+
universe: z.ZodString;
|
|
170
|
+
costBasis: z.ZodObject<{
|
|
171
|
+
bytes: z.ZodLiteral<"utf8-length">;
|
|
172
|
+
approxTokens: z.ZodLiteral<"ceil(bytes/4) approximation">;
|
|
173
|
+
}, "strict", z.ZodTypeAny, {
|
|
174
|
+
bytes: "utf8-length";
|
|
175
|
+
approxTokens: "ceil(bytes/4) approximation";
|
|
176
|
+
}, {
|
|
177
|
+
bytes: "utf8-length";
|
|
178
|
+
approxTokens: "ceil(bytes/4) approximation";
|
|
179
|
+
}>;
|
|
180
|
+
/**
|
|
181
|
+
* The session-start hook's global char slice — string-level, so its cut
|
|
182
|
+
* is NOT attributed per-candidate (declared limitation, not a gap).
|
|
183
|
+
*/
|
|
184
|
+
finalTruncation: z.ZodOptional<z.ZodObject<{
|
|
185
|
+
cap: z.ZodNumber;
|
|
186
|
+
totalChars: z.ZodNumber;
|
|
187
|
+
applied: z.ZodBoolean;
|
|
188
|
+
}, "strict", z.ZodTypeAny, {
|
|
189
|
+
cap: number;
|
|
190
|
+
totalChars: number;
|
|
191
|
+
applied: boolean;
|
|
192
|
+
}, {
|
|
193
|
+
cap: number;
|
|
194
|
+
totalChars: number;
|
|
195
|
+
applied: boolean;
|
|
196
|
+
}>>;
|
|
197
|
+
candidates: z.ZodArray<z.ZodEffects<z.ZodObject<{
|
|
198
|
+
/**
|
|
199
|
+
* Candidate identity: repo-relative path or logical id. The coarse join
|
|
200
|
+
* key for the overlap number — a whole-file fingerprint and a chunk
|
|
201
|
+
* fingerprint of the same source will not collide, so cross-emitter joins
|
|
202
|
+
* anchor on `id` first and use `fingerprint` for exactness. Join policy
|
|
203
|
+
* belongs to the measurement pass, declared here rather than solved.
|
|
204
|
+
*/
|
|
205
|
+
id: z.ZodString;
|
|
206
|
+
/** Linked-repo origin for federated hits; absent for primary/local. */
|
|
207
|
+
sourceRepo: z.ZodOptional<z.ZodString>;
|
|
208
|
+
/**
|
|
209
|
+
* sha256 hex, first 16 chars, over the EXACT bytes the policy considered.
|
|
210
|
+
* Absent when the policy never read the content (id-only exclusion) or
|
|
211
|
+
* when hashing failed (which also appends to `warnings` — an absent
|
|
212
|
+
* fingerprint is honest, a fabricated one never is).
|
|
213
|
+
*/
|
|
214
|
+
fingerprint: z.ZodOptional<z.ZodString>;
|
|
215
|
+
/** UTF-8 byte length of the considered content. Absent on id-only rows. */
|
|
216
|
+
bytes: z.ZodOptional<z.ZodNumber>;
|
|
217
|
+
/** ceil(bytes/4), under the declared approximation basis. */
|
|
218
|
+
approxTokens: z.ZodOptional<z.ZodNumber>;
|
|
219
|
+
/**
|
|
220
|
+
* What the policy did with this candidate. `truncated` = selected but
|
|
221
|
+
* partially delivered (`deliveredBytes` carries what actually shipped).
|
|
222
|
+
*/
|
|
223
|
+
disposition: z.ZodEnum<["selected", "truncated", "excluded"]>;
|
|
224
|
+
/**
|
|
225
|
+
* The policy's own stated reason — the why-selected / why-excluded half
|
|
226
|
+
* that is invisible today. Free text owned by the emitting policy.
|
|
227
|
+
*/
|
|
228
|
+
reason: z.ZodString;
|
|
229
|
+
/** For `truncated` rows: bytes actually delivered after the cut. */
|
|
230
|
+
deliveredBytes: z.ZodOptional<z.ZodNumber>;
|
|
231
|
+
}, "strict", z.ZodTypeAny, {
|
|
232
|
+
reason: string;
|
|
233
|
+
id: string;
|
|
234
|
+
disposition: "truncated" | "selected" | "excluded";
|
|
235
|
+
sourceRepo?: string | undefined;
|
|
236
|
+
fingerprint?: string | undefined;
|
|
237
|
+
bytes?: number | undefined;
|
|
238
|
+
approxTokens?: number | undefined;
|
|
239
|
+
deliveredBytes?: number | undefined;
|
|
240
|
+
}, {
|
|
241
|
+
reason: string;
|
|
242
|
+
id: string;
|
|
243
|
+
disposition: "truncated" | "selected" | "excluded";
|
|
244
|
+
sourceRepo?: string | undefined;
|
|
245
|
+
fingerprint?: string | undefined;
|
|
246
|
+
bytes?: number | undefined;
|
|
247
|
+
approxTokens?: number | undefined;
|
|
248
|
+
deliveredBytes?: number | undefined;
|
|
249
|
+
}>, {
|
|
250
|
+
reason: string;
|
|
251
|
+
id: string;
|
|
252
|
+
disposition: "truncated" | "selected" | "excluded";
|
|
253
|
+
sourceRepo?: string | undefined;
|
|
254
|
+
fingerprint?: string | undefined;
|
|
255
|
+
bytes?: number | undefined;
|
|
256
|
+
approxTokens?: number | undefined;
|
|
257
|
+
deliveredBytes?: number | undefined;
|
|
258
|
+
}, {
|
|
259
|
+
reason: string;
|
|
260
|
+
id: string;
|
|
261
|
+
disposition: "truncated" | "selected" | "excluded";
|
|
262
|
+
sourceRepo?: string | undefined;
|
|
263
|
+
fingerprint?: string | undefined;
|
|
264
|
+
bytes?: number | undefined;
|
|
265
|
+
approxTokens?: number | undefined;
|
|
266
|
+
deliveredBytes?: number | undefined;
|
|
267
|
+
}>, "many">;
|
|
268
|
+
/** Per-row accounting: every non-fatal degradation names itself here. */
|
|
269
|
+
warnings: z.ZodArray<z.ZodString, "many">;
|
|
270
|
+
}, "strict", z.ZodTypeAny, {
|
|
271
|
+
schemaVersion: 1;
|
|
272
|
+
timestamp: string;
|
|
273
|
+
warnings: string[];
|
|
274
|
+
emitter: "orient" | "search_knowledge" | "session-start";
|
|
275
|
+
context: Partial<Record<"status" | "method" | "boundary" | "branch" | "ticket" | "query" | "typeFilter" | "floor" | "finalLimit" | "storesFailed" | "storesUnavailable" | "render" | "selfAgent" | "template", string | number | boolean | null>>;
|
|
276
|
+
universe: string;
|
|
277
|
+
costBasis: {
|
|
278
|
+
bytes: "utf8-length";
|
|
279
|
+
approxTokens: "ceil(bytes/4) approximation";
|
|
280
|
+
};
|
|
281
|
+
candidates: {
|
|
282
|
+
reason: string;
|
|
283
|
+
id: string;
|
|
284
|
+
disposition: "truncated" | "selected" | "excluded";
|
|
285
|
+
sourceRepo?: string | undefined;
|
|
286
|
+
fingerprint?: string | undefined;
|
|
287
|
+
bytes?: number | undefined;
|
|
288
|
+
approxTokens?: number | undefined;
|
|
289
|
+
deliveredBytes?: number | undefined;
|
|
290
|
+
}[];
|
|
291
|
+
agent_source?: string | undefined;
|
|
292
|
+
session_id?: string | undefined;
|
|
293
|
+
cli_version?: string | undefined;
|
|
294
|
+
finalTruncation?: {
|
|
295
|
+
cap: number;
|
|
296
|
+
totalChars: number;
|
|
297
|
+
applied: boolean;
|
|
298
|
+
} | undefined;
|
|
299
|
+
}, {
|
|
300
|
+
schemaVersion: 1;
|
|
301
|
+
timestamp: string;
|
|
302
|
+
warnings: string[];
|
|
303
|
+
emitter: "orient" | "search_knowledge" | "session-start";
|
|
304
|
+
context: Partial<Record<"status" | "method" | "boundary" | "branch" | "ticket" | "query" | "typeFilter" | "floor" | "finalLimit" | "storesFailed" | "storesUnavailable" | "render" | "selfAgent" | "template", string | number | boolean | null>>;
|
|
305
|
+
universe: string;
|
|
306
|
+
costBasis: {
|
|
307
|
+
bytes: "utf8-length";
|
|
308
|
+
approxTokens: "ceil(bytes/4) approximation";
|
|
309
|
+
};
|
|
310
|
+
candidates: {
|
|
311
|
+
reason: string;
|
|
312
|
+
id: string;
|
|
313
|
+
disposition: "truncated" | "selected" | "excluded";
|
|
314
|
+
sourceRepo?: string | undefined;
|
|
315
|
+
fingerprint?: string | undefined;
|
|
316
|
+
bytes?: number | undefined;
|
|
317
|
+
approxTokens?: number | undefined;
|
|
318
|
+
deliveredBytes?: number | undefined;
|
|
319
|
+
}[];
|
|
320
|
+
agent_source?: string | undefined;
|
|
321
|
+
session_id?: string | undefined;
|
|
322
|
+
cli_version?: string | undefined;
|
|
323
|
+
finalTruncation?: {
|
|
324
|
+
cap: number;
|
|
325
|
+
totalChars: number;
|
|
326
|
+
applied: boolean;
|
|
327
|
+
} | undefined;
|
|
328
|
+
}>;
|
|
329
|
+
export type SelectionManifestRow = z.infer<typeof SelectionManifestRowSchema>;
|
|
330
|
+
/**
|
|
331
|
+
* Fingerprint the exact bytes a policy considered: sha256 hex, first 16.
|
|
332
|
+
* 64 bits of collision resistance is ample for a per-workspace corpus join
|
|
333
|
+
* key; the full digest would double every row's bulk for no analytical gain.
|
|
334
|
+
*/
|
|
335
|
+
export declare function fingerprintContent(content: string | Buffer): string;
|
|
336
|
+
/** Cost of a considered candidate under {@link SELECTION_COST_BASIS}. */
|
|
337
|
+
export declare function measureCandidateCost(content: string | Buffer): {
|
|
338
|
+
bytes: number;
|
|
339
|
+
approxTokens: number;
|
|
340
|
+
};
|
|
341
|
+
/**
|
|
342
|
+
* Build a fully-measured candidate from content the policy actually read.
|
|
343
|
+
*
|
|
344
|
+
* TOTAL over its input space (leg round 1, H-7): a non-string/non-Buffer
|
|
345
|
+
* `content` (a store row whose unchecked cast lied) or a hash failure
|
|
346
|
+
* degrades to an ID-ONLY row with the failure named on the returned warning —
|
|
347
|
+
* it never throws into the emitting command, and it never persists a
|
|
348
|
+
* fabricated or NaN measurement.
|
|
349
|
+
*/
|
|
350
|
+
export declare function buildMeasuredCandidate(input: {
|
|
351
|
+
id: string;
|
|
352
|
+
content: string | Buffer;
|
|
353
|
+
disposition: SelectionCandidate['disposition'];
|
|
354
|
+
reason: string;
|
|
355
|
+
sourceRepo?: string;
|
|
356
|
+
deliveredBytes?: number;
|
|
357
|
+
}): {
|
|
358
|
+
candidate: SelectionCandidate;
|
|
359
|
+
warning?: string;
|
|
360
|
+
};
|
|
361
|
+
export interface SelectionManifestInput {
|
|
362
|
+
/** Absolute path to the resolved `.totem` directory. */
|
|
363
|
+
totemDir: string;
|
|
364
|
+
emitter: SelectionEmitter;
|
|
365
|
+
context: Partial<Record<SelectionContextKey, string | number | boolean | null>>;
|
|
366
|
+
universe: string;
|
|
367
|
+
candidates: SelectionCandidate[];
|
|
368
|
+
warnings?: string[];
|
|
369
|
+
finalTruncation?: {
|
|
370
|
+
cap: number;
|
|
371
|
+
totalChars: number;
|
|
372
|
+
applied: boolean;
|
|
373
|
+
};
|
|
374
|
+
cliVersion?: string;
|
|
375
|
+
/** Test seam — production callers omit and the writer reads the clock. */
|
|
376
|
+
nowMs?: number;
|
|
377
|
+
/** Test seam — production callers omit and the writer reads `process.env`. */
|
|
378
|
+
env?: NodeJS.ProcessEnv;
|
|
379
|
+
/**
|
|
380
|
+
* Session UUID override for emitters that minted the id themselves (the
|
|
381
|
+
* session-start hooks). When absent, the id is read from the
|
|
382
|
+
* `.totem/ledger/.session-id` pointer.
|
|
383
|
+
*/
|
|
384
|
+
sessionId?: string;
|
|
385
|
+
}
|
|
386
|
+
export interface SelectionManifestResult {
|
|
387
|
+
/** True when the manifest row reached disk. */
|
|
388
|
+
written: boolean;
|
|
389
|
+
/**
|
|
390
|
+
* True when nothing was recorded because this is not an instrumented
|
|
391
|
+
* project (no `.totem` directory) — a normal state, not a degradation.
|
|
392
|
+
*/
|
|
393
|
+
skipped?: boolean;
|
|
394
|
+
warnings: string[];
|
|
395
|
+
}
|
|
396
|
+
/** Stamp attribution + basis onto an emitter's assembled input. */
|
|
397
|
+
export declare function buildSelectionManifestRow(input: SelectionManifestInput): SelectionManifestRow;
|
|
398
|
+
/**
|
|
399
|
+
* Validate and append one manifest row.
|
|
400
|
+
*
|
|
401
|
+
* Throws `SELECTION_MANIFEST_CONTRACT` on a schema-invalid row — that is a
|
|
402
|
+
* programming error in an emitter, and persisting it would hand the
|
|
403
|
+
* measurement pass a row `readSelectionManifests` silently skips (data loss
|
|
404
|
+
* dressed as data). I/O failures do not throw; they report through the
|
|
405
|
+
* returned `warnings` (the accounting channel).
|
|
406
|
+
*/
|
|
407
|
+
export declare function appendSelectionManifest(input: SelectionManifestInput): SelectionManifestResult;
|
|
408
|
+
export declare function senseSelectionManifest(input: SelectionManifestInput, onWarn?: (msg: string) => void): SelectionManifestResult;
|
|
409
|
+
/**
|
|
410
|
+
* Read all manifest rows, skipping schema-invalid lines (the generic-consumer
|
|
411
|
+
* convention shared with `readLedgerEvents`; a measurement pass that must
|
|
412
|
+
* count rejects reads the file raw — same division of labor as QBD's
|
|
413
|
+
* compliance scanner).
|
|
414
|
+
*/
|
|
415
|
+
export declare function readSelectionManifests(totemDir: string, onWarn?: (msg: string) => void): SelectionManifestRow[];
|
|
416
|
+
//# sourceMappingURL=selection-manifest.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"selection-manifest.d.ts","sourceRoot":"","sources":["../src/selection-manifest.ts"],"names":[],"mappings":"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"}
|