@sema-agent/core 7.63.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 (239) hide show
  1. package/CHANGELOG.md +725 -0
  2. package/dist/agents/cc-peer-directory.js +1 -0
  3. package/dist/agents/cc-peer-wire.d.ts +4 -0
  4. package/dist/agents/cc-peer-wire.js +1 -0
  5. package/dist/agents/cc-uds-peer-channel.js +5 -0
  6. package/dist/agents/cross-session-judge.d.ts +3 -1
  7. package/dist/agents/cross-session-judge.js +4 -1
  8. package/dist/agents/peer-directory.d.ts +8 -0
  9. package/dist/agents/peer-directory.js +4 -0
  10. package/dist/agents/peer-held-queue.d.ts +9 -3
  11. package/dist/agents/peer-held-queue.js +12 -9
  12. package/dist/agents/peer-idle.d.ts +20 -1
  13. package/dist/agents/peer-idle.js +23 -12
  14. package/dist/agents/peer-notice-route.d.ts +16 -5
  15. package/dist/agents/peer-notice-route.js +11 -9
  16. package/dist/agents/peer-notices.d.ts +25 -8
  17. package/dist/agents/peer-notices.js +6 -1
  18. package/dist/agents/peer-session-drain.d.ts +32 -6
  19. package/dist/agents/peer-session-drain.js +100 -26
  20. package/dist/agents/send-message-tool.d.ts +7 -0
  21. package/dist/agents/send-message-tool.js +18 -6
  22. package/dist/agents/subagent.js +25 -5
  23. package/dist/core/allow-entry.d.ts +4 -0
  24. package/dist/core/ask-origin.d.ts +1 -1
  25. package/dist/core/ask-origin.js +2 -2
  26. package/dist/core/ask-unresolvable-notice.d.ts +13 -4
  27. package/dist/core/ask-unresolvable-notice.js +10 -3
  28. package/dist/core/auto-compaction.d.ts +7 -5
  29. package/dist/core/auto-promote.d.ts +3 -2
  30. package/dist/core/background-agent-store.d.ts +14 -0
  31. package/dist/core/background-agent-store.js +3 -0
  32. package/dist/core/checkpoint-queries.d.ts +9 -6
  33. package/dist/core/checkpoint-queries.js +8 -3
  34. package/dist/core/checkpoint-store.d.ts +7 -4
  35. package/dist/core/context-settings.d.ts +39 -9
  36. package/dist/core/context-settings.js +32 -10
  37. package/dist/core/engine-attestation.d.ts +26 -6
  38. package/dist/core/engine-attestation.js +5 -1
  39. package/dist/core/engine-notice.d.ts +37 -2
  40. package/dist/core/engine-notice.js +3 -1
  41. package/dist/core/extension-requester.d.ts +9 -0
  42. package/dist/core/extension-requester.js +7 -0
  43. package/dist/core/file-history-store.d.ts +30 -2
  44. package/dist/core/file-history-store.js +48 -9
  45. package/dist/core/fs-write-gate-policy.js +1 -1
  46. package/dist/core/gate-fold.js +5 -1
  47. package/dist/core/gate-lanes.js +2 -0
  48. package/dist/core/gate-outcome.d.ts +39 -2
  49. package/dist/core/gate-outcome.js +20 -1
  50. package/dist/core/governance-codes.d.ts +8 -4
  51. package/dist/core/governance-codes.js +8 -3
  52. package/dist/core/leg-identity.d.ts +35 -1
  53. package/dist/core/leg-identity.js +10 -0
  54. package/dist/core/mailbox-store.d.ts +39 -4
  55. package/dist/core/mailbox-store.js +14 -2
  56. package/dist/core/memory-engine/consolidation.d.ts +13 -6
  57. package/dist/core/memory-engine/consolidation.js +26 -0
  58. package/dist/core/memory-engine/control-objects.d.ts +58 -0
  59. package/dist/core/memory-engine/control-objects.js +273 -0
  60. package/dist/core/memory-engine/control-plane-adoption.d.ts +51 -0
  61. package/dist/core/memory-engine/control-plane-adoption.js +161 -0
  62. package/dist/core/memory-engine/delegation-settlement.d.ts +73 -40
  63. package/dist/core/memory-engine/delegation-settlement.js +271 -107
  64. package/dist/core/memory-engine/dual-root.d.ts +3 -2
  65. package/dist/core/memory-engine/dual-root.js +7 -3
  66. package/dist/core/memory-engine/engine.d.ts +54 -33
  67. package/dist/core/memory-engine/engine.js +150 -157
  68. package/dist/core/memory-engine/file-backend.d.ts +58 -76
  69. package/dist/core/memory-engine/file-backend.js +111 -268
  70. package/dist/core/memory-engine/index.d.ts +3 -2
  71. package/dist/core/memory-engine/index.js +2 -1
  72. package/dist/core/memory-engine/layout.d.ts +135 -50
  73. package/dist/core/memory-engine/layout.js +214 -89
  74. package/dist/core/memory-engine/memory-age.d.ts +12 -0
  75. package/dist/core/memory-engine/memory-age.js +17 -0
  76. package/dist/core/memory-engine/memory-backend-contract.d.ts +10 -3
  77. package/dist/core/memory-engine/memory-backend-contract.js +159 -2
  78. package/dist/core/memory-engine/memory-deployment.d.ts +12 -4
  79. package/dist/core/memory-engine/memory-deployment.js +31 -6
  80. package/dist/core/memory-engine/origin-clearance.d.ts +12 -3
  81. package/dist/core/memory-engine/origin-clearance.js +64 -9
  82. package/dist/core/memory-engine/session-write-home.d.ts +34 -1
  83. package/dist/core/memory-engine/session-write-home.js +37 -10
  84. package/dist/core/memory-engine/tools.d.ts +2 -2
  85. package/dist/core/memory-engine/tools.js +7 -7
  86. package/dist/core/memory-engine/types.d.ts +55 -12
  87. package/dist/core/memory-engine/types.js +2 -1
  88. package/dist/core/memory-vector.d.ts +6 -14
  89. package/dist/core/memory.d.ts +0 -462
  90. package/dist/core/memory.js +0 -333
  91. package/dist/core/mode-policy.js +3 -3
  92. package/dist/core/mods/agent-stations.d.ts +18 -0
  93. package/dist/core/mods/agent-stations.js +8 -6
  94. package/dist/core/mods/extension-call.d.ts +4 -0
  95. package/dist/core/mods/extension-call.js +8 -0
  96. package/dist/core/mods/tool-call.js +3 -4
  97. package/dist/core/parent-spec-seat.d.ts +2 -2
  98. package/dist/core/peer-channel.d.ts +5 -0
  99. package/dist/core/permission-rule-consent.d.ts +64 -22
  100. package/dist/core/permission-rule-consent.js +106 -58
  101. package/dist/core/permission-rule-store.d.ts +56 -21
  102. package/dist/core/permission-rule-store.js +2 -0
  103. package/dist/core/refusal-echo.d.ts +20 -0
  104. package/dist/core/refusal-echo.js +33 -0
  105. package/dist/core/retention.d.ts +175 -10
  106. package/dist/core/retention.js +44 -0
  107. package/dist/core/retired-keys.d.ts +5 -0
  108. package/dist/core/retired-keys.js +3 -0
  109. package/dist/core/rule-offer-read.d.ts +0 -4
  110. package/dist/core/rule-offer-read.js +2 -18
  111. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  112. package/dist/core/runner/classifier-ladder.js +4 -2
  113. package/dist/core/runner/compact-session.js +10 -7
  114. package/dist/core/runner/compaction-call-options.d.ts +7 -7
  115. package/dist/core/runner/compaction-call-options.js +3 -2
  116. package/dist/core/runner/contracts.d.ts +28 -9
  117. package/dist/core/runner/delegation-owner.d.ts +2 -3
  118. package/dist/core/runner/delegation-owner.js +2 -1
  119. package/dist/core/runner/gate-exit.d.ts +6 -0
  120. package/dist/core/runner/gate-exit.js +11 -2
  121. package/dist/core/runner/memory-consolidation-driver.d.ts +4 -2
  122. package/dist/core/runner/memory-consolidation-driver.js +8 -5
  123. package/dist/core/runner/prepare-ask-lane.js +3 -3
  124. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -1
  125. package/dist/core/runner/prepare-caps-and-workflow.js +2 -2
  126. package/dist/core/runner/prepare-config-doors.js +4 -0
  127. package/dist/core/runner/prepare-delegation-surface.d.ts +3 -0
  128. package/dist/core/runner/prepare-delegation-surface.js +2 -2
  129. package/dist/core/runner/prepare-gate-stations.d.ts +8 -0
  130. package/dist/core/runner/prepare-gate-stations.js +15 -7
  131. package/dist/core/runner/prepare-hands-readface.js +1 -1
  132. package/dist/core/runner/prepare-inherited-gate.d.ts +3 -1
  133. package/dist/core/runner/prepare-inherited-gate.js +4 -2
  134. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  135. package/dist/core/runner/prepare-memory.d.ts +4 -0
  136. package/dist/core/runner/prepare-memory.js +22 -28
  137. package/dist/core/runner/prepare-policy-chain.js +18 -10
  138. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  139. package/dist/core/runner/prepare-task.d.ts +5 -1
  140. package/dist/core/runner/prepare-task.js +16 -11
  141. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -1
  142. package/dist/core/runner/prepare-wiring-manifest.js +3 -2
  143. package/dist/core/runner/resume-admission.d.ts +2 -2
  144. package/dist/core/runner/resume-admission.js +2 -23
  145. package/dist/core/runner/role-resolution-table.d.ts +98 -0
  146. package/dist/core/runner/role-resolution-table.js +62 -0
  147. package/dist/core/runner/run-compaction-machinery.js +2 -2
  148. package/dist/core/runner/run-identity-wiring.js +12 -9
  149. package/dist/core/runner/run-leg.js +8 -4
  150. package/dist/core/runner/run-notification-lane.js +23 -23
  151. package/dist/core/runner/run-recovery-lanes.js +3 -3
  152. package/dist/core/runner/run-terminal-adoption.js +1 -1
  153. package/dist/core/runner/run-turn-boundary.js +14 -15
  154. package/dist/core/runner/runtask.js +1 -1
  155. package/dist/core/runner/sub-agent-deny-lists.d.ts +19 -0
  156. package/dist/core/runner/sub-agent-deny-lists.js +25 -0
  157. package/dist/core/runner/tool-occurrence.d.ts +4 -2
  158. package/dist/core/runner/tool-occurrence.js +2 -2
  159. package/dist/core/runner-deps.d.ts +1 -1
  160. package/dist/core/secret-env.d.ts +2 -2
  161. package/dist/core/secret-env.js +6 -20
  162. package/dist/core/session-checkout.d.ts +63 -3
  163. package/dist/core/session-checkout.js +152 -58
  164. package/dist/core/session-store.d.ts +6 -6
  165. package/dist/core/session-store.js +3 -3
  166. package/dist/core/shell-read-silence.js +8 -0
  167. package/dist/core/store-contracts/background-agent-store-contract.js +13 -0
  168. package/dist/core/store-contracts/peer-directory-contract.js +8 -1
  169. package/dist/core/task-event.d.ts +9 -5
  170. package/dist/core/task-notification.d.ts +137 -31
  171. package/dist/core/task-notification.js +198 -100
  172. package/dist/core/task-registry-agent.d.ts +11 -0
  173. package/dist/core/task-registry-agent.js +12 -3
  174. package/dist/core/task-registry-shared.d.ts +11 -0
  175. package/dist/core/task-registry.d.ts +18 -0
  176. package/dist/core/task-registry.js +27 -8
  177. package/dist/core/task-spec.d.ts +7 -2
  178. package/dist/core/tool-errors.d.ts +17 -9
  179. package/dist/core/tool-errors.js +1 -1
  180. package/dist/core/tool-policy.d.ts +18 -1
  181. package/dist/core/tool-policy.js +16 -7
  182. package/dist/core/tool-result-store.d.ts +20 -0
  183. package/dist/core/tool-spec.d.ts +10 -6
  184. package/dist/core/trace.d.ts +3 -2
  185. package/dist/core/workflow-journal-store.d.ts +11 -0
  186. package/dist/core/workflow-journal-store.js +7 -0
  187. package/dist/core/workflow-run-store.d.ts +9 -0
  188. package/dist/core/workflow-run-store.js +6 -0
  189. package/dist/core/write-protect.d.ts +16 -0
  190. package/dist/core/write-protect.js +10 -0
  191. package/dist/engine/compaction/compaction.d.ts +2 -1
  192. package/dist/engine/harness/types.d.ts +1 -0
  193. package/dist/engine/session/repo-utils.d.ts +14 -4
  194. package/dist/engine/session/repo-utils.js +5 -4
  195. package/dist/engine/session/session.d.ts +7 -1
  196. package/dist/engine/session/session.js +5 -2
  197. package/dist/index.d.ts +13 -11
  198. package/dist/index.js +13 -11
  199. package/dist/orchestration/run-workflow-tool.d.ts +4 -0
  200. package/dist/orchestration/run-workflow-tool.js +7 -0
  201. package/dist/orchestration/workflow-types.d.ts +2 -1
  202. package/dist/orchestration/workflow.d.ts +3 -0
  203. package/dist/orchestration/workflow.js +2 -1
  204. package/dist/prompts/default.d.ts +1 -2
  205. package/dist/scenarios/full-body.d.ts +1 -1
  206. package/dist/stores/file/adoption/adopt.d.ts +1 -1
  207. package/dist/stores/file/checkpoint-store.d.ts +6 -0
  208. package/dist/stores/file/checkpoint-store.js +4 -1
  209. package/dist/stores/file/file-history-store.d.ts +13 -0
  210. package/dist/stores/file/file-history-store.js +75 -13
  211. package/dist/stores/file/index.d.ts +12 -16
  212. package/dist/stores/file/index.js +7 -25
  213. package/dist/stores/file/permission-rule-store.d.ts +34 -0
  214. package/dist/stores/file/permission-rule-store.js +104 -9
  215. package/dist/stores/file/session-store.js +1 -1
  216. package/dist/stores/file/tool-result-store.d.ts +14 -0
  217. package/dist/stores/file/tool-result-store.js +39 -2
  218. package/dist/stores/file/workflow-journal-store.d.ts +4 -0
  219. package/dist/stores/file/workflow-journal-store.js +17 -0
  220. package/dist/stores/file/workflow-run-store.d.ts +3 -0
  221. package/dist/stores/file/workflow-run-store.js +15 -0
  222. package/dist/tools/fs/read-deny.d.ts +15 -2
  223. package/dist/tools/fs/read-deny.js +10 -2
  224. package/dist/tools/fs/shell-read-check.d.ts +8 -2
  225. package/dist/tools/fs/shell-read-check.js +7 -7
  226. package/package.json +2 -2
  227. package/test/export-surface.snapshot.json +71 -73
  228. package/wire-changes/core-stores-sql@7.64.0.json +30 -0
  229. package/wire-changes/core-stores-sql@7.65.0.json +30 -0
  230. package/wire-changes/core@7.64.0.json +2653 -0
  231. package/wire-changes/core@7.65.0.json +1650 -0
  232. package/wire-changes/mods-kernel@7.64.0.json +30 -0
  233. package/wire-changes/mods-kernel@7.65.0.json +30 -0
  234. package/wire-changes/primitives@7.64.0.json +30 -0
  235. package/wire-changes/primitives@7.65.0.json +337 -0
  236. package/dist/core/memory-recall.d.ts +0 -208
  237. package/dist/core/memory-recall.js +0 -136
  238. package/dist/stores/file/memory-store.d.ts +0 -124
  239. package/dist/stores/file/memory-store.js +0 -353
