@sema-agent/core 7.64.0 → 7.65.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.
Files changed (103) hide show
  1. package/CHANGELOG.md +317 -0
  2. package/dist/agents/peer-held-queue.js +1 -1
  3. package/dist/agents/peer-idle.js +1 -1
  4. package/dist/agents/peer-session-drain.js +3 -3
  5. package/dist/agents/subagent.js +5 -2
  6. package/dist/core/auto-promote.d.ts +3 -2
  7. package/dist/core/background-agent-store.d.ts +7 -0
  8. package/dist/core/checkpoint-store.d.ts +2 -3
  9. package/dist/core/context-settings.d.ts +1 -2
  10. package/dist/core/context-settings.js +1 -1
  11. package/dist/core/engine-attestation.d.ts +2 -2
  12. package/dist/core/engine-notice.d.ts +13 -1
  13. package/dist/core/engine-notice.js +3 -1
  14. package/dist/core/file-history-store.d.ts +2 -2
  15. package/dist/core/file-history-store.js +0 -4
  16. package/dist/core/gate-fold.js +3 -1
  17. package/dist/core/governance-codes.d.ts +6 -4
  18. package/dist/core/governance-codes.js +4 -3
  19. package/dist/core/leg-identity.d.ts +18 -2
  20. package/dist/core/leg-identity.js +5 -7
  21. package/dist/core/mailbox-store.d.ts +1 -1
  22. package/dist/core/memory-engine/consolidation.d.ts +10 -4
  23. package/dist/core/memory-engine/consolidation.js +11 -1
  24. package/dist/core/memory-engine/control-objects.d.ts +36 -3
  25. package/dist/core/memory-engine/control-objects.js +134 -12
  26. package/dist/core/memory-engine/control-plane-adoption.d.ts +5 -2
  27. package/dist/core/memory-engine/control-plane-adoption.js +5 -3
  28. package/dist/core/memory-engine/delegation-settlement.d.ts +59 -42
  29. package/dist/core/memory-engine/delegation-settlement.js +175 -202
  30. package/dist/core/memory-engine/dual-root.d.ts +3 -2
  31. package/dist/core/memory-engine/dual-root.js +5 -1
  32. package/dist/core/memory-engine/engine.d.ts +16 -10
  33. package/dist/core/memory-engine/engine.js +138 -145
  34. package/dist/core/memory-engine/file-backend.d.ts +17 -11
  35. package/dist/core/memory-engine/file-backend.js +53 -103
  36. package/dist/core/memory-engine/layout.d.ts +129 -49
  37. package/dist/core/memory-engine/layout.js +202 -82
  38. package/dist/core/memory-engine/memory-age.d.ts +12 -0
  39. package/dist/core/memory-engine/memory-age.js +17 -0
  40. package/dist/core/memory-engine/memory-backend-contract.js +5 -4
  41. package/dist/core/memory-engine/memory-deployment.d.ts +1 -1
  42. package/dist/core/memory-engine/origin-clearance.js +1 -5
  43. package/dist/core/memory-engine/tools.d.ts +2 -2
  44. package/dist/core/memory-engine/tools.js +7 -7
  45. package/dist/core/memory-engine/types.d.ts +16 -10
  46. package/dist/core/memory-vector.d.ts +6 -14
  47. package/dist/core/memory.d.ts +0 -462
  48. package/dist/core/memory.js +0 -333
  49. package/dist/core/permission-rule-consent.d.ts +49 -18
  50. package/dist/core/permission-rule-consent.js +59 -38
  51. package/dist/core/permission-rule-store.d.ts +24 -14
  52. package/dist/core/retention.d.ts +2 -7
  53. package/dist/core/retention.js +0 -1
  54. package/dist/core/runner/classifier-ladder.d.ts +3 -1
  55. package/dist/core/runner/classifier-ladder.js +2 -2
  56. package/dist/core/runner/contracts.d.ts +9 -9
  57. package/dist/core/runner/delegation-owner.d.ts +0 -8
  58. package/dist/core/runner/delegation-owner.js +1 -3
  59. package/dist/core/runner/prepare-gate-stations.d.ts +8 -5
  60. package/dist/core/runner/prepare-gate-stations.js +13 -5
  61. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  62. package/dist/core/runner/prepare-memory.js +9 -9
  63. package/dist/core/runner/prepare-policy-chain.js +11 -3
  64. package/dist/core/runner/prepare-task.d.ts +5 -1
  65. package/dist/core/runner/prepare-task.js +3 -3
  66. package/dist/core/runner/run-notification-lane.js +1 -1
  67. package/dist/core/runner/sub-agent-deny-lists.d.ts +19 -0
  68. package/dist/core/runner/sub-agent-deny-lists.js +25 -0
  69. package/dist/core/secret-env.d.ts +2 -2
  70. package/dist/core/secret-env.js +6 -20
  71. package/dist/core/session-store.d.ts +6 -6
  72. package/dist/core/session-store.js +3 -3
  73. package/dist/core/store-contracts/background-agent-store-contract.js +13 -0
  74. package/dist/core/task-notification.d.ts +35 -8
  75. package/dist/core/task-notification.js +31 -13
  76. package/dist/core/task-registry-agent.js +1 -0
  77. package/dist/core/task-registry-shared.d.ts +4 -0
  78. package/dist/core/tool-errors.d.ts +3 -3
  79. package/dist/core/tool-spec.d.ts +7 -7
  80. package/dist/core/write-protect.d.ts +16 -0
  81. package/dist/core/write-protect.js +10 -0
  82. package/dist/engine/session/repo-utils.d.ts +14 -4
  83. package/dist/engine/session/repo-utils.js +5 -4
  84. package/dist/index.d.ts +6 -6
  85. package/dist/index.js +6 -6
  86. package/dist/prompts/default.d.ts +1 -2
  87. package/dist/scenarios/full-body.d.ts +1 -1
  88. package/dist/stores/file/adoption/adopt.d.ts +1 -1
  89. package/dist/stores/file/index.d.ts +1 -15
  90. package/dist/stores/file/index.js +1 -15
  91. package/dist/stores/file/permission-rule-store.d.ts +12 -1
  92. package/dist/stores/file/permission-rule-store.js +31 -4
  93. package/dist/stores/file/session-store.js +1 -1
  94. package/package.json +2 -2
  95. package/test/export-surface.snapshot.json +9 -73
  96. package/wire-changes/core-stores-sql@7.65.0.json +30 -0
  97. package/wire-changes/core@7.65.0.json +1650 -0
  98. package/wire-changes/mods-kernel@7.65.0.json +30 -0
  99. package/wire-changes/primitives@7.65.0.json +337 -0
  100. package/dist/core/memory-recall.d.ts +0 -208
  101. package/dist/core/memory-recall.js +0 -136
  102. package/dist/stores/file/memory-store.d.ts +0 -124
  103. package/dist/stores/file/memory-store.js +0 -353
