@melite/estate-drafts 0.0.0-stage → 0.1.5-pre-alpha

package/lib/spec.d.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+/** One drafts-domain record: the doc plus the recency column the
+ *  list arm orders by (the file-mtime equivalent — seconds). */
+declare const DraftRecordSchema: z.ZodObject<{
+    updated_at: z.ZodNumber;
+    doc: z.ZodObject<{
+        draft_id: z.ZodString;
+        status: z.ZodString;
+        createdAt: z.ZodNumber;
+        completedAt: z.ZodUnion<readonly [z.ZodNumber, z.ZodNull]>;
+        intent: z.ZodString;
+        stages: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+export type DraftRecord = z.infer<typeof DraftRecordSchema>;
+/** One character record (audit 004/C2): the reusable identity
+ *  bundle. `references` is the ORDERED reference-image list — path
+ *  strings of exactly the class the submit walk stages (data URLs,
+ *  http(s), estate asset URLs, runs-relative and cwd-relative
+ *  paths; `uploadReferenced` walks the whole graph and stages any
+ *  of them, audit 004 §3), order preserved — sheet views are
+ *  position-coded. `description` is the LOCKED identity prompt (a
+ *  character-sheet ten-section block, audit 004/C7's skill); the
+ *  run-time seam (how it reaches a prompt) is C3's decision, not
+ *  this table's. */
+declare const CharacterRecordSchema: z.ZodObject<{
+    name: z.ZodString;
+    references: z.ZodArray<z.ZodString>;
+    description: z.ZodString;
+    updated_at: z.ZodNumber;
+}, z.core.$strip>;
+export type CharacterRecord = z.infer<typeof CharacterRecordSchema>;
+/** The draft-id law (editor_runs.818-822 heritage): 1..96 chars,
+ *  [A-Za-z0-9_-] ASCII only, path-safe. THE SSOT — the queue's
+ *  submit gate and the drafts remote both test this one address
+ *  (the queue re-exports it; gateway-core's copy is dead). */
+export declare const DRAFT_ID_RE: RegExp;
+/** The id's PATTERN and its bound, published so every gate that
+ *  admits a draft id enforces the SAME rule (the census's H13: the
+ *  queue's copy had no cap, so a long id passed one door and was
+ *  refused by the next with a different voice). */
+export declare const DRAFT_ID_PATTERN: RegExp;
+export declare const DRAFT_ID_MAX_LEN = 96;
+/** draft_id_ok (the doors' hand-loop drop-in): the law, one voice. */
+export declare function draftIdOk(draftId: string): boolean;
+/** The drafts domain (unit dir `drafts/`, version 2 — the
+ *  characters table join; version-1 record documents stay
+ *  readable through compatibleVersions, the per-record
+ *  contract's accepted-stamp set). */
+export declare const draftsDomainSpec: {
+    name: string;
+    version: number;
+    compatibleVersions: number[];
+    layout: "per-record";
+    invalidRecords: "backup-and-skip";
+    global: {
+        schema: z.ZodNumber;
+        initial: number;
+    };
+    tables: {
+        docs: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            updated_at: number;
+            doc: {
+                [x: string]: unknown;
+                draft_id: string;
+                status: string;
+                createdAt: number;
+                completedAt: number | null;
+                intent: string;
+                stages: {
+                    [x: string]: unknown;
+                    id: string;
+                }[];
+            };
+        }>;
+        characters: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            name: string;
+            references: string[];
+            description: string;
+            updated_at: number;
+        }>;
+    };
+};
+export type DraftsDomainSpec = typeof draftsDomainSpec;
+export {};
+//# sourceMappingURL=spec.d.ts.map

package/lib/spec.js

