@smthrs/gateway 0.35.0 → 1.0.0-rc.4

package/src/internal/actionRenderings.ts

@@ -0,0 +1,212 @@
+// Generated by scripts/catalog-mvp.ts from Appendix C; do not edit.
+/**
+ * The deterministic Inspect label of each kept action in .specs/product/actions.md
+ * Appendix C, keyed by action id; null marks an action whose Inspect shows no label.
+ *
+ * @since 1.0.0
+ */
+
+/**
+ * @since 1.0.0
+ * @private
+ */
+export const ACTION_RENDERINGS: Readonly<Record<string, string | null>> = {
+  "<boundary:name>": null,
+  "<park>/parked": null,
+  "<quota-park>/<session>": null,
+  "<seal-step>": null,
+  "<structured-output-count>/<name>": null,
+  "agent/capacity/<seat>/cool/<n>": "Waiting for a model",
+  "agent/opening-instructions": "Read the instructions",
+  "agent/opening-memory": "Loaded context",
+  "agent/route-seat": "Chose a model",
+  "agent/run": "Worked a turn",
+  "agent/send (stamp)": null,
+  "agent/trace/checkpoint": null,
+  "apply_patch": "An attributed edit in the File and Diff cards",
+  "ask": "Needs you",
+  "bash": "Terminal card (agent session). Missing: no terminal today",
+  "checks/lint": "Linted the change",
+  "checks/review": "Reviewed the change",
+  "checks/security": "Reviewed security",
+  "checks/wiki": "Checked the wiki",
+  "coding/AdmitVibe": "Opened the change for landing",
+  "coding/ApplyNative": "Applied the changes",
+  "coding/CleanVibeHistory": "Tidied the history",
+  "coding/CommandCheck": "Ran checks",
+  "coding/CoordinateRequest": "Worked the TODO",
+  "coding/CorrectPlan": "Fixed review findings",
+  "coding/CorrectionRound": "Fixed review findings",
+  "coding/DescribeFinalAtom": "Wrote the commit message",
+  "coding/Dispatch": "Ran an agent turn",
+  "coding/FlowLoad": "Validated the flows",
+  "coding/ImplementAtom": "Implemented one step",
+  "coding/ImplementAtoms": "Implemented the plan",
+  "coding/ImplementPlan": "Implemented the plan",
+  "coding/JevCheck": "Checked rules",
+  "coding/LandVibe": "Landed the change",
+  "coding/ObservePlan": "Tracked progress",
+  "coding/Poc": "Drafted a prototype",
+  "coding/PreparePlan": "Planned the change",
+  "coding/PrepareRequest": "Prepared the request",
+  "coding/ProposeFinalHistory": "Reviewed the history",
+  "coding/Prototype": "Drafted a prototype",
+  "coding/PublishVibeSource": "Published the change",
+  "coding/ReadNative": "Read the changes",
+  "coding/RecheckCorrected": "Re-checked the fix",
+  "coding/RecheckFinalHistory": "Re-checked the history",
+  "coding/RefreshWiki": "Refreshed wiki pages",
+  "coding/RepairPass": "Repaired the change",
+  "coding/ReviewCapturedChange": "Reviewed the change",
+  "coding/ReviewCapturedWiki": "Checked the wiki",
+  "coding/ReviewCheck": "Reviewed the change",
+  "coding/RewriteFinalHistory": "Tidied the history",
+  "coding/SecurityAudit": "Audited security",
+  "coding/SecurityReviewCheck": "Reviewed security",
+  "coding/VerifyVibe": "Verified before landing",
+  "coding/Wiki": "Refreshed the wiki",
+  "coding/WikiCheck": "Checked the wiki",
+  "coding/admit-retained-source": "Opened the source",
+  "coding/admit-verify-source": "Opened the candidate",
+  "coding/assess": "Assessed the change",
+  "coding/audit-security": "Audited security",
+  "coding/begin-correction": "Started a fix round",
+  "coding/capture-poc-source": "Captured the source",
+  "coding/capture-review-check": "Captured the change",
+  "coding/capture-wiki-check": "Captured the wiki",
+  "coding/check": "Ran checks",
+  "coding/check-command": "Ran checks",
+  "coding/check-jev-rules": "Checked rules",
+  "coding/configure-planning-wiki": "Chose wiki pages",
+  "coding/confirm-final-description": "Confirmed the commit message",
+  "coding/create-stack-base": "Created the stack base",
+  "coding/create-vibe-landing": "Added to the stack",
+  "coding/decline-request": "Declined the request",
+  "coding/dispatch-turn": "Worked a turn",
+  "coding/draft-plan": "Drafted the plan",
+  "coding/draft-poc": "Drafted a prototype",
+  "coding/edit-atom": "Edited the files",
+  "coding/fast-forward-vibe": "Moved the branch forward",
+  "coding/fast-gate": "Ran quick checks",
+  "coding/fence-vibe-source": "Pinned the change",
+  "coding/finalize-plan": "Finalized the plan",
+  "coding/find-planning-wiki-review": "Found wiki notes",
+  "coding/finish-correction": "Finished the fix round",
+  "coding/finish-final-history": "Finished the history",
+  "coding/finish-review-check": "Collected review findings",
+  "coding/finish-wiki-check": "Checked the wiki",
+  "coding/gather-planning-context": "Gathered context",
+  "coding/implement-change": "Implemented the change",
+  "coding/import-dependency-docs": "Imported dependency docs",
+  "coding/install-dependency-pages": "Added dependency pages",
+  "coding/load-flows": "Validated the flows",
+  "coding/materialize-poc": "Applied the prototype",
+  "coding/merge-request-feedback": "Took in your steer",
+  "coding/merge-vibe-local-pull": "Merged the change",
+  "coding/observe-atom": "Saved the edit",
+  "coding/observe-dispatch": "Saved the turn",
+  "coding/observe-vibe-append": "Added to the stack",
+  "coding/observe-vibe-pull-checks": "Watched PR checks",
+  "coding/open-vibe-local-pull": "Opened the pull request",
+  "coding/open-vibe-pull": "Opened the pull request",
+  "coding/prepare-atom": "Opened the working copy",
+  "coding/prepare-atom-mutation": "Prepared to edit",
+  "coding/prepare-final-description": "Drafted the commit message",
+  "coding/prepare-owner-repair": "Prepared the repair",
+  "coding/prepare-repair-context": "Gathered repair context",
+  "coding/prepare-return-mythical-tip": "Returned to the stack tip",
+  "coding/prepare-stack-base": "Prepared the stack",
+  "coding/prepare-vibe-append": "Prepared to add to the stack",
+  "coding/prepare-vibe-candidate": "Prepared the change",
+  "coding/publish-vibe-source": "Published the change",
+  "coding/queue-vibe-append": "Queued for the stack",
+  "coding/read-correction-history": "Read earlier fixes",
+  "coding/read-feedback-cancellation": "Read your steer",
+  "coding/read-published-wiki": "Read the wiki",
+  "coding/read-vibe-delivery": "Read delivery status",
+  "coding/read-vibe-lander": "Read landing state",
+  "coding/read-vibe-request": "Read the request",
+  "coding/read-vibe-stack": "Read the stack",
+  "coding/receive-request-feedback": "Waited for your steer",
+  "coding/record-fast-gated-progress": "Recorded progress",
+  "coding/record-learning": "Saved a lesson",
+  "coding/record-slow-feedback": "Recorded feedback",
+  "coding/refresh-final-history": "Refreshed the history",
+  "coding/refresh-planning-wiki": "Refreshed wiki pages",
+  "coding/refresh-restacked-evidence": "Refreshed evidence",
+  "coding/refuse-plan-approval": "Refused a plan approval",
+  "coding/repair-final-history": "Corrected the history",
+  "coding/retain-poc": "Saved the prototype",
+  "coding/review-final-history": "Reviewed the history",
+  "coding/review-lens": "Reviewed through one lens",
+  "coding/review-poc": "Reviewed the prototype",
+  "coding/review-request": "Reviewed the request",
+  "coding/review-security": "Reviewed security",
+  "coding/run-correction-round": "Fixed review findings",
+  "coding/select-owner-repair": "Chose what to fix",
+  "coding/submit-vibe-lane": "Queued the change",
+  "coding/todo-boundary": null,
+  "coding/todo-delivery": "Prepared the delivery",
+  "coding/todo-pause-requested": null,
+  "coding/todo-resume": null,
+  "coding/todo-review": null,
+  "coding/todo-review-input": null,
+  "coding/validate-final-history": "Checked the history",
+  "coding/validate-plan": "Checked the plan",
+  "coding/verify-planning-context": "Checked the context",
+  "coding/verify-vibe-landed": "Confirmed it landed",
+  "create-flow": "Created a flow",
+  "create-flow/clarify": "Asked what the flow should do",
+  "create-flow/design": "Designed the flow",
+  "create-flow/document": "Documented the flow",
+  "create-flow/fix": "Fixed the flow",
+  "create-flow/provision": "Set up the flow",
+  "create-flow/scaffold": "Wrote the flow",
+  "edit": "An attributed edit in the File and Diff cards",
+  "factory/Todo": "Routed the TODO",
+  "factory/route-todo": "Chose how to start",
+  "factory/stamp-route": "Declined the TODO",
+  "glob": "A \"read\" line in branch activity, opening the File card",
+  "grep": "A \"read\" line in branch activity, opening the File card",
+  "jev": "Inspect only: \"Decided <question>\"",
+  "ls": "A \"read\" line in branch activity, opening the File card",
+  "memory": "The \"Context\" line and the preflight cell in Inspect",
+  "memory/mine": "Saved lessons",
+  "memory/mine/run": "Saved lessons",
+  "read": "A \"read\" line in branch activity, opening the File card",
+  "recall": "The \"Context\" line and the preflight cell in Inspect",
+  "recall (namespaced)": "The \"Context\" line and the preflight cell in Inspect",
+  "remember": "Learning receipt",
+  "review": "Reviewed the change",
+  "smithers-review/ApplyVerdicts": "Settled findings",
+  "smithers-review/FinalizeReview": "Finished the review",
+  "smithers-review/MergeFileBatch": "Collected findings",
+  "smithers-review/NarrateChanges": "Wrote the walkthrough",
+  "smithers-review/NarrateReview": "Wrote the walkthrough",
+  "smithers-review/PrepareReview": "Prepared the review",
+  "smithers-review/RenderWalkthrough": "Rendered the walkthrough",
+  "smithers-review/ReviewFile": "Reviewed one file",
+  "smithers-review/ReviewFiles": "Reviewed the files",
+  "smithers-review/VerifyFindings": "Verified findings",
+  "smithers-review/VerifyReview": "Verified findings",
+  "smithers/IncrementalWiki": "Refreshed the wiki",
+  "smithers/Wiki": "Refreshed the wiki",
+  "stack.candidate": "Saved the candidate",
+  "stack.propose": "Proposed the candidate",
+  "system/human-task": "Waited for your answer",
+  "system/sleep": null,
+  "system/wait-for": null,
+  "test": "Terminal card plus checks. Missing: needs SMITHERS_TEST_COMMAND",
+  "wait": "Waited",
+  "wiki/assess-review": "Assessed a wiki page",
+  "wiki/bind-review-provenance": "Linked a review to its source",
+  "wiki/check-citations": "Checked citations",
+  "wiki/collect-page": "Collected sources for a page",
+  "wiki/load-recorded-reviews": "Found earlier reviews",
+  "wiki/publish-recorded-reviews": "Saved wiki pages",
+  "wiki/review-page": "Reviewed a wiki page",
+  "wiki/select-recorded-review": "Reused a review",
+  "wiki/validate-review": "Checked a wiki page",
+  "wiki/write-snapshot": "Saved wiki pages",
+  "write": "An attributed edit in the File and Diff cards"
+}