@@ -1,44 +1,7 @@
1
- import { uuidv7 } from "../internal/harness.js";
2
1
  import { parseScopeKey } from "./memory-engine/scope-contract.js";
3
- import { termSet } from "./memory-vector.js";
4
2
  import { attrEscape } from "./task-notification.js";
5
3
  import { sanitizeUntrustedText, ENGINE_AUTHORITY_ENVELOPE_TAGS } from "./untrusted-text.js";
6
- import { thrownText } from "./thrown-value.js";
7
4
  import { CREDENTIAL_VOCABULARY, scanSecrets } from "@sema-agent/primitives";
8
- export function supportsConsolidation(store) {
9
- return (typeof store.searchScored === "function" &&
10
- typeof store.update === "function" &&
11
- typeof store.delete === "function");
12
- }
13
- export function supportsPeriodicConsolidation(store) {
14
- return (typeof store.getConsolidationCursor === "function" &&
15
- typeof store.setConsolidationCursor === "function");
16
- }
17
- export const CALLER_AUTHORED_TYPES = new Set(["user", "feedback", "project", "reference"]);
18
- export const DEFAULT_CALLER_AUTHORED_TYPE = "project";
19
- export class MemoryGateError extends Error {
20
- code;
21
- constructor(code, detail) {
22
- super(detail ? `${code}: ${detail}` : code);
23
- this.name = "MemoryGateError";
24
- this.code = code;
25
- }
26
- }
27
- export class MemoryProjectionError extends Error {
28
- code = "memory.projection_failed";
29
- committed = true;
30
- path;
31
- constructor(path, cause) {
32
- const detail = thrownText(cause);
33
- super(`memory.projection_failed: the note IS durably committed — only the derived projection ${path} could not be rewritten: ${detail}. ` +
34
- `Do not retry the write (it would store the note twice); the projection is rebuilt by the next mutation of this scope.`, cause !== undefined ? { cause } : undefined);
35
- this.name = "MemoryProjectionError";
36
- this.path = path;
37
- }
38
- }
39
- function hasPromotableMarker(note) {
40
- return note.outcomeStats !== undefined;
41
- }
42
5
  const REFUSE_WRITE_POLICY = Object.freeze({
43
6
  grade: "strict",
44
7
  readings: Object.freeze([Object.freeze({ kind: "raw" })]),
@@ -58,308 +21,12 @@ export function detectSecret(text) {
58
21
  return refuseLabel(row.id);
59
22
  return null;
60
23
  }
61
- export function enforceSecretWriteGate(body) {
62
- const label = detectSecret(body);
63
- if (label !== null) {
64
- throw new MemoryGateError("memory.secret_detected", `memory write blocked: detected ${label}`);
65
- }
66
- }
67
- export function enforceStructuredNoteSecretGate(note) {
68
- enforceSecretWriteGate(note.body);
69
- if (note.name !== undefined)
70
- enforceSecretWriteGate(note.name);
71
- if (note.description !== undefined)
72
- enforceSecretWriteGate(note.description);
73
- if (note.type !== undefined)
74
- enforceSecretWriteGate(note.type);
75
- }
76
- export function classifyPromotable(note) {
77
- if (hasPromotableMarker(note))
78
- return "promotable";
79
- if (note.type !== undefined && !CALLER_AUTHORED_TYPES.has(note.type))
80
- return "promotable";
81
- return "caller_authored";
82
- }
83
- export function enforcePromotableWriteGate(note, utilityVerdict, utilityGate) {
84
- if (classifyPromotable(note) === "caller_authored")
85
- return;
86
- if (utilityVerdict === undefined) {
87
- throw new MemoryGateError("memory.promotable_ungated", "promotable memory write requires a utilityVerdict");
88
- }
89
- if (utilityGate === undefined) {
90
- throw new MemoryGateError("memory.promotable_ungated", "promotable memory write but profile utilityGate is unwired");
91
- }
92
- if (!utilityGate(note.outcomeStats)) {
93
- throw new MemoryGateError("memory.promotable_ungated", "promotable memory write failed the profile utilityGate");
94
- }
95
- }
96
- function stripConsolidationGenerated(note) {
97
- if (note.consolidationGenerated === undefined)
98
- return note;
99
- const { consolidationGenerated: _drop, ...rest } = note;
100
- return rest;
101
- }
102
- export function guardedMemoryStore(inner, utilityGate) {
103
- const guarded = {
104
- get vectorMode() {
105
- return inner.vectorMode;
106
- },
107
- read: (scope) => inner.read(scope),
108
- clear: (scope) => inner.clear(scope),
109
- append: (scope, note) => {
110
- enforceSecretWriteGate(note);
111
- return inner.append(scope, note);
112
- },
113
- appendStructured: inner.appendStructured
114
- ? (scope, note) => {
115
- enforceStructuredNoteSecretGate(note);
116
- enforcePromotableWriteGate(note, undefined, utilityGate);
117
- return inner.appendStructured(scope, stripConsolidationGenerated(note));
118
- }
119
- : undefined,
120
- appendConsolidationGenerated: inner.appendStructured
121
- ? (scope, note) => {
122
- enforceStructuredNoteSecretGate(note);
123
- enforcePromotableWriteGate(note, undefined, utilityGate);
124
- const withMarker = { ...note, consolidationGenerated: true };
125
- if (inner.appendConsolidationGenerated)
126
- return inner.appendConsolidationGenerated(scope, withMarker);
127
- return inner.appendStructured(scope, withMarker);
128
- }
129
- : undefined,
130
- appendPromotable: (scope, note, utilityVerdict) => {
131
- enforceStructuredNoteSecretGate(note);
132
- enforcePromotableWriteGate(note, utilityVerdict, utilityGate);
133
- if (inner.appendPromotable)
134
- return inner.appendPromotable(scope, note, utilityVerdict);
135
- if (inner.appendStructured)
136
- return inner.appendStructured(scope, note);
137
- return inner.append(scope, note.body);
138
- },
139
- };
140
- if (inner.search)
141
- guarded.search = (scope, query, limit) => inner.search(scope, query, limit);
142
- if (inner.searchScored)
143
- guarded.searchScored = (scope, query, limit) => inner.searchScored(scope, query, limit);
144
- if (inner.update)
145
- guarded.update = (scope, id, text) => {
146
- enforceSecretWriteGate(text);
147
- return inner.update(scope, id, text);
148
- };
149
- if (inner.delete)
150
- guarded.delete = (scope, id) => inner.delete(scope, id);
151
- if (inner.listStructuredNotes)
152
- guarded.listStructuredNotes = (scope) => inner.listStructuredNotes(scope);
153
- if (inner.getByIds)
154
- guarded.getByIds = (scope, ids) => inner.getByIds(scope, ids);
155
- if (inner.getConsolidationCursor)
156
- guarded.getConsolidationCursor = (scope) => inner.getConsolidationCursor(scope);
157
- if (inner.setConsolidationCursor)
158
- guarded.setConsolidationCursor = (scope, cursor) => inner.setConsolidationCursor(scope, cursor);
159
- return guarded;
160
- }
161
- function renderBullet(e) {
162
- return `- (${e.ts} UTC) ${e.text}`;
163
- }
164
- export class InMemoryMemoryStore {
165
- byScope = new Map();
166
- cursorByScope = new Map();
167
- vectorMode = "lexical";
168
- read(scope) {
169
- const entries = this.byScope.get(scope);
170
- if (!entries || entries.length === 0) {
171
- return null;
172
- }
173
- return entries.map(renderBullet).join("\n");
174
- }
175
- append(scope, note) {
176
- const text = note.trim().replace(/^#+\s*/, "");
177
- if (!text) {
178
- return;
179
- }
180
- const ts = new Date().toISOString().replace("T", " ").slice(0, 16);
181
- const entry = { id: uuidv7(), text, ts };
182
- const arr = this.byScope.get(scope) ?? [];
183
- arr.push(entry);
184
- this.byScope.set(scope, arr);
185
- return entry.id;
186
- }
187
- appendStructured(scope, note) {
188
- const body = note.body.trim().replace(/^#+\s*/, "");
189
- if (!body)
190
- return "";
191
- const ts = new Date().toISOString().replace("T", " ").slice(0, 16);
192
- const entry = {
193
- id: uuidv7(),
194
- text: body,
195
- ts,
196
- name: note.name,
197
- type: note.type ?? "project",
198
- description: note.description?.trim() || firstSentence(body),
199
- links: note.links,
200
- ...(note.consolidationGenerated ? { consolidationGenerated: true } : {}),
201
- };
202
- const arr = this.byScope.get(scope) ?? [];
203
- arr.push(entry);
204
- this.byScope.set(scope, arr);
205
- return entry.id;
206
- }
207
- clear(scope) {
208
- this.byScope.delete(scope);
209
- this.cursorByScope.delete(scope);
210
- }
211
- search(scope, query, limit = 10) {
212
- const entries = this.byScope.get(scope);
213
- if (!entries || entries.length === 0) {
214
- return [];
215
- }
216
- return entries
217
- .map(renderBullet)
218
- .filter((b) => lexicalSearchMatch(query, b))
219
- .slice(-limit);
220
- }
221
- searchScored(scope, query, limit = 20) {
222
- const entries = this.byScope.get(scope);
223
- if (!entries || entries.length === 0) {
224
- return [];
225
- }
226
- const q = termSet(query);
227
- if (q.size === 0) {
228
- return [];
229
- }
230
- const scored = [];
231
- for (const e of entries) {
232
- const t = termSet(e.text);
233
- let inter = 0;
234
- for (const term of q) {
235
- if (t.has(term))
236
- inter++;
237
- }
238
- const union = q.size + t.size - inter;
239
- const jaccard = union === 0 ? 0 : inter / union;
240
- if (jaccard === 0)
241
- continue;
242
- scored.push({ id: e.id, text: e.text, score: 1 - jaccard, ...(e.consolidationGenerated ? { consolidationGenerated: true } : {}) });
243
- }
244
- scored.sort((a, b) => a.score - b.score);
245
- return scored.slice(0, limit);
246
- }
247
- update(scope, id, text) {
248
- const clean = text.trim();
249
- if (!clean) {
250
- return;
251
- }
252
- const entry = this.byScope.get(scope)?.find((e) => e.id === id);
253
- if (!entry) {
254
- return;
255
- }
256
- const newBody = clean.replace(/^#+\s*/, "");
257
- if (entry.description !== undefined && entry.description === firstSentence(entry.text)) {
258
- entry.description = firstSentence(newBody);
259
- }
260
- entry.text = newBody;
261
- entry.ts = new Date().toISOString().replace("T", " ").slice(0, 16);
262
- }
263
- delete(scope, id) {
264
- const arr = this.byScope.get(scope);
265
- if (!arr) {
266
- return;
267
- }
268
- const i = arr.findIndex((e) => e.id === id);
269
- if (i !== -1) {
270
- arr.splice(i, 1);
271
- }
272
- }
273
- listStructuredNotes(scope) {
274
- const entries = this.byScope.get(scope) ?? [];
275
- return entries.map((e) => ({
276
- id: e.id,
277
- description: e.description ?? firstSentence(e.text),
278
- ...parseNoteTimestamp(e.ts),
279
- ...(e.name ? { name: e.name } : {}),
280
- ...(e.type ? { type: e.type } : {}),
281
- ...(e.consolidationGenerated ? { consolidationGenerated: true } : {}),
282
- }));
283
- }
284
- getConsolidationCursor(scope) {
285
- return this.cursorByScope.get(scope);
286
- }
287
- setConsolidationCursor(scope, cursor) {
288
- this.cursorByScope.set(scope, cursor);
289
- }
290
- getByIds(scope, ids) {
291
- const entries = this.byScope.get(scope);
292
- if (!entries)
293
- return [];
294
- const want = new Set(ids);
295
- return entries
296
- .filter((e) => want.has(e.id))
297
- .map((e) => ({
298
- id: e.id,
299
- text: e.text,
300
- description: e.description ?? firstSentence(e.text),
301
- ...parseNoteTimestamp(e.ts),
302
- ...(e.name ? { name: e.name } : {}),
303
- ...(e.type ? { type: e.type } : {}),
304
- ...(e.consolidationGenerated ? { consolidationGenerated: true } : {}),
305
- }));
306
- }
307
- }
308
- export function expandLexicalTerms(term) {
309
- const t = term.toLowerCase();
310
- const out = new Set([t]);
311
- const stem = lightStem(t);
312
- const stemOk = stem !== t && stem.length >= 3;
313
- if (stemOk)
314
- out.add(stem);
315
- for (const group of LEXICAL_SYNONYM_GROUPS) {
316
- if (group.has(t) || (stemOk && group.has(stem)))
317
- for (const w of group)
318
- out.add(w);
319
- }
320
- return [...out];
321
- }
322
- export function lexicalSearchMatch(query, text) {
323
- const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
324
- if (terms.length === 0)
325
- return false;
326
- const lower = text.toLowerCase();
327
- const tokens = termSet(text);
328
- return terms.every((t) => {
329
- const variants = expandLexicalTerms(t);
330
- return variants.some((v) => v === t ? lower.includes(v) : tokens.has(v));
331
- });
332
- }
333
- const LEXICAL_SYNONYM_GROUPS = [
334
- new Set(["auth", "authentication", "authorization", "credentials", "credential", "login", "signin"]),
335
- new Set(["token", "bearer", "apikey", "secret", "key"]),
336
- new Set(["password", "passwd", "passphrase", "pwd"]),
337
- new Set(["delete", "remove", "drop", "erase"]),
338
- new Set(["config", "configuration", "settings", "setting"]),
339
- new Set(["error", "failure", "exception", "fault"]),
340
- new Set(["db", "database"]),
341
- ];
342
- function lightStem(t) {
343
- if (t.length > 4 && t.endsWith("ies"))
344
- return `${t.slice(0, -3)}y`;
345
- if (t.length > 3 && t.endsWith("es"))
346
- return t.slice(0, -2);
347
- if (t.length > 3 && t.endsWith("s") && !t.endsWith("ss"))
348
- return t.slice(0, -1);
349
- return t;
350
- }
351
24
  export function firstSentence(text) {
352
25
  const t = text.trim().replace(/\s+/g, " ");
353
26
  const dot = t.search(/[.!?](\s|$)/);
354
27
  const cut = dot >= 0 && dot < 160 ? dot + 1 : Math.min(t.length, 120);
355
28
  return t.slice(0, cut).trim();
356
29
  }
357
- export function parseNoteTimestamp(ts) {
358
- if (typeof ts !== "string" || ts.trim() === "")
359
- return { mtimeMs: 0, timestampMissing: true };
360
- const ms = Date.parse(`${ts.replace(" ", "T")}:00Z`);
361
- return Number.isFinite(ms) ? { mtimeMs: ms } : { mtimeMs: 0, timestampMissing: true };
362
- }
363
30
  export const MEMORY_PROJECT_KEY_ABSENT_REASONS = Object.freeze(["not_git", "bare", "unreadable"]);
364
31
  export function normalizeMemorySpec(input) {
365
32
  if (!input)
@@ -307,7 +307,10 @@ export declare function mintRuleTicket(recordId: string, candidateIndex: number)
307
307
  * field in which to write a rule of one's own, on this entry as on the redemption entry.
308
308
  *
309
309
  * `toolCallId` and `boundInputHash` are recorded so an auditor can tie the record back to the exact ask,
310
- * and a command the lane cannot speak for yields no record and no tickets at all.
310
+ * and a command the lane cannot speak for yields no record and no tickets at all (`undefined`). A record the approval-record
311
+ * store fails to create answers the refusal, not a rejection: `status: "refused"`, `code` `store_write`, `committed` `no`,
312
+ * `retriable` `true` (no rule is written here; a backend can commit the record and lose its acknowledgement, but nobody holds
313
+ * that record's id, so a repeat prepares a fresh card).
311
314
  *
312
315
  * What this does NOT claim: that the command named here is the command that was displayed. A surface that
313
316
  * shows one thing and says another is the same-layer trust §5 already states plainly — in an in-process
@@ -376,7 +379,7 @@ export declare function prepareCardApproval(opts: {
376
379
  offers: readonly RuleOffer[];
377
380
  tickets: RuleTicket[];
378
381
  candidates: RuleCandidate[];
379
- } | undefined>;
382
+ } | StoreRefusal | undefined>;
380
383
  /**
381
384
  * The authenticated confirmation transfer: pending → approved.
382
385
  *
@@ -430,8 +433,15 @@ export declare function confirmRuleApproval(opts: {
430
433
  * (missing echo, a record minted without one, or a different card). Refused BEFORE anything else,
431
434
  * settled replays included, and never returns a minted ticket;
432
435
  * - `"edit_rejected"` — the edited text failed a gate (validator refusal, coverage, record shape);
433
- * `detail` carries the specifics. */
434
- export type ConfirmRefusalReason = "record_not_found" | "record_schema_stale" | "record_malformed" | "selection_missing" | "selection_invalid" | "selection_mismatch" | "not_pending" | "conflict" | "edit_disabled" | "edit_binding_mismatch" | "edit_rejected";
436
+ * `detail` carries the specifics.
437
+ * The two storage words are the approval-record store's failure, in the words the redemption leg answers it in
438
+ * ({@link RuleRefusalCode}), minted by the same step ({@link storeStep}); `detail.message` carries the store's own message:
439
+ * - `"store_read"` — a read of the record threw, before anything of this confirmation was written;
440
+ * - `"store_write"` — the compare-and-set that records the confirmation threw: a backend can commit and lose its
441
+ * acknowledgement, so the record may or may not be settled — repeat the same confirmation, which a settled record
442
+ * answers as the idempotent yes.
443
+ * A confirmation writes no rule, so it carries no `committed` of its own: the word says what happened to the record. */
444
+ export type ConfirmRefusalReason = "record_not_found" | "record_schema_stale" | "record_malformed" | "selection_missing" | "selection_invalid" | "selection_mismatch" | "not_pending" | "conflict" | "edit_disabled" | "edit_binding_mismatch" | "edit_rejected" | "store_read" | "store_write";
435
445
  /** The confirmation outcome: landed, or refused with a named reason.
436
446
  *
437
447
  * `mintedCandidate` (additive) is present exactly when an EDITED candidate settled this confirmation —
@@ -440,8 +450,9 @@ export type ConfirmRefusalReason = "record_not_found" | "record_schema_stale" |
440
450
  * second card). `rule` is the CANONICAL spelling, which may differ from the submitted bytes (spelling
441
451
  * normalization); a surface echoes it back so the person sees the form that will actually persist.
442
452
  *
443
- * `detail` (additive, refusal arm) rides `edit_rejected`: `code` is the shared validator's refusal
444
- * code when the validator is what refused, absent when another gate did; `message` always says why. */
453
+ * `detail` (additive, refusal arm) rides `edit_rejected` and the two storage words: `code` is the shared validator's refusal
454
+ * code when the validator is what refused, absent when another gate did (and always absent beside a storage word); `message`
455
+ * always says why. */
445
456
  export type ConfirmResult = {
446
457
  ok: true;
447
458
  mintedCandidate?: {
@@ -512,7 +523,8 @@ export type EditedRuleTextPrecheck = {
512
523
  * so the surface's move is to not offer the edit box at all.
513
524
  */
514
525
  export declare function precheckEditedRuleText(text: string, command: string): EditedRuleTextPrecheck;
515
- /** What a redemption produced. `alreadyRedeemed` marks the replay path — the same dot, no second rule.
526
+ /** What a redemption produced. `alreadyRedeemed` marks the replay path — the same dot, no second rule. `redeemed` says
527
+ * the rule stands: a replayed dot the person removed since answers `dot_removed`, never `redeemed`.
516
528
  *
517
529
  * `rev` is the DURABLE store's revision. A session-scope redemption (design/382 §4.3) lands in the
518
530
  * session overlay and does not move it: its `rev` is a best-effort read of the store's current
@@ -522,7 +534,8 @@ export declare function precheckEditedRuleText(text: string, command: string): E
522
534
  * A refusal is one shape wherever this module refuses — the single ticket, the batch's own record-level refusals and
523
535
  * (with the member's identity beside them) a batch member's row: `reason` is the sentence for a person and is never
524
536
  * parsed, `code` the cause ({@link RuleRefusalCode}), `committed` what may be claimed about the bytes
525
- * ({@link RuleWriteCommitted}). */
537
+ * ({@link RuleWriteCommitted}), `retriable` whether repeating the same call may land what this one did not
538
+ * ({@link refusalRetriable}). */
526
539
  export type RedeemResult = {
527
540
  status: "redeemed";
528
541
  behavior: RuleBehavior;
@@ -535,8 +548,16 @@ export type RedeemResult = {
535
548
  status: "refused";
536
549
  code: RuleRefusalCode;
537
550
  committed: RuleWriteCommitted;
551
+ retriable: boolean;
538
552
  reason: string;
539
553
  };
554
+ /** What a step of this module that asks the approval-record store (or the writer's dot allocation) answers when it fails: the
555
+ * one mint's refusal, narrowed to the two words a storage failure carries. */
556
+ type StoreRefusal = Extract<RedeemResult, {
557
+ status: "refused";
558
+ }> & {
559
+ readonly code: "store_read" | "store_write";
560
+ };
540
561
  /**
541
562
  * Redeem one ticket into one persisted rule.
542
563
  *
@@ -545,7 +566,7 @@ export type RedeemResult = {
545
566
  * turn a click on `git status` into a rule for something else.
546
567
  *
547
568
  * This is also the one leg every member of a batch walk takes ({@link redeemRuleBatch}), so a refusal here is the
548
- * same `code` / `committed` / `reason` a member row carries (a member's row adds the member's identity).
569
+ * same `code` / `committed` / `retriable` / `reason` a member row carries (a member's row adds the member's identity).
549
570
  */
550
571
  export declare function redeemRuleTicket(opts: {
551
572
  ticket: RuleTicket;
@@ -608,10 +629,12 @@ export interface ImportPreview {
608
629
  * independent `alreadyRedeemed` axis (the single-leg replay marker: a dot-recorded-but-unlanded
609
630
  * retry is `alreadyRedeemed: true` AND `persisted`; a rule that pre-existed in the store is
610
631
  * `false` AND `deduped` — the two axes answer different questions and neither implies the other).
611
- * A refused row always carries its `reason` (a sentence for a person, never parsed) and two closed words: `code`, the
612
- * cause ({@link RuleRefusalCode}), and `committed`, what may be claimed about the bytes — the one reading is
613
- * {@link RuleWriteCommitted}'s, stated there and not here (a member whose dot a successful read finds no longer live is
614
- * read by it too). `deduped` counts as LANDED: an equivalent rule already standing means the consent is already in effect.
632
+ * A refused row always carries its `reason` (a sentence for a person, never parsed), two closed words — `code`, the
633
+ * cause ({@link RuleRefusalCode}), and `committed`, what may be claimed about the bytes (the one reading is
634
+ * {@link RuleWriteCommitted}'s, stated there and not here; a member whose dot a successful read finds no longer live is
635
+ * read by it too) — and `retriable`, whether walking the batch again may land this member ({@link refusalRetriable},
636
+ * derived once from the two words). `deduped` counts as LANDED: an equivalent rule already standing means the consent is
637
+ * already in effect.
615
638
  *
616
639
  * design/382 §4.3 — on a SESSION-scope member the two landed words mean the same thing about a
617
640
  * different home: landed in / already in the session's OVERLAY (a session rule's home store), never
@@ -635,6 +658,7 @@ export type RedeemedBatchMember = {
635
658
  readonly status: "refused";
636
659
  readonly code: RuleRefusalCode;
637
660
  readonly committed: RuleWriteCommitted;
661
+ readonly retriable: boolean;
638
662
  readonly reason: string;
639
663
  };
640
664
  /**
@@ -651,6 +675,10 @@ export type RedeemedBatchMember = {
651
675
  * asks". An entry that does not import (a spelling with no rule form, a tool the lane does not speak
652
676
  * for, a non-string) is DISCLOSED in `skipped` with its reason and stays in the settings file.
653
677
  *
678
+ * A record the approval-record store fails to create answers the same refusal the card entry does (`status: "refused"`,
679
+ * `store_write`, `committed: no`, `retriable: true`), in place of `{ preview, approvalId }`: a preview with no record behind it
680
+ * confirms nothing.
681
+ *
654
682
  * Only a rule the store reads the way its layer does is carried. A bare tool name is not (`unsupported.form`), and
655
683
  * neither is a user-layer path pattern written from `/` (`unsupported.layer_root`, every behavior): the user layer reads
656
684
  * it at its own directory (the configuration directory), a stored global rule reads `/x` at each task's project root, and
@@ -667,7 +695,7 @@ export declare function prepareCcImport(opts: {
667
695
  }): Promise<{
668
696
  preview: ImportPreview;
669
697
  approvalId?: string;
670
- }>;
698
+ } | StoreRefusal>;
671
699
  /**
672
700
  * The factory-reviewed starter set, offered when there is nothing to import.
673
701
  *
@@ -678,7 +706,8 @@ export declare function prepareCcImport(opts: {
678
706
  */
679
707
  export declare const STARTER_RULES: readonly string[];
680
708
  /** Prepare the starter batch as a pending approval record. Nothing takes effect without confirmation;
681
- * an unconfirmed deployment simply starts with an empty rule set. */
709
+ * an unconfirmed deployment simply starts with an empty rule set. A record the approval-record store fails to create answers
710
+ * the refusal (`status: "refused"`, `store_write`, `committed: no`, `retriable: true`), as the card and import entries do. */
682
711
  export declare function prepareStarterBatch(opts: {
683
712
  principal?: string;
684
713
  owner?: RuleOwner;
@@ -686,7 +715,7 @@ export declare function prepareStarterBatch(opts: {
686
715
  }): Promise<{
687
716
  preview: RuleCandidate[];
688
717
  approvalId: string;
689
- }>;
718
+ } | StoreRefusal>;
690
719
  /**
691
720
  * Redeem the CHOSEN offer of a confirmed record, member by member — reporting what actually landed
692
721
  * rather than what was previewed (dedup, concurrency and redemption-time validation can all move a
@@ -703,7 +732,8 @@ export declare function prepareStarterBatch(opts: {
703
732
  * dot reuse included; the walk adds no concurrency primitive of its own;
704
733
  * · a refused member does NOT fold the batch: "all or nothing" is the CONFIRMATION's semantics
705
734
  * (one yes covered the whole offer), not the landing's transaction shape — the walk continues
706
- * and the member's row says refused, with its reason, cause (`code`) and claim (`committed`);
735
+ * and the member's row says refused, with its reason, cause (`code`), claim (`committed`) and whether a
736
+ * re-walk may land it (`retriable`);
707
737
  * · resuming a partial walk IS re-walking: already-landed members answer `alreadyRedeemed: true`
708
738
  * and reuse their recorded dots (two concurrent walkers converge on one dot set, zero double
709
739
  * mints), unlanded members mint on;
@@ -714,7 +744,7 @@ export declare function prepareStarterBatch(opts: {
714
744
  * partial one;
715
745
  * · a walk that cannot start (the record is missing or cannot be read, another principal's, stale, pending,
716
746
  * malformed, or the owner's store cannot be resolved) answers no table: it answers the
717
- * {@link RedeemResult} refused arm, `code` / `committed` / `reason`, the one shape a single
747
+ * {@link RedeemResult} refused arm, `code` / `committed` / `retriable` / `reason`, the one shape a single
718
748
  * ticket's refusal and a member's row take.
719
749
  */
720
750
  export declare function redeemRuleBatch(opts: {
@@ -728,3 +758,4 @@ export declare function redeemRuleBatch(opts: {
728
758
  } | Extract<RedeemResult, {
729
759
  status: "refused";
730
760
  }>>;
761
+ export {};