@@ -0,0 +1,87 @@
+
+//
+// The domain truth for draft docs: table `docs` keyed by draft id
+// (DRAFT_ID_RE admits path-safe chars only, so the identity codec
+// holds — no b64u here), one record per draft (large, sparse,
+// individually disposable), schema-failing records backed up and
+// skipped by the facility (`invalidRecords: 'backup-and-skip'`).
+// The global slot is the one-time legacy-import marker: 0 until the
+// legacy drafts tree has been imported, the import epoch (ms) after.
+//
+
+// character bundle (ordered reference paths + a locked description),
+// same id grammar as drafts (one address class, one law — the
+// per-record layout's SAFE_KEY_RE is exactly DRAFT_ID_RE's set), the
+// storage root itself is the tenant boundary. Version 2 with
+// compatibleVersions [1]: existing v1-stamped record documents keep
+// reading green (the per-record contract accepts the declared set),
+// new writes stamp 2.
+import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
+import { z } from "zod";
+/** One draft doc — the composer's shape: six contract keys plus
+ *  caller extras verbatim. THE SERVE READ IS DELIBERATELY LOOSE
+ *  (the write doors are strict; this read hands the composer's own
+ *  extras back, pinned by bench-coverage's "extras ride the loose
+ *  schema" row) — a looseObject needs no .passthrough() on top. */
+const DraftDocSchema = z.looseObject({
+    draft_id: z.string(),
+    status: z.string(),
+    createdAt: z.number(),
+    completedAt: z.union([z.number(), z.null()]),
+    intent: z.string(),
+    stages: z.array(z.looseObject({ id: z.string() })),
+});
+/** One drafts-domain record: the doc plus the recency column the
+ *  list arm orders by (the file-mtime equivalent — seconds). */
+const DraftRecordSchema = z.object({
+    updated_at: z.number().int(),
+    doc: DraftDocSchema,
+});
+/** One character record (audit 004/C2): the reusable identity
+ *  bundle. `references` is the ORDERED reference-image list — path
+ *  strings of exactly the class the submit walk stages (data URLs,
+ *  http(s), estate asset URLs, runs-relative and cwd-relative
+ *  paths; `uploadReferenced` walks the whole graph and stages any
+ *  of them, audit 004 §3), order preserved — sheet views are
+ *  position-coded. `description` is the LOCKED identity prompt (a
+ *  character-sheet ten-section block, audit 004/C7's skill); the
+ *  run-time seam (how it reaches a prompt) is C3's decision, not
+ *  this table's. */
+const CharacterRecordSchema = z.object({
+    name: z.string().min(1),
+    references: z.array(z.string()),
+    description: z.string(),
+    updated_at: z.number().int(),
+});
+/** The draft-id law (editor_runs.818-822 heritage): 1..96 chars,
+ *  [A-Za-z0-9_-] ASCII only, path-safe. THE SSOT — the queue's
+ *  submit gate and the drafts remote both test this one address
+ *  (the queue re-exports it; gateway-core's copy is dead). */
+export const DRAFT_ID_RE = /^[A-Za-z0-9_-]{1,96}$/;
+/** The id's PATTERN and its bound, published so every gate that
+ *  admits a draft id enforces the SAME rule (the census's H13: the
+ *  queue's copy had no cap, so a long id passed one door and was
+ *  refused by the next with a different voice). */
+export const DRAFT_ID_PATTERN = DRAFT_ID_RE;
+export const DRAFT_ID_MAX_LEN = 96;
+/** draft_id_ok (the doors' hand-loop drop-in): the law, one voice. */
+export function draftIdOk(draftId) {
+    return DRAFT_ID_RE.test(draftId);
+}
+/** The drafts domain (unit dir `drafts/`, version 2 — the
+ *  characters table join; version-1 record documents stay
+ *  readable through compatibleVersions, the per-record
+ *  contract's accepted-stamp set). */
+export const draftsDomainSpec = defineDomain({
+    name: "drafts",
+    version: 2,
+    compatibleVersions: [1],
+    layout: "per-record",
+    invalidRecords: "backup-and-skip",
+    global: { schema: z.number().int(), initial: 0 },
+    tables: {
+        docs: domainTable(DraftRecordSchema),
+        characters: domainTable(CharacterRecordSchema),
+    },
+});
+//# sourceMappingURL=spec.js.map

package/lib/store.d.ts