package/src/internal/callEvents.ts

@@ -0,0 +1,257 @@
+/**
+ * Shared call lifecycle identity rules for full and incremental projections.
+ *
+ * @since 1.0.0
+ */
+
+import { CallFact, StepFact } from "@smthrs/journal"
+import * as Schema from "effect/Schema"
+
+/** A sparse historical observation is readable without inventing missing fields.
+ * @category models
+ * @since 1.0.0
+ */
+export interface CallObservation {
+  readonly kind?: string | undefined
+  readonly runId?: string | undefined
+  readonly sequence?: number | undefined
+  readonly payload?: unknown
+}
+
+/** Interpret only the native producer's versioned, run-scoped outbox facts.
+ * @category projections
+ * @since 1.0.0
+ */
+export const nativeCallEvent = <Event extends CallObservation>(event: Event): Event | undefined => {
+  if (event.kind !== "control.engine.event" || typeof event.payload !== "object" || event.payload === null) {
+    return undefined
+  }
+  const envelope = event.payload as Record<string, unknown>
+  if (
+    envelope.version !== 1 || envelope.eventType !== CallFact.eventType || typeof envelope.executionId !== "string" ||
+    typeof envelope.generation !== "number" || !Number.isSafeInteger(envelope.generation) || envelope.generation < 0 ||
+    typeof envelope.sequence !== "number" || !Number.isSafeInteger(envelope.sequence) || envelope.sequence < 0 ||
+    typeof envelope.emittedAtMs !== "number" || !Number.isFinite(envelope.emittedAtMs) || envelope.emittedAtMs < 0 ||
+    envelope.sourceSequence !== 0
+  ) return undefined
+  const fact = Schema.decodeUnknownOption(CallFact.Fact)(envelope.payload)
+  if (
+    fact._tag === "None" || fact.value.identity.runId !== event.runId ||
+    envelope.sourceId !== `call-fact-v1:${fact.value.callId}:${fact.value.phase}`
+  ) return undefined
+  return {
+    ...event,
+    kind: fact.value.phase === "invoked" ? "control.agent.cell-call-started" : "control.agent.cell-call-settled",
+    payload: JSON.parse(JSON.stringify({ ...fact.value, callFactVersion: 1, at: envelope.emittedAtMs }))
+  }
+}
+
+/** Normalize a checkpoint only within its recorded execution and source.
+ * Replayed prefixes retain the generation that first recorded the work.
+ * @category projections
+ * @since 1.0.0
+ */
+export const nativeStepEvent = <Event extends CallObservation>(event: Event): Event | undefined => {
+  if (event.kind !== "control.engine.event" || typeof event.payload !== "object" || event.payload === null) {
+    return undefined
+  }
+  const envelope = event.payload as Record<string, unknown>
+  if (
+    envelope.version !== 1 || envelope.eventType !== StepFact.eventType ||
+    typeof envelope.generation !== "number" || !Number.isSafeInteger(envelope.generation) || envelope.generation < 0 ||
+    typeof envelope.sequence !== "number" || !Number.isSafeInteger(envelope.sequence) || envelope.sequence < 0 ||
+    typeof envelope.emittedAtMs !== "number" || !Number.isFinite(envelope.emittedAtMs) || envelope.emittedAtMs < 0
+  ) return undefined
+  const decoded = Schema.decodeUnknownOption(StepFact.Fact)(envelope.payload)
+  if (decoded._tag === "None") return undefined
+  const fact = decoded.value
+  const step = fact.step
+  if (
+    envelope.executionId !== step.executionId || envelope.sourceSequence !== fact.sourceSequence ||
+    envelope.sourceId !== `step-fact-v1:${step.stepId}:${step.attempt}:${step.ask}:${step.retry}` ||
+    fact.generation > envelope.generation || !Number.isFinite(fact.at) ||
+    typeof fact.payload !== "object" || fact.payload === null || Array.isArray(fact.payload)
+  ) return undefined
+  return {
+    ...event,
+    kind: fact.eventType,
+    payload: {
+      ...fact.payload,
+      step: { ...step, generation: fact.generation, frame: fact.frame, ordinal: fact.ordinal },
+      at: fact.at
+    }
+  }
+}
+
+/** Scope call matching to the recorded invocation, including its generation.
+ * @category projections
+ * @since 1.0.0
+ */
+export const callScope = (event: CallObservation): string | undefined => {
+  const payload = event.payload
+  if (typeof payload !== "object" || payload === null || !("step" in payload)) return undefined
+  const step = payload.step
+  if (typeof step !== "object" || step === null || Array.isArray(step)) return undefined
+  const scope = step as Record<string, unknown>
+  return JSON.stringify([
+    scope.executionId,
+    scope.stepId,
+    scope.attempt,
+    scope.ask,
+    scope.retry,
+    scope.scope,
+    scope.generation
+  ])
+}
+
+/**
+ * Identity first; the upgrade fallback can consume only unidentified starts.
+ *
+ * @category projections
+ * @since 1.0.0
+ */
+export const openCallIndex = (
+  open: ReadonlyArray<
+    { readonly flowName: string; readonly callId?: string | undefined; readonly scope?: string | undefined }
+  >,
+  callId: string | undefined,
+  flowName: string | undefined,
+  scope?: string
+): number => {
+  const identified = callId === undefined
+    ? -1
+    : open.findIndex((call) => call.callId === callId && call.scope === scope)
+  if (identified >= 0) return identified
+  return open.findIndex((call) =>
+    call.scope === scope && call.callId === undefined && (flowName === undefined || call.flowName === flowName)
+  )
+}
+
+/**
+ * Deduplicate identified call lifecycles and committed checkpoint observations.
+ *
+ * @category projections
+ * @since 1.0.0
+ */
+export const callEventKey = (event: CallObservation): string | undefined => {
+  const stepEvent = nativeStepEvent(event)
+  const original = event
+  event = stepEvent ?? nativeCallEvent(event) ?? event
+  const payload = event.payload
+  if (
+    (event.kind === "control.agent.cell-call-started" || event.kind === "control.agent.cell-call-settled") &&
+    typeof payload === "object" && payload !== null && "callId" in payload && typeof payload.callId === "string"
+  ) {
+    return JSON.stringify([event.kind, payload.callId, callScope(event)])
+  }
+  // An older checkpoint may not have a call ID. Its durable source identity
+  // still deduplicates replay, including after the event body is evicted.
+  if (stepEvent === undefined) return undefined
+  const envelope = original.payload as Record<string, unknown>
+  return JSON.stringify(["step-fact", original.runId, callScope(stepEvent), envelope.sourceSequence])
+}
+
+/**
+ * Native facts supersede identified telemetry while retaining its display
+ * position. Unidentified history cannot acquire an invented identity.
+ *
+ * @category projections
+ * @since 1.0.0
+ */
+export const uniqueCallEvents = <Event extends CallObservation>(
+  events: ReadonlyArray<Event>
+): ReadonlyArray<Event> => {
+  const native = new Map<string, Event>()
+  const normalized = events.map((event) => {
+    const fact = nativeStepEvent(event) ?? nativeCallEvent(event)
+    if (fact === undefined) return event
+    const key = callEventKey(event)
+    if (key !== undefined && !native.has(key)) native.set(key, fact)
+    return fact
+  })
+  const seen = new Set<string>()
+  const stepSeen = new Set<string>()
+  return normalized.flatMap((event, index) => {
+    const original = events[index]!
+    if (nativeStepEvent(original) !== undefined) {
+      const envelope = original.payload as Record<string, unknown>
+      const fact = envelope.payload as Record<string, unknown>
+      const identity = JSON.stringify([original.runId, callScope(event), envelope.sourceSequence, fact.generation])
+      if (stepSeen.has(identity)) return []
+      stepSeen.add(identity)
+    }
+    const key = callEventKey(original)
+    if (key === undefined) return [event]
+    if (seen.has(key)) return []
+    seen.add(key)
+    const preferred = native.get(key)
+    return [preferred === undefined ? event : { ...preferred, sequence: event.sequence }]
+  })
+}
+
+/**
+ * What {@link CallEventFilter} did with one event.
+ *
+ * `rewrite` means the event superseded one the filter already kept: the batch
+ * rule replaces the earlier event in place, so a reader holding the earlier
+ * output must refold from the whole journal.
+ *
+ * @category projections
+ * @since 1.0.0
+ */
+export type CallEventVerdict<Event> =
+  | { readonly _tag: "keep"; readonly event: Event }
+  | { readonly _tag: "drop" }
+  | { readonly _tag: "rewrite" }
+
+/**
+ * {@link uniqueCallEvents} one event at a time, for a journal read in order.
+ *
+ * The sets are exactly the ones the batch builds, so a filter fed a whole
+ * journal holds the state the batch ended with. Only one case cannot be
+ * answered in order: a native fact whose key an earlier telemetry event
+ * already claimed. That verdict is `rewrite`.
+ *
+ * @category projections
+ * @since 1.0.0
+ */
+export interface CallEventFilter<Event extends CallObservation> {
+  readonly push: (event: Event) => CallEventVerdict<Event>
+}
+
+/**
+ * Builds an empty {@link CallEventFilter}.
+ *
+ * @category projections
+ * @since 1.0.0
+ */
+export const callEventFilter = <Event extends CallObservation>(): CallEventFilter<Event> => {
+  const native = new Map<string, Event>()
+  const seen = new Set<string>()
+  const stepSeen = new Set<string>()
+  return {
+    push: (original) => {
+      const step = nativeStepEvent(original)
+      const fact = step ?? nativeCallEvent(original)
+      const event = fact ?? original
+      const key = callEventKey(original)
+      if (fact !== undefined && key !== undefined && !native.has(key)) {
+        native.set(key, fact)
+        // The batch hands this fact to the event that first claimed the key.
+        if (seen.has(key)) return { _tag: "rewrite" }
+      }
+      if (step !== undefined) {
+        const envelope = original.payload as Record<string, unknown>
+        const payload = envelope.payload as Record<string, unknown>
+        const identity = JSON.stringify([original.runId, callScope(event), envelope.sourceSequence, payload.generation])
+        if (stepSeen.has(identity)) return { _tag: "drop" }
+        stepSeen.add(identity)
+      }
+      if (key === undefined) return { _tag: "keep", event }
+      if (seen.has(key)) return { _tag: "drop" }
+      seen.add(key)
+      const preferred = native.get(key)
+      return { _tag: "keep", event: preferred === undefined ? event : { ...preferred, sequence: event.sequence } }
+    }
+  }
+}

