@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/plugin-storage.d.ts

@@ -0,0 +1,118 @@
+/**
+ * storage.local contract surface (C-040, `storage.dsh/v1alpha1#LocalStorage`):
+ * per-plugin private persistence, mounted by the dsh-tui-plugin-host row as
+ * `ctx.tuiPluginStorage`.
+ *
+ * The plugin-facing API is `open(ctx)` → `{ get, set, delete }`:
+ *
+ * - VERIFIED IDENTITY: the namespace is derived from the admitted Component
+ *   identity bound to the PASSED activation — there is no parameter to name
+ *   another plugin, so cross-plugin access is rejected by construction.
+ * - GRANTS AT CALL TIME: `get` requires `storage.local.read`, `set`/`delete`
+ *   require `storage.local.write` — checked per call against the live grant
+ *   store (a revoked grant blocks the very next operation without restart).
+ * - Backend: `~/.dsh-tui/plugin-storage/<namespace>.json`, one flat JSON
+ *   object per namespace. Writes go through dsh-atomic-write (`withFileLock`
+ *   for the read-modify-write cycle + `writeFileAtomic` for the commit), and
+ *   an in-process per-namespace promise chain serializes operations in
+ *   invocation order (contract concurrency rule — the lock alone does not
+ *   order contenders).
+ * - QUOTA (host-defined): 256 keys AND 256 KiB of serialized content per
+ *   namespace; a `set` that would cross either fails with QUOTA_EXCEEDED and
+ *   changes nothing.
+ * - Keys stay ordinary data even when they collide with Object.prototype
+ *   names ("__proto__", "toString", "constructor"): namespace tables are
+ *   null-prototype and membership is decided with Object.hasOwn. Values
+ *   must be EXACT JSON values — inputs JSON.stringify would silently
+ *   mutate (undefined, NaN/±Infinity, functions, class instances, sparse
+ *   arrays, cycles) are rejected instead of round-tripping a lie.
+ * - A corrupt namespace file is NEVER overwritten silently: every operation
+ *   fails with STORAGE_UNAVAILABLE and the bytes stay on disk for manual
+ *   recovery. Closing a handle (plugin unload) retains data (contract
+ *   cleanup rule); later calls on a closed handle fail STORAGE_UNAVAILABLE.
+ * - privacyClass: sensitive — keys AND values are never logged.
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { type GrantStore } from '../adapter/standard/grants.js';
+import type { TuiEffectLedgerRuntime } from './effect-ledger.js';
+/** Quota: max distinct keys per namespace. */
+export declare const STORAGE_MAX_KEYS = 256;
+/** Quota: max serialized file size per namespace (bytes). */
+export declare const STORAGE_MAX_BYTES: number;
+/** Max key length (characters). */
+export declare const STORAGE_KEY_MAX_LENGTH = 128;
+export type PluginStorageErrorCode = 'PERMISSION_NOT_GRANTED' | 'INVALID_KEY' | 'INVALID_VALUE' | 'QUOTA_EXCEEDED' | 'STORAGE_UNAVAILABLE';
+/** Storage failure with the contract's error code on `.code`. */
+export declare class PluginStorageError extends Error {
+    readonly code: PluginStorageErrorCode;
+    constructor(code: PluginStorageErrorCode, message: string);
+}
+/** The per-namespace handle returned by {@link TuiPluginStorageRuntime.open}. */
+export interface TuiPluginStorage {
+    get(input: {
+        key: string;
+    }): Promise<{
+        value: unknown | null;
+    }>;
+    set(input: {
+        key: string;
+        value: unknown;
+    }): Promise<{
+        stored: true;
+    }>;
+    delete(input: {
+        key: string;
+    }): Promise<{
+        deleted: boolean;
+    }>;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiPluginStorage: TuiPluginStorageRuntime;
+    }
+}
+/** Namespace directory under the data dir. */
+export declare const PLUGIN_STORAGE_DIR = "plugin-storage";
+/**
+ * Plugin name → safe, collision-free file name. encodeURIComponent keeps
+ * alphanumerics and `- _ . ! ~ * ' ( )`, so scoped names like `@foo/bar`
+ * encode reversibly; pathological results ('', '.', '..') map to '_'.
+ */
+export declare function storageFileName(plugin: string): string;
+/**
+ * `ctx.tuiPluginStorage` — storage.local contract surface. Mounted by the
+ * dsh-tui-plugin-host row; grants come from that row's store when present
+ * (normal path) or a private read otherwise (bare mounts in tests).
+ */
+export declare class TuiPluginStorageRuntime extends Service {
+    #private;
+    constructor(ctx: Context, options?: {
+        dir?: string;
+        grants?: GrantStore;
+        ledger?: TuiEffectLedgerRuntime;
+    });
+    /** Grants: the plugin-host row's store when mounted, else a private read.
+     *  Resolved PER CALL — sibling services mounted later by the same apply()
+     *  are not visible to constructors (cordis), so a constructor-time probe
+     *  would silently stick to the fallback. */
+    private grants;
+    /** Optional observability; a bare mount (tests) simply records nothing. */
+    private ledger;
+    /**
+     * Host-internal read-only diagnostic probe. Never opens a namespace, never
+     * writes to disk; it only confirms the mounted storage runtime is reachable.
+     */
+    probeDiagnostic(): {
+        service: 'tuiPluginStorage';
+        ok: true;
+        dir: string;
+    };
+    /**
+     * Open the caller's private namespace. Identity = the PASSED context's
+     * verified Component identity (no way to name another plugin). The handle
+     * closes automatically when the caller's context unloads (idempotent
+     * disposer); data is retained (contract cleanup rule).
+     */
+    open(pluginCtx: Context): TuiPluginStorage;
+}
+//# sourceMappingURL=plugin-storage.d.ts.map

