@lmzhen/dsh-evolution-core 0.26.26 → 0.27.0

package/lib/types/tool-dispatch.js

@@ -0,0 +1,535 @@
+/**
+ * The family's ONE reader of platform tool-dispatch events.
+ *
+ * The platform records a finished tool call under two different event
+ * vocabularies and only one of them is written per dispatch, chosen by the
+ * mounted tool runtime's mode:
+ *
+ * - native mode: \`tool/call\` (with \`callId\`) settled by \`tool/result\`, the
+ *   write sites being core/agent-loop/src/tool-calls.ts:264 and :282.
+ * - PTC mode: \`tool/ptc-dispatch-start\` and \`tool/ptc-dispatch\` (with
+ *   \`subCallId\`), the write sites being core/tools/src/ptc.ts:534 and :509.
+ *
+ * A consumer that matches a vocabulary directly therefore goes blind in the
+ * other mode while still appearing to work — the defect this module exists to
+ * make impossible. Every family consumer reads dispatches through
+ * \`ToolDispatchNormalizer\` (or the pure helpers below) and matches on
+ * \`ToolDispatchSignal\` fields only; \`verify-arch-guards\` rule N11 rejects a
+ * dispatch event-type comparison anywhere else.
+ *
+ * ## The one-dispatch invariant
+ *
+ * One dispatch produces exactly one \`ToolDispatchSignal\`, no matter how many
+ * events carry it: a start/settle pair for a PTC sub-dispatch, a call/result
+ * pair for a native call, or both vocabularies for the same call. Deduplication
+ * and outcome folding are keyed by the platform's own per-vocabulary call
+ * identity, which is stable across the pair (the platform's event JSDoc:
+ * "the pairing ids (matching the \`tool/ptc-dispatch-start\` with the same
+ * \`subCallId\`)").
+ *
+ * ## Layer
+ *
+ * Cross-cutting normalization: the reader half of the dispatch vocabulary,
+ * next to \`signals.ts\` (which folds the signals this module emits). Both are
+ * consumers; neither subscribes to the platform bus itself.
+ * @module
+ */
+import { CITATION_SUPPORT_DIRS } from "./citations.js";
+// S1-E6 (0.3.80): the former third value 'program-root' (the run_code call
+// itself) was UNREACHABLE — the platform appends the root's `tool/call` BEFORE
+// any PTC sub-dispatch pair exists, so the root's signal always emitted as
+// 'native'. Dead vocabulary removed rather than kept as a trap.
+/** The platform event type carrying a PTC sub-dispatch start. */
+export const PTC_DISPATCH_START_EVENT = 'tool/ptc-dispatch-start';
+/** The platform event type carrying a PTC sub-dispatch settle. */
+export const PTC_DISPATCH_EVENT = 'tool/ptc-dispatch';
+/** The platform event type carrying a native tool call. */
+export const NATIVE_CALL_EVENT = 'tool/call';
+/** The platform event type carrying a native tool result. */
+export const NATIVE_RESULT_EVENT = 'tool/result';
+/**
+ * The dispatch vocabulary this module owns. A consumer must never compare
+ * against these literals itself (rule N11); it compares \`kind\` instead.
+ */
+export const DISPATCH_EVENT_TYPES = [
+    NATIVE_CALL_EVENT,
+    NATIVE_RESULT_EVENT,
+    PTC_DISPATCH_START_EVENT,
+    PTC_DISPATCH_EVENT,
+];
+/**
+ * Model-visible session frames: the message types plus the ONE dispatch vocabulary above.
+ * Consumers classify through this list instead of naming event literals (rule N11).
+ */
+export const MODEL_SESSION_EVENT_TYPES = ['user/message', 'assistant/message', ...DISPATCH_EVENT_TYPES];
+/**
+ * \`TypeError\` thrown when a payload that claims to be a dispatch event
+ * violates the platform's event declaration. Named so a deployment can tell this
+ * refusal apart from a generic failure in a log line.
+ */
+export class ToolDispatchPayloadError extends TypeError {
+    name = 'ToolDispatchPayloadError';
+}
+/** The dispatch event types this module recognizes, as a set. */
+const DISPATCH_EVENT_TYPE_SET = new Set(DISPATCH_EVENT_TYPES);
+/** \`name\`-less payloads: an external emitter or a corrupt log can produce these. */
+const MALFORMED = 'malformed';
+/** One tool-result block of a native result payload, or \`null\` when the payload carries none. */
+function firstResultBlock(data) {
+    const content = data.message?.content;
+    if (!Array.isArray(content))
+        return null;
+    for (const entry of content) {
+        if (entry === null || typeof entry !== 'object')
+            continue;
+        const block = entry;
+        if (block.type === 'tool-result')
+            return block;
+    }
+    return null;
+}
+/** Deterministic identity for a dispatch payload that carries no call id. */
+function payloadIdentity(data) {
+    if (data === undefined)
+        return '';
+    try {
+        return JSON.stringify(data);
+    }
+    catch {
+        // A cyclic payload cannot be identified by value; the event TYPE is then the
+        // whole identity, so two undecidable frames collapse into one rather than
+        // inflating the count. The refusal is loud at the live boundary
+        // (`assertDispatchPayload`), which is where a producer bug is actionable.
+        return '';
+    }
+}
+/** Read the payload of a recognized dispatch event, or \`null\` for any other event. */
+function readDispatchRecord(event) {
+    if (!DISPATCH_EVENT_TYPE_SET.has(event.type))
+        return null;
+    const data = (event.data ?? {});
+    if (event.type === NATIVE_RESULT_EVENT) {
+        // The call identity lives INSIDE the message (`message.source.callId`, the
+        // shape `createToolResultMessage` produces — llm/src/message.ts:258); the
+        // event payload has no top-level `callId`. A `toolCallId` on a result block
+        // is accepted as the same identity for a hand-built or legacy frame.
+        const owner = data.message?.source?.callId;
+        const block = firstResultBlock(data);
+        const callId = typeof owner === 'string' && owner !== ''
+            ? owner
+            : typeof block?.toolCallId === 'string' && block.toolCallId !== '' ? block.toolCallId : undefined;
+        if (callId === undefined)
+            return null;
+        return {
+            kind: 'native',
+            callId,
+            rootCallId: callId,
+            name: '',
+            arguments: undefined,
+            // A failure is marked by the payload-level `error` OR a result block's own
+            // `isError` (both shapes exist in persisted pre-rc.2 logs).
+            outcome: { ok: data.isError !== true && data.error === undefined && block?.isError !== true },
+        };
+    }
+    const isPtc = event.type === PTC_DISPATCH_START_EVENT || event.type === PTC_DISPATCH_EVENT;
+    const identity = isPtc ? data.subCallId : data.callId;
+    // An id-less payload is still evidence of a call the model made: a real log
+    // always carries the id, but a replayed pre-upgrade frame or an external
+    // emitter may not, and dropping those would silently under-count. The
+    // payload itself becomes the identity, so the same broken frame delivered
+    // twice is still ONE dispatch.
+    const callId = typeof identity === 'string' && identity !== '' ? identity : `${event.type}:${payloadIdentity(event.data)}`;
+    const parent = isPtc && typeof data.parentCallId === 'string' && data.parentCallId !== '' ? data.parentCallId : undefined;
+    const name = typeof data.name === 'string' && data.name !== '' ? data.name : MALFORMED;
+    return {
+        kind: isPtc ? 'program' : 'native',
+        callId,
+        rootCallId: typeof data.rootCallId === 'string' && data.rootCallId !== '' ? data.rootCallId : (parent ?? callId),
+        name,
+        arguments: data.arguments,
+        ...isPtc && event.type === PTC_DISPATCH_EVENT ? { outcome: { ok: data.isError !== true } } : {},
+    };
+}
+/**
+ * The ledger key of one dispatch: a scope-qualified call id.
+ *
+ * v43 audit (FLOW4-4): a normalizer shared by every session (skill-usage's live listener holds ONE
+ * process-wide instance) used the bare call id, so two sessions that produced the same id — PTC
+ * sub-call ids are short, and an id-less payload falls back to a type+payload key that is not
+ * unique by construction — collided: the second session's read was absorbed as "already seen" and
+ * never counted, and a settle in one session flipped the other's `ok`. Callers that span sessions
+ * pass the session id as `scope`.
+ * @param callId - the dispatch's call id (or its payload-derived fallback).
+ * @param scope - the owning session id, or '' for a fold that never leaves one session.
+ * @returns the key both the ledger and every projection fold dedupe on.
+ */
+export function dispatchKeyOf(callId, scope = '') {
+    return scope === '' ? callId : `${scope}:${callId}`;
+}
+/**
+ * The pure half of the ledger: what one event says about one dispatch.
+ *
+ * The DECISION (which dispatch, and whether this event is the one that opens it) lives here and
+ * only here; carriers differ in what they keep — the class below keeps consumer-visible mutable
+ * signals, the family's `evolutionReads`/`evolutionSignals` projection units keep plain-JSON
+ * ledgers. `name` is empty on an event that only settles an already-opened dispatch (a native
+ * `tool/result`), and `outcome` is present exactly when the event carried one.
+ * @param event - one session event; any non-dispatch event answers `null`.
+ * @param scope - the owning session id, or '' for a single-session fold.
+ * @returns the step, or `null` when the event is not a dispatch.
+ */
+export function dispatchStepOf(event, scope = '') {
+    const record = readDispatchRecord(event);
+    if (record === null)
+        return null;
+    return {
+        key: dispatchKeyOf(record.callId, scope),
+        kind: record.kind,
+        callId: record.callId,
+        rootCallId: record.rootCallId,
+        name: record.name,
+        arguments: record.arguments,
+        ...record.outcome === undefined ? {} : { outcome: record.outcome },
+    };
+}
+/**
+ * The family's single dispatch ledger: absorbs platform events in log order,
+ * emits one \`ToolDispatchSignal\` per dispatch, and folds later events of the
+ * same dispatch into the record it already emitted.
+ *
+ * Consumers keep the \`ToolDispatchSignal\` object they received and re-read it
+ * later; no consumer needs to correlate events itself.
+ */
+export class ToolDispatchNormalizer {
+    records = new Map();
+    /** S2-P2-14: cap for the LEDGER (and the settle markers) — opt-in, meant for
+     * the long-lived live listener (skill-usage) whose ledger is pure dedup
+     * state and would otherwise grow with the process lifetime. `Infinity` (the
+     * default, used by whole-log folding) keeps every dispatch. Eviction is
+     * oldest-first: a call/result pair spans one tool call, so an evicted
+     * dispatch can never be re-paired within any realistic window. */
+    maxTracked;
+    /** S2-P2-12: call ids whose outcome has already been reported to the settle
+     * channel — a replayed result event must not settle the same dispatch twice. */
+    settledIds = new Set();
+    constructor(options = {}) {
+        this.maxTracked = options.maxTracked ?? Number.POSITIVE_INFINITY;
+    }
+    /**
+     * Absorb one session event.
+     * @param event - the event to absorb; any non-dispatch event is ignored.
+     * @returns the dispatch's signal when this event FIRST reveals the dispatch,
+     * otherwise \`null\` (the paired event of an already-emitted dispatch, or a
+     * non-dispatch event). A \`null\` return is never a dispatch to count again.
+     */
+    advance(event, scope = '') {
+        const step = dispatchStepOf(event, scope);
+        if (step === null)
+            return null;
+        const existing = this.records.get(step.key);
+        if (existing !== undefined) {
+            if (step.outcome !== undefined)
+                existing.ok = step.outcome.ok;
+            return null;
+        }
+        // An event that only settles a dispatch this ledger never saw open carries no name:
+        // there is no signal to emit (the same answer the pre-refactor branch gave).
+        if (step.name === '')
+            return null;
+        const signal = {
+            kind: step.kind,
+            callId: step.callId,
+            rootCallId: step.rootCallId,
+            name: step.name,
+            arguments: step.arguments,
+            // Explicitly `undefined` when the event carried no outcome: the signal type requires the key
+            // (`exactOptionalPropertyTypes`), and consumers read it as "pending" in exactly that case.
+            ok: step.outcome?.ok,
+        };
+        this.records.set(step.key, signal);
+        this.evict();
+        // S1-E6: a former 'program-root' upgrade lived here (a PTC sub-dispatch
+        // proving its parent was a run_code root) — but the platform appends the
+        // root's `tool/call` BEFORE any PTC pair, so the root's signal had already
+        // emitted as 'native' and the branch never ran. The root counting once as
+        // 'native' and its sub-dispatches as 'program' is the observable contract.
+        return signal;
+    }
+    /**
+     * S2-P2-12: the SETTLE channel. \`advance\` answers \`null\` for the paired
+     * event that settles an already-emitted dispatch, so a consumer that must act
+     * on the OUTCOME (e.g. count successful skill reads only) cannot tell which
+     * dispatch a \`null\` belonged to. Call this with the same event AFTER
+     * \`advance\`: it answers the settled dispatch exactly once (replayed settle
+     * events answer \`null\`).
+     * @param event - the event already absorbed by \`advance\`.
+     * @returns the dispatch this event settled, or \`null\`.
+     */
+    settledSignalOf(event, scope = '') {
+        const step = dispatchStepOf(event, scope);
+        if (step?.outcome === undefined)
+            return null;
+        if (this.settledIds.has(step.key))
+            return null;
+        const signal = this.records.get(step.key);
+        if (signal === undefined)
+            return null;
+        this.settledIds.add(step.key);
+        this.evict();
+        return signal;
+    }
+    /** Oldest-first eviction once the ledger (or the settle markers) overflows. */
+    evict() {
+        while (this.records.size > this.maxTracked) {
+            const oldest = this.records.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.records.delete(oldest);
+            this.settledIds.delete(oldest);
+        }
+        while (this.settledIds.size > this.maxTracked) {
+            const oldest = this.settledIds.values().next().value;
+            if (oldest === undefined)
+                break;
+            this.settledIds.delete(oldest);
+        }
+    }
+    /** Every emitted dispatch, in first-seen order. */
+    get signals() {
+        return [...this.records.values()];
+    }
+    /**
+     * Fold every event of a session log, in order.
+     * @param events - the log, oldest first.
+     * @returns one signal per dispatch, in first-seen order.
+     */
+    foldAll(events) {
+        const emitted = [];
+        for (const event of events) {
+            const signal = this.advance(event);
+            if (signal !== null)
+                emitted.push(signal);
+        }
+        return emitted;
+    }
+}
+/**
+ * Read one event into a dispatch record without a ledger (the pure half of the
+ * fold). Unlike the ledger it does NOT dedupe: a caller that walks a log and
+ * emits its own lines needs the call line on the event that opens the result.
+ * @param event - one session event; an absent event (an over-advanced index)
+ * answers \`null\` rather than throwing.
+ * @returns the dispatch this event opens, or \`null\` for any other event.
+ */
+export function readDispatchSignal(event) {
+    if (event?.type === undefined)
+        return null;
+    const record = readDispatchRecord({ type: event.type, ...event.data === undefined ? {} : { data: event.data } });
+    if (record === null || record.name === '')
+        return null;
+    return {
+        kind: record.kind,
+        callId: record.callId,
+        rootCallId: record.rootCallId,
+        name: record.name,
+        arguments: record.arguments,
+    };
+}
+/** Tool names that READ one skill. The single authority for skill-read detection. */
+const SKILL_READ_TOOL_NAMES = new Set(['skill']);
+/**
+ * Is this dispatched tool name a single-skill read?
+ * @param name - the dispatched tool name.
+ * @returns \`true\` only for the read tool whose arguments name one skill.
+ */
+export function isSkillReadToolName(name) {
+    return SKILL_READ_TOOL_NAMES.has(name);
+}
+/** Tool names whose dispatch opens a code program, i.e. whose sub-dispatches are \`program\`. */
+const PROGRAM_TOOL_NAMES = new Set(['run_code']);
+/**
+ * Does this signal read one skill, and did it not fail?
+ * @param signal - a normalized dispatch.
+ * @returns the skill name the dispatch read, or \`undefined\` when the dispatch
+ * is not a skill read or has failed. A dispatch whose outcome is still pending
+ * counts as a read: the platform settles every started sub-dispatch, so pending
+ * is a live-window state, not a failure.
+ */
+/** Tool names whose dispatch reads one FILE — the deployment's file tool
+ * (default `read`). A differently named tool is configured, not guessed. */
+export const DEFAULT_SUPPORT_READ_TOOL_NAMES = ['read'];
+/** Dispatch arguments: a JSON string in native mode and an already-parsed
+ * object in PTC mode (core/tools/src/types.ts:11-23) — parsed defensively so no
+ * consumer has to trust one modality's encoding. */
+function parsedArguments(signal) {
+    let parsed = signal.arguments;
+    if (typeof parsed === 'string') {
+        try {
+            parsed = JSON.parse(parsed);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    return parsed;
+}
+/** The path-shaped argument of a file tool, when it carries one. */
+function readPathArgument(signal) {
+    const record = parsedArguments(signal);
+    if (record === null)
+        return null;
+    for (const key of ['file_path', 'path', 'file', 'target']) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim() !== '')
+            return value;
+    }
+    return null;
+}
+/**
+ * Read one dispatch as a SUPPORT-FILE read attributed to a skill: a read of
+ * `<root>/<skill>/<support dir>/…` is demand evidence for that one file, the
+ * way `skillReadNameOf` is demand evidence for a whole body.
+ * @param signal - a settled dispatch.
+ * @param options - the deployment's file-tool names and its skills root; an
+ *   empty root falls back to the `/skills/` marker in the path.
+ * @returns the skill name and the skill-root-relative path, or `null` when the
+ *   dispatch is not a support-file read. Pure: no IO, no service lookup.
+ */
+export function supportFileReadOf(signal, options) {
+    if (!options.toolNames.includes(signal.name))
+        return null;
+    if (signal.ok === false)
+        return null;
+    const raw = readPathArgument(signal);
+    if (raw === null)
+        return null;
+    const normalized = raw.replace(/\\/g, '/').trim();
+    if (normalized === '' || normalized.split('/').includes('..'))
+        return null;
+    const root = options.root.replace(/\\/g, '/').replace(/\/+$/, '');
+    let relative = null;
+    if (root !== '') {
+        const lower = normalized.toLowerCase();
+        const lowerRoot = root.toLowerCase();
+        if (lower.startsWith(lowerRoot + '/'))
+            relative = normalized.slice(root.length + 1);
+    }
+    if (relative === null) {
+        const marker = '/skills/';
+        const at = normalized.toLowerCase().lastIndexOf(marker);
+        if (at === -1)
+            return null;
+        relative = normalized.slice(at + marker.length);
+    }
+    const parts = relative.split('/').filter(part => part !== '');
+    const skill = parts[0];
+    const dir = parts[1];
+    if (skill === undefined || dir === undefined || parts.length < 3)
+        return null;
+    if (!CITATION_SUPPORT_DIRS.includes(dir))
+        return null;
+    return { skill: skill.trim(), rel: parts.slice(1).join('/') };
+}
+export function skillReadNameOf(signal) {
+    if (!SKILL_READ_TOOL_NAMES.has(signal.name))
+        return undefined;
+    if (signal.ok === false)
+        return undefined;
+    // One defensive re-parse for both readers (parsedArguments): the encoding
+    // differs by runtime mode, so neither may trust the other's.
+    const candidate = parsedArguments(signal);
+    if (candidate === null)
+        return undefined;
+    const name = typeof candidate.name === 'string' ? candidate.name : typeof candidate.skill === 'string' ? candidate.skill : '';
+    return name === '' ? undefined : name;
+}
+/**
+ * Fold one session log into its deduplicated dispatches.
+ * @param events - the log, oldest first. Pass an array, not a live snapshot
+ * iterator, when the log can grow while folding.
+ * @returns one signal per dispatch, in first-seen order.
+ */
+export function foldToolDispatches(events) {
+    return new ToolDispatchNormalizer().foldAll(events);
+}
+/**
+ * Every skill name this log read through a dispatch, deduplicated by dispatch.
+ * @param events - the log, oldest first.
+ * @returns the names read by at least one non-failed skill dispatch.
+ */
+export function collectReadSkillNames(events) {
+    const names = new Set();
+    for (const signal of foldToolDispatches(events)) {
+        const name = skillReadNameOf(signal);
+        if (name !== undefined)
+            names.add(name);
+    }
+    return names;
+}
+/** Tool names that touch the skill library at all — the review's skill-signal set. */
+const SKILL_TOOL_NAMES = new Set([...SKILL_READ_TOOL_NAMES, 'skill_manage']);
+/**
+ * Does this dispatched tool name touch the skill library (read or mutate)?
+ * @param name - the dispatched tool name.
+ * @returns \`true\` for any skill-library tool. This is the review cadence's
+ * skill signal, which has always covered reads and writes alike.
+ */
+export function isSkillToolName(name) {
+    return SKILL_TOOL_NAMES.has(name);
+}
+/**
+ * Does this dispatched tool name open a code program?
+ * @param name - the dispatched tool name.
+ * @returns \`true\` for the tool whose sub-dispatches are \`program\` kind.
+ */
+export function isProgramToolName(name) {
+    return PROGRAM_TOOL_NAMES.has(name);
+}
+/**
+ * Assert that a payload really is the dispatch event it claims to be.
+ *
+ * The normalizer is deliberately lenient (it also folds persisted logs, where a
+ * payload may predate the current declaration). S1-E7 (honesty fix): this
+ * function is an OPT-IN gate — NO production consumer calls it; the shipped
+ * listeners fold tolerant (`'malformed'` synthesis) precisely because a
+ * throwing gate wired into every session event would brick the family on any
+ * upstream payload drift. Deployments that want fail-loud behavior call this
+ * from their own `session/event` listener. It never silently downgrades: an
+ * unrecognized event type or a payload missing a declared field throws a named
+ * \`ToolDispatchPayloadError\`.
+ * @param event - the session event to check.
+ * @returns nothing; throws when the payload violates the platform declaration.
+ */
+export function assertDispatchPayload(event) {
+    const data = (event.data ?? {});
+    if (event.type === NATIVE_CALL_EVENT) {
+        if (typeof data.name !== 'string' || data.name === '' || typeof data.callId !== 'string' || data.callId === '') {
+            throw new ToolDispatchPayloadError('tool/call carries no name/callId: the agent-loop write site is broken');
+        }
+        return;
+    }
+    if (event.type === PTC_DISPATCH_START_EVENT || event.type === PTC_DISPATCH_EVENT) {
+        if (typeof data.subCallId !== 'string' || data.subCallId === '' || typeof data.name !== 'string' || data.name === '') {
+            throw new ToolDispatchPayloadError(`${event.type} carries no name/subCallId: the PTC bridge write site is broken`);
+        }
+        if (event.type === PTC_DISPATCH_EVENT && typeof data.isError !== 'boolean') {
+            throw new ToolDispatchPayloadError('tool/ptc-dispatch carries no boolean isError: the settle outcome is unusable');
+        }
+        return;
+    }
+    if (event.type === NATIVE_RESULT_EVENT)
+        return;
+    throw new ToolDispatchPayloadError(`${event.type} is not a platform dispatch event; compare signal.kind instead of event types`);
+}
+/**
+ * Total dispatches in a log, deduplicated.
+ * @param events - the log, oldest first.
+ * @returns the number of distinct dispatches, one per dispatch regardless of
+ * how many events carried it.
+ */
+export function countDispatches(events) {
+    return foldToolDispatches(events).length;
+}
+//# sourceMappingURL=tool-dispatch.js.map