@@ -0,0 +1,46 @@
+import { Service, type Context } from "@deepseek-ai/cordis";
+import type { Domain } from "@deepseek-ai/dsh-storage-domain";
+import type { DraftsDomainSpec } from "./spec.js";
+/** The drafts plugin's config (J12: the retired
+ *  MELITE_STORAGE_ROOT / MELITE_STATE_ROOT env seams' config
+ *  twin — the unit-file root the json backend hangs under,
+ *  named at the composition site, never read from the env). */
+export interface DraftsConfig {
+    /** The storage unit-file root (`<stateRoot>/storage` at the
+     *  composition site); default `data/runs/storage`. */
+    storageRoot?: string;
+}
+/** The json backend's unit-file root. */
+export declare function resolveStorageRoot(config?: Readonly<DraftsConfig>): string;
+/** The fiber-scoped seat owning the drafts domain handles (id
+ *  `meliteDraftsDomain` — the estate-seat prefix law, cf.
+ *  skillRegistry.ts:20-28): one instance per mounting fiber, so the
+ *  cached opens die with the fiber instead of living at module
+ *  scope. Fields are TS-`private`, never `#private` — cordis
+ *  `ctx.get` returns a proxy and private class fields die through
+ *  it ("Cannot read private member ... whose class did not declare
+ *  it"; the flows seat, flowsData.ts, is the measured precedent). */
+export declare class DraftsDomainSeatService extends Service {
+    static readonly inject: {
+        readonly optional: readonly [];
+    };
+    /** Per-facility open handles, keyed by the facility object (one
+     *  slot per provider; GC-bounded, fiber-lifetime). */
+    private cached;
+    constructor(ctx: Context, config?: Readonly<DraftsConfig>);
+    /** The composition site's named storage root (J12: config —
+     *  the retired env seam's twin). */
+    readonly config: Readonly<DraftsConfig>;
+    
+
+
+
+    open(): Promise<Domain<DraftsDomainSpec>>;
+}
+/** Open (or reuse) the drafts domain through the mounted seat. The
+ *  apply mounts `DraftsDomainSeatService` before the remote
+ *  services; tests mount it on their own Context.
+ *  @param ctx - the Context whose fiber carries the seat.
+ *  @returns the ready domain handle. */
+export declare function openDraftsDomain(ctx: Context): Promise<Domain<DraftsDomainSpec>>;
+//# sourceMappingURL=store.d.ts.map

package/lib/store.js