package/lib/types/dsh-adapter/plugin-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-storage.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/plugin-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAkBtD,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAA;AAC/E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAGhE,8CAA8C;AAC9C,eAAO,MAAM,gBAAgB,MAAM,CAAA;AACnC,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB,QAAa,CAAA;AAC3C,mCAAmC;AACnC,eAAO,MAAM,sBAAsB,MAAM,CAAA;AAEzC,MAAM,MAAM,sBAAsB,GAC9B,wBAAwB,GACxB,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,qBAAqB,CAAA;AAEzB,iEAAiE;AACjE,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;gBACzB,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM;CAK1D;AAoBD,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC,CAAA;IAC/D,GAAG,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,IAAI,CAAA;KAAE,CAAC,CAAA;IACtE,MAAM,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAC9D;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,gBAAgB,EAAE,uBAAuB,CAAA;KAC1C;CACF;AAED,8CAA8C;AAC9C,eAAO,MAAM,kBAAkB,mBAAmB,CAAA;AAElD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGtD;AAgID;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,OAAO;;gBACtC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,UAAU,CAAC;QAAC,MAAM,CAAC,EAAE,sBAAsB,CAAA;KAAO;IAkB9G;;;gDAG4C;IAC5C,OAAO,CAAC,MAAM;IAKd,2EAA2E;IAC3E,OAAO,CAAC,MAAM;IAKd;;;OAGG;IACH,eAAe,IAAI;QAAE,OAAO,EAAE,kBAAkB,CAAC;QAAC,EAAE,EAAE,IAAI,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;IA4FzE;;;;;OAKG;IACH,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,gBAAgB;CAyN3C"}

package/lib/types/dsh-adapter/plugin-storage.js