@@ -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,12 +523,19 @@ 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
519
531
  * revision (0 when the store could not be read — the landing is in the overlay either way, and the
520
- * durable revision is reporting, not the landing's identity). */
532
+ * durable revision is reporting, not the landing's identity).
533
+ *
534
+ * A refusal is one shape wherever this module refuses — the single ticket, the batch's own record-level refusals and
535
+ * (with the member's identity beside them) a batch member's row: `reason` is the sentence for a person and is never
536
+ * parsed, `code` the cause ({@link RuleRefusalCode}), `committed` what may be claimed about the bytes
537
+ * ({@link RuleWriteCommitted}), `retriable` whether repeating the same call may land what this one did not
538
+ * ({@link refusalRetriable}). */
521
539
  export type RedeemResult = {
522
540
  status: "redeemed";
523
541
  behavior: RuleBehavior;
@@ -528,14 +546,27 @@ export type RedeemResult = {
528
546
  alreadyRedeemed: boolean;
529
547
  } | {
530
548
  status: "refused";
549
+ code: RuleRefusalCode;
550
+ committed: RuleWriteCommitted;
551
+ retriable: boolean;
531
552
  reason: string;
532
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
+ };
533
561
  /**
534
562
  * Redeem one ticket into one persisted rule.
535
563
  *
536
564
  * Takes a ticket and a verified principal, and nothing else. There is deliberately no field carrying rule
537
565
  * text: what gets persisted is what the engine put in the record when it drew the card, so a host cannot
538
566
  * turn a click on `git status` into a rule for something else.
567
+ *
568
+ * This is also the one leg every member of a batch walk takes ({@link redeemRuleBatch}), so a refusal here is the
569
+ * same `code` / `committed` / `retriable` / `reason` a member row carries (a member's row adds the member's identity).
539
570
  */
540
571
  export declare function redeemRuleTicket(opts: {
541
572
  ticket: RuleTicket;
@@ -598,12 +629,12 @@ export interface ImportPreview {
598
629
  * independent `alreadyRedeemed` axis (the single-leg replay marker: a dot-recorded-but-unlanded
599
630
  * retry is `alreadyRedeemed: true` AND `persisted`; a rule that pre-existed in the store is
600
631
  * `false` AND `deduped` — the two axes answer different questions and neither implies the other).
601
- * A refused row always carries its `reason` (a sentence for a person, never parsed) and two closed words: `code`, the
602
- * cause ({@link RuleRefusalCode}), and `committed`, what may be claimed about the bytes ({@link RuleWriteCommitted}) —
603
- * `no` when the member's rule does not stand because of this call (nothing was written, or the store answered that
604
- * nothing landed, or the rule's dot is no longer live), `unknown` when the write or the read-back that would have settled
605
- * it did not settle, so the caller reconciles with `list()` rather than retrying blind. `deduped` counts as LANDED: an
606
- * 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.
607
638
  *
608
639
  * design/382 §4.3 — on a SESSION-scope member the two landed words mean the same thing about a
609
640
  * different home: landed in / already in the session's OVERLAY (a session rule's home store), never
@@ -627,6 +658,7 @@ export type RedeemedBatchMember = {
627
658
  readonly status: "refused";
628
659
  readonly code: RuleRefusalCode;
629
660
  readonly committed: RuleWriteCommitted;
661
+ readonly retriable: boolean;
630
662
  readonly reason: string;
631
663
  };
632
664
  /**
@@ -643,6 +675,10 @@ export type RedeemedBatchMember = {
643
675
  * asks". An entry that does not import (a spelling with no rule form, a tool the lane does not speak
644
676
  * for, a non-string) is DISCLOSED in `skipped` with its reason and stays in the settings file.
645
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
+ *
646
682
  * Only a rule the store reads the way its layer does is carried. A bare tool name is not (`unsupported.form`), and
647
683
  * neither is a user-layer path pattern written from `/` (`unsupported.layer_root`, every behavior): the user layer reads
648
684
  * it at its own directory (the configuration directory), a stored global rule reads `/x` at each task's project root, and
@@ -659,7 +695,7 @@ export declare function prepareCcImport(opts: {
659
695
  }): Promise<{
660
696
  preview: ImportPreview;
661
697
  approvalId?: string;
662
- }>;
698
+ } | StoreRefusal>;
663
699
  /**
664
700
  * The factory-reviewed starter set, offered when there is nothing to import.
665
701
  *
@@ -670,7 +706,8 @@ export declare function prepareCcImport(opts: {
670
706
  */
671
707
  export declare const STARTER_RULES: readonly string[];
672
708
  /** Prepare the starter batch as a pending approval record. Nothing takes effect without confirmation;
673
- * 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. */
674
711
  export declare function prepareStarterBatch(opts: {
675
712
  principal?: string;
676
713
  owner?: RuleOwner;
@@ -678,7 +715,7 @@ export declare function prepareStarterBatch(opts: {
678
715
  }): Promise<{
679
716
  preview: RuleCandidate[];
680
717
  approvalId: string;
681
- }>;
718
+ } | StoreRefusal>;
682
719
  /**
683
720
  * Redeem the CHOSEN offer of a confirmed record, member by member — reporting what actually landed
684
721
  * rather than what was previewed (dedup, concurrency and redemption-time validation can all move a
@@ -695,7 +732,8 @@ export declare function prepareStarterBatch(opts: {
695
732
  * dot reuse included; the walk adds no concurrency primitive of its own;
696
733
  * · a refused member does NOT fold the batch: "all or nothing" is the CONFIRMATION's semantics
697
734
  * (one yes covered the whole offer), not the landing's transaction shape — the walk continues
698
- * 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`);
699
737
  * · resuming a partial walk IS re-walking: already-landed members answer `alreadyRedeemed: true`
700
738
  * and reuse their recorded dots (two concurrent walkers converge on one dot set, zero double
701
739
  * mints), unlanded members mint on;
@@ -703,7 +741,11 @@ export declare function prepareStarterBatch(opts: {
703
741
  * offer's member order, no extras — so a caller's aggregate is an honest projection: all rows
704
742
  * landed (`persisted` or `deduped`, both count as the consent being in effect) is full
705
743
  * success, and ANY refused row must project to a non-success aggregate, never to a silent
706
- * partial one.
744
+ * partial one;
745
+ * · a walk that cannot start (the record is missing or cannot be read, another principal's, stale, pending,
746
+ * malformed, or the owner's store cannot be resolved) answers no table: it answers the
747
+ * {@link RedeemResult} refused arm, `code` / `committed` / `retriable` / `reason`, the one shape a single
748
+ * ticket's refusal and a member's row take.
707
749
  */
708
750
  export declare function redeemRuleBatch(opts: {
709
751
  approvalId: string;
@@ -713,7 +755,7 @@ export declare function redeemRuleBatch(opts: {
713
755
  }): Promise<{
714
756
  members: readonly RedeemedBatchMember[];
715
757
  rev: number;
716
- } | {
758
+ } | Extract<RedeemResult, {
717
759
  status: "refused";
718
- reason: string;
719
- }>;
760
+ }>>;
761
+ export {};
@@ -466,7 +466,9 @@ export async function prepareCardApproval(opts) {
466
466
  ...(opts.toolCallId !== undefined ? { toolCallId: opts.toolCallId } : {}),
467
467
  ...(opts.boundInputHash !== undefined ? { boundInputHash: opts.boundInputHash } : {}),
468
468
  };
469
- await opts.deps.approvals.create(record);
469
+ const created = await storeStep(() => opts.deps.approvals.create(record), RECORD_CREATE);
470
+ if ("refused" in created)
471
+ return created.refused;
470
472
  return {
471
473
  approvalId: record.id,
472
474
  offers: ruleOffersOfRecord(record),
@@ -491,7 +493,10 @@ export async function confirmRuleApproval(opts) {
491
493
  e.code = "config.invalid_argument";
492
494
  throw e;
493
495
  }
494
- const rec = await opts.deps.approvals.get(opts.approvalId);
496
+ const read = await storeStep(() => opts.deps.approvals.get(opts.approvalId), RECORD_READ);
497
+ if ("refused" in read)
498
+ return confirmStoreFailure(read.refused);
499
+ const rec = read.value;
495
500
  const recOwner = rec === undefined ? undefined : ownerOfRecord(rec);
496
501
  if (rec === undefined || recOwner === undefined || !sameRuleOwner(recOwner, caller))
497
502
  return no("record_not_found");
@@ -518,10 +523,15 @@ export async function confirmRuleApproval(opts) {
518
523
  return no("not_pending");
519
524
  if (rec.selectedOffer !== undefined)
520
525
  return no("record_malformed", { message: "a pending record must not already carry a chosen offer" });
521
- const won = await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved", selectedOffer: chosen });
522
- if (won)
526
+ const casted = await storeStep(() => opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved", selectedOffer: chosen }), RECORD_CONFIRM_CAS);
527
+ if ("refused" in casted)
528
+ return confirmStoreFailure(casted.refused);
529
+ if (casted.value)
523
530
  return { ok: true };
524
- const again = await opts.deps.approvals.get(rec.id);
531
+ const reread = await storeStep(() => opts.deps.approvals.get(rec.id), RECORD_READ);
532
+ if ("refused" in reread)
533
+ return confirmStoreFailure(reread.refused);
534
+ const again = reread.value;
525
535
  if (again === undefined)
526
536
  return no("record_not_found");
527
537
  if (isStale(again))
@@ -646,9 +656,14 @@ async function confirmEditedCandidate(rec, edit, deps) {
646
656
  selectedOffer: rec.offers.length,
647
657
  edited: { index, text: edit.text, at: nowIso(deps), ...(checked.warnings !== undefined ? { warnings: checked.warnings.map((w) => w.code) } : {}) },
648
658
  };
649
- const won = await deps.approvals.cas(rec.id, rec.rev, next);
650
- if (!won) {
651
- const again = await deps.approvals.get(rec.id);
659
+ const casted = await storeStep(() => deps.approvals.cas(rec.id, rec.rev, next), RECORD_EDIT_CAS);
660
+ if ("refused" in casted)
661
+ return confirmStoreFailure(casted.refused);
662
+ if (!casted.value) {
663
+ const reread = await storeStep(() => deps.approvals.get(rec.id), RECORD_READ);
664
+ if ("refused" in reread)
665
+ return confirmStoreFailure(reread.refused);
666
+ const again = reread.value;
652
667
  if (again === undefined || isStale(again))
653
668
  return no("record_not_found");
654
669
  if (again.state === "pending")
@@ -657,19 +672,38 @@ async function confirmEditedCandidate(rec, edit, deps) {
657
672
  }
658
673
  return { ok: true, mintedCandidate: { index, rule: checked.canonicalRule, ticket: mintRuleTicket(rec.id, index) } };
659
674
  }
675
+ function refusalRetriable(code, committed) {
676
+ return (code === "store_read" || code === "store_write") && committed === "no";
677
+ }
660
678
  function refusal(code, reason, committed = "no") {
661
- return { status: "refused", code, committed, reason };
679
+ return { status: "refused", code, committed, retriable: refusalRetriable(code, committed), reason };
662
680
  }
663
- export async function redeemRuleTicket(opts) {
664
- const res = await redeemTicketLeg(opts);
665
- return res.status === "refused" ? { status: "refused", reason: res.reason } : res;
681
+ async function storeStep(step, failure) {
682
+ try {
683
+ return { value: await step() };
684
+ }
685
+ catch (err) {
686
+ return { refused: refusal(failure.code, `${failure.what}: ${errText(err)}`) };
687
+ }
688
+ }
689
+ const RECORD_READ = { code: "store_read", what: "could not read the approval record" };
690
+ const RECORD_CAS = { code: "store_write", what: "the approval record store failed the compare-and-set that records this redemption's dot" };
691
+ const DOT_ALLOCATION = { code: "store_write", what: "the permission-rule store failed to allocate this redemption's dot" };
692
+ const RECORD_CREATE = { code: "store_write", what: "the approval record store failed to create the record" };
693
+ const RECORD_CONFIRM_CAS = { code: "store_write", what: "the approval record store failed the compare-and-set that records this confirmation" };
694
+ const RECORD_EDIT_CAS = { code: "store_write", what: "the approval record store failed the compare-and-set that records this card edit" };
695
+ function confirmStoreFailure(refused) {
696
+ return { ok: false, reason: refused.code, detail: { message: refused.reason } };
666
697
  }
667
- async function redeemTicketLeg(opts) {
698
+ export async function redeemRuleTicket(opts) {
668
699
  const caller = resolveCallerOwner(opts.principal, opts.owner, "redeemRuleTicket");
669
700
  const parsed = parseRuleTicket(opts.ticket);
670
701
  if (parsed === undefined)
671
702
  return refusal("ticket_invalid", "malformed ticket");
672
- const rec = await opts.deps.approvals.get(parsed.recordId);
703
+ const read = await storeStep(() => opts.deps.approvals.get(parsed.recordId), RECORD_READ);
704
+ if ("refused" in read)
705
+ return read.refused;
706
+ const rec = read.value;
673
707
  if (rec === undefined)
674
708
  return refusal("record_missing", "no such approval record");
675
709
  const recOwner = ownerOfRecord(rec);
@@ -710,7 +744,16 @@ async function redeemTicketLeg(opts) {
710
744
  if (writer === undefined)
711
745
  return refusal("store_unavailable", "the resolved permission-rule store has no write face");
712
746
  const known = rec.redeemedDots?.[parsed.index];
713
- const dot = known ?? (await writer.nextDot());
747
+ let dot;
748
+ if (known !== undefined) {
749
+ dot = known;
750
+ }
751
+ else {
752
+ const minted = await storeStep(() => writer.nextDot(), DOT_ALLOCATION);
753
+ if ("refused" in minted)
754
+ return minted.refused;
755
+ dot = minted.value;
756
+ }
714
757
  if (known === undefined) {
715
758
  const next = {
716
759
  ...rec,
@@ -718,9 +761,14 @@ async function redeemTicketLeg(opts) {
718
761
  state: "redeemed",
719
762
  redeemedDots: { ...(rec.redeemedDots ?? {}), [parsed.index]: dot },
720
763
  };
721
- const ok = await opts.deps.approvals.cas(rec.id, rec.rev, next);
722
- if (!ok) {
723
- const again = await opts.deps.approvals.get(rec.id);
764
+ const casted = await storeStep(() => opts.deps.approvals.cas(rec.id, rec.rev, next), RECORD_CAS);
765
+ if ("refused" in casted)
766
+ return casted.refused;
767
+ if (!casted.value) {
768
+ const reread = await storeStep(() => opts.deps.approvals.get(rec.id), RECORD_READ);
769
+ if ("refused" in reread)
770
+ return reread.refused;
771
+ const again = reread.value;
724
772
  const theirs = again === undefined || isStale(again) ? undefined : again.redeemedDots?.[parsed.index];
725
773
  if (theirs === undefined)
726
774
  return refusal("record_changed", "the approval record changed state concurrently");
@@ -740,12 +788,14 @@ async function tighteningSiblingsStand(rec, offer, index, store, durableSnapshot
740
788
  if (dot === undefined)
741
789
  return false;
742
790
  const view = sibling.scope.kind === "session" ? await effectiveOrThrow(store, { sessionId: sibling.scope.sessionId }) : durableSnapshot;
743
- const live = view.rules.some((r) => r.behavior === sibling.behavior && r.rule === sibling.rule && sameScope(r.scope, sibling.scope) && r.adds.some((a) => a.dot.actor === dot.actor && a.dot.counter === dot.counter));
744
- if (!live)
791
+ if (!redeemedDotLive(view, sibling, dot))
745
792
  return false;
746
793
  }
747
794
  return true;
748
795
  }
796
+ function redeemedDotLive(view, candidate, dot) {
797
+ return view.rules.some((r) => r.behavior === candidate.behavior && sameScope(r.scope, candidate.scope) && r.adds.some((a) => a.dot.actor === dot.actor && a.dot.counter === dot.counter));
798
+ }
749
799
  async function applyRedemption(args) {
750
800
  let store;
751
801
  try {
@@ -786,6 +836,17 @@ async function applyRedemption(args) {
786
836
  });
787
837
  if (!landing.landed)
788
838
  return refusal(landing.code, landing.reason, landing.committed);
839
+ let live = false;
840
+ try {
841
+ const snap = await effectiveOrThrow(store, args.candidate.scope.kind === "session" ? { sessionId: args.candidate.scope.sessionId } : undefined);
842
+ live = redeemedDotLive(snap, args.candidate, args.dot);
843
+ }
844
+ catch (err) {
845
+ return refusal("store_read", `could not read the permission-rule store to confirm this ${args.candidate.behavior} rule stands after its redemption: ${errText(err)}`, "unknown");
846
+ }
847
+ if (!live) {
848
+ return refusal("dot_removed", `this ${args.candidate.behavior} rule's redeemed dot ${args.dot.actor}#${args.dot.counter} is not live in the store (removed since it was redeemed) — a removed rule is not re-landed by replaying its record; a new consent is required`);
849
+ }
789
850
  return { status: "redeemed", behavior: args.parsedRule.behavior, rule: args.parsedRule.rule, scope: args.candidate.scope, dot: args.dot, rev: landing.rev, alreadyRedeemed: args.replay };
790
851
  }
791
852
  function originOfRecordKind(kind) {
@@ -907,7 +968,9 @@ export async function prepareCcImport(opts) {
907
968
  offers: [{ kind: "batch", candidates: candidates.map((_, i) => i) }],
908
969
  createdAt: nowIso(opts.deps),
909
970
  };
910
- await opts.deps.approvals.create(record);
971
+ const created = await storeStep(() => opts.deps.approvals.create(record), RECORD_CREATE);
972
+ if ("refused" in created)
973
+ return created.refused;
911
974
  return { preview, approvalId: record.id };
912
975
  }
913
976
  export const STARTER_RULES = [
@@ -941,35 +1004,40 @@ export async function prepareStarterBatch(opts) {
941
1004
  offers: [{ kind: "batch", candidates: candidates.map((_, i) => i) }],
942
1005
  createdAt: nowIso(opts.deps),
943
1006
  };
944
- await opts.deps.approvals.create(record);
1007
+ const created = await storeStep(() => opts.deps.approvals.create(record), RECORD_CREATE);
1008
+ if ("refused" in created)
1009
+ return created.refused;
945
1010
  return { preview: candidates, approvalId: record.id };
946
1011
  }
947
1012
  export async function redeemRuleBatch(opts) {
948
1013
  const caller = resolveCallerOwner(opts.principal, opts.owner, "redeemRuleBatch");
949
- const rec = await opts.deps.approvals.get(opts.approvalId);
1014
+ const read = await storeStep(() => opts.deps.approvals.get(opts.approvalId), RECORD_READ);
1015
+ if ("refused" in read)
1016
+ return read.refused;
1017
+ const rec = read.value;
950
1018
  if (rec === undefined)
951
- return { status: "refused", reason: "no such approval record" };
1019
+ return refusal("record_missing", "no such approval record");
952
1020
  const recOwner = ownerOfRecord(rec);
953
1021
  if (recOwner === undefined || !sameRuleOwner(recOwner, caller))
954
- return { status: "refused", reason: "the record belongs to a different principal" };
1022
+ return refusal("wrong_principal", "the record belongs to a different principal");
955
1023
  if (isStale(rec))
956
- return { status: "refused", reason: `record_schema_stale: ${STALE_RECORD_MESSAGE}` };
1024
+ return refusal("record_schema_stale", `record_schema_stale: ${STALE_RECORD_MESSAGE}`);
957
1025
  if (rec.state === "pending")
958
- return { status: "refused", reason: "the approval record has not been confirmed" };
1026
+ return refusal("not_confirmed", "the approval record has not been confirmed");
959
1027
  const damage = approvalRecordDamageOf(rec);
960
1028
  if (damage !== undefined)
961
- return { status: "refused", reason: `the approval record is malformed: ${damage}` };
1029
+ return refusal("record_malformed", `the approval record is malformed: ${damage}`);
962
1030
  const chosen = rec.selectedOffer;
963
1031
  const chosenOffer = chosen !== undefined && Number.isInteger(chosen) ? rec.offers[chosen] : undefined;
964
1032
  if (chosenOffer === undefined) {
965
- return { status: "refused", reason: "the approval record is malformed: it is settled but names no valid chosen offer" };
1033
+ return refusal("record_malformed", "the approval record is malformed: it is settled but names no valid chosen offer");
966
1034
  }
967
1035
  let store;
968
1036
  try {
969
1037
  store = storeForOwner(opts.deps.provider, caller);
970
1038
  }
971
1039
  catch (err) {
972
- return { status: "refused", reason: errText(err) };
1040
+ return refusal("store_unavailable", errText(err));
973
1041
  }
974
1042
  const members = [];
975
1043
  let rev = 0;
@@ -982,8 +1050,9 @@ export async function redeemRuleBatch(opts) {
982
1050
  for (const candidateIndex of ordered) {
983
1051
  const candidate = rec.candidates[candidateIndex];
984
1052
  const row = { candidateIndex, behavior: candidate.behavior, rule: candidate.rule, scope: candidate.scope };
985
- if (candidate.behavior === "allow" && tighteningFailed !== undefined) {
986
- members.push({ ...row, status: "refused", code: "withheld", committed: "no", reason: `withheld: candidate ${tighteningFailed} (a deny/ask member of this batch) did not land, and an allow must not stand wider than the list that was confirmed — redeem the batch again once the store accepts the tightening member` });
1053
+ const tightening = candidate.behavior !== "allow";
1054
+ if (!tightening && tighteningFailed !== undefined) {
1055
+ members.push({ ...row, ...refusal("withheld", `withheld: candidate ${tighteningFailed} (a deny/ask member of this batch) did not land, and an allow must not stand wider than the list that was confirmed — redeem the batch again once the store accepts the tightening member`) });
987
1056
  continue;
988
1057
  }
989
1058
  let alreadyThere = false;
@@ -994,44 +1063,23 @@ export async function redeemRuleBatch(opts) {
994
1063
  alreadyThere = snap.rules.some((r) => r.behavior === candidate.behavior && r.rule === candidate.rule && sameScope(r.scope, candidate.scope));
995
1064
  }
996
1065
  catch (err) {
997
- members.push({ ...row, status: "refused", code: "store_read", committed: "no", reason: `could not read the permission-rule store: ${errText(err)}` });
998
- if (candidate.behavior !== "allow")
1066
+ members.push({ ...row, ...refusal("store_read", `could not read the permission-rule store: ${errText(err)}`) });
1067
+ if (tightening)
999
1068
  tighteningFailed ??= candidateIndex;
1000
1069
  continue;
1001
1070
  }
1002
1071
  }
1003
- const res = await redeemTicketLeg({
1072
+ const res = await redeemRuleTicket({
1004
1073
  ticket: mintRuleTicket(rec.id, candidateIndex),
1005
1074
  ...(caller.kind === "principal" ? { principal: caller.principal } : { owner: caller }),
1006
1075
  deps: opts.deps,
1007
1076
  });
1008
1077
  if (res.status === "refused") {
1009
- members.push({ ...row, status: "refused", code: res.code, committed: res.committed, reason: res.reason });
1010
- if (candidate.behavior !== "allow")
1078
+ members.push({ ...row, ...res });
1079
+ if (tightening)
1011
1080
  tighteningFailed ??= candidateIndex;
1012
1081
  continue;
1013
1082
  }
1014
- if (candidate.behavior !== "allow") {
1015
- let live = false;
1016
- let unreadable;
1017
- try {
1018
- const snap = await effectiveOrThrow(store, candidate.scope.kind === "session" ? { sessionId: candidate.scope.sessionId } : undefined);
1019
- live = snap.rules.some((r) => r.behavior === candidate.behavior && r.rule === candidate.rule && sameScope(r.scope, candidate.scope) && r.adds.some((a) => a.dot.actor === res.dot.actor && a.dot.counter === res.dot.counter));
1020
- }
1021
- catch (err) {
1022
- unreadable = errText(err);
1023
- }
1024
- if (unreadable !== undefined) {
1025
- members.push({ ...row, status: "refused", code: "store_read", committed: "unknown", reason: `could not read the permission-rule store to confirm this ${candidate.behavior} member stands after its redemption: ${unreadable}` });
1026
- tighteningFailed ??= candidateIndex;
1027
- continue;
1028
- }
1029
- if (!live) {
1030
- members.push({ ...row, status: "refused", code: "dot_removed", committed: "no", reason: `this ${candidate.behavior} member's redeemed dot ${res.dot.actor}#${res.dot.counter} is not live in the store (removed since it was redeemed) — a removed rule is not re-landed by replaying its record; a new consent is required` });
1031
- tighteningFailed ??= candidateIndex;
1032
- continue;
1033
- }
1034
- }
1035
1083
  rev = candidate.scope.kind === "session" ? Math.max(rev, res.rev) : res.rev;
1036
1084
  members.push({ ...row, status: alreadyThere ? "deduped" : "persisted", alreadyRedeemed: res.alreadyRedeemed, dot: res.dot });
1037
1085
  }
@@ -64,6 +64,24 @@ export interface StoredRules {
64
64
  * partition that cannot be read: every call is asked about until a read succeeds.
65
65
  */
66
66
  export declare const PERMISSION_RULES_LATER_GRAMMAR_CODE = "permission_rules.later_grammar";
67
+ /**
68
+ * The code a file bucket's refusal carries when the bucket is DETERMINISTICALLY unreadable: the same bytes will be refused the same
69
+ * way on every read until a person repairs or removes them — a link or a file that is not a regular file, bytes that are not JSON, a
70
+ * shape that is not a schema-4 bucket, a checksum that does not match, a rule-grammar stamp that is no whole number, a row whose
71
+ * behavior word is outside the set, or a store directory this engine refuses to use. Every face refuses the bucket whole with it
72
+ * (reads answer zero rules and disclose; a write refuses), so a caller tells "this bucket cannot be read and a retry reads the same" from
73
+ * a read that failed ({@link PERMISSION_RULES_UNREADABLE_BUCKET_CODE}) and from a bucket a newer engine wrote
74
+ * ({@link PERMISSION_RULES_LATER_GRAMMAR_CODE}). Decide by the code, never by the sentence.
75
+ */
76
+ export declare const PERMISSION_RULES_DAMAGED_BUCKET_CODE = "permission_rules.bucket_damaged";
77
+ /**
78
+ * The code a file bucket's refusal carries when reading it FAILED — the filesystem answered with an error (`EIO`, `EACCES`, …) rather
79
+ * than with bytes this engine judged — so a retry may read it. The system error's name rides on the refusal as its own member `errno`
80
+ * (a string, as the system gave it: `"EIO"`, `"EACCES"`), absent when the failure carried none; it is not part of `code`, which has one
81
+ * vocabulary. A caller that must not act on a bucket it could not read (it is not known to be empty) refuses on this code and may try
82
+ * again; one that meets {@link PERMISSION_RULES_DAMAGED_BUCKET_CODE} has a bucket that will not read until a person acts.
83
+ */
84
+ export declare const PERMISSION_RULES_UNREADABLE_BUCKET_CODE = "permission_rules.bucket_unreadable";
67
85
  /**
68
86
  * The durable partition's read face: read-only, already anchored to a single owner. Rows carry the two
69
87
  * durable scopes only (`global` = the `user` source, `project` = the `project` source); a session row
@@ -596,15 +614,31 @@ export type RemovalLiveness = (typeof REMOVAL_LIVENESS_WORDS)[number];
596
614
  * What a terminal write FAILURE may claim about the bytes — the failure half of the honesty
597
615
  * {@link RemovalLiveness} keeps on the success half, spelled ONCE and read by every write entry here.
598
616
  *
599
- * `"no"` = the store ITSELF answered: a face that cannot write at all, a target the type face refuses,
600
- * a read that failed before any write, a refused preflight, an epoch seal, a compare-and-set that lost
601
- * every attempt. Each of those is the store saying nothing landed, so saying it is a fact.
602
- * `"unknown"` = the apply THREW, which proves nothing either way (a backend can commit and then lose
603
- * its acknowledgement), or the read-back that would have settled it could not be taken.
617
+ * ONE reading: the word answers "has the store ITSELF settled whether anything this call wrote stands?".
604
618
  *
605
- * The word exists because the caller's two branches — retry, or reconcile with `list()` — are not
606
- * derivable from the failure PROSE. A consumer reading the strength out of the sentence is parsing a
607
- * message written for a person, and every such reader has to be updated by hand when the sentence is.
619
+ * `"no"` = it has, and nothing does: a face that cannot write at all, a target the type face refuses,
620
+ * a read that failed before any write, a refused preflight, an epoch seal, a compare-and-set that lost
621
+ * every attempt. Each of those is the store saying nothing landed, so saying it is a fact. The same word
622
+ * covers a write that DID land and that a read which SUCCEEDED then finds removed (a redemption's
623
+ * `dot_removed`, at the single ticket and a batch member alike): the add's dot is in the raw state under its tombstone, the rule does not stand, and the
624
+ * store has said so — the word is about whether the call's rule stands, never about the history of the
625
+ * bytes, and a retry of the same ticket re-reads the same tombstone (a new consent is what lands it).
626
+ * The same word covers a failure at a step BEFORE the call's rule write is sent — the approval record's
627
+ * read, its creation, the compare-and-set that records the dot (or a confirmation, or a card edit), the
628
+ * dot's allocation: whatever that step's own bytes did (a compare-and-set can commit and lose its
629
+ * acknowledgement), the rule write was never issued, so the call's rule does not stand; a replay of the
630
+ * same ticket reuses the dot the record kept.
631
+ * `"unknown"` = it has not: the rule write WAS issued and the apply threw, which proves nothing either
632
+ * way (a backend can commit and then lose its acknowledgement), or the read-back after it that would have
633
+ * settled it could not be taken. A settled absence is never `unknown`: that word would send the caller to
634
+ * reconcile with `list()` for an answer the store already gave.
635
+ *
636
+ * The word exists because the caller's branch — reconcile with `list()`, or not — is not derivable from
637
+ * the failure PROSE. A consumer reading the strength out of the sentence is parsing a message written for
638
+ * a person, and every such reader has to be updated by hand when the sentence is. `no` does not say that
639
+ * repeating the call would land anything (a refused preflight, a tombstone and an epoch seal are all `no`,
640
+ * and none is cured by a retry): a redemption's refusal answers that second question beside this word, in
641
+ * its own member (`retriable`), derived once from the cause and this word, and never read off `no`.
608
642
  */
609
643
  export declare const RULE_WRITE_COMMITTED_WORDS: readonly ["no", "unknown"];
610
644
  export type RuleWriteCommitted = (typeof RULE_WRITE_COMMITTED_WORDS)[number];
@@ -617,7 +651,9 @@ export type RuleWriteCommitted = (typeof RULE_WRITE_COMMITTED_WORDS)[number];
617
651
  *
618
652
  * It rides beside {@link RuleWriteCommitted}, and the two answer different questions. The code says what stopped the
619
653
  * redemption; `committed` says what may be claimed about the bytes. The same code can carry both words (`store_read`:
620
- * a read before any write says `no`, a read-back after one that could not be taken says `unknown`).
654
+ * a read before the rule write says `no`, a read-back after it that could not be taken says `unknown`; `store_write`: a
655
+ * step before the rule write says `no`, the rule write itself `unknown`), and a consumer that needs to tell two `no`s
656
+ * apart reads the code.
621
657
  *
622
658
  * - `unsupported.layer_root` — an import record's global rule written from `/`, which no stored row can hold
623
659
  * - `ticket_invalid` — the ticket does not name a candidate (unparseable, or an index the record has none at)
@@ -631,11 +667,12 @@ export type RuleWriteCommitted = (typeof RULE_WRITE_COMMITTED_WORDS)[number];
631
667
  * - `store_unavailable` — the owner's store cannot be resolved, or has no write face
632
668
  * - `record_changed` — the record moved under this redemption and the dot it needed is not there
633
669
  * - `withheld` — held back because the batch's deny/ask members do not all stand, and an allow may not stand wider
634
- * - `store_read` — a permission-rule store read failed (before the write: `no`; the read-back after it: `unknown`)
635
- * - `store_write` — the write threw, answered unreadably, or was reported landed with no trace of its dot (`unknown`)
670
+ * - `store_read` — a store read failed: the permission-rule store's, or the approval record's (before the rule write: `no`; the read-back after it: `unknown`); the confirmation and card-edit entries answer a failed record read with the same word
671
+ * - `store_write` — the rule write threw, answered unreadably, or was reported landed with no trace of its dot (`unknown`); or a step before it threw — the approval record's compare-and-set that records the dot (or the confirmation, or a card edit), the dot's allocation, or the record's creation at the prepare, import and starter entries (`no`: the rule write was never issued)
636
672
  * - `session_ended` — a session-scope rule whose session has ended; a late redemption cannot revive it
637
673
  * - `occ` — every optimistic-concurrency attempt lost its compare-and-set
638
- * - `dot_removed` — the member's redeemed dot is no longer live in the store (the rule was removed since)
674
+ * - `dot_removed` — the redeemed dot (a single ticket's or a batch member's) is no longer live in the store (the rule was removed since); its
675
+ * `committed` is `no`, the store having settled that the rule does not stand ({@link RuleWriteCommitted})
639
676
  */
640
677
  export declare const RULE_REFUSAL_CODES: readonly ["unsupported.layer_root", "ticket_invalid", "record_missing", "wrong_principal", "record_schema_stale", "not_confirmed", "record_malformed", "not_chosen", "parse_rejected", "store_unavailable", "record_changed", "withheld", "store_read", "store_write", "session_ended", "occ", "dot_removed"];
641
678
  export type RuleRefusalCode = (typeof RULE_REFUSAL_CODES)[number];
@@ -670,8 +707,8 @@ export type RemoveResult =
670
707
  }
671
708
  /** Terminal failure, in one of two strengths — word for word the dual of {@link AddResult}'s, and
672
709
  * `committed` is the word for it ({@link RuleWriteCommitted}), so the strength is READ, not parsed out
673
- * of the sentence. When the STORE answered every attempt (the compare-and-set simply lost), nothing
674
- * landed: `committed: "no"`, and the read-back confirms it in the text. When the apply THREW, a missing
710
+ * of the sentence (the one reading is {@link RuleWriteCommitted}'s). When the STORE answered every attempt (the
711
+ * compare-and-set simply lost), nothing landed: `committed: "no"`, and the read-back confirms it in the text. When the apply THREW, a missing
675
712
  * tombstone cannot tell a write that never landed from one whose evidence a paired collection erased
676
713
  * (`collectBelowFrontier` recycles a tombstone together with the adds it covered), so that outcome is
677
714
  * `committed: "unknown"`, reported INDETERMINATE, and the caller reconciles with `list()` rather than
@@ -714,10 +751,7 @@ export type RuleAddLanding = {
714
751
  landed: true;
715
752
  rev: number;
716
753
  }
717
- /** `committed` is what the caller may CLAIM afterwards. `"no"` means the store itself answered — a
718
- * read that failed before any write, a refused preflight, an epoch seal, or a compare-and-set that
719
- * lost every attempt: each of those is the store saying nothing landed. `"unknown"` means the apply
720
- * THREW, which proves nothing either way: a backend can commit and then lose its acknowledgement.
754
+ /** `committed` is what the caller may CLAIM afterwards, read as {@link RuleWriteCommitted} reads it (defined there, once).
721
755
  * `code` is the cause ({@link RuleRefusalCode}); this path mints five of them (`withheld`, `store_read`,
722
756
  * `store_write`, `session_ended`, `occ`), so a door never reads the cause out of `reason`. */
723
757
  | {
@@ -767,10 +801,11 @@ export type AddResult =
767
801
  status: "no-op";
768
802
  rev: number;
769
803
  }
770
- /** Terminal failure, in one of two strengths the `error` text distinguishes. When the STORE answered
804
+ /** Terminal failure, in one of two strengths the `error` text distinguishes (read as {@link RuleWriteCommitted}
805
+ * reads them). When the STORE answered
771
806
  * (a read that failed before any write, a refused preflight, an epoch seal, a compare-and-set that
772
- * lost every attempt) nothing landed and the text says so plainly. When the apply THREW, the write
773
- * may have committed and lost its acknowledgement: the read-back asks the raw face, where an add
807
+ * lost every attempt) nothing landed and the text says so plainly. When the apply THREW (or reported a landing
808
+ * that could not be witnessed), the write may have committed and lost its acknowledgement: the read-back asks the raw face, where an add
774
809
  * survives the tombstone a concurrent removal laid on it — but a sync collection can erase even
775
810
  * that, so a dot it cannot find is reported INDETERMINATE rather than as a confirmed nothing, and
776
811
  * the caller reconciles with `list()` instead of retrying blind (a blind retry mints a fresh dot and