@@ -0,0 +1,194 @@
+// store.ts — open the drafts domain through the host's facility.
+//
+// The facility seat (`ctx.storageDomain`) is provided by the HOST's
+// storage rows (json backend + domain facility); this package never
+// bundles them. The open is lazy and process-scoped (one open per
+// storage root — the domain write chain serializes concurrent puts,
+// so sharing the handle is correct), cached on first use.
+//
+// First open runs the one-time legacy import (the pre-domain
+// STATE_ROOT/drafts tree → the domain), guarded by the global slot:
+// runs only while it serves the initial 0, then stamps the epoch —
+// a wiped unit never re-imports frozen ghosts. The legacy files stay
+// untouched on disk — evidence, never truth.
+import { Service } from "@deepseek-ai/cordis";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { isPurelyUnstatedRequiredVoice } from "@melite/contracts/laneRelations";
+import { draftsDomainSpec } from "./spec.js";
+/** The json backend's unit-file root. */
+export function resolveStorageRoot(config = {}) {
+    return config.storageRoot ?? join("data", "runs", "storage");
+}
+/** The one-time legacy-drafts import (the pre-domain drafts tree →
+ *  the drafts domain). Unparseable/non-object legacy files skip;
+ *  schema-failing rows skip individually; the rest import. */
+async function importLegacyDrafts(drafts, storageRoot) {
+    const marker = drafts.global;
+    if (marker.get() !== 0)
+        return;
+    const docs = drafts.table("docs");
+    const legacyDir = join(storageRoot, "..", "drafts");
+    let names;
+    try {
+        names = readdirSync(legacyDir);
+    }
+    catch {
+        names = [];
+    }
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        const did = name.slice(0, -5);
+        if (docs.get(did) !== undefined)
+            continue;
+        let doc;
+        try {
+            doc = JSON.parse(readFileSync(join(legacyDir, name), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (typeof doc !== "object" || doc === null || Array.isArray(doc))
+            continue;
+        const rec = doc;
+        if (typeof rec["draft_id"] !== "string")
+            rec["draft_id"] = did;
+        let updated = Math.floor(Date.now() / 1000);
+        try {
+            updated = Math.floor(statSync(join(legacyDir, name)).mtimeMs / 1000);
+        }
+        catch {
+            /* unstatable imports as now — ordering stays total */
+        }
+        try {
+            await docs.put(did, {
+                updated_at: updated,
+                doc: rec,
+            });
+        }
+        catch {
+            /* a schema-failing legacy row skips; the rest import */
+        }
+    }
+    await marker.set(Date.now());
+}
+
+
+
+
+
+
+
+
+
+
+
+
+async function healReplayedRefusals(drafts) {
+    const docs = drafts.table("docs");
+    for (const [did, rec] of docs.entries()) {
+        // persisted rows are a durable boundary: a record without a doc
+        // object (or without stages) carries no bench row to heal
+        const doc = typeof rec === "object" && rec !== null ? rec.doc : undefined;
+        if (typeof doc !== "object" || doc === null)
+            continue;
+        const stages = Array.isArray(doc.stages) ? doc.stages : [];
+        let changed = false;
+        for (const stage of stages) {
+            if (typeof stage !== "object" || stage === null)
+                continue;
+            const row = stage;
+            const runStatus = row["runStatus"];
+            if (runStatus !== "failed" && runStatus !== "error")
+                continue;
+            const result = row["result"];
+            const error = typeof result === "object" && result !== null
+                ? result["error"]
+                : undefined;
+            // PURELY the class (the mixed-carry guard): a composite
+            // refusal can join the stem with a stated-wrong half — that
+            // row keeps its failed face, only whole-stem texts heal
+            if (typeof error !== "string" || !isPurelyUnstatedRequiredVoice(error)) {
+                continue;
+            }
+            row["runStatus"] = "";
+            row["result"] = {};
+            changed = true;
+        }
+        if (changed)
+            await docs.put(did, rec);
+    }
+}
+/** The fiber-scoped seat owning the drafts domain handles (id
+ *  `meliteDraftsDomain` — the estate-seat prefix law, cf.
+ *  skillRegistry.ts:20-28): one instance per mounting fiber, so the
+ *  cached opens die with the fiber instead of living at module
+ *  scope. Fields are TS-`private`, never `#private` — cordis
+ *  `ctx.get` returns a proxy and private class fields die through
+ *  it ("Cannot read private member ... whose class did not declare
+ *  it"; the flows seat, flowsData.ts, is the measured precedent). */
+export class DraftsDomainSeatService extends Service {
+    static inject = { optional: [] };
+    /** Per-facility open handles, keyed by the facility object (one
+     *  slot per provider; GC-bounded, fiber-lifetime). */
+    cached = new WeakMap();
+    constructor(ctx, config = {}) {
+        // the estate-seat id: dsh core may own the bare name
+        super(ctx, "meliteDraftsDomain");
+        this.config = config;
+    }
+    /** The composition site's named storage root (J12: config —
+     *  the retired env seam's twin). */
+    config;
+    
+
+
+
+    async open() {
+        const root = resolveStorageRoot(this.config);
+        // OPTIONAL-dependency probe per the tutorial's documented pattern
+        // (cordis-tutorial/03-services.md: "skip inject and probe at the
+        // use site" — property reads demand inject on loader-mounted
+        // fibers; ctx.get returns the active provider or undefined).
+        const facility = this.ctx.get("storageDomain");
+        if (facility === undefined || facility === null) {
+            throw new Error("[estate-drafts] storage domain facility not mounted (ctx.storageDomain)");
+        }
+        const hit = this.cached.get(facility);
+        // (J12) the config root is immutable per boot, so a cached hit is
+        // always this root — the drifting-mid-process root the retired
+        
+        if (hit !== undefined)
+            return hit.ready;
+        const ready = (async () => {
+            const drafts = await facility.open(draftsDomainSpec);
+            await importLegacyDrafts(drafts, root);
+            await healReplayedRefusals(drafts);
+            return drafts;
+        })();
+        this.cached.set(facility, { root, ready });
+        try {
+            return await ready;
+        }
+        catch (error) {
+            // Unconditional: one slot per facility exists at a time (a
+            // foreign root refuses above), so this rejection owns the slot.
+            this.cached.delete(facility);
+            throw error;
+        }
+    }
+}
+/** Open (or reuse) the drafts domain through the mounted seat. The
+ *  apply mounts `DraftsDomainSeatService` before the remote
+ *  services; tests mount it on their own Context.
+ *  @param ctx - the Context whose fiber carries the seat.
+ *  @returns the ready domain handle. */
+export async function openDraftsDomain(ctx) {
+    const seat = ctx.get("meliteDraftsDomain");
+    if (seat === undefined || seat === null) {
+        throw new Error("[estate-drafts] drafts domain seat not mounted (new DraftsDomainSeatService(ctx))");
+    }
+    return seat.open();
+}
+//# sourceMappingURL=store.js.map

package/lib/trail.d.ts

@@ -0,0 +1,16 @@
+export declare function canonicalOutputUrl(url: string): string;
+/** 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). */
+export declare function resultOutputUrls(result: unknown): string[];
+/** The draft row's terminal words (see remote.ts's trail laws). */
+export declare function isTerminalTrailWord(v: unknown): boolean;
+/** Same run identity: two non-empty equal run_id strings. */
+export declare function sameTrailRunIdentity(a: unknown, b: unknown): boolean;
+/** THE ONE-ROW-PER-RUN TRAIL (bench-trail W2's law, applied to any
+ *  carried history): identity is the run_id first — the media route
+ *  and the gallery proxy spell the same file differently — with the
+ *  canonical-url set as the no-id fallback. Order preserved, newest
+ *  first in, newest first out. */
+export declare function trailDedupe(history: unknown[]): unknown[];
+//# sourceMappingURL=trail.d.ts.map

package/lib/trail.js

@@ -0,0 +1,91 @@
+
+// trail's dedup/canonical laws live here so EVERY carrier obeys them
+// — the patch door's archive (remote.ts), the load/undo memory carry
+// (bench.ts), and any future writer. remote.ts imports bench.ts, so
+// bench-facing carriers can never import remote.ts back; this module
+// is the cycle-free home both sides share.
+import { RUN_MEDIA_PREFIX } from "@melite/contracts/benchStage";
+/** One url, canonical: the run-relative path. The media route and
+ *  the gallery proxy spell the SAME file two ways
+ *  (/melite-media/runs/<rest>, /infer-gallery/artifact?path=<enc>) —
+ *  every dedup compares canonical forms, never wire spellings. The
+ *  run-media prefix rides the contract's constant — the closure
+ *  gate's no-second-copy law. */
+const MEDIA_RUNS = RUN_MEDIA_PREFIX + "/";
+export function canonicalOutputUrl(url) {
+    if (url.startsWith(MEDIA_RUNS))
+        return url.slice(MEDIA_RUNS.length);
+    if (url.startsWith("/infer-gallery/artifact?path=")) {
+        try {
+            return decodeURIComponent(url.slice("/infer-gallery/artifact?path=".length));
+        }
+        catch {
+            // a malformed escape is not a spelling of another file — keep it
+            return url;
+        }
+    }
+    return url;
+}
+/** 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). */
+export function resultOutputUrls(result) {
+    if (typeof result !== "object" || result === null || Array.isArray(result))
+        return [];
+    const row = result;
+    const urls = [];
+    if (row["artifacts"] !== null && typeof row["artifacts"] === "object" && !Array.isArray(row["artifacts"])) {
+        for (const v of Object.values(row["artifacts"])) {
+            if (typeof v === "string" && v !== "")
+                urls.push(v);
+        }
+    }
+    if (urls.length === 0 && Array.isArray(row["assetUrls"])) {
+        for (const v of row["assetUrls"]) {
+            if (typeof v === "string" && v !== "")
+                urls.push(v);
+        }
+    }
+    if (urls.length === 0 && typeof row["url"] === "string" && row["url"] !== "")
+        urls.push(row["url"]);
+    return urls;
+}
+const TRAIL_TERMINAL = new Set(["done", "completed", "failed", "stopped"]);
+/** The draft row's terminal words (see remote.ts's trail laws). */
+export function isTerminalTrailWord(v) {
+    return typeof v === "string" && TRAIL_TERMINAL.has(v);
+}
+/** Same run identity: two non-empty equal run_id strings. */
+export function sameTrailRunIdentity(a, b) {
+    return typeof a === "string" && a !== "" && a === b;
+}
+/** THE ONE-ROW-PER-RUN TRAIL (bench-trail W2's law, applied to any
+ *  carried history): identity is the run_id first — the media route
+ *  and the gallery proxy spell the same file differently — with the
+ *  canonical-url set as the no-id fallback. Order preserved, newest
+ *  first in, newest first out. */
+export function trailDedupe(history) {
+    const out = [];
+    const runIds = new Set();
+    const sets = [];
+    for (const entry of history) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            out.push(entry);
+            continue;
+        }
+        const row = entry;
+        const rid = row["run_id"];
+        if (typeof rid === "string" && rid !== "") {
+            if (runIds.has(rid))
+                continue;
+            runIds.add(rid);
+        }
+        const canon = new Set(resultOutputUrls(row).map(canonicalOutputUrl));
+        if (sets.some((s) => s.size === canon.size && [...s].every((u) => canon.has(u))))
+            continue;
+        sets.push(canon);
+        out.push(entry);
+    }
+    return out;
+}
+//# sourceMappingURL=trail.js.map

package/lib/typert.host.d.ts

@@ -0,0 +1,3 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from FaceModel — do not edit. */
+
+export declare const TYPERT: unknown