package/src/internal/digestIndex.ts

@@ -0,0 +1,134 @@
+/** Persistent scalar indexes for carried diagnosis corrections.
+ * @since 1.0.0
+ */
+
+import { encodedBytes } from "./digestMemory.ts"
+
+/** An ordinal and its optional timestamps, with cached subtree extrema.
+ * @category models
+ * @since 1.0.0
+ */
+export interface Index {
+  readonly ordinal: number
+  readonly start: number | undefined
+  readonly end: number | undefined
+  readonly left: Index | undefined
+  readonly right: Index | undefined
+  readonly height: number
+  readonly size: number
+  readonly first: number
+  readonly min: number | undefined
+  readonly max: number | undefined
+  readonly bytes: number
+}
+
+const height = (tree: Index | undefined): number => tree?.height ?? 0
+const min = (a: number | undefined, b: number | undefined): number | undefined =>
+  a === undefined ? b : b === undefined ? a : Math.min(a, b)
+const max = (a: number | undefined, b: number | undefined): number | undefined =>
+  a === undefined ? b : b === undefined ? a : Math.max(a, b)
+const node = (
+  ordinal: number,
+  start: number | undefined,
+  end: number | undefined,
+  left: Index | undefined,
+  right: Index | undefined
+): Index => {
+  const subtreeHeight = 1 + Math.max(height(left), height(right))
+  const size = 1 + (left?.size ?? 0) + (right?.size ?? 0)
+  const first = left?.first ?? ordinal
+  const earliest = min(start, min(left?.min, right?.min))
+  const latest = max(end, max(left?.max, right?.max))
+  return {
+    ordinal,
+    start,
+    end,
+    left,
+    right,
+    height: subtreeHeight,
+    size,
+    first,
+    min: earliest,
+    max: latest,
+    bytes: (left?.bytes ?? 0) + (right?.bytes ?? 0) +
+      encodedBytes([ordinal, start, end, left?.ordinal, right?.ordinal, subtreeHeight, size, first, earliest, latest])
+  }
+}
+
+const rotateLeft = (tree: Index): Index => {
+  const right = tree.right!
+  return node(
+    right.ordinal,
+    right.start,
+    right.end,
+    node(tree.ordinal, tree.start, tree.end, tree.left, right.left),
+    right.right
+  )
+}
+const rotateRight = (tree: Index): Index => {
+  const left = tree.left!
+  return node(
+    left.ordinal,
+    left.start,
+    left.end,
+    left.left,
+    node(tree.ordinal, tree.start, tree.end, left.right, tree.right)
+  )
+}
+const balanced = (tree: Index): Index => {
+  if (height(tree.left) > height(tree.right) + 1) {
+    const left = tree.left!
+    return rotateRight(
+      height(left.left) < height(left.right)
+        ? node(tree.ordinal, tree.start, tree.end, rotateLeft(left), tree.right)
+        : tree
+    )
+  }
+  if (height(tree.right) > height(tree.left) + 1) {
+    const right = tree.right!
+    return rotateLeft(
+      height(right.right) < height(right.left)
+        ? node(tree.ordinal, tree.start, tree.end, tree.left, rotateRight(right))
+        : tree
+    )
+  }
+  return tree
+}
+
+/** Inserts or replaces scalar evidence without changing an earlier index.
+ * @category constructors
+ * @since 1.0.0
+ */
+export const set = (
+  tree: Index | undefined,
+  ordinal: number,
+  start?: number,
+  end?: number
+): Index => {
+  if (tree === undefined) return node(ordinal, start, end, undefined, undefined)
+  if (ordinal === tree.ordinal) return node(ordinal, start, end, tree.left, tree.right)
+  return balanced(
+    ordinal < tree.ordinal
+      ? node(tree.ordinal, tree.start, tree.end, set(tree.left, ordinal, start, end), tree.right)
+      : node(tree.ordinal, tree.start, tree.end, tree.left, set(tree.right, ordinal, start, end))
+  )
+}
+
+/** Removes one ordinal, keeping earlier index versions valid.
+ * @category constructors
+ * @since 1.0.0
+ */
+export const remove = (tree: Index | undefined, ordinal: number): Index | undefined => {
+  if (tree === undefined) return undefined
+  if (ordinal < tree.ordinal) {
+    return balanced(node(tree.ordinal, tree.start, tree.end, remove(tree.left, ordinal), tree.right))
+  }
+  if (ordinal > tree.ordinal) {
+    return balanced(node(tree.ordinal, tree.start, tree.end, tree.left, remove(tree.right, ordinal)))
+  }
+  if (tree.left === undefined) return tree.right
+  if (tree.right === undefined) return tree.left
+  let next = tree.right
+  while (next.left !== undefined) next = next.left
+  return balanced(node(next.ordinal, next.start, next.end, tree.left, remove(tree.right, next.ordinal)))
+}