@@ -0,0 +1,536 @@
+/**
+ * storage.local contract surface (C-040, `storage.dsh/v1alpha1#LocalStorage`):
+ * per-plugin private persistence, mounted by the dsh-tui-plugin-host row as
+ * `ctx.tuiPluginStorage`.
+ *
+ * The plugin-facing API is `open(ctx)` → `{ get, set, delete }`:
+ *
+ * - VERIFIED IDENTITY: the namespace is derived from the admitted Component
+ *   identity bound to the PASSED activation — there is no parameter to name
+ *   another plugin, so cross-plugin access is rejected by construction.
+ * - GRANTS AT CALL TIME: `get` requires `storage.local.read`, `set`/`delete`
+ *   require `storage.local.write` — checked per call against the live grant
+ *   store (a revoked grant blocks the very next operation without restart).
+ * - Backend: `~/.dsh-tui/plugin-storage/<namespace>.json`, one flat JSON
+ *   object per namespace. Writes go through dsh-atomic-write (`withFileLock`
+ *   for the read-modify-write cycle + `writeFileAtomic` for the commit), and
+ *   an in-process per-namespace promise chain serializes operations in
+ *   invocation order (contract concurrency rule — the lock alone does not
+ *   order contenders).
+ * - QUOTA (host-defined): 256 keys AND 256 KiB of serialized content per
+ *   namespace; a `set` that would cross either fails with QUOTA_EXCEEDED and
+ *   changes nothing.
+ * - Keys stay ordinary data even when they collide with Object.prototype
+ *   names ("__proto__", "toString", "constructor"): namespace tables are
+ *   null-prototype and membership is decided with Object.hasOwn. Values
+ *   must be EXACT JSON values — inputs JSON.stringify would silently
+ *   mutate (undefined, NaN/±Infinity, functions, class instances, sparse
+ *   arrays, cycles) are rejected instead of round-tripping a lie.
+ * - A corrupt namespace file is NEVER overwritten silently: every operation
+ *   fails with STORAGE_UNAVAILABLE and the bytes stay on disk for manual
+ *   recovery. Closing a handle (plugin unload) retains data (contract
+ *   cleanup rule); later calls on a closed handle fail STORAGE_UNAVAILABLE.
+ * - privacyClass: sensitive — keys AND values are never logged.
+ */
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeFileAtomic, withFileLock } from '@deepseek-ai/dsh-atomic-write';
+import { Service } from '@deepseek-ai/cordis';
+import { validateDeleteInput, validateGetInput, validateSetInput, validateGetOutput, validateSetOutput, validateDeleteOutput, } from '../adapter/standard/protocols.js';
+import { DATA_DIR } from '../utils/paths.js';
+import { assertCapabilityShadowPolicy, } from '../adapter/kernel/runtime.js';
+import { adapterRuntimeFor } from '../adapter/kernel/runtime-context.js';
+import { activationContext, assertCallerContext, bindCallerEffect, compositionRoot, concreteService } from './host-access.js';
+import { registerStorageLiveProbe } from '../adapter/kernel/host-probe-access.js';
+import { declaresPermission, requireComponentIdentity, requiresContract } from './component-identity.js';
+import { readGrantStore } from '../adapter/standard/grants.js';
+import { getHostGrantStore } from './host-grants.js';
+/** Quota: max distinct keys per namespace. */
+export const STORAGE_MAX_KEYS = 256;
+/** Quota: max serialized file size per namespace (bytes). */
+export const STORAGE_MAX_BYTES = 256 * 1024;
+/** Max key length (characters). */
+export const STORAGE_KEY_MAX_LENGTH = 128;
+/** Storage failure with the contract's error code on `.code`. */
+export class PluginStorageError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PluginStorageError';
+        this.code = code;
+    }
+}
+const storageStates = new WeakMap();
+function storageStateFor(runtime) {
+    const state = storageStates.get(concreteService(runtime));
+    if (state === undefined)
+        throw new Error('tuiPluginStorage host state is unavailable');
+    return state;
+}
+/** Namespace directory under the data dir. */
+export const PLUGIN_STORAGE_DIR = 'plugin-storage';
+/**
+ * Plugin name → safe, collision-free file name. encodeURIComponent keeps
+ * alphanumerics and `- _ . ! ~ * ' ( )`, so scoped names like `@foo/bar`
+ * encode reversibly; pathological results ('', '.', '..') map to '_'.
+ */
+export function storageFileName(plugin) {
+    const encoded = encodeURIComponent(plugin);
+    return encoded === '' || encoded === '.' || encoded === '..' ? '_' : encoded;
+}
+function assertKey(key) {
+    if (typeof key !== 'string' || key === '' || key.length > STORAGE_KEY_MAX_LENGTH || /[\x00-\x1f\x7f-\x9f]/.test(key)) {
+        throw new PluginStorageError('INVALID_KEY', 'storage keys are non-empty control-free strings of at most 128 characters');
+    }
+}
+function validateStorageInput(operation, input) {
+    try {
+        if (operation === 'get')
+            validateGetInput(input);
+        else if (operation === 'set')
+            validateSetInput(input);
+        else
+            validateDeleteInput(input);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (operation !== 'set')
+            throw new PluginStorageError('INVALID_KEY', message);
+        // The standard validator intentionally reports exact-record failures in a
+        // single stream. Preserve the contract's distinction: malformed/missing
+        // `key` is INVALID_KEY; once the key itself is valid, every value/shape
+        // failure (including a missing `value`) is INVALID_VALUE.
+        let keyValid = false;
+        try {
+            const candidate = input;
+            assertKey(candidate?.key);
+            keyValid = true;
+        }
+        catch {
+            keyValid = false;
+        }
+        throw new PluginStorageError(keyValid ? 'INVALID_VALUE' : 'INVALID_KEY', message);
+    }
+}
+/**
+ * Exact JSON values only. JSON.stringify silently MUTATES edge inputs
+ * (NaN/±Infinity → null, undefined array items → null, undefined object
+ * properties dropped, class instances reduced to own fields) — a storage
+ * contract must not round-trip a value the caller never stored, so those
+ * inputs are rejected instead. Accepts: null, boolean, string, finite
+ * number, arrays (dense), and plain objects (Object.prototype or null
+ * prototype only). Every own property is inspected because JSON.stringify
+ * ignores array side-properties, symbols, and non-enumerable fields, while
+ * accessors/toJSON can replace the value being serialized. Those inputs,
+ * cycles, and anything whose inspection throws are rejected.
+ */
+function assertJsonValue(value) {
+    let ok = false;
+    try {
+        ok = isJsonValue(value, new Set());
+    }
+    catch {
+        ok = false;
+    }
+    if (!ok) {
+        throw new PluginStorageError('INVALID_VALUE', 'storage values must be exact JSON values (no undefined, functions, symbols, BigInt, NaN/Infinity, class instances, sparse arrays, or cycles)');
+    }
+}
+function isJsonValue(value, seen) {
+    if (value === null)
+        return true;
+    switch (typeof value) {
+        case 'boolean':
+        case 'string':
+            return true;
+        case 'number':
+            return Number.isFinite(value);
+        case 'object': {
+            const object = value;
+            if (seen.has(object))
+                return false;
+            seen.add(object);
+            try {
+                if (Array.isArray(value)) {
+                    // Array subclasses/custom prototypes can supply an inherited toJSON
+                    // hook. JSON would serialize its replacement, not this array.
+                    if (Object.getPrototypeOf(value) !== Array.prototype)
+                        return false;
+                    if (Object.getOwnPropertySymbols(value).length > 0)
+                        return false;
+                    const ownNames = Object.getOwnPropertyNames(value);
+                    for (const name of ownNames) {
+                        if (name === 'length')
+                            continue;
+                        const descriptor = Object.getOwnPropertyDescriptor(value, name);
+                        // JSON arrays serialize only their indexed elements. Any other
+                        // own property (especially toJSON) would be silently lost.
+                        const index = Number(name);
+                        if (descriptor === undefined || !('value' in descriptor) ||
+                            !Number.isSafeInteger(index) || index < 0 || String(index) !== name || index >= value.length)
+                            return false;
+                    }
+                    for (let index = 0; index < value.length; index++) {
+                        // A sparse hole would serialize as null — a value never stored.
+                        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+                        if (descriptor === undefined || !('value' in descriptor))
+                            return false;
+                        if (!isJsonValue(descriptor.value, seen))
+                            return false;
+                    }
+                    return true;
+                }
+                const proto = Object.getPrototypeOf(value);
+                if (proto !== Object.prototype && proto !== null)
+                    return false;
+                // A modified Object.prototype can add an inherited toJSON hook; own
+                // non-enumerable/accessor properties are likewise not exact JSON.
+                if (typeof value.toJSON === 'function')
+                    return false;
+                if (Object.getOwnPropertySymbols(value).length > 0)
+                    return false;
+                for (const name of Object.getOwnPropertyNames(value)) {
+                    const descriptor = Object.getOwnPropertyDescriptor(value, name);
+                    if (descriptor === undefined || !descriptor.enumerable || !('value' in descriptor))
+                        return false;
+                    if (!isJsonValue(descriptor.value, seen))
+                        return false;
+                }
+                return true;
+            }
+            finally {
+                // DAGs (shared references without cycles) serialize fine — only
+                // reject a value reachable from ITSELF.
+                seen.delete(object);
+            }
+        }
+        default:
+            // undefined / function / symbol / bigint
+            return false;
+    }
+}
+/**
+ * `ctx.tuiPluginStorage` — storage.local contract surface. Mounted by the
+ * dsh-tui-plugin-host row; grants come from that row's store when present
+ * (normal path) or a private read otherwise (bare mounts in tests).
+ */
+export class TuiPluginStorageRuntime extends Service {
+    constructor(ctx, options = {}) {
+        super(ctx, 'tuiPluginStorage');
+        storageStates.set(this, {
+            hostContext: compositionRoot(ctx),
+            grantsOption: options.grants,
+            fallbackGrants: readGrantStore(undefined, undefined, adapterRuntimeFor(ctx)),
+            ledgerOption: options.ledger,
+            runtime: adapterRuntimeFor(ctx),
+            namespaces: new Map(),
+            dir: options.dir ?? join(DATA_DIR, PLUGIN_STORAGE_DIR),
+        });
+        // Host-only live probe runner. The method is a private ECMAScript member;
+        // plugin-visible Cordis proxies and public types never see a
+        // `probeReversible` entry. Only the internal host-probe accessor (with the
+        // host token) can invoke it.
+        registerStorageLiveProbe(this, () => this.#runReversibleProbe());
+    }
+    /** Grants: the plugin-host row's store when mounted, else a private read.
+     *  Resolved PER CALL — sibling services mounted later by the same apply()
+     *  are not visible to constructors (cordis), so a constructor-time probe
+     *  would silently stick to the fallback. */
+    grants() {
+        const state = storageStateFor(this);
+        return state.grantsOption ?? getHostGrantStore(state.hostContext.get('tuiPluginHost')) ?? state.fallbackGrants;
+    }
+    /** Optional observability; a bare mount (tests) simply records nothing. */
+    ledger() {
+        const state = storageStateFor(this);
+        return state.ledgerOption ?? state.hostContext.get('tuiEffectLedger');
+    }
+    /**
+     * Host-internal read-only diagnostic probe. Never opens a namespace, never
+     * writes to disk; it only confirms the mounted storage runtime is reachable.
+     */
+    probeDiagnostic() {
+        assertCapabilityShadowPolicy('host.storage.probe', storageStateFor(this).runtime.mode, storageStateFor(this).runtime.slices);
+        const state = storageStateFor(this);
+        return Object.freeze({
+            service: 'tuiPluginStorage',
+            ok: true,
+            dir: state.dir,
+        });
+    }
+    /**
+     * Host-internal reversible live probe.
+     *
+     * This runs through the same production storage handle path as plugin
+     * storage (`#openInternal`), using a random temporary namespace. It writes a
+     * tiny JSON document, reads it back, deletes it, and guarantees the file is
+     * removed in a `finally`. The probe deliberately bypasses only the
+     * caller-facing grant/lifecycle bookkeeping; key validation, exact-JSON
+     * validation, quota checks and namespace I/O are the production code.
+     *
+     * Side-effect boundary: the probe file and in-process namespace entry are
+     * removed before this method returns; the storage directory itself is
+     * retained. In passive/replay shadow the capability guard denies this before
+     * any file operation.
+     *
+     * This is an ECMAScript private method. It is reachable only through the
+     * host-only probe accessor registered in the constructor.
+     */
+    async #runReversibleProbe() {
+        assertCapabilityShadowPolicy('host.storage.liveProbe', storageStateFor(this).runtime.mode, storageStateFor(this).runtime.slices);
+        const state = storageStateFor(this);
+        const tempNamespace = `__dsh_tui_live_probe_${randomUUID().replace(/-/g, '')}`;
+        const file = join(state.dir, `${storageFileName(tempNamespace)}.json`);
+        const operations = [];
+        const identity = {
+            componentId: tempNamespace,
+            activationId: tempNamespace,
+            version: '0.0.0',
+            facet: 'host',
+            manifest: { id: tempNamespace },
+            projection: { id: tempNamespace },
+        };
+        const handle = concreteService(this).#openInternal(state.hostContext, identity, tempNamespace, {
+            enforceGrants: false,
+            bindLifecycle: false,
+            recordLedger: false,
+        });
+        const dirExisted = existsSync(state.dir);
+        try {
+            await handle.set({ key: 'probe', value: { ok: true } });
+            operations.push('write');
+            const read = await handle.get({ key: 'probe' });
+            const parsed = read.value;
+            if (parsed?.ok !== true)
+                throw new Error('temporary storage probe document did not round-trip through the production handle');
+            operations.push('read');
+            const deleted = await handle.delete({ key: 'probe' });
+            if (!deleted.deleted)
+                throw new Error('temporary storage probe key was not deleted through the production handle');
+            operations.push('delete');
+            return Object.freeze({
+                service: 'tuiPluginStorage',
+                ok: true,
+                operations: Object.freeze(operations),
+                tempNamespace,
+            });
+        }
+        catch (error) {
+            throw new PluginStorageError('STORAGE_UNAVAILABLE', `storage reversible probe failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            state.namespaces.delete(tempNamespace);
+            try {
+                unlinkSync(file);
+            }
+            catch {
+                // Cleanup is best-effort; the file is namespaced by a fresh UUID and
+                // cannot be confused with a real plugin namespace.
+            }
+            if (!dirExisted) {
+                try {
+                    if (existsSync(state.dir))
+                        rmdirSync(state.dir);
+                }
+                catch {
+                    // The probe must not remove a non-empty pre-existing user directory.
+                }
+            }
+        }
+    }
+    /**
+     * Open the caller's private namespace. Identity = the PASSED context's
+     * verified Component identity (no way to name another plugin). The handle
+     * closes automatically when the caller's context unloads (idempotent
+     * disposer); data is retained (contract cleanup rule).
+     */
+    open(pluginCtx) {
+        assertCapabilityShadowPolicy('host.storage.open', storageStateFor(this).runtime.mode, storageStateFor(this).runtime.slices);
+        const caller = activationContext(pluginCtx);
+        if (caller === undefined)
+            throw new PluginStorageError('STORAGE_UNAVAILABLE', 'storage.local.open requires a live activation context');
+        assertCallerContext(this.ctx, caller, 'storage.local.open', this);
+        const state = storageStateFor(this);
+        const identity = requireComponentIdentity(caller);
+        if (!requiresContract(identity, 'storage.dsh/v1alpha1', 'LocalStorage')) {
+            throw new PluginStorageError('PERMISSION_NOT_GRANTED', 'storage.local requires the storage.dsh/v1alpha1#LocalStorage contract in the admitted manifest');
+        }
+        // Cordis hands the service out through a Proxy, so `this` is not branded:
+        // unwrap to the concrete instance before calling the `#private` member
+        // (same pattern as message-observer's `#registerSubscription`).
+        return concreteService(this).#openInternal(caller, identity, identity.componentId, {
+            enforceGrants: true,
+            bindLifecycle: true,
+            recordLedger: true,
+        });
+    }
+    /**
+     * Internal production storage-path implementation shared by the public
+     * `open()` surface and the reversible live probe. The probe passes a
+     * synthetic temporary identity and disables only the caller-facing
+     * authorization/lifecycle bookkeeping; all key validation, exact-JSON
+     * validation, namespace file handling, quota checks and read/write/delete
+     * operations are exactly the production handle code.
+     *
+     * A true `#private` member, not TS `private`: the latter still compiles to a
+     * prototype method, so a plugin holding `ctx.tuiPluginStorage` could call it
+     * through `as any` with `enforceGrants: false` and a forged namespace and
+     * read another component's storage with no grant, ledger entry or unload
+     * cleanup. Only the two in-class call sites above may reach it.
+     */
+    #openInternal(caller, identity, plugin, options) {
+        const state = storageStateFor(this);
+        const runtime = state.runtime;
+        let namespace = state.namespaces.get(plugin);
+        if (namespace === undefined) {
+            namespace = { chain: Promise.resolve() };
+            state.namespaces.set(plugin, namespace);
+        }
+        if (options.recordLedger) {
+            this.ledger()?.record({ operation: 'create', resource: { kind: 'storage-namespace', id: plugin }, result: 'applied' }, caller);
+        }
+        // `closed` is PER HANDLE, not per namespace: unloading one fiber must not
+        // kill another handle opened on the same namespace. Close on unload;
+        // idempotent (a double-close stays harmless by design).
+        let closed = false;
+        const close = () => {
+            if (closed)
+                return;
+            closed = true;
+            if (options.recordLedger) {
+                this.ledger()?.record({ operation: 'release', resource: { kind: 'storage-namespace', id: plugin }, result: 'applied' }, caller);
+            }
+        };
+        if (options.bindLifecycle)
+            bindCallerEffect(caller, close);
+        const file = join(state.dir, `${storageFileName(plugin)}.json`);
+        const grants = () => this.grants();
+        const ledger = () => this.ledger();
+        const enqueue = (operation) => {
+            if (closed) {
+                return Promise.reject(new PluginStorageError('STORAGE_UNAVAILABLE', `storage namespace "${plugin}" handle is closed`));
+            }
+            const run = namespace.chain.then(operation);
+            // Keep the chain alive after a failure without unhandled rejections.
+            namespace.chain = run.catch(() => { });
+            return run;
+        };
+        const readTable = () => {
+            let raw;
+            try {
+                raw = readFileSync(file, 'utf8');
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return Object.create(null);
+                throw new PluginStorageError('STORAGE_UNAVAILABLE', `storage namespace "${plugin}" is unreadable; the file was left untouched for manual recovery`);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                throw new PluginStorageError('STORAGE_UNAVAILABLE', `storage namespace "${plugin}" is corrupt on disk; the file was left untouched for manual recovery`);
+            }
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                throw new PluginStorageError('STORAGE_UNAVAILABLE', `storage namespace "${plugin}" holds a non-object document; the file was left untouched for manual recovery`);
+            }
+            // Rebuild on a NULL-PROTOTYPE table: key membership is decided with
+            // Object.hasOwn, and keys like "__proto__" / "toString" must behave
+            // as ordinary data (a prototype-chain read would leak host objects
+            // into plugin results and fake membership for never-stored keys).
+            const table = Object.create(null);
+            for (const [key, value] of Object.entries(parsed))
+                table[key] = value;
+            return table;
+        };
+        const requireGrant = (permission) => {
+            if (options.enforceGrants
+                && (!declaresPermission(identity, permission, plugin)
+                    || !grants().allows({ componentId: identity.componentId, activationId: identity.activationId }, permission, plugin))) {
+                ledger()?.record({
+                    operation: 'bind',
+                    resource: { kind: 'permission', id: permission },
+                    result: 'failed',
+                    errorCode: 'PERMISSION_NOT_GRANTED',
+                }, caller);
+                throw new PluginStorageError('PERMISSION_NOT_GRANTED', `storage.${permission.endsWith('.read') ? 'get' : 'set/delete'} from plugin "${plugin}" denied — grant "${permission}" ` +
+                    `for "${plugin}" in ~/.dsh-tui/extension-grants.json first`);
+            }
+        };
+        // withFileLock creates its lock as a SIBLING of the file and does not
+        // create parent directories — ensure the tree exists before any write
+        // path (read paths tolerate ENOENT as an empty namespace and never
+        // materialize the tree).
+        const ensureDir = () => {
+            mkdirSync(state.dir, { recursive: true, mode: 0o700 });
+        };
+        return {
+            get: (input) => enqueue(async () => {
+                assertCapabilityShadowPolicy('host.storage.read', runtime.mode, runtime.slices);
+                validateStorageInput('get', input);
+                const key = input.key;
+                assertKey(key);
+                requireGrant('storage.local.read');
+                const table = readTable();
+                const output = { value: Object.hasOwn(table, key) ? table[key] : null };
+                try {
+                    validateGetOutput(output);
+                }
+                catch {
+                    throw new PluginStorageError('STORAGE_UNAVAILABLE', `storage namespace "${plugin}" contains an invalid JSON value`);
+                }
+                return output;
+            }),
+            set: (input) => enqueue(async () => {
+                assertCapabilityShadowPolicy('host.storage.write', runtime.mode, runtime.slices);
+                validateStorageInput('set', input);
+                const key = input.key;
+                const value = input.value;
+                assertKey(key);
+                assertJsonValue(value);
+                requireGrant('storage.local.write');
+                ensureDir();
+                return withFileLock(file, async () => {
+                    const table = readTable();
+                    const isNewKey = !Object.hasOwn(table, key);
+                    if (isNewKey && Object.keys(table).length >= STORAGE_MAX_KEYS) {
+                        throw new PluginStorageError('QUOTA_EXCEEDED', `storage namespace "${plugin}" holds ${STORAGE_MAX_KEYS} keys already`);
+                    }
+                    table[key] = value;
+                    const content = JSON.stringify(table);
+                    if (Buffer.byteLength(content, 'utf8') > STORAGE_MAX_BYTES) {
+                        throw new PluginStorageError('QUOTA_EXCEEDED', `storage namespace "${plugin}" would exceed ${STORAGE_MAX_BYTES} bytes`);
+                    }
+                    // 0o600/0o700: the namespace is privacyClass sensitive.
+                    await writeFileAtomic(file, content, { mode: 0o600, dirMode: 0o700 });
+                    const output = { stored: true };
+                    validateSetOutput(output);
+                    return output;
+                });
+            }),
+            delete: (input) => enqueue(async () => {
+                assertCapabilityShadowPolicy('host.storage.write', runtime.mode, runtime.slices);
+                validateStorageInput('delete', input);
+                const key = input.key;
+                assertKey(key);
+                requireGrant('storage.local.write');
+                ensureDir();
+                return withFileLock(file, async () => {
+                    const table = readTable();
+                    if (!Object.hasOwn(table, key)) {
+                        const output = { deleted: false };
+                        validateDeleteOutput(output);
+                        return output;
+                    }
+                    delete table[key];
+                    await writeFileAtomic(file, JSON.stringify(table), { mode: 0o600, dirMode: 0o700 });
+                    const output = { deleted: true };
+                    validateDeleteOutput(output);
+                    return output;
+                });
+            }),
+        };
+    }
+}