package/lib/types/tree-write.js

@@ -0,0 +1,40 @@
+/**
+ * G1/1.5 (S7-09): the TYPED critical section around a tree write.
+ *
+ * The control-plane lock used to wrap a whole pass, LLM call and all: an operator undo/restore waited up to
+ * one `curatorReviewTimeoutMs` (~120s) for a review that was merely thinking. The fix is to give the critical
+ * section a shape that a review cannot be squeezed into.
+ *
+ * WHAT THIS TYPE CAN AND CANNOT DO (the plan wording says "cannot be put inside the lock by TYPE" - that is
+ * only half true and the half that is false is the half people rely on): a callback is a CLOSURE, so even
+ * with `view` as its only parameter it can still reach `this.io` / `this.ctx` / `this.llm` from the enclosing
+ * scope. TypeScript cannot stop that, and a criterion claiming it would never go red.
+ *
+ * What the type DOES give: new code has no other entry - the callback is handed a `SnapshotView` and nothing
+ * else, so a phase that needs `io` or `llm` has to stay OUTSIDE and be passed its result in. What the type
+ * CANNOT give is covered by the companion source guard (see the family gates): an `io` / `llm` / `this.`
+ * / `ctx.` reference inside a `withTreeWrite` callback is a violation, and that guard is the executable form
+ * of "cannot be put inside the lock".
+ *
+ * @module @lmzhen/dsh-evolution-core/tree-write
+ */
+/**
+ * Run one tree-writing section under a caller-owned serial queue, exposing ONLY a {@link SnapshotView}.
+ *
+ * The queue is passed in rather than owned here: the lock belongs to whoever serializes the control plane
+ * (the curator), and a second lock would be a second answer to one question.
+ * @param acquire - the caller serial queue (e.g. the curator mutex), returning its release.
+ * @param view - what this section sees while it holds the lock.
+ * @param fn - the section. It may only use the view.
+ * @returns whatever the section returns.
+ */
+export async function withTreeWrite(acquire, view, fn) {
+    const release = await acquire();
+    try {
+        return await fn(view);
+    }
+    finally {
+        release();
+    }
+}
+//# sourceMappingURL=tree-write.js.map