package/src/internal/digestMemory.ts

@@ -0,0 +1,27 @@
+/** Encoded retained-data accounting for private diagnosis state.
+ * @since 1.0.0
+ */
+
+const sizes = new WeakMap<object, number>()
+const encoder = new TextEncoder()
+
+/** Measures retained JSON-shaped data without keeping another copy.
+ * @category utilities
+ * @since 1.0.0
+ */
+export const encodedBytes = (value: unknown): number => encoder.encode(JSON.stringify(value)).byteLength
+
+/** Associates a digest with its compact identity ledger's byte budget.
+ * @category utilities
+ * @since 1.0.0
+ */
+export const recordDigestBytes = (digest: object, bytes: number): void => {
+  sizes.set(digest, bytes)
+}
+
+/** Includes private scalar contributions in the projection retention budget.
+ * @category utilities
+ * @since 1.0.0
+ */
+export const retainedDigestBytes = (digest: object | undefined): number =>
+  digest === undefined ? 0 : sizes.get(digest) ?? encodedBytes(digest)

package/src/internal/inspectLabels.ts

@@ -0,0 +1,18 @@
+/**
+ * Inspect labels for recorded actions, read from the generated Appendix C table.
+ *
+ * @since 1.0.0
+ */
+
+import { ACTION_RENDERINGS } from "./actionRenderings.ts"
+
+/**
+ * The recorded action's Appendix C label, with unknown historical tags retained.
+ * Dynamic cell-call wrappers name the tool they recorded, never a new action.
+ * @category utilities
+ * @since 1.0.0
+ */
+export const inspectLabel = (tag: string): string => {
+  const tool = /^<cell-call:(.+)>$/.exec(tag)?.[1] ?? tag
+  return ACTION_RENDERINGS[tool] ?? tool
+}