@deepseek-harness-tui/dsh-tui 0.8.0 → 0.8.2

package/lib/types/dsh-adapter/dialogs.js

@@ -0,0 +1,316 @@
+/**
+ * Managed plugin dialogs — the pi `ctx.ui.select/confirm/input` seam for
+ * dsh-TUI. Plugins hand the HOST a declarative request; the TUI renders the
+ * dialog in its own chrome (next to the approval panel), owns the keyboard,
+ * and settles the plugin's promise with the user's answer. Plugins never
+ * touch the TTY themselves.
+ *
+ * Split in two, mirroring QuestionStore/ApprovalStore:
+ *
+ * - {@link TuiDialogStore} — cordis-free queue + snapshot. The chat screen
+ *   subscribes to it and renders the current dialog; tests can drive it
+ *   without a cordis context.
+ * - {@link TuiDialogRuntime} — the cordis service (`ctx.tuiDialogs`)
+ *   plugins call. Validation of untrusted request data lives here.
+ *
+ * Queue semantics mirror the approval store: parallel plugin calls park
+ * FIFO and surface one at a time. A request settles exactly once — user
+ * answer, Esc cancel, caller AbortSignal, caller timeout, or service
+ * teardown (`cancelled` outcomes map to `undefined`/`false` returns).
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { cleanScalarText } from './sanitize.js';
+import { activationContext, bindCallerEffect, compositionRoot, concreteService, requirePluginCaller } from './host-access.js';
+/** Render-path strings are untrusted: sanitization (control-char stripping,
+ *  cell-width caps, scalar-only coercion) lives in ./sanitize.js — the one
+ *  implementation of the Track A contract. `clean` drops non-scalars to ''
+ *  so callers take their refuse path instead of rendering "[object Object]". */
+const clean = cleanScalarText;
+const TITLE_CELLS = 120;
+const LABEL_CELLS = 120;
+const MESSAGE_CELLS = 400;
+/** The documented bound of the resolved input text; the panel enforces it
+ *  on every edit path (typing AND paste) so the promise never resolves with
+ *  a larger value. */
+export const INPUT_CELLS = 500;
+const MAX_OPTIONS = 100;
+/** Bound a request that omits both signal and timeout. */
+export const DIALOG_DEFAULT_TIMEOUT_MS = 30_000;
+let nextDialogId = 1;
+/**
+ * Cordis-free dialog queue. `ask` parks a request; the UI drains one at a
+ * time via the snapshot and settles through {@link decide}/{@link cancel}.
+ */
+export class TuiDialogStore {
+    listeners = new Set();
+    queue = [];
+    active = null;
+    /** Park a request. The snapshot argument must already be sanitized. */
+    ask(snapshot, signal, timeoutMs, owner, bindOwnerEffect) {
+        if (signal?.aborted)
+            return Promise.resolve(undefined);
+        return new Promise((resolve) => {
+            let settled = false;
+            const pending = {
+                // The key is stable per dialog (the panel remounts fresh per
+                // request, like ApprovalSnapshot.key) and unique across the queue.
+                key: `dlg-${nextDialogId++}`,
+                snapshot: undefined,
+                settle: () => { },
+                onAbort: () => { },
+                timer: undefined,
+                ownerCleanup: undefined,
+            };
+            pending.snapshot = { ...snapshot, key: pending.key };
+            pending.settle = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (pending.timer !== undefined)
+                    clearTimeout(pending.timer);
+                signal?.removeEventListener('abort', pending.onAbort);
+                const ownerCleanup = pending.ownerCleanup;
+                pending.ownerCleanup = undefined;
+                ownerCleanup?.();
+                resolve(value);
+            };
+            pending.onAbort = () => {
+                // Normal completion also disposes the owner effect. The effect's
+                // cleanup must not re-enter the abort path and advance the queue a
+                // second time.
+                if (settled)
+                    return;
+                // Aborted while queued: drop silently. Aborted while active: close
+                // the dialog and advance the queue.
+                const index = this.queue.indexOf(pending);
+                if (index !== -1)
+                    this.queue.splice(index, 1);
+                if (this.active === pending)
+                    this.active = null;
+                pending.settle(undefined);
+                // Must advance (not just emit): with the active dialog gone, the
+                // next queued request has to become active — otherwise its Promise
+                // parks forever and the UI shows no dialog until an unrelated ask
+                // happens to trigger advance.
+                this.advance();
+            };
+            signal?.addEventListener('abort', pending.onAbort, { once: true });
+            if (timeoutMs !== undefined && timeoutMs > 0) {
+                pending.timer = setTimeout(pending.onAbort, timeoutMs);
+            }
+            if (owner !== undefined) {
+                const bound = bindOwnerEffect?.(pending.onAbort, cleanup => { pending.ownerCleanup = cleanup; }) ?? false;
+                if (!bound) {
+                    // An inactive or untrusted activation must never leave an orphan in
+                    // the queue. The binder also rolls back partial owner state.
+                    pending.onAbort();
+                    return;
+                }
+            }
+            this.queue.push(pending);
+            this.advance();
+        });
+    }
+    /** The dialog the UI should render right now, if any. */
+    getSnapshot() {
+        return this.active?.snapshot ?? null;
+    }
+    /**
+     * Settle the active dialog with the user's answer. The caller passes the
+     * key of the snapshot IT rendered; a mismatched key is a stale callback
+     * and ignored. This is not paranoia: ConPTY can deliver one Enter as a
+     * same-batch CR+LF pair, firing the old panel's handler twice before
+     * React unmounts it — an unkeyed decide would settle the active dialog
+     * AND the successor the first call just promoted (one Enter answering two
+     * consecutive dialogs).
+     */
+    decide(key, value) {
+        const pending = this.active;
+        if (pending === null || pending.key !== key)
+            return;
+        this.active = null;
+        pending.settle(value);
+        this.advance();
+    }
+    /** Cancel the active dialog (Esc). Keyed like {@link decide}: a stale
+     *  panel's Esc must not close the successor it never rendered. */
+    cancel(key) {
+        const pending = this.active;
+        if (pending === null || pending.key !== key)
+            return;
+        this.active = null;
+        pending.settle(undefined);
+        this.advance();
+    }
+    /** Settle everything queued + active (teardown): all resolve cancelled. */
+    settleAll() {
+        const pending = [...this.queue];
+        this.queue.length = 0;
+        if (this.active !== null)
+            pending.push(this.active);
+        this.active = null;
+        for (const item of pending)
+            item.settle(undefined);
+        this.emit();
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    advance() {
+        if (this.active === null && this.queue.length > 0) {
+            this.active = this.queue.shift() ?? null;
+        }
+        this.emit();
+    }
+    emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+/**
+ * `ctx.tuiDialogs` — plugin-facing managed dialogs. Every method validates
+ * its request (untrusted data on the render path) and resolves with the
+ * cancelled value (`undefined`/`false`) rather than throwing when the
+ * request is malformed — a dialog must never take the plugin or the TUI
+ * down; callers get a logger warning instead.
+ */
+export class TuiDialogRuntime extends Service {
+    constructor(ctx) {
+        super(ctx, 'tuiDialogs');
+        compositionRoot(ctx);
+        // Keep queue state off the service object. Cordis invokes public methods
+        // through a caller-bound proxy, so JS `#private` fields are unsuitable
+        // here; the module-local WeakMap preserves both encapsulation and proxy
+        // compatibility.
+        const store = new TuiDialogStore();
+        hostDialogStores.set(this, store);
+        ctx.effect(() => () => store.settleAll());
+    }
+    /** Cordis traceable services normally provide the caller through `this.ctx`;
+     * the explicit overloads below make ownership unambiguous for embedders and
+     * tests that retain the service instance directly. */
+    callContext(value) {
+        const caller = requirePluginCaller(this.ctx, 'tuiDialogs', this);
+        if (!Context.is(value))
+            return caller;
+        // An explicit owner is accepted only when it is the activation that made
+        // the service call.  Otherwise a plugin could pass the root (or another
+        // plugin's context) and leave an orphaned dialog alive after deactivation.
+        const canonical = activationContext(value);
+        if (canonical === undefined || activationContext(caller) !== canonical) {
+            throw new Error('tuiDialogs owner context must be the calling activation');
+        }
+        return canonical;
+    }
+    timeoutOf(value) {
+        return typeof value === 'number' && Number.isFinite(value) && value > 0
+            ? Math.min(Math.floor(value), 24 * 60 * 60 * 1000)
+            : DIALOG_DEFAULT_TIMEOUT_MS;
+    }
+    select(ownerOrRequest, explicitRequest) {
+        try {
+            const owner = this.callContext(ownerOrRequest);
+            const request = (explicitRequest ?? ownerOrRequest);
+            const title = clean(request?.title, TITLE_CELLS);
+            const rawOptions = Array.isArray(request?.options) ? request.options : [];
+            const options = [];
+            for (const raw of rawOptions.slice(0, MAX_OPTIONS)) {
+                // The id is NOT render-path data — it is the opaque token the promise
+                // resolves with, matched by the plugin against its own options. Sanitizing
+                // it (whitespace collapse, cell truncation) would hand back a DIFFERENT
+                // string the plugin cannot look up; validate and keep it verbatim.
+                const id = raw?.id;
+                const label = clean(raw?.label, LABEL_CELLS);
+                if (typeof id !== 'string' || id === '' || !label)
+                    continue;
+                // '' (absent, blank, or a dropped non-scalar) means no description row.
+                const description = clean(raw?.description, MESSAGE_CELLS);
+                options.push({ id, label, ...(description === '' ? {} : { description }) });
+            }
+            if (!title || options.length === 0) {
+                this.ctx.logger.warn('dsh-tui: tuiDialogs.select called without a title or options; cancelled');
+                return Promise.resolve(undefined);
+            }
+            return dialogStoreFor(this)
+                .ask({ kind: 'select', title, options }, request.signal, this.timeoutOf(request.timeoutMs), owner, (disposer, onRegistered) => bindCallerEffect(owner, disposer, onRegistered))
+                .then(value => (typeof value === 'string' ? value : undefined));
+        }
+        catch {
+            this.ctx.logger.warn('dsh-tui: tuiDialogs.select received malformed data; cancelled');
+            return Promise.resolve(undefined);
+        }
+    }
+    confirm(ownerOrRequest, explicitRequest) {
+        try {
+            const owner = this.callContext(ownerOrRequest);
+            const request = (explicitRequest ?? ownerOrRequest);
+            const title = clean(request?.title, TITLE_CELLS);
+            if (!title) {
+                this.ctx.logger.warn('dsh-tui: tuiDialogs.confirm called without a title; cancelled');
+                return Promise.resolve(false);
+            }
+            const message = clean(request?.message, MESSAGE_CELLS);
+            const confirmLabel = clean(request?.confirmLabel, LABEL_CELLS);
+            const cancelLabel = clean(request?.cancelLabel, LABEL_CELLS);
+            return dialogStoreFor(this)
+                .ask({
+                kind: 'confirm',
+                title,
+                ...(message === '' ? {} : { message }),
+                confirmLabel,
+                cancelLabel,
+            }, request.signal, this.timeoutOf(request.timeoutMs), owner, (disposer, onRegistered) => bindCallerEffect(owner, disposer, onRegistered))
+                .then(value => value === true);
+        }
+        catch {
+            this.ctx.logger.warn('dsh-tui: tuiDialogs.confirm received malformed data; cancelled');
+            return Promise.resolve(false);
+        }
+    }
+    input(ownerOrRequest, explicitRequest) {
+        try {
+            const owner = this.callContext(ownerOrRequest);
+            const request = (explicitRequest ?? ownerOrRequest);
+            const title = clean(request?.title, TITLE_CELLS);
+            if (!title) {
+                this.ctx.logger.warn('dsh-tui: tuiDialogs.input called without a title; cancelled');
+                return Promise.resolve(undefined);
+            }
+            const placeholder = clean(request?.placeholder, LABEL_CELLS);
+            const initial = clean(request?.initial, INPUT_CELLS);
+            return dialogStoreFor(this)
+                .ask({ kind: 'input', title, ...(placeholder === '' ? {} : { placeholder }), initial }, request.signal, this.timeoutOf(request.timeoutMs), owner, (disposer, onRegistered) => bindCallerEffect(owner, disposer, onRegistered))
+                .then(value => (typeof value === 'string' ? value : undefined));
+        }
+        catch {
+            this.ctx.logger.warn('dsh-tui: tuiDialogs.input received malformed data; cancelled');
+            return Promise.resolve(undefined);
+        }
+    }
+}
+/**
+ * Host-only queue accessor. This module is intentionally not a package
+ * export; plugins receive only the traceable `tuiDialogs` capability, whose
+ * public surface is select/confirm/input.
+ */
+const hostDialogStores = new WeakMap();
+function dialogStoreFor(runtime) {
+    const store = hostDialogStores.get(concreteService(runtime));
+    if (store === undefined)
+        throw new Error('tuiDialogs host store is unavailable');
+    return store;
+}
+export function getHostDialogStore(runtime) {
+    if (runtime === undefined)
+        return undefined;
+    try {
+        return hostDialogStores.get(concreteService(runtime));
+    }
+    catch {
+        return undefined;
+    }
+}
+export default TuiDialogRuntime;

package/lib/types/dsh-adapter/effect-ledger.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Effect ledger (C-060): an append-only JSONL journal of plugin-visible
+ * effects at `~/.dsh-tui/effect-ledger.jsonl`, mounted by the
+ * dsh-tui-plugin-host row as `ctx.tuiEffectLedger`.
+ *
+ * Every record carries the lifecycle triple:
+ *
+ * - `pluginId` — derived from the verified Component identity bound to the
+ *   PASSED activation. `'host'` is used for host/root records and
+ *   `'undeclared'` for a plugin-facing call without a verified identity; a
+ *   display fiber name is never trusted as authorization identity.
+ * - `activationInstance` — stable per cordis fiber for the lifetime of this
+ *   process (first-seen assignment from a WeakMap), so a hot-reloaded plugin
+ *   shows up as a NEW instance while all effects of one activation share one
+ *   id.
+ * - `runtimeGenerationId` — the plugin-host row's generation (C-050), so
+ *   records from different process generations can never be confused.
+ *
+ * Recording rules:
+ *
+ * - FAIL-CLOSED ON SCHEMA: every record is validated against the vendored
+ *   `effect-ledger-record.schema.json` BEFORE it is appended; a record that
+ *   fails is dropped with a warning, never written. A missing vendored
+ *   schema suppresses ALL writes (warned once) — the same posture as the
+ *   messages.observe envelope check. The schema's `additionalProperties:
+ *   false` is what structurally bans secrets from the ledger: callers
+ *   cannot smuggle payload fields through.
+ * - SEQUENCE: continues across restarts (max sequence in the existing file
+ *   + 1); corrupt lines are skipped, never rewritten.
+ * - NEVER THROWS: recording is observability, not a gate — internal errors
+ *   (including disk failures) are caught and warned, the caller's path is
+ *   unaffected.
+ *
+ * privacyClass: operational — records hold identifiers and error codes,
+ * never message content, storage values, or grant-file contents.
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+/** Default ledger file (JSONL, one record per line). */
+export declare const EFFECT_LEDGER_FILE: string;
+/** Resource kinds recorded by the host's wired emitters. */
+export declare const LEDGER_RESOURCE_KINDS: readonly ["command", "scene", "shortcut", "status", "renderer", "storage-namespace", "subscription", "permission"];
+export type LedgerOperation = 'create' | 'bind' | 'replace' | 'release' | 'cleanup-failed';
+export type LedgerResult = 'applied' | 'pending' | 'failed';
+/** Caller-facing record input; the runtime fills the lifecycle triple. */
+export interface LedgerEntry {
+    operation: LedgerOperation;
+    resource: {
+        kind: string;
+        id: string;
+    };
+    result: LedgerResult;
+    /** Contract error code when result is 'failed' (e.g. PERMISSION_NOT_GRANTED). */
+    errorCode?: string;
+    /** What this record supersedes (operation 'replace'). */
+    replaces?: {
+        resourceId?: string;
+        activationInstance?: string;
+    };
+    /** `sha256:<64hex>` digest of an opaque value, when a record must reference one. */
+    valueDigest?: string;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiEffectLedger: TuiEffectLedgerRuntime;
+    }
+}
+/** `ctx.tuiEffectLedger` — append-only effect journal (C-060). */
+export declare class TuiEffectLedgerRuntime extends Service {
+    constructor(ctx: Context, options?: {
+        file?: string;
+        generationId?: string;
+        ledgerSchema?: Record<string, unknown>;
+    });
+    /**
+     * Append one record. `identity` is the caller's own context (plugins pass
+     * their plugin ctx through the managed services' optional trailing
+     * parameter); omitting it records `undeclared`, never a guess.
+     */
+    record(entry: LedgerEntry, identity?: Context): void;
+    /** Runtime generation (C-050): options override, else the plugin-host
+     *  service's id — resolved on first record and cached (the host row mounts
+     *  before any caller can record). */
+    private generation;
+    /** Continue numbering after the existing file's max sequence (restart-safe). */
+    private resumeSequence;
+    private fiberOf;
+    private pluginIdOf;
+    private activationOf;
+}
+export default TuiEffectLedgerRuntime;
+//# sourceMappingURL=effect-ledger.d.ts.map

package/lib/types/dsh-adapter/effect-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-ledger.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/effect-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAOtD,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,QAAwC,CAAA;AAEvE,4DAA4D;AAC5D,eAAO,MAAM,qBAAqB,oHASxB,CAAA;AAEV,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,gBAAgB,CAAA;AAC1F,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE3D,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,eAAe,CAAA;IAC1B,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;IACtC,MAAM,EAAE,YAAY,CAAA;IACpB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,yDAAyD;IACzD,QAAQ,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/D,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,eAAe,EAAE,sBAAsB,CAAA;KACxC;CACF;AAWD,kEAAkE;AAClE,qBAAa,sBAAuB,SAAQ,OAAO;gBAE/C,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAO;IA0BhG;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI;IA6DpD;;yCAEqC;IACrC,OAAO,CAAC,UAAU;IAOlB,gFAAgF;IAChF,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,UAAU;IAgBlB,OAAO,CAAC,YAAY;CAarB;AA6CD,eAAe,sBAAsB,CAAA"}

package/lib/types/dsh-adapter/effect-ledger.js

@@ -0,0 +1,251 @@
+/**
+ * Effect ledger (C-060): an append-only JSONL journal of plugin-visible
+ * effects at `~/.dsh-tui/effect-ledger.jsonl`, mounted by the
+ * dsh-tui-plugin-host row as `ctx.tuiEffectLedger`.
+ *
+ * Every record carries the lifecycle triple:
+ *
+ * - `pluginId` — derived from the verified Component identity bound to the
+ *   PASSED activation. `'host'` is used for host/root records and
+ *   `'undeclared'` for a plugin-facing call without a verified identity; a
+ *   display fiber name is never trusted as authorization identity.
+ * - `activationInstance` — stable per cordis fiber for the lifetime of this
+ *   process (first-seen assignment from a WeakMap), so a hot-reloaded plugin
+ *   shows up as a NEW instance while all effects of one activation share one
+ *   id.
+ * - `runtimeGenerationId` — the plugin-host row's generation (C-050), so
+ *   records from different process generations can never be confused.
+ *
+ * Recording rules:
+ *
+ * - FAIL-CLOSED ON SCHEMA: every record is validated against the vendored
+ *   `effect-ledger-record.schema.json` BEFORE it is appended; a record that
+ *   fails is dropped with a warning, never written. A missing vendored
+ *   schema suppresses ALL writes (warned once) — the same posture as the
+ *   messages.observe envelope check. The schema's `additionalProperties:
+ *   false` is what structurally bans secrets from the ledger: callers
+ *   cannot smuggle payload fields through.
+ * - SEQUENCE: continues across restarts (max sequence in the existing file
+ *   + 1); corrupt lines are skipped, never rewritten.
+ * - NEVER THROWS: recording is observability, not a gate — internal errors
+ *   (including disk failures) are caught and warned, the caller's path is
+ *   unaffected.
+ *
+ * privacyClass: operational — records hold identifiers and error codes,
+ * never message content, storage values, or grant-file contents.
+ */
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { Service } from '@deepseek-ai/cordis';
+import { DATA_DIR } from '../utils/paths.js';
+import { loadSpecData } from '../plugin-spec/registry.js';
+import { check } from '../plugin-spec/schema-check.js';
+import { componentIdentityOf } from './component-identity.js';
+import { compositionRoot, concreteService } from './host-access.js';
+/** Default ledger file (JSONL, one record per line). */
+export const EFFECT_LEDGER_FILE = join(DATA_DIR, 'effect-ledger.jsonl');
+/** Resource kinds recorded by the host's wired emitters. */
+export const LEDGER_RESOURCE_KINDS = [
+    'command',
+    'scene',
+    'shortcut',
+    'status',
+    'renderer',
+    'storage-namespace',
+    'subscription',
+    'permission',
+];
+/** Strip control chars and cap length so a hostile id cannot break the JSONL
+ *  line format or blow the schema bounds (JSON.stringify would keep the line
+ *  intact, but downstream tooling reads these fields raw). */
+function cleanField(value, max, fallback) {
+    if (typeof value !== 'string')
+        return fallback;
+    const cleaned = value.replace(/[\x00-\x1f\x7f-\x9f]/g, '').slice(0, max);
+    return cleaned === '' ? fallback : cleaned;
+}
+/** `ctx.tuiEffectLedger` — append-only effect journal (C-060). */
+export class TuiEffectLedgerRuntime extends Service {
+    constructor(ctx, options = {}) {
+        super(ctx, 'tuiEffectLedger');
+        const file = options.file ?? EFFECT_LEDGER_FILE;
+        // The generation is resolved LAZILY (per first record): cordis does not
+        // make sibling services visible to constructors of plugins mounted later
+        // by the same apply(), so a constructor-time probe would always miss the
+        // plugin-host service and fall back to 'unknown-generation'.
+        const state = {
+            hostContext: compositionRoot(ctx),
+            file,
+            optionsGenerationId: options.generationId,
+            generationId: undefined,
+            activations: new WeakMap(),
+            nextActivation: 1,
+            sequence: 0,
+            schemaWarned: false,
+            ledgerSchema: undefined,
+        };
+        // `'ledgerSchema' in options` lets a caller force-undefined (fail-closed
+        // test seam), same contract as the message observer's envelopeSchema.
+        state.ledgerSchema = 'ledgerSchema' in options ? options.ledgerSchema : loadSpecData()?.schemas.ledger;
+        state.sequence = resumeSequence(file);
+        ledgerStates.set(this, state);
+    }
+    /**
+     * Append one record. `identity` is the caller's own context (plugins pass
+     * their plugin ctx through the managed services' optional trailing
+     * parameter); omitting it records `undeclared`, never a guess.
+     */
+    record(entry, identity) {
+        let state;
+        try {
+            state = ledgerStateFor(this);
+            if (state.ledgerSchema === undefined) {
+                if (!state.schemaWarned) {
+                    state.schemaWarned = true;
+                    state.hostContext.logger.warn('dsh-tui: effect ledger schema unavailable — suppressing all ledger writes (fail-closed)');
+                }
+                return;
+            }
+            const fiber = this.fiberOf(identity);
+            const verified = identity === undefined ? undefined : componentIdentityOf(identity);
+            const pluginId = this.pluginIdOf(identity, fiber, verified?.componentId);
+            const record = {
+                ledgerVersion: '0.15',
+                sequence: state.sequence,
+                timestamp: new Date().toISOString(),
+                pluginId,
+                activationInstance: verified?.activationId ?? this.activationOf(fiber, pluginId),
+                runtimeGenerationId: this.generation(),
+                operation: entry.operation,
+                resource: {
+                    kind: cleanField(entry.resource?.kind, 64, 'unknown'),
+                    id: cleanField(entry.resource?.id, 128, 'unknown'),
+                },
+                result: entry.result,
+                ...(entry.errorCode !== undefined ? { errorCode: cleanField(entry.errorCode, 64, 'UNKNOWN') } : {}),
+                ...(entry.replaces !== undefined
+                    ? {
+                        replaces: {
+                            ...(entry.replaces.resourceId !== undefined
+                                ? { resourceId: cleanField(entry.replaces.resourceId, 128, 'unknown') }
+                                : {}),
+                            ...(entry.replaces.activationInstance !== undefined
+                                ? { activationInstance: cleanField(entry.replaces.activationInstance, 128, 'unknown') }
+                                : {}),
+                        },
+                    }
+                    : {}),
+                ...(entry.valueDigest !== undefined ? { valueDigest: entry.valueDigest } : {}),
+            };
+            // Fail-closed self-check: a record that does not satisfy the vendored
+            // schema is DROPPED, not written (the schema's additionalProperties:
+            // false is the structural secret ban).
+            try {
+                check(record, state.ledgerSchema, state.ledgerSchema);
+            }
+            catch (error) {
+                state.hostContext.logger.warn(`dsh-tui: effect ledger record dropped (schema: ${error instanceof Error ? error.message : String(error)})`);
+                return;
+            }
+            mkdirSync(dirname(state.file), { recursive: true, mode: 0o700 });
+            appendFileSync(state.file, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+            state.sequence += 1;
+        }
+        catch (error) {
+            ;
+            (state?.hostContext ?? this.ctx).logger.warn('dsh-tui: effect ledger write failed');
+        }
+    }
+    /** Runtime generation (C-050): options override, else the plugin-host
+     *  service's id — resolved on first record and cached (the host row mounts
+     *  before any caller can record). */
+    generation() {
+        const state = ledgerStateFor(this);
+        if (state.optionsGenerationId !== undefined)
+            return state.optionsGenerationId;
+        state.generationId ??= state.hostContext.get('tuiPluginHost')?.generationId ?? 'unknown-generation';
+        return state.generationId;
+    }
+    /** Continue numbering after the existing file's max sequence (restart-safe). */
+    resumeSequence() {
+        return resumeSequence(ledgerStateFor(this).file);
+    }
+    fiberOf(identity) {
+        if (identity === undefined)
+            return undefined;
+        try {
+            const fiber = identity.fiber;
+            return typeof fiber === 'object' && fiber !== null ? fiber : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    pluginIdOf(identity, fiber, verifiedComponentId) {
+        if (identity === undefined)
+            return 'undeclared';
+        if (verifiedComponentId !== undefined)
+            return cleanField(verifiedComponentId, 128, 'undeclared');
+        let name = '';
+        try {
+            name = typeof identity.fiber?.name === 'string' ? identity.fiber.name : '';
+        }
+        catch {
+            name = '';
+        }
+        // A non-root fiber without a verified Component is intentionally not
+        // attributed by its Cordis export name.  Names are display metadata and
+        // can differ from the manifest identity (or be impersonated).
+        if (fiber === undefined || name === '' || name === 'root')
+            return 'host';
+        return 'undeclared';
+    }
+    activationOf(fiber, pluginId) {
+        // 'host'/'undeclared' are single-tenant identities (one root fiber per
+        // process; 'undeclared' has no fiber at all) — the constant instance id
+        // is exact; per-fiber ids only matter for plugin fibers.
+        if (fiber === undefined || pluginId === 'host' || pluginId === 'undeclared')
+            return pluginId;
+        const state = ledgerStateFor(this);
+        let activation = state.activations.get(fiber);
+        if (activation === undefined) {
+            activation = `activation-${state.nextActivation++}`;
+            state.activations.set(fiber, activation);
+        }
+        return activation;
+    }
+}
+const ledgerStates = new WeakMap();
+function ledgerStateFor(runtime) {
+    const state = ledgerStates.get(concreteService(runtime));
+    if (state === undefined)
+        throw new Error('tuiEffectLedger host state is unavailable');
+    return state;
+}
+/** Continue numbering after the existing file's max sequence (restart-safe). */
+function resumeSequence(file) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return 0; // missing file = fresh ledger, not corruption
+    }
+    let max = -1;
+    for (const line of text.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            const sequence = parsed.sequence;
+            if (typeof sequence === 'number' && Number.isInteger(sequence) && sequence > max)
+                max = sequence;
+        }
+        catch {
+            // Corrupt line: skip it (never rewritten — the bytes stay for manual
+            // recovery, same posture as plugin-storage).
+        }
+    }
+    return max + 1;
+}
+export default TuiEffectLedgerRuntime;