@melite/estate-drafts 0.1.4-alpha → 0.1.5-pre-alpha

package/README.md

@@ -0,0 +1,56 @@
+---
+description: The drafts and bench Typert remote owner — draft docs in a storage domain plus the shared bench mutation surface, mounted as host Cordis services.
+kind: package-library
+---
+
+# @melite/estate-drafts
+
+`@melite/estate-drafts` owns the composer's draft docs and the shared bench.
+It mounts the drafts storage-domain seat, `DraftsRemoteService`, and
+`BenchRemoteService` on the host fiber; the host's typert gateway claims the
+endpoints through its discovery walk, and the storage facility arrives via
+the host's storageDomain seat (lazy open on first call). The estate bundle
+mounts it before the runs registry, whose submit gate re-uses this package's
+draft-id law.
+
+## Contract
+
+- Storage: table `docs` keyed by draft id (`DRAFT_ID_RE`: 1..96 chars of
+  `[A-Za-z0-9_-]`, path-safe — the SSOT the queue re-exports).
+  Schema-failing records are backed up and skipped; the global slot holds
+  the one-time legacy-import marker.
+- Draft docs: six contract keys (`draft_id`, `status`, `createdAt`,
+  `completedAt`, `intent`, `stages`) plus caller extras verbatim — the serve
+  read is deliberately loose; the write doors are strict.
+- Bench: `ensure`, `get`, `patch`, `add-stage`, `remove-stage`, `reorder`,
+  `group`, `rewire`, `undo`, `clear`, keyed by the caller's session key,
+  with change notification through the bench change seam.
+- Failures are the protocol's ONE RemoteError with `draft/*` and `bench/*`
+  codes declared next to their throws.
+- Declared exports: `.` (plugin + services), `./types` (shared row types),
+  `./typert` (generated host-face declaration), `./remote` (generated
+  browser client), `./package.json`.
+
+## Model Experience
+
+### Request context and condition
+
+#### What the model sees
+
+None — the package contributes no model-visible input.
+
+#### Token effect
+
+Zero-direct token effect.
+
+#### KV Cache effect
+
+Independent — no conversation state.
+
+## Known Limitations and Deferred Work
+
+- **Bench access is session-key scoped** — a caller outside the editor's
+  session model must carry the session key itself; there is no cross-session
+  bench view.
+- **The loose serve read is deliberate** — extras ride back unvalidated; a
+  writer bug can land extras the read will not catch.

package/lib/bench.d.ts

@@ -48,6 +48,15 @@ declare module "@deepseek-ai/dsh-typert-protocol" {
             readonly session: string;
             readonly stage: string;
         };
+        /** The anchored reorder's target is gone (the F1-residue cure,
+         *  round 25): the id the drop named as its anchor is not on the
+         *  CURRENT list — a second author removed it between the press
+         *  and the apply. The honest re-ask, never a silent fallback to
+         *  the stale numeric slot. */
+        "bench/anchor-gone": {
+            readonly session: string;
+            readonly anchor: string;
+        };
         
 
 
@@ -188,7 +197,7 @@ export interface BenchPatchRow {
 
 
 
-export declare function patchBench(drafts: Domain<DraftsDomainSpec>, session: string, body: Record<string, unknown>, admit?: StageAdmission): Promise<BenchPatchRow>;
+export declare function patchBench(drafts: Domain<DraftsDomainSpec>, session: string, body: Record<string, unknown>, admit?: StageAdmission, migrate?: LaneMigration): Promise<BenchPatchRow>;
 /** The stage row: the arm's answer (stage id + rev). */
 export interface BenchStageRow {
     readonly draft_id: string;
@@ -217,12 +226,37 @@ export type StageAdmission = (card: string, params: Record<string, unknown>, pro
 
 
 
+
+
+export type LaneMigration = (card: string, params: Record<string, unknown>, priorParams: Record<string, unknown>) => Record<string, unknown>;
+
+
+
+
+
 export declare function strippedForAdmission(card: string, params: Record<string, unknown>): Record<string, unknown>;
 /** The wiring admission over ONE row (params = the MERGED view the
  *  next run composes; inputs = the MERGED wiring; liveIds = the
  *  bench's stage ids after the write; selfId = the row's own id —
  *  self-wiring is a cycle, refused). Throws bench/* named. */
 export declare function admitWiring(row: Record<string, unknown>, params: Record<string, unknown>, inputs: Record<string, unknown>, liveIds: readonly string[], selfId: string, session: string, tolerate?: ReadonlySet<string>): void;
+/** The un-wedge law's tolerance table: for every row in the list
+ *  being JUDGED, the upstreams it wires that are absent from the
+ *  PRE-verb live set — refs the verb did not create (they were
+ *  already dead, or ride a restored snapshot the log itself
+ *  recorded) and must not be refused for. Keyed by row/child id.
+ *
+ *  The walk is over the JUDGED rows (not the pre rows): a verb
+ *  like clear leaves no pre rows at all, and undo restores rows
+ *  the pre state doesn't hold — the ref a row CARRIES is the
+ *  thing to classify, against what was live before the verb. A
+ *  ref newly introduced by a verb (rewire's `from`, a patch's
+ *  spell changes) never rides this table: those seats build their
+ *  tolerate sets from the PRE ROW's own inputs, so a fresh dead
+ *  target stays strict. */
+/** Exported for the drafts seat (audit S-S1): the un-wedge table is
+ *  the same law at every author seat. */
+export declare function toleratedByRow(stages: Array<Record<string, unknown>>, preLive: ReadonlySet<string>): Map<string, Set<string>>;
 /** add_stage — append a card stage with optional wiring (the
  *  runner's input convention rides the row). */
 export declare function addStageBench(drafts: Domain<DraftsDomainSpec>, session: string, body: Record<string, unknown>, admit?: StageAdmission): Promise<BenchStageRow>;
@@ -233,6 +267,12 @@ export declare function addStageBench(drafts: Domain<DraftsDomainSpec>, session:
 
 
 
+
+
+
+
+
+
 export declare function reorderBench(drafts: Domain<DraftsDomainSpec>, session: string, body: Record<string, unknown>): Promise<BenchReorderRow>;
 /** The reorder row: the move's coordinates for the caller's optimistic
  *  update (from → to, both POST-splice-clamp). */
@@ -309,6 +349,13 @@ export interface BenchChangeSeam {
 /** Install the seam (the plugin does this with its Context; tests do
  *  it with their own). Pass null to detach. */
 export declare function setBenchChangeSeam(seam: BenchChangeSeam | null): void;
+/** Detach the seam ONLY if `seam` is still the installed one — the
+ *  ownership stamp that keeps dispose honest: a fiber that installed
+ *  EARLIER (a newer install displaced it) detaches nothing, so the
+ *  live seam survives the older fiber's unwind.
+ * @param seam - the seam instance the caller installed.
+ */
+export declare function clearBenchChangeSeam(seam: BenchChangeSeam): void;
 
 
 

package/lib/bench.js

@@ -15,6 +15,7 @@
 import { unwrapItemArrays } from '@melite/comfyui-card-kit';
 import { benchDraftIdOf, BIRTH_STRIP_KEYS, LOAD_CARRY_KEYS, normalizeBenchStage, SELF_NAMED_FAMILIES, stripKeys } from '@melite/contracts/benchStage';
 import { RemoteError } from "@deepseek-ai/dsh-typert-protocol";
+import { trailDedupe } from "./trail.js";
 
 
 
@@ -438,7 +439,14 @@ export async function ensureBench(drafts, body, admit) {
             continue;
         for (const key of MEMORY_KEYS) {
             if (prev[key] !== undefined && row[key] === undefined) {
-                row[key] = prev[key];
+                // THE TRAIL HEAL AT CARRY (trail-defect-hunt §6): a memory
+                // carry of history passes through the one-row-per-run dedup —
+                // a pre-law duplicated trail (the operator's re-add wound,
+                // one run under two url spellings) never fossilises forward
+                // through load.
+                row[key] = key === "history" && Array.isArray(prev[key])
+                    ? trailDedupe(prev[key])
+                    : prev[key];
             }
         }
     }
@@ -635,7 +643,7 @@ const PATCH_KEYS = ["stage", "params", "result", "runStatus", "expect_rev", "aut
 
 
 
-export async function patchBench(drafts, session, body, admit) {
+export async function patchBench(drafts, session, body, admit, migrate) {
     refuseUnknown(body, PATCH_KEYS);
     if ("result" in body || "runStatus" in body) {
         throw new RemoteError("bench/bad-body", "run outcomes ride the drafts/patch door (result/runStatus refused on the bench verb — it authors params only)", {});
@@ -704,7 +712,25 @@ export async function patchBench(drafts, session, body, admit) {
         // row (a group, an undo) judged a different object than the one
         // on disk. The merge strips before judging AND before storing:
         // one row, one view.
-        const stored = strippedForAdmission(typeof st["card"] === "string" ? st["card"] : "", cur);
+        
+        // incident — live on :3088): the merge above is where a lane
+        // switch assembles its view, and BEFORE this seat the switch
+        // REFUSED itself — the prior lane's members (voice on
+        // CustomVoice) ride the merged view, the new lane's surface
+        // (VoiceDesign) does not take them, and the admission refused
+        // "drop it or switch lane" while the form HIDES the row on the
+        // new lane: the named cure unclickable, the switch unlandable,
+        // the studio wedged between "the studio shows your edit; the
+        // bench does not". The registry drops the stale carry here —
+        // BEFORE the strip, the admission, and the store, so the row
+        // that lands is the row the next run composes (one view, every
+        // seat). The undo contract: undoing the switch restores the
+        // axes, not the dropped members — the author re-picks on the
+        // lane they return to.
+        const migrated = migrate !== undefined && isRecord(st["params"])
+            ? migrate(typeof st["card"] === "string" ? st["card"] : "", cur, st["params"])
+            : cur;
+        const stored = strippedForAdmission(typeof st["card"] === "string" ? st["card"] : "", migrated);
         // THE COMPOUND IS JUDGED BY ITS MEMBERS HERE TOO (the walls
         
         // belongs to a compound judged the COMPOUND ROW as a whole, and
@@ -969,7 +995,9 @@ function liveIdsOf(stages) {
  *  spell changes) never rides this table: those seats build their
  *  tolerate sets from the PRE ROW's own inputs, so a fresh dead
  *  target stays strict. */
-function toleratedByRow(stages, preLive) {
+/** Exported for the drafts seat (audit S-S1): the un-wedge table is
+ *  the same law at every author seat. */
+export function toleratedByRow(stages, preLive) {
     const out = new Map();
     const rowOf = (r, id) => {
         const inputs = r["inputs"];
@@ -1159,7 +1187,13 @@ export async function addStageBench(drafts, session, body, admit) {
     return { draft_id: loaded.draftId, session, rev: newRev, stage: stageId };
 }
 const REMOVE_KEYS = ["stage", "expect_rev", "author"];
-const REORDER_KEYS = ["stage", "to", "expect_rev", "author"];
+const REORDER_KEYS = ["stage", "to", "expect_rev", "author", "after"];
+
+
+
+
+
+
 
 
 
@@ -1179,6 +1213,10 @@ export async function reorderBench(drafts, session, body) {
     if (typeof toRaw !== "number" || !Number.isInteger(toRaw) || toRaw < 0) {
         throw new RemoteError("bench/bad-body", "to must be a non-negative integer index", {});
     }
+    const afterRaw = body["after"];
+    if (afterRaw !== undefined && typeof afterRaw !== "string") {
+        throw new RemoteError("bench/bad-body", "after must be a stage id string when present", {});
+    }
     const author = authorOk(body["author"])
         ? body["author"]
         : "agent";
@@ -1187,8 +1225,20 @@ export async function reorderBench(drafts, session, body) {
     if (from < 0) {
         throw new RemoteError("bench/stage-not-found", "stage not found: " + stageId, { session, stage: stageId });
     }
+    // anchor resolution: re-derive the target from the id the press
+    // SAW, not the numeric slot it guessed. Unchanged list → the same
+    // `to` the press sent (identity, never a behavior change); a
+    // shifted list → the drop's intent survives the shift.
+    let toTarget = toRaw;
+    if (afterRaw !== undefined) {
+        const anchor = stages.findIndex((s) => s["id"] === afterRaw);
+        if (anchor < 0) {
+            throw new RemoteError("bench/anchor-gone", "the card you dropped after is gone — drop again", { session, anchor: afterRaw });
+        }
+        toTarget = anchor;
+    }
     const [row] = stages.splice(from, 1);
-    const to = Math.min(toRaw, stages.length);
+    const to = Math.min(toTarget, stages.length);
     stages.splice(to, 0, row);
     loaded.doc["stages"] = stages;
     const newRev = await appendAndSave(drafts, loaded, {
@@ -1196,7 +1246,7 @@ export async function reorderBench(drafts, session, body) {
         kind: "reorder",
         stage: stageId,
         summary: "reorder " + String(row["card"] ?? stageId),
-        inverse: { stage: stageId, from, to },
+        inverse: { stage: stageId, from, to, ...(afterRaw !== undefined ? { after: afterRaw } : {}) },
     });
     return { draft_id: loaded.draftId, session, rev: newRev, stage: stageId, from, to };
 }
@@ -1523,9 +1573,13 @@ const UNDO_KEYS = ["n", "author", "expect_rev"];
 export async function undoBench(drafts, session, body, admit) {
     refuseUnknown(body, UNDO_KEYS);
     const loaded = await loadBench(drafts, session);
-    if (body["expect_rev"] !== undefined) {
-        casCheck(loaded.block, body["expect_rev"], session);
-    }
+    // THE FENCE IS NOT OPTIONAL (audit W-E2): undo reverts writes —
+    // exactly the mutations the CAS law fences. It was the only verb
+    // that skipped the check when expect_rev was absent, so an
+    // un-read revert raced any concurrent writer and silently
+    // double-applied. Same voice as every verb: absent expect_rev
+    // refuses bench/cas-conflict with current_rev.
+    casCheck(loaded.block, body["expect_rev"], session);
     const n = typeof body["n"] === "number" &&
         Number.isInteger(body["n"]) &&
         body["n"] > 0
@@ -1600,6 +1654,13 @@ export async function undoBench(drafts, session, body, admit) {
             }
         }
         const baseIds = liveIdsOf(baseRows);
+        // THE TRAIL HEAL AT UNDO (trail-defect-hunt §6): a reinserted
+        // pre-law row's duplicated history never rides back in — same
+        // dedup the load carry applies.
+        for (const r of stagesOf(undoDoc)) {
+            if (Array.isArray(r["history"]))
+                r["history"] = trailDedupe(r["history"]);
+        }
         const restored = stagesOf(undoDoc);
         admitWiringList(restored, session, toleratedByRow(restored.filter((r) => baseIds.has(String(r["id"] ?? ""))), baseIds));
     })();
@@ -1828,6 +1889,16 @@ let benchChangeSeam = null;
 export function setBenchChangeSeam(seam) {
     benchChangeSeam = seam;
 }
+/** Detach the seam ONLY if `seam` is still the installed one — the
+ *  ownership stamp that keeps dispose honest: a fiber that installed
+ *  EARLIER (a newer install displaced it) detaches nothing, so the
+ *  live seam survives the older fiber's unwind.
+ * @param seam - the seam instance the caller installed.
+ */
+export function clearBenchChangeSeam(seam) {
+    if (benchChangeSeam === seam)
+        benchChangeSeam = null;
+}
 
 
 
@@ -1844,8 +1915,12 @@ export function onBenchChange(fn) {
         try {
             fn(session);
         }
-        catch {
-            /* a listener's fault never breaks the write */
+        catch (listenerError) {
+            // listenerError: the contract keeps a subscriber's fault from
+            // breaking the write, but the fault is not silence — the row
+            // names it like the runs seam's own wrap does
+            console.warn("[estate-drafts] bench change listener refused for session " +
+                JSON.stringify(session) + ":", listenerError);
         }
     });
 }

package/lib/index.d.ts

@@ -1,12 +1,15 @@
 import type { Context, Plugin } from "@deepseek-ai/cordis";
+import type { DraftsConfig } from "./store.js";
 export { BenchRemoteService, DraftsRemoteService, installBenchChangeSeam } from "./remote.js";
 export { resolveStorageRoot, openDraftsDomain, } from "./store.js";
+export type { DraftsConfig } from "./store.js";
 export { DRAFT_ID_RE, draftIdOk } from "./spec.js";
+export type { CharacterRecord } from "./spec.js";
 export type { BenchChangeSeam } from "./bench.js";
 export { setBenchChangeSeam } from "./bench.js";
 export type { BenchEnsureRow, BenchGetRow, DraftListResult, DraftListRow, } from "./remote.js";
 export declare const name = "estate-drafts";
-export declare function apply(ctx: Context): void;
+export declare function apply(ctx: Context, config?: DraftsConfig): void;
 declare const plugin: Plugin;
 export default plugin;
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -1,10 +1,14 @@
 import { BenchRemoteService, DraftsRemoteService } from "./remote.js";
+import { DraftsDomainSeatService } from "./store.js";
 export { BenchRemoteService, DraftsRemoteService, installBenchChangeSeam } from "./remote.js";
 export { resolveStorageRoot, openDraftsDomain, } from "./store.js";
 export { DRAFT_ID_RE, draftIdOk } from "./spec.js";
 export { setBenchChangeSeam } from "./bench.js";
 export const name = "estate-drafts";
-export function apply(ctx) {
+export function apply(ctx, config = {}) {
+    // the domain seat mounts FIRST — the remote services' writers open
+    // the drafts domain through it (openDraftsDomain probes this seat)
+    new DraftsDomainSeatService(ctx, config);
     new DraftsRemoteService(ctx);
     new BenchRemoteService(ctx);
 }

package/lib/remote.d.ts

@@ -2,6 +2,7 @@ import type { Context } from "@deepseek-ai/cordis";
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { STAGE_PATCH_KEYS, type StagePatchKey } from "@melite/contracts/benchStage";
 export { STAGE_PATCH_KEYS, type StagePatchKey };
+import { type LaneMigration } from "./bench.js";
 import type { BenchEnsureRow, BenchGetRow, BenchPatchRow, BenchReorderRow, BenchRewireRow, BenchClearRow, BenchStageRow, BenchUndoRow } from "./bench.js";
 export type { BenchEnsureRow, BenchGetRow, BenchPatchRow, BenchReorderRow, BenchRewireRow, BenchStageRow, BenchUndoRow, } from "./bench.js";
 /** Endpoint `drafts/patch` answer — the old door's delivered envelope:
@@ -34,6 +35,11 @@ export interface DraftListResult {
  *  boundary contains unconstrained unknown data"); open card
  *  payloads (stage params, results, history) are honestly JSON all
  *  the way down, so the wire face says exactly that. */
+
+
+
+
+
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     readonly [key: string]: JsonValue;
 };
@@ -98,6 +104,7 @@ declare module "@deepseek-ai/cordis" {
         /**
          * A bench write landed. Emitted after every successful bench verb
          * (and after the drafts-patch door's bench-shaped write).
+         * @mode emit
          * @param session - the bench session whose doc changed.
          */
         "bench.changed": (session: string) => void;
@@ -121,21 +128,21 @@ declare module "@deepseek-ai/cordis" {
 
 
 
+
 export declare function installBenchChangeSeam(ctx: Context): () => void;
 /** ── THE OUTPUT HISTORY HELPERS (stroke 40) ──────────────────────
- * A result's OUTPUT urls, one spelling: the artifacts name→url map
- * first, the flat assetUrls list second, the lone url third (the
- * same harvest order the client's preview reads — the history and
- * the hero can never disagree about what a run produced). */
-export declare function resultOutputUrls(result: unknown): string[];
-/** Same OUTPUTS (the uniqueness key): two results match when their
- * url sets are equal — a re-run landing the same urls is not a new
- * history entry (the operator's "when it is unique"). */
+ *  resultOutputUrls now lives in trail.ts (the cycle-free seam) and
+ *  is re-exported below with the trail laws. ───────────────────── */
 export declare function sameResultOutputs(a: unknown, b: unknown): boolean;
 
 
 
 
+export { canonicalOutputUrl, resultOutputUrls, isTerminalTrailWord as isTerminalWord, trailDedupe } from "./trail.js";
+
+
+
+
 
 
 
@@ -191,8 +198,16 @@ export declare function laneAdmissionOf(ctx: Context): ((card: string, params: R
 
 
 
+
+
+
+export declare function laneMigrationOf(ctx: Context): LaneMigration | undefined;
+
+
+
+
+
 export declare function benchAdmissionOf(ctx: Context): ((card: string, params: Record<string, unknown>, provenance: unknown) => void) | undefined;
-/** The drafts Remote owner: list/get over the storage domain. */
 export declare class DraftsRemoteService extends TypertRemoteService {
     
 
@@ -240,8 +255,12 @@ export declare class DraftsRemoteService extends TypertRemoteService {
 
 
     remoteExportPatch(draftId: string, stageId: string, patch: DraftStagePatch, expectRev: number | null, signal: AbortSignal): Promise<DraftPatchRow>;
-    /** The patch arm the adapter above delegates to. */
+    /** The patch arm the adapter above delegates to — one write
+     *  transaction on the draft's own key, shared with the bench
+     *  verbs (the round-14 race audit's R3: the author arm's
+     *  spread-copy of the log forked against their in-place push). */
     patch(draftId: string, stageId: string, patch: Record<string, unknown>, expectRev: number | null, signal: AbortSignal): Promise<DraftPatchRow>;
+    private patchBody;
 }
 /** The bench Remote owner: ensure/get over the same drafts domain
  *  (the bench doc IS a draft doc, id "bench-<session>"). */