@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.
- package/CHANGELOG.md +725 -0
- package/dist/agents/cc-peer-directory.js +1 -0
- package/dist/agents/cc-peer-wire.d.ts +4 -0
- package/dist/agents/cc-peer-wire.js +1 -0
- package/dist/agents/cc-uds-peer-channel.js +5 -0
- package/dist/agents/cross-session-judge.d.ts +3 -1
- package/dist/agents/cross-session-judge.js +4 -1
- package/dist/agents/peer-directory.d.ts +8 -0
- package/dist/agents/peer-directory.js +4 -0
- package/dist/agents/peer-held-queue.d.ts +9 -3
- package/dist/agents/peer-held-queue.js +12 -9
- package/dist/agents/peer-idle.d.ts +20 -1
- package/dist/agents/peer-idle.js +23 -12
- package/dist/agents/peer-notice-route.d.ts +16 -5
- package/dist/agents/peer-notice-route.js +11 -9
- package/dist/agents/peer-notices.d.ts +25 -8
- package/dist/agents/peer-notices.js +6 -1
- package/dist/agents/peer-session-drain.d.ts +32 -6
- package/dist/agents/peer-session-drain.js +100 -26
- package/dist/agents/send-message-tool.d.ts +7 -0
- package/dist/agents/send-message-tool.js +18 -6
- package/dist/agents/subagent.js +25 -5
- package/dist/core/allow-entry.d.ts +4 -0
- package/dist/core/ask-origin.d.ts +1 -1
- package/dist/core/ask-origin.js +2 -2
- package/dist/core/ask-unresolvable-notice.d.ts +13 -4
- package/dist/core/ask-unresolvable-notice.js +10 -3
- package/dist/core/auto-compaction.d.ts +7 -5
- package/dist/core/auto-promote.d.ts +3 -2
- package/dist/core/background-agent-store.d.ts +14 -0
- package/dist/core/background-agent-store.js +3 -0
- package/dist/core/checkpoint-queries.d.ts +9 -6
- package/dist/core/checkpoint-queries.js +8 -3
- package/dist/core/checkpoint-store.d.ts +7 -4
- package/dist/core/context-settings.d.ts +39 -9
- package/dist/core/context-settings.js +32 -10
- package/dist/core/engine-attestation.d.ts +26 -6
- package/dist/core/engine-attestation.js +5 -1
- package/dist/core/engine-notice.d.ts +37 -2
- package/dist/core/engine-notice.js +3 -1
- package/dist/core/extension-requester.d.ts +9 -0
- package/dist/core/extension-requester.js +7 -0
- package/dist/core/file-history-store.d.ts +30 -2
- package/dist/core/file-history-store.js +48 -9
- package/dist/core/fs-write-gate-policy.js +1 -1
- package/dist/core/gate-fold.js +5 -1
- package/dist/core/gate-lanes.js +2 -0
- package/dist/core/gate-outcome.d.ts +39 -2
- package/dist/core/gate-outcome.js +20 -1
- package/dist/core/governance-codes.d.ts +8 -4
- package/dist/core/governance-codes.js +8 -3
- package/dist/core/leg-identity.d.ts +35 -1
- package/dist/core/leg-identity.js +10 -0
- package/dist/core/mailbox-store.d.ts +39 -4
- package/dist/core/mailbox-store.js +14 -2
- package/dist/core/memory-engine/consolidation.d.ts +13 -6
- package/dist/core/memory-engine/consolidation.js +26 -0
- package/dist/core/memory-engine/control-objects.d.ts +58 -0
- package/dist/core/memory-engine/control-objects.js +273 -0
- package/dist/core/memory-engine/control-plane-adoption.d.ts +51 -0
- package/dist/core/memory-engine/control-plane-adoption.js +161 -0
- package/dist/core/memory-engine/delegation-settlement.d.ts +73 -40
- package/dist/core/memory-engine/delegation-settlement.js +271 -107
- package/dist/core/memory-engine/dual-root.d.ts +3 -2
- package/dist/core/memory-engine/dual-root.js +7 -3
- package/dist/core/memory-engine/engine.d.ts +54 -33
- package/dist/core/memory-engine/engine.js +150 -157
- package/dist/core/memory-engine/file-backend.d.ts +58 -76
- package/dist/core/memory-engine/file-backend.js +111 -268
- package/dist/core/memory-engine/index.d.ts +3 -2
- package/dist/core/memory-engine/index.js +2 -1
- package/dist/core/memory-engine/layout.d.ts +135 -50
- package/dist/core/memory-engine/layout.js +214 -89
- package/dist/core/memory-engine/memory-age.d.ts +12 -0
- package/dist/core/memory-engine/memory-age.js +17 -0
- package/dist/core/memory-engine/memory-backend-contract.d.ts +10 -3
- package/dist/core/memory-engine/memory-backend-contract.js +159 -2
- package/dist/core/memory-engine/memory-deployment.d.ts +12 -4
- package/dist/core/memory-engine/memory-deployment.js +31 -6
- package/dist/core/memory-engine/origin-clearance.d.ts +12 -3
- package/dist/core/memory-engine/origin-clearance.js +64 -9
- package/dist/core/memory-engine/session-write-home.d.ts +34 -1
- package/dist/core/memory-engine/session-write-home.js +37 -10
- package/dist/core/memory-engine/tools.d.ts +2 -2
- package/dist/core/memory-engine/tools.js +7 -7
- package/dist/core/memory-engine/types.d.ts +55 -12
- package/dist/core/memory-engine/types.js +2 -1
- package/dist/core/memory-vector.d.ts +6 -14
- package/dist/core/memory.d.ts +0 -462
- package/dist/core/memory.js +0 -333
- package/dist/core/mode-policy.js +3 -3
- package/dist/core/mods/agent-stations.d.ts +18 -0
- package/dist/core/mods/agent-stations.js +8 -6
- package/dist/core/mods/extension-call.d.ts +4 -0
- package/dist/core/mods/extension-call.js +8 -0
- package/dist/core/mods/tool-call.js +3 -4
- package/dist/core/parent-spec-seat.d.ts +2 -2
- package/dist/core/peer-channel.d.ts +5 -0
- package/dist/core/permission-rule-consent.d.ts +64 -22
- package/dist/core/permission-rule-consent.js +106 -58
- package/dist/core/permission-rule-store.d.ts +56 -21
- package/dist/core/permission-rule-store.js +2 -0
- package/dist/core/refusal-echo.d.ts +20 -0
- package/dist/core/refusal-echo.js +33 -0
- package/dist/core/retention.d.ts +175 -10
- package/dist/core/retention.js +44 -0
- package/dist/core/retired-keys.d.ts +5 -0
- package/dist/core/retired-keys.js +3 -0
- package/dist/core/rule-offer-read.d.ts +0 -4
- package/dist/core/rule-offer-read.js +2 -18
- package/dist/core/runner/classifier-ladder.d.ts +10 -2
- package/dist/core/runner/classifier-ladder.js +4 -2
- package/dist/core/runner/compact-session.js +10 -7
- package/dist/core/runner/compaction-call-options.d.ts +7 -7
- package/dist/core/runner/compaction-call-options.js +3 -2
- package/dist/core/runner/contracts.d.ts +28 -9
- package/dist/core/runner/delegation-owner.d.ts +2 -3
- package/dist/core/runner/delegation-owner.js +2 -1
- package/dist/core/runner/gate-exit.d.ts +6 -0
- package/dist/core/runner/gate-exit.js +11 -2
- package/dist/core/runner/memory-consolidation-driver.d.ts +4 -2
- package/dist/core/runner/memory-consolidation-driver.js +8 -5
- package/dist/core/runner/prepare-ask-lane.js +3 -3
- package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -1
- package/dist/core/runner/prepare-caps-and-workflow.js +2 -2
- package/dist/core/runner/prepare-config-doors.js +4 -0
- package/dist/core/runner/prepare-delegation-surface.d.ts +3 -0
- package/dist/core/runner/prepare-delegation-surface.js +2 -2
- package/dist/core/runner/prepare-gate-stations.d.ts +8 -0
- package/dist/core/runner/prepare-gate-stations.js +15 -7
- package/dist/core/runner/prepare-hands-readface.js +1 -1
- package/dist/core/runner/prepare-inherited-gate.d.ts +3 -1
- package/dist/core/runner/prepare-inherited-gate.js +4 -2
- package/dist/core/runner/prepare-memory-engine-session.js +1 -1
- package/dist/core/runner/prepare-memory.d.ts +4 -0
- package/dist/core/runner/prepare-memory.js +22 -28
- package/dist/core/runner/prepare-policy-chain.js +18 -10
- package/dist/core/runner/prepare-prompt-inputs.js +1 -1
- package/dist/core/runner/prepare-task.d.ts +5 -1
- package/dist/core/runner/prepare-task.js +16 -11
- package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -1
- package/dist/core/runner/prepare-wiring-manifest.js +3 -2
- package/dist/core/runner/resume-admission.d.ts +2 -2
- package/dist/core/runner/resume-admission.js +2 -23
- package/dist/core/runner/role-resolution-table.d.ts +98 -0
- package/dist/core/runner/role-resolution-table.js +62 -0
- package/dist/core/runner/run-compaction-machinery.js +2 -2
- package/dist/core/runner/run-identity-wiring.js +12 -9
- package/dist/core/runner/run-leg.js +8 -4
- package/dist/core/runner/run-notification-lane.js +23 -23
- package/dist/core/runner/run-recovery-lanes.js +3 -3
- package/dist/core/runner/run-terminal-adoption.js +1 -1
- package/dist/core/runner/run-turn-boundary.js +14 -15
- package/dist/core/runner/runtask.js +1 -1
- package/dist/core/runner/sub-agent-deny-lists.d.ts +19 -0
- package/dist/core/runner/sub-agent-deny-lists.js +25 -0
- package/dist/core/runner/tool-occurrence.d.ts +4 -2
- package/dist/core/runner/tool-occurrence.js +2 -2
- package/dist/core/runner-deps.d.ts +1 -1
- package/dist/core/secret-env.d.ts +2 -2
- package/dist/core/secret-env.js +6 -20
- package/dist/core/session-checkout.d.ts +63 -3
- package/dist/core/session-checkout.js +152 -58
- package/dist/core/session-store.d.ts +6 -6
- package/dist/core/session-store.js +3 -3
- package/dist/core/shell-read-silence.js +8 -0
- package/dist/core/store-contracts/background-agent-store-contract.js +13 -0
- package/dist/core/store-contracts/peer-directory-contract.js +8 -1
- package/dist/core/task-event.d.ts +9 -5
- package/dist/core/task-notification.d.ts +137 -31
- package/dist/core/task-notification.js +198 -100
- package/dist/core/task-registry-agent.d.ts +11 -0
- package/dist/core/task-registry-agent.js +12 -3
- package/dist/core/task-registry-shared.d.ts +11 -0
- package/dist/core/task-registry.d.ts +18 -0
- package/dist/core/task-registry.js +27 -8
- package/dist/core/task-spec.d.ts +7 -2
- package/dist/core/tool-errors.d.ts +17 -9
- package/dist/core/tool-errors.js +1 -1
- package/dist/core/tool-policy.d.ts +18 -1
- package/dist/core/tool-policy.js +16 -7
- package/dist/core/tool-result-store.d.ts +20 -0
- package/dist/core/tool-spec.d.ts +10 -6
- package/dist/core/trace.d.ts +3 -2
- package/dist/core/workflow-journal-store.d.ts +11 -0
- package/dist/core/workflow-journal-store.js +7 -0
- package/dist/core/workflow-run-store.d.ts +9 -0
- package/dist/core/workflow-run-store.js +6 -0
- package/dist/core/write-protect.d.ts +16 -0
- package/dist/core/write-protect.js +10 -0
- package/dist/engine/compaction/compaction.d.ts +2 -1
- package/dist/engine/harness/types.d.ts +1 -0
- package/dist/engine/session/repo-utils.d.ts +14 -4
- package/dist/engine/session/repo-utils.js +5 -4
- package/dist/engine/session/session.d.ts +7 -1
- package/dist/engine/session/session.js +5 -2
- package/dist/index.d.ts +13 -11
- package/dist/index.js +13 -11
- package/dist/orchestration/run-workflow-tool.d.ts +4 -0
- package/dist/orchestration/run-workflow-tool.js +7 -0
- package/dist/orchestration/workflow-types.d.ts +2 -1
- package/dist/orchestration/workflow.d.ts +3 -0
- package/dist/orchestration/workflow.js +2 -1
- package/dist/prompts/default.d.ts +1 -2
- package/dist/scenarios/full-body.d.ts +1 -1
- package/dist/stores/file/adoption/adopt.d.ts +1 -1
- package/dist/stores/file/checkpoint-store.d.ts +6 -0
- package/dist/stores/file/checkpoint-store.js +4 -1
- package/dist/stores/file/file-history-store.d.ts +13 -0
- package/dist/stores/file/file-history-store.js +75 -13
- package/dist/stores/file/index.d.ts +12 -16
- package/dist/stores/file/index.js +7 -25
- package/dist/stores/file/permission-rule-store.d.ts +34 -0
- package/dist/stores/file/permission-rule-store.js +104 -9
- package/dist/stores/file/session-store.js +1 -1
- package/dist/stores/file/tool-result-store.d.ts +14 -0
- package/dist/stores/file/tool-result-store.js +39 -2
- package/dist/stores/file/workflow-journal-store.d.ts +4 -0
- package/dist/stores/file/workflow-journal-store.js +17 -0
- package/dist/stores/file/workflow-run-store.d.ts +3 -0
- package/dist/stores/file/workflow-run-store.js +15 -0
- package/dist/tools/fs/read-deny.d.ts +15 -2
- package/dist/tools/fs/read-deny.js +10 -2
- package/dist/tools/fs/shell-read-check.d.ts +8 -2
- package/dist/tools/fs/shell-read-check.js +7 -7
- package/package.json +2 -2
- package/test/export-surface.snapshot.json +71 -73
- package/wire-changes/core-stores-sql@7.64.0.json +30 -0
- package/wire-changes/core-stores-sql@7.65.0.json +30 -0
- package/wire-changes/core@7.64.0.json +2653 -0
- package/wire-changes/core@7.65.0.json +1650 -0
- package/wire-changes/mods-kernel@7.64.0.json +30 -0
- package/wire-changes/mods-kernel@7.65.0.json +30 -0
- package/wire-changes/primitives@7.64.0.json +30 -0
- package/wire-changes/primitives@7.65.0.json +337 -0
- package/dist/core/memory-recall.d.ts +0 -208
- package/dist/core/memory-recall.js +0 -136
- package/dist/stores/file/memory-store.d.ts +0 -124
- package/dist/stores/file/memory-store.js +0 -353
|
@@ -99,9 +99,22 @@ export interface MailboxPeerMeta {
|
|
|
99
99
|
* ahead of the non-urgent ones of the same pass and counts it on the inbox notice; it never changes
|
|
100
100
|
* WHEN the recipient reads (the recipient's setting decides that, never the sender). */
|
|
101
101
|
urgent?: boolean;
|
|
102
|
+
/**
|
|
103
|
+
* WHO the record is for: the occupant (`SessionMetadata.incarnation`) of the session the writer addressed, as the writer
|
|
104
|
+
* resolved that address — a park seat from its leg's address, a sender from the recipient's directory row, a notice from the
|
|
105
|
+
* reply address it answers. A session box outlives its occupant (the id can be deleted and created again, the box stays), so a
|
|
106
|
+
* drain hands a record only to the occupant it names ({@link import("../engine/session/repo-utils.js").sameOccupant}: absent on
|
|
107
|
+
* both sides is one occupant — a deployment whose store mints no tokens; absent on one side only is another occupant). A
|
|
108
|
+
* record for another occupant is discarded with an account, never delivered. An addressing fact, not a secret and not a
|
|
109
|
+
* credential: it proves nothing about who wrote the record.
|
|
110
|
+
*/
|
|
111
|
+
occupant?: string;
|
|
112
|
+
/** The occupant of the SENDING session, beside `fromSession`: what a notice answering this record (a receipt, an idle notice)
|
|
113
|
+
* is addressed to ({@link occupant} of that notice). Absent = the sender stated none. */
|
|
114
|
+
fromOccupant?: string;
|
|
102
115
|
}
|
|
103
116
|
/** design/385 — the typed body of a notice-kind record. `state` is drawn from the receipt states on a
|
|
104
|
-
* `delivery_notice` (`held|denied|expired|delivered|refused|dropped`) and from the idle kinds on an
|
|
117
|
+
* `delivery_notice` (`held|denied|expired|delivered|refused|dropped|held_by_policy`) and from the idle kinds on an
|
|
105
118
|
* `idle_notice` (`idle|exited|unavailable|expired`); the validator admits the union, the drain checks
|
|
106
119
|
* the pairing (a state that does not fit its kind is settled `notice_unrouted`, never rendered). */
|
|
107
120
|
export interface MailboxPeerNoticeMeta {
|
|
@@ -142,8 +155,9 @@ export declare const MAILBOX_PEER_RECORD_KINDS: readonly ["peer_message", "idle_
|
|
|
142
155
|
export type MailboxPeerRecordKind = (typeof MAILBOX_PEER_RECORD_KINDS)[number];
|
|
143
156
|
/** The `notice.state` vocabulary the validator admits (the union of both notice families; the drain
|
|
144
157
|
* checks the kind↔state pairing). Spelled here, beside the record kinds, so the store contract is
|
|
145
|
-
* self-contained — the lane's
|
|
146
|
-
|
|
158
|
+
* self-contained — the lane's two closed sets (`PEER_DELIVERY_RECEIPT_STATES`, `PEER_IDLE_NOTICE_KINDS`)
|
|
159
|
+
* are spelled beside their renderers and together equal this one (a pin holds the two spellings together). */
|
|
160
|
+
export declare const MAILBOX_PEER_NOTICE_STATES: readonly ["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable", "held_by_policy"];
|
|
147
161
|
export type MailboxPeerNoticeState = (typeof MAILBOX_PEER_NOTICE_STATES)[number];
|
|
148
162
|
/** The `append` refusal code for a malformed `peerMeta` (design/385): a garbage record is refused up
|
|
149
163
|
* front with this code, never silently stripped or stored — a drain that reads a half-typed record
|
|
@@ -383,7 +397,15 @@ export interface MailboxStore {
|
|
|
383
397
|
releaseLease(scope: string, handle: string, owner: string): Promise<void>;
|
|
384
398
|
/** Observation face (the "N pending" receipt figure) — count of currently-visible messages. */
|
|
385
399
|
peekCount(scope: string, handle: string): Promise<number>;
|
|
386
|
-
/**
|
|
400
|
+
/**
|
|
401
|
+
* Drop the WHOLE mailbox for (scope, handle) — the row-deletion companion (F-13).
|
|
402
|
+
*
|
|
403
|
+
* @contract mailbox.session_box_outlives_its_occupant — deleting a session's row does not remove its box
|
|
404
|
+
* `(scope, session.<id>)`: a deployment's deletion cascade clears it with this verb (retention is the deployment's). What
|
|
405
|
+
* stays behind is never delivered to another occupant: every session-box record names the occupant it is for
|
|
406
|
+
* ({@link MailboxPeerMeta.occupant}), and a drain hands a record only to that occupant — a record for an earlier occupant
|
|
407
|
+
* of the id is discarded with an account (`delegation.delivery_discarded`) by the next occupant's drain.
|
|
408
|
+
*/
|
|
387
409
|
drop(scope: string, handle: string): Promise<void>;
|
|
388
410
|
/** Age out mailboxes whose newest message BY `sentAt` (not by array/insertion order — RB-250②)
|
|
389
411
|
* is older than maxAgeMs. Returns mailboxes dropped. */
|
|
@@ -444,6 +466,19 @@ export type MailboxCrossProcessVerdict = {
|
|
|
444
466
|
* value of the wrong type (a malformed declaration is refused, not read as "probably fine").
|
|
445
467
|
*/
|
|
446
468
|
export declare function mailboxCrossProcessMountVerdict(store: MailboxStore): MailboxCrossProcessVerdict;
|
|
469
|
+
/**
|
|
470
|
+
* THE mount verdict of the SESSION-BOX lane — a session's own `session.<id>` box, the drain that consumes it and every seat that
|
|
471
|
+
* appends to it: the mailbox's cross-process declaration ({@link mailboxCrossProcessMountVerdict}) AND a session store that reads a
|
|
472
|
+
* session's row by id (`SessionStore.headOf`). A box outlives its session's occupant (the id can be deleted and created again), and
|
|
473
|
+
* a drain discards a record addressed to another occupant only after it has read, by id, that its run's session still holds the
|
|
474
|
+
* occupant it acquired; over a store that cannot be read by id every such record is undecidable and the box would jam, so the lane
|
|
475
|
+
* does not mount, and the reason names the missing read. One judgment, read by the drain mount, the peer-lane mount and the send
|
|
476
|
+
* face, so where a record is parked and where it is drained cannot disagree. `sessions` absent = no session store at all: the same
|
|
477
|
+
* refusal.
|
|
478
|
+
*/
|
|
479
|
+
export declare function sessionBoxMountVerdict(mailbox: MailboxStore, sessions: {
|
|
480
|
+
readonly headOf?: unknown;
|
|
481
|
+
} | undefined): MailboxCrossProcessVerdict;
|
|
447
482
|
/** RB-250② (2026-07-28) class fix — the box age for `reap` is the MAX `sentAt`, not the
|
|
448
483
|
* last array element: `sentAt` is caller-supplied, so append order need not be time order, and taking
|
|
449
484
|
* the tail let a box whose freshest message was mid-array be swept — both bundled backends discarded
|
|
@@ -52,10 +52,10 @@ export function assertMailboxDecisionMove(seq, expect, next) {
|
|
|
52
52
|
}
|
|
53
53
|
export const MAILBOX_PEER_FROM_MODES = Object.freeze(["bypass", "prompting"]);
|
|
54
54
|
export const MAILBOX_PEER_RECORD_KINDS = Object.freeze(["peer_message", "idle_notice", "delivery_notice", "idle_subscription", "engine_frame"]);
|
|
55
|
-
export const MAILBOX_PEER_NOTICE_STATES = Object.freeze(["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable"]);
|
|
55
|
+
export const MAILBOX_PEER_NOTICE_STATES = Object.freeze(["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable", "held_by_policy"]);
|
|
56
56
|
export const MAILBOX_INVALID_PEER_META_CODE = "mailbox.invalid_peer_meta";
|
|
57
57
|
export const MAILBOX_CROSS_PROCESS_UNSAFE_CODE = "mailbox.cross_process_unsafe";
|
|
58
|
-
const PEER_META_STRING_KEYS = ["fromSession", "fromRoot", "senderKey", "fromScope", "gateReceiptId"];
|
|
58
|
+
const PEER_META_STRING_KEYS = ["fromSession", "fromRoot", "senderKey", "fromScope", "gateReceiptId", "occupant", "fromOccupant"];
|
|
59
59
|
export function readMailboxPeerMeta(raw) {
|
|
60
60
|
if (raw === undefined)
|
|
61
61
|
return undefined;
|
|
@@ -228,6 +228,18 @@ export function mailboxCrossProcessMountVerdict(store) {
|
|
|
228
228
|
: `the mailbox backend's crossProcessSafe declaration is malformed (${typeof declared}, expected a boolean)`;
|
|
229
229
|
return { ok: false, code: MAILBOX_CROSS_PROCESS_UNSAFE_CODE, reason };
|
|
230
230
|
}
|
|
231
|
+
export function sessionBoxMountVerdict(mailbox, sessions) {
|
|
232
|
+
const store = mailboxCrossProcessMountVerdict(mailbox);
|
|
233
|
+
if (!store.ok)
|
|
234
|
+
return store;
|
|
235
|
+
if (typeof sessions?.headOf === "function")
|
|
236
|
+
return { ok: true };
|
|
237
|
+
return {
|
|
238
|
+
ok: false,
|
|
239
|
+
code: MAILBOX_CROSS_PROCESS_UNSAFE_CODE,
|
|
240
|
+
reason: "the session store has no by-id read (SessionStore.headOf): a session box outlives its session's occupant, and without that read a drain cannot confirm that its run's session still holds the occupant it acquired before it discards a record addressed to another, so a box shared across runs would hand one occupant's records to another on luck",
|
|
241
|
+
};
|
|
242
|
+
}
|
|
231
243
|
export function newestSentAt(messages) {
|
|
232
244
|
let newest;
|
|
233
245
|
for (const m of messages) {
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* they land) — a second implementation would be a drift seam, exactly the class the challenge
|
|
9
9
|
* exclusion view closed.
|
|
10
10
|
*/
|
|
11
|
-
import type { MemoryBackend, MemoryEntry, MemoryEntryHeader, MemoryEntryOrigin, MemoryGovernanceStore, NotePatch } from "./types.js";
|
|
11
|
+
import type { MemoryBackend, MemoryEntry, MemoryEntryHeader, MemoryEntryOrigin, MemoryGovernanceObjects, MemoryGovernanceStore, NotePatch } from "./types.js";
|
|
12
12
|
import type { ConsolidationDriverRunRow } from "./consolidation-driver.js";
|
|
13
13
|
/**
|
|
14
14
|
* Derive the SUPERSEDED set from a committed header listing: superseded entry id → the standing
|
|
@@ -547,9 +547,9 @@ export type MemoryGovernanceDurability = "backend" | "replica-local";
|
|
|
547
547
|
* `"backend"` ⇔ the backend publishes its own control plane (`controlPlaneRoot`, a non-empty string — the File backend:
|
|
548
548
|
* every control-plane record, the consolidation store and the governance ledgers alike, sits in its directory). A
|
|
549
549
|
* backend that carries `MemoryBackend.governance` but no control plane still answers `"replica-local"`: the
|
|
550
|
-
* consolidation state
|
|
551
|
-
* announcement queue a consolidation writes)
|
|
552
|
-
*
|
|
550
|
+
* consolidation state, the governance documents (lineage, challenges, settlements, session accounts and the
|
|
551
|
+
* announcement queue a consolidation writes) and the instruction holds with their captured bytes (#3485) ride its
|
|
552
|
+
* store, and the answer stays `"replica-local"` there: eligibility also reads the capture opt-out records
|
|
553
553
|
* (`MemoryEngineOptions.captureRecordStore`: a carrier the host injects is its declaration of a store every replica
|
|
554
554
|
* reads; the default is a file in the engine's control plane — the store's own directory on the File backend): an
|
|
555
555
|
* answer that turns `"backend"` for a backend without a control plane must hold for the default carrier as well.
|
|
@@ -557,11 +557,18 @@ export type MemoryGovernanceDurability = "backend" | "replica-local";
|
|
|
557
557
|
export declare function memoryGovernanceDurability(backend: MemoryBackend): MemoryGovernanceDurability;
|
|
558
558
|
/** The control plane a File governance store keeps its documents in; `undefined` for any other store. */
|
|
559
559
|
export declare function fileGovernanceStoreDir(store: MemoryGovernanceStore): string | undefined;
|
|
560
|
+
/** A store's control objects as a reader that must see damage rather than be spared it reads them — an erasure's count,
|
|
561
|
+
* an export's roster: for a File store the listing names every entry standing in the kind's directory
|
|
562
|
+
* (`standingFileControlObjectNames`) — a subdirectory, a dangling link, a name no writer could have used — so the verbs
|
|
563
|
+
* that meet it refuse it by name and the reader counts it; any other store's listing is its own (KL-3466-c). The other
|
|
564
|
+
* verbs are the store's. */
|
|
565
|
+
export declare function standingControlObjectsOf(store: MemoryGovernanceStore): MemoryGovernanceObjects;
|
|
560
566
|
/**
|
|
561
567
|
* The consolidation state's File store over one control plane — the gate file, the plan workbook, the intent
|
|
562
568
|
* credentials, the run account and the mint archive exactly as they have always been laid out (same names, same
|
|
563
|
-
* bytes, same locks)
|
|
564
|
-
*
|
|
569
|
+
* bytes, same locks), each governance document in its own file ({@link fileGovernanceDocOf}) and each control object
|
|
570
|
+
* in its kind's directory (`control-objects.ts`). The File backend carries it over its own control plane; an engine
|
|
571
|
+
* whose backend carries no store keeps its state with this over the replica's control plane.
|
|
565
572
|
*/
|
|
566
573
|
export declare function fileGovernanceStore(controlDir: string): MemoryGovernanceStore;
|
|
567
574
|
/** Derive a product's slug from its proposed name (memory filename charset; collisions are the
|
|
@@ -2,6 +2,7 @@ import { existsSync, readdirSync, readFileSync, renameSync, rmSync } from "node:
|
|
|
2
2
|
import { join } from "node:path";
|
|
3
3
|
import { uuidv7 } from "../../engine/session/uuid.js";
|
|
4
4
|
import { atomicWriteFileSync, fileGovernanceDocOf, lockedStrictUpdate, readStrictSidecar, ControlPlaneCorruptError, ensureDirExists } from "./layout.js";
|
|
5
|
+
import { deleteFileControlObject, getFileControlObject, listFileControlObjects, moveFileControlObject, putFileControlObject, standingFileControlObjectNames } from "./control-objects.js";
|
|
5
6
|
import { thrownText } from "../thrown-value.js";
|
|
6
7
|
import { optionKeys, receiveMembers } from "../own-property-receipt.js";
|
|
7
8
|
export function deriveSupersededSet(headers, opts = {}) {
|
|
@@ -407,6 +408,16 @@ const FILE_GOVERNANCE_DIRS = new WeakMap();
|
|
|
407
408
|
export function fileGovernanceStoreDir(store) {
|
|
408
409
|
return FILE_GOVERNANCE_DIRS.get(store);
|
|
409
410
|
}
|
|
411
|
+
export function standingControlObjectsOf(store) {
|
|
412
|
+
const dir = fileGovernanceStoreDir(store);
|
|
413
|
+
return {
|
|
414
|
+
putObject: (kind, name, bytes, meta) => store.putObject(kind, name, bytes, meta),
|
|
415
|
+
getObject: (kind, name) => store.getObject(kind, name),
|
|
416
|
+
listObjects: dir === undefined ? (kind) => store.listObjects(kind) : async (kind) => standingFileControlObjectNames(dir, kind),
|
|
417
|
+
moveObject: (from, to) => store.moveObject(from, to),
|
|
418
|
+
deleteObject: (kind, name) => store.deleteObject(kind, name),
|
|
419
|
+
};
|
|
420
|
+
}
|
|
410
421
|
function isMintArchive(value) {
|
|
411
422
|
return typeof value === "object" && value !== null && Reflect.get(value, "kind") === "llm-consolidation-plan";
|
|
412
423
|
}
|
|
@@ -514,6 +525,21 @@ export function fileGovernanceStore(controlDir) {
|
|
|
514
525
|
rmSync(path, { force: true });
|
|
515
526
|
return true;
|
|
516
527
|
},
|
|
528
|
+
async putObject(kind, name, bytes) {
|
|
529
|
+
return putFileControlObject(controlDir, kind, name, bytes);
|
|
530
|
+
},
|
|
531
|
+
async getObject(kind, name) {
|
|
532
|
+
return getFileControlObject(controlDir, kind, name);
|
|
533
|
+
},
|
|
534
|
+
async listObjects(kind) {
|
|
535
|
+
return listFileControlObjects(controlDir, kind);
|
|
536
|
+
},
|
|
537
|
+
async moveObject(from, to) {
|
|
538
|
+
return moveFileControlObject(controlDir, from, to);
|
|
539
|
+
},
|
|
540
|
+
async deleteObject(kind, name) {
|
|
541
|
+
return deleteFileControlObject(controlDir, kind, name);
|
|
542
|
+
},
|
|
517
543
|
});
|
|
518
544
|
FILE_GOVERNANCE_DIRS.set(store, controlDir);
|
|
519
545
|
return store;
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { type MemoryControlObjectKind } from "./types.js";
|
|
2
|
+
import { type QuarantineCapture } from "./layout.js";
|
|
3
|
+
/** Where a File store stages an object's bytes before publishing them under the object's name. Never a kind's
|
|
4
|
+
* directory: a listing of a kind answers published names only. */
|
|
5
|
+
export declare const CONTROL_OBJECT_STAGE_DIR = ".control-object-stage";
|
|
6
|
+
/** A control-object kind's directory under a File store's control plane. A kind outside
|
|
7
|
+
* {@link MEMORY_CONTROL_OBJECT_KINDS} is refused (`memory.control_object_unknown`) — never given a directory of its own. */
|
|
8
|
+
export declare function fileControlObjectDirOf(kind: MemoryControlObjectKind): string;
|
|
9
|
+
/** A name a store keeps an object under: one opaque, non-empty segment of at most 255 UTF-8 bytes — never `.` / `..`, never a
|
|
10
|
+
* separator or a NUL. */
|
|
11
|
+
export declare function isControlObjectName(name: unknown): name is string;
|
|
12
|
+
/** The filesystem code behind a File control-object refusal: the refusal's own `code` when it is the filesystem's, else
|
|
13
|
+
* the code of the filesystem error it was raised over (`cause`) — `undefined` when neither names one. */
|
|
14
|
+
export declare function fileControlObjectFaultCode(err: unknown): string | undefined;
|
|
15
|
+
/**
|
|
16
|
+
* The open judge of a File governance store over `controlDir` (#3512): the store publishes every object with `link`
|
|
17
|
+
* ({@link putFileControlObject}, {@link moveFileControlObject}), so on a file system that cannot make a hard link every
|
|
18
|
+
* object write would fail — and a containment whose copy fails still takes the suspect off the plane (its copy is
|
|
19
|
+
* lost, not kept). One link is tried, at the open, between two files at the control plane's top level (named with
|
|
20
|
+
* `LINK_PROBE_PREFIX`), and both are removed; a link the file system refuses is refused here
|
|
21
|
+
* (`memory.control_plane_links_unsupported`, `controlPlaneLinksRefusal`, `detail.path` = `controlDir`). Not judged — the
|
|
22
|
+
* open proceeds as before — when the first file cannot be created (a control plane that is read-only, full or not
|
|
23
|
+
* writable: what was not tried is not claimed) or when the link's name already stands. Asked at each open, never
|
|
24
|
+
* cached. The callers are the two holders of a File store: the File backend's construction and an engine whose backend
|
|
25
|
+
* carries no store of its own. `controlDir` stands when it is asked.
|
|
26
|
+
*/
|
|
27
|
+
export declare function probeControlPlaneLinks(controlDir: string): void;
|
|
28
|
+
/** Write `(kind, name)` once ({@link import("./types.js").MemoryGovernanceStore.putObject}): `"existed"` only when the name already
|
|
29
|
+
* holds these same bytes; a name holding other bytes is refused, never answered as written. */
|
|
30
|
+
export declare function putFileControlObject(controlDir: string, kind: MemoryControlObjectKind, name: string, bytes: Uint8Array): "created" | "existed";
|
|
31
|
+
/** A control object's bytes ({@link import("./types.js").MemoryGovernanceStore.getObject}). */
|
|
32
|
+
export declare function getFileControlObject(controlDir: string, kind: MemoryControlObjectKind, name: string): Uint8Array | undefined;
|
|
33
|
+
/** Every name standing in a kind's directory, sorted — the objects and whatever else stands there (a subdirectory, a dangling link,
|
|
34
|
+
* a name no writer could have used). For the readers that must see damage rather than be spared it: the adoption of a replica
|
|
35
|
+
* refuses each such entry by name and withholds the documents behind it, and the strays reader counts them — an entry standing
|
|
36
|
+
* where an object's record belongs is a fact, never an absence. {@link listFileControlObjects} is the store's verb: objects only. */
|
|
37
|
+
export declare function standingFileControlObjectNames(controlDir: string, kind: MemoryControlObjectKind): string[];
|
|
38
|
+
/** Every name of `kind`, sorted ({@link import("./types.js").MemoryGovernanceStore.listObjects}): the regular files under a legal
|
|
39
|
+
* name — the entries {@link getFileControlObject} reads. A subdirectory or a dangling link in a kind's directory is no object and
|
|
40
|
+
* is not named here; the verbs that meet it refuse it, and {@link standingFileControlObjectNames} still names it. */
|
|
41
|
+
export declare function listFileControlObjects(controlDir: string, kind: MemoryControlObjectKind): string[];
|
|
42
|
+
/** Move one object, never overwriting ({@link import("./types.js").MemoryGovernanceStore.moveObject}). */
|
|
43
|
+
export declare function moveFileControlObject(controlDir: string, from: {
|
|
44
|
+
readonly kind: MemoryControlObjectKind;
|
|
45
|
+
readonly name: string;
|
|
46
|
+
}, to: {
|
|
47
|
+
readonly kind: MemoryControlObjectKind;
|
|
48
|
+
readonly name: string;
|
|
49
|
+
}): "moved" | "already-moved";
|
|
50
|
+
/** {@link putFileControlObject} for a writer whose record is the first one under the name — the synchronous twin of
|
|
51
|
+
* `putControlObjectOnce` (`layout.ts`), one law: `"existed"` ⇔ an object stands there that reads back (the same bytes,
|
|
52
|
+
* or other bytes the put refused); a refusal no readable object explains is the put's own and is thrown. */
|
|
53
|
+
export declare function putFileControlObjectOnce(controlDir: string, kind: MemoryControlObjectKind, name: string, bytes: Uint8Array): "created" | "existed";
|
|
54
|
+
/** The File store's capture of one suspect file's copy into its `quarantine` objects — the synchronous twin of
|
|
55
|
+
* `captureIntoQuarantine` (`layout.ts`) for the File backend's own synchronous read paths, under the same names. */
|
|
56
|
+
export declare function captureIntoFileQuarantine(controlDir: string, path: string, content: string, now: () => number): QuarantineCapture;
|
|
57
|
+
/** Delete one object ({@link import("./types.js").MemoryGovernanceStore.deleteObject}). */
|
|
58
|
+
export declare function deleteFileControlObject(controlDir: string, kind: MemoryControlObjectKind, name: string): boolean;
|
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
import { closeSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync, writeSync } from "node:fs";
|
|
2
|
+
import { randomUUID } from "node:crypto";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
import { MEMORY_CONTROL_OBJECT_KINDS } from "./types.js";
|
|
5
|
+
import { ControlPlaneCorruptError, IMPORT_RECEIPTS_DIR, LINK_PROBE_PREFIX, QUARANTINE_DIR, SESSION_CAPTURE_OPTOUT_DIR, SESSION_POLLUTION_DIR, controlPlaneLinksRefusal, ensureDirExists, quarantineCaptureBase, quarantineCaptureName } from "./layout.js";
|
|
6
|
+
import { thrownText } from "../thrown-value.js";
|
|
7
|
+
const FILE_CONTROL_OBJECT_DIRS = Object.freeze({
|
|
8
|
+
pollution: SESSION_POLLUTION_DIR,
|
|
9
|
+
"import-receipt": IMPORT_RECEIPTS_DIR,
|
|
10
|
+
quarantine: QUARANTINE_DIR,
|
|
11
|
+
hold: "hold",
|
|
12
|
+
"clearance-custody": "origin-clearance-custody",
|
|
13
|
+
capture: SESSION_CAPTURE_OPTOUT_DIR,
|
|
14
|
+
});
|
|
15
|
+
export const CONTROL_OBJECT_STAGE_DIR = ".control-object-stage";
|
|
16
|
+
function unknownObject(what) {
|
|
17
|
+
const e = new Error(`memory governance store: ${what} (a control object is one of ${MEMORY_CONTROL_OBJECT_KINDS.join(", ")}, named by one opaque segment)`);
|
|
18
|
+
e.code = "memory.control_object_unknown";
|
|
19
|
+
return e;
|
|
20
|
+
}
|
|
21
|
+
export function fileControlObjectDirOf(kind) {
|
|
22
|
+
if (typeof kind !== "string" || !Object.prototype.hasOwnProperty.call(FILE_CONTROL_OBJECT_DIRS, kind))
|
|
23
|
+
throw unknownObject(`${JSON.stringify(String(kind))} is not a control-object kind`);
|
|
24
|
+
return FILE_CONTROL_OBJECT_DIRS[kind];
|
|
25
|
+
}
|
|
26
|
+
const CONTROL_OBJECT_NAME_MAX_BYTES = 255;
|
|
27
|
+
export function isControlObjectName(name) {
|
|
28
|
+
return typeof name === "string" && name !== "" && name !== "." && name !== ".." && !/[/\\\0]/.test(name) && Buffer.byteLength(name, "utf8") <= CONTROL_OBJECT_NAME_MAX_BYTES;
|
|
29
|
+
}
|
|
30
|
+
function objectPath(controlDir, kind, name) {
|
|
31
|
+
const dir = fileControlObjectDirOf(kind);
|
|
32
|
+
if (!isControlObjectName(name))
|
|
33
|
+
throw unknownObject(`${JSON.stringify(String(name))} is not a control-object name`);
|
|
34
|
+
return join(controlDir, dir, name);
|
|
35
|
+
}
|
|
36
|
+
function errnoOf(err) {
|
|
37
|
+
return typeof err === "object" && err !== null ? Reflect.get(err, "code") : undefined;
|
|
38
|
+
}
|
|
39
|
+
export function fileControlObjectFaultCode(err) {
|
|
40
|
+
if (err instanceof ControlPlaneCorruptError)
|
|
41
|
+
return errnoOf(err.cause);
|
|
42
|
+
return errnoOf(err);
|
|
43
|
+
}
|
|
44
|
+
function unprobeable(path, err) {
|
|
45
|
+
return new ControlPlaneCorruptError(`memory control object at ${path} could not be probed (${errnoOf(err) ?? "io error"}) — whether it stands is unknown (fail-closed)`, { cause: err });
|
|
46
|
+
}
|
|
47
|
+
function entryAt(path) {
|
|
48
|
+
let found;
|
|
49
|
+
try {
|
|
50
|
+
found = lstatSync(path);
|
|
51
|
+
}
|
|
52
|
+
catch (err) {
|
|
53
|
+
if (errnoOf(err) === "ENOENT")
|
|
54
|
+
return "absent";
|
|
55
|
+
throw unprobeable(path, err);
|
|
56
|
+
}
|
|
57
|
+
if (found.isFile())
|
|
58
|
+
return "object";
|
|
59
|
+
if (!found.isSymbolicLink())
|
|
60
|
+
return "other";
|
|
61
|
+
try {
|
|
62
|
+
return statSync(path).isFile() ? "object" : "other";
|
|
63
|
+
}
|
|
64
|
+
catch (err) {
|
|
65
|
+
const code = errnoOf(err);
|
|
66
|
+
if (code === "ENOENT" || code === "ELOOP" || code === "ENOTDIR")
|
|
67
|
+
return "other";
|
|
68
|
+
throw unprobeable(path, err);
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
function stands(path) {
|
|
72
|
+
return entryAt(path) !== "absent";
|
|
73
|
+
}
|
|
74
|
+
function notAnObject(kind, name, refusal) {
|
|
75
|
+
return new ControlPlaneCorruptError(`memory control object ${kind}/${name} stands but is not a control object (a regular file under a legal name) — ${refusal} (fail-closed)`);
|
|
76
|
+
}
|
|
77
|
+
function otherBytesStand(kind, name) {
|
|
78
|
+
return new ControlPlaneCorruptError(`memory control object put ${kind}/${name}: the name already stands with different bytes — refusing to overwrite it (fail-closed)`);
|
|
79
|
+
}
|
|
80
|
+
function standingHolds(controlDir, kind, name, bytes) {
|
|
81
|
+
const standing = getFileControlObject(controlDir, kind, name);
|
|
82
|
+
return standing === undefined ? undefined : Buffer.from(standing).equals(bytes);
|
|
83
|
+
}
|
|
84
|
+
export function probeControlPlaneLinks(controlDir) {
|
|
85
|
+
const source = join(controlDir, `${LINK_PROBE_PREFIX}${randomUUID()}`);
|
|
86
|
+
const linked = `${source}.link`;
|
|
87
|
+
try {
|
|
88
|
+
closeSync(openSync(source, "wx", 0o600));
|
|
89
|
+
}
|
|
90
|
+
catch {
|
|
91
|
+
return;
|
|
92
|
+
}
|
|
93
|
+
let made = false;
|
|
94
|
+
try {
|
|
95
|
+
linkSync(source, linked);
|
|
96
|
+
made = true;
|
|
97
|
+
}
|
|
98
|
+
catch (err) {
|
|
99
|
+
const fault = errnoOf(err);
|
|
100
|
+
if (fault !== "EEXIST")
|
|
101
|
+
throw controlPlaneLinksRefusal(controlDir, fault);
|
|
102
|
+
}
|
|
103
|
+
finally {
|
|
104
|
+
for (const path of made ? [linked, source] : [source]) {
|
|
105
|
+
try {
|
|
106
|
+
rmSync(path, { force: true });
|
|
107
|
+
}
|
|
108
|
+
catch {
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
export function putFileControlObject(controlDir, kind, name, bytes) {
|
|
114
|
+
const path = objectPath(controlDir, kind, name);
|
|
115
|
+
const held = standingHolds(controlDir, kind, name, bytes);
|
|
116
|
+
if (held === true)
|
|
117
|
+
return "existed";
|
|
118
|
+
if (held === false)
|
|
119
|
+
throw otherBytesStand(kind, name);
|
|
120
|
+
ensureDirExists(join(controlDir, fileControlObjectDirOf(kind)));
|
|
121
|
+
const stageDir = join(controlDir, CONTROL_OBJECT_STAGE_DIR);
|
|
122
|
+
ensureDirExists(stageDir);
|
|
123
|
+
const staged = join(stageDir, randomUUID());
|
|
124
|
+
const fd = openSync(staged, "wx", 0o600);
|
|
125
|
+
try {
|
|
126
|
+
let written = 0;
|
|
127
|
+
while (written < bytes.byteLength) {
|
|
128
|
+
const n = writeSync(fd, bytes, written, bytes.byteLength - written);
|
|
129
|
+
if (n <= 0)
|
|
130
|
+
throw new Error(`memory control object ${kind}/${name}: write made no progress (${written}/${bytes.byteLength} bytes)`);
|
|
131
|
+
written += n;
|
|
132
|
+
}
|
|
133
|
+
fsyncSync(fd);
|
|
134
|
+
}
|
|
135
|
+
finally {
|
|
136
|
+
closeSync(fd);
|
|
137
|
+
}
|
|
138
|
+
try {
|
|
139
|
+
linkSync(staged, path);
|
|
140
|
+
return "created";
|
|
141
|
+
}
|
|
142
|
+
catch (err) {
|
|
143
|
+
if (errnoOf(err) === "EEXIST") {
|
|
144
|
+
const held = standingHolds(controlDir, kind, name, bytes);
|
|
145
|
+
if (held === true)
|
|
146
|
+
return "existed";
|
|
147
|
+
if (held === false)
|
|
148
|
+
throw otherBytesStand(kind, name);
|
|
149
|
+
throw new ControlPlaneCorruptError(`memory control object put ${kind}/${name}: the name stood when the object was published and was gone when its bytes were compared — nothing was written (fail-closed)`);
|
|
150
|
+
}
|
|
151
|
+
throw err;
|
|
152
|
+
}
|
|
153
|
+
finally {
|
|
154
|
+
rmSync(staged, { force: true });
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
export function getFileControlObject(controlDir, kind, name) {
|
|
158
|
+
const path = objectPath(controlDir, kind, name);
|
|
159
|
+
const state = entryAt(path);
|
|
160
|
+
if (state === "absent")
|
|
161
|
+
return undefined;
|
|
162
|
+
if (state === "other")
|
|
163
|
+
throw notAnObject(kind, name, "it is never read as missing");
|
|
164
|
+
try {
|
|
165
|
+
return new Uint8Array(readFileSync(path));
|
|
166
|
+
}
|
|
167
|
+
catch (err) {
|
|
168
|
+
if ((errnoOf(err) === "ENOENT" || errnoOf(err) === "ENOTDIR") && !stands(path))
|
|
169
|
+
return undefined;
|
|
170
|
+
throw new ControlPlaneCorruptError(`memory control object ${kind}/${name} stands but cannot be read (${errnoOf(err) ?? "io error"}) — it is never read as missing (fail-closed)`, { cause: err });
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
export function standingFileControlObjectNames(controlDir, kind) {
|
|
174
|
+
const dir = join(controlDir, fileControlObjectDirOf(kind));
|
|
175
|
+
try {
|
|
176
|
+
return readdirSync(dir).sort();
|
|
177
|
+
}
|
|
178
|
+
catch (err) {
|
|
179
|
+
if (errnoOf(err) === "ENOENT" && !stands(dir))
|
|
180
|
+
return [];
|
|
181
|
+
throw new ControlPlaneCorruptError(`memory control objects of kind ${kind} could not be enumerated (${errnoOf(err) ?? "io error"}) at ${dir} — an enumeration failure is not an empty kind (fail-closed)`, { cause: err });
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
export function listFileControlObjects(controlDir, kind) {
|
|
185
|
+
const dir = join(controlDir, fileControlObjectDirOf(kind));
|
|
186
|
+
return standingFileControlObjectNames(controlDir, kind).filter((name) => isControlObjectName(name) && entryAt(join(dir, name)) === "object");
|
|
187
|
+
}
|
|
188
|
+
function sameBytes(a, b) {
|
|
189
|
+
const sa = statSync(a);
|
|
190
|
+
const sb = statSync(b);
|
|
191
|
+
if (sa.dev === sb.dev && sa.ino === sb.ino)
|
|
192
|
+
return true;
|
|
193
|
+
return readFileSync(a).equals(readFileSync(b));
|
|
194
|
+
}
|
|
195
|
+
export function moveFileControlObject(controlDir, from, to) {
|
|
196
|
+
const src = objectPath(controlDir, from.kind, from.name);
|
|
197
|
+
const dst = objectPath(controlDir, to.kind, to.name);
|
|
198
|
+
const neither = () => new ControlPlaneCorruptError(`memory control object move ${from.kind}/${from.name} → ${to.kind}/${to.name}: neither the source nor the target stands — nothing to move or to resume (fail-closed)`);
|
|
199
|
+
if (src === dst) {
|
|
200
|
+
if (stands(src))
|
|
201
|
+
return "already-moved";
|
|
202
|
+
throw neither();
|
|
203
|
+
}
|
|
204
|
+
ensureDirExists(join(controlDir, fileControlObjectDirOf(to.kind)));
|
|
205
|
+
try {
|
|
206
|
+
linkSync(src, dst);
|
|
207
|
+
}
|
|
208
|
+
catch (err) {
|
|
209
|
+
const code = errnoOf(err);
|
|
210
|
+
if (code === "ENOENT" && !stands(src)) {
|
|
211
|
+
if (stands(dst))
|
|
212
|
+
return "already-moved";
|
|
213
|
+
throw neither();
|
|
214
|
+
}
|
|
215
|
+
if (code !== "EEXIST")
|
|
216
|
+
throw err;
|
|
217
|
+
if (!lstatSync(dst).isFile())
|
|
218
|
+
throw new ControlPlaneCorruptError(`memory control object move ${from.kind}/${from.name} → ${to.kind}/${to.name}: the target already stands but is not a file of its own (a link, or no file) — refusing to drop the source onto it (fail-closed)`);
|
|
219
|
+
if (!sameBytes(src, dst))
|
|
220
|
+
throw new ControlPlaneCorruptError(`memory control object move ${from.kind}/${from.name} → ${to.kind}/${to.name}: the target already stands with different bytes — refusing to overwrite it (fail-closed)`);
|
|
221
|
+
}
|
|
222
|
+
unlinkSync(src);
|
|
223
|
+
return "moved";
|
|
224
|
+
}
|
|
225
|
+
export function putFileControlObjectOnce(controlDir, kind, name, bytes) {
|
|
226
|
+
try {
|
|
227
|
+
return putFileControlObject(controlDir, kind, name, bytes);
|
|
228
|
+
}
|
|
229
|
+
catch (err) {
|
|
230
|
+
let standing;
|
|
231
|
+
try {
|
|
232
|
+
standing = getFileControlObject(controlDir, kind, name);
|
|
233
|
+
}
|
|
234
|
+
catch {
|
|
235
|
+
throw err;
|
|
236
|
+
}
|
|
237
|
+
if (standing === undefined)
|
|
238
|
+
throw err;
|
|
239
|
+
return "existed";
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
export function captureIntoFileQuarantine(controlDir, path, content, now) {
|
|
243
|
+
const bytes = new TextEncoder().encode(content);
|
|
244
|
+
const base = quarantineCaptureBase(path, now);
|
|
245
|
+
try {
|
|
246
|
+
for (let attempt = 0; attempt <= 10; attempt++) {
|
|
247
|
+
const name = quarantineCaptureName(base, attempt);
|
|
248
|
+
if (putFileControlObjectOnce(controlDir, "quarantine", name, bytes) === "created")
|
|
249
|
+
return { name };
|
|
250
|
+
}
|
|
251
|
+
return { failed: "quarantine copy failed: every capture name already stands" };
|
|
252
|
+
}
|
|
253
|
+
catch (err) {
|
|
254
|
+
return { failed: `quarantine copy failed: ${thrownText(err)}` };
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
export function deleteFileControlObject(controlDir, kind, name) {
|
|
258
|
+
const path = objectPath(controlDir, kind, name);
|
|
259
|
+
const state = entryAt(path);
|
|
260
|
+
if (state === "absent")
|
|
261
|
+
return false;
|
|
262
|
+
if (state === "other")
|
|
263
|
+
throw notAnObject(kind, name, "refusing to delete it");
|
|
264
|
+
try {
|
|
265
|
+
unlinkSync(path);
|
|
266
|
+
return true;
|
|
267
|
+
}
|
|
268
|
+
catch (err) {
|
|
269
|
+
if ((errnoOf(err) === "ENOENT" || errnoOf(err) === "ENOTDIR") && !stands(path))
|
|
270
|
+
return false;
|
|
271
|
+
throw new ControlPlaneCorruptError(`memory control object ${kind}/${name} stands but could not be deleted (${errnoOf(err) ?? "io error"}) (fail-closed)`, { cause: err });
|
|
272
|
+
}
|
|
273
|
+
}
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
import { type MemoryControlObjectKind, type MemoryGovernanceDocName, type MemoryGovernanceStore } from "./types.js";
|
|
2
|
+
/** The carrier records a replica control plane still holds. */
|
|
3
|
+
export interface ReplicaControlPlaneStrays {
|
|
4
|
+
/** The governance documents with a file (or a journal) in the replica. */
|
|
5
|
+
readonly docs: readonly MemoryGovernanceDocName[];
|
|
6
|
+
/** How many entries stand in each kind's directory of the replica (kinds with none are absent): the control objects, and whatever
|
|
7
|
+
* else stands where an object's record belongs — adoption refuses each of those by name, never skips it. */
|
|
8
|
+
readonly objects: Readonly<Partial<Record<MemoryControlObjectKind, number>>>;
|
|
9
|
+
}
|
|
10
|
+
/** One record adoption handled: a document (`doc:<name>`) or an object (`<kind>/<name>`). */
|
|
11
|
+
export interface AdoptedControlRecord {
|
|
12
|
+
readonly record: string;
|
|
13
|
+
/** What the carrier holds now, never what became of the replica's copy (which stays): `"written"` ⇔ the carrier
|
|
14
|
+
* lacked the record and now holds the same value; `"converged"` ⇔ it already held the same value. */
|
|
15
|
+
readonly outcome: "written" | "converged";
|
|
16
|
+
/** sha-256 of the record as the replica held it: an object's bytes, a document's committed JSON value. */
|
|
17
|
+
readonly digest: string;
|
|
18
|
+
}
|
|
19
|
+
/** {@link adoptReplicaControlPlane}'s answer. */
|
|
20
|
+
export interface ControlPlaneAdoptionReport {
|
|
21
|
+
/** Records the carrier now holds with the replica's value (the replica keeps its copy). */
|
|
22
|
+
readonly adopted: readonly AdoptedControlRecord[];
|
|
23
|
+
/** Records whose adoption did not complete, each with why — a different value already in the carrier, a record that
|
|
24
|
+
* could not be read or verified, or a receipt row that could not be written (then the carrier may already hold the
|
|
25
|
+
* value, and a re-run converges it). */
|
|
26
|
+
readonly refused: readonly {
|
|
27
|
+
readonly record: string;
|
|
28
|
+
readonly reason: string;
|
|
29
|
+
}[];
|
|
30
|
+
}
|
|
31
|
+
/** The replica's body-less record of which of its records the carrier holds with the same value (one row per record and digest). */
|
|
32
|
+
export declare const CONTROL_PLANE_ADOPTION_FILE = "control-plane-adoption.json";
|
|
33
|
+
/** The carrier records `controlDir` holds — documents with a file or journal, objects by kind. An enumeration that
|
|
34
|
+
* fails throws `ControlPlaneCorruptError` (never an empty answer). */
|
|
35
|
+
export declare function replicaControlPlaneStrays(controlDir: string): ReplicaControlPlaneStrays;
|
|
36
|
+
/**
|
|
37
|
+
* Copy the replica control plane's carrier records into `carrier` (see the module note). Answers what the carrier now
|
|
38
|
+
* holds with the replica's value and what was refused; the replica's records are not removed either way. When `carrier`
|
|
39
|
+
* is the File store over `controlDir` itself there is nothing to hand over and the answer is empty. A `controlDir` that does
|
|
40
|
+
* not exist is refused (`ControlPlaneCorruptError`): the call is an operator's, over a path they named, and a wrong path must
|
|
41
|
+
* not read as "nothing to adopt".
|
|
42
|
+
*/
|
|
43
|
+
export declare function adoptReplicaControlPlane(controlDir: string, carrier: MemoryGovernanceStore, opts?: {
|
|
44
|
+
readonly now?: () => number;
|
|
45
|
+
}): Promise<ControlPlaneAdoptionReport>;
|
|
46
|
+
/** The replica's adoption receipt: one body-less row per adopted record (what, the digest of its bytes, when). */
|
|
47
|
+
export declare function readControlPlaneAdoptionReceipt(controlDir: string): ReadonlyArray<{
|
|
48
|
+
readonly record: string;
|
|
49
|
+
readonly digest: string;
|
|
50
|
+
readonly at: number;
|
|
51
|
+
}>;
|