@lmzhen/dsh-evolution-core 0.26.26 → 0.27.1

package/lib/types/write-gates.js

@@ -0,0 +1,344 @@
+/**
+ * The write-admission sequence: ONE ordered table of the reasons a skill write is refused.
+ *
+ * Two points read this table (design `dsh-evolution-write-gate-design.md` §3). The ADMISSION
+ * point (`execute`, BEFORE the approval seam) runs every gate that applies to `'admission'`, so a
+ * write that is refused is never staged and never spends the operator's attention twice. The
+ * EXECUTION point (the `executeCore` funnel, reached by the direct path and by the approval
+ * replay) runs the gates that apply to `'execution'`: the stored plan of a replayed write passed
+ * no schema, and the protected list can change while a record sits pending, so those verdicts are
+ * re-decided at the bytes.
+ *
+ * Order is part of the contract: a gate that can only refuse comes before one that needs a round
+ * trip with the operator, so a write that is refused anyway never asks anything.
+ *
+ * A gate decides whether a write may be ATTEMPTED. The library decides whether it can be
+ * PERFORMED — its own structured refusals (a restructure element that is not an object, a patch
+ * anchor that no longer matches, an `absorbed_into` that does not exist) stay where the bytes are
+ * read.
+ *
+ * Rule bodies live in `evolution-core` (the read-before-write rule in `skill-reads`, the
+ * required-argument table in `SKILL_ACTION_REQUIRED_FIELDS`); this module owns the ORDER and the
+ * applicability of each gate, which is an execution-point fact of this tool.
+ * @module @lmzhen/dsh-evolution-core/write-gates
+ */
+import { DEFAULT_WRITE_CONFIRM_MODE, DEFAULT_WRITE_CONFIRM_TIMEOUT_SECONDS } from "./write-authority.js";
+import { SKILL_ACTION_REQUIRED_FIELDS, errorText, isUnreadWrite } from "./index.js";
+/** The confirm question's stable id — one question per write, so an answer to an earlier prompt
+ * can never be read as the answer to a later one. */
+const CONFIRM_QUESTION_ID = 'evolution-skill-write';
+/** The cancel label every confirm question offers. */
+const CANCEL_LABEL = '取消';
+/** What a `timeout`-mode deadline settles with: comparable by identity against the seam's
+ * boolean, so the two outcomes stay distinguishable without a mutable flag (which a linter
+ * cannot follow through a timer callback, and a reader cannot either). */
+const CONFIRM_TIMED_OUT = 'confirm-timed-out';
+/**
+ * How the ONE confirmation behaves (registry `skillWriteConfirm`).
+ *
+ * `auto` writes without asking — the default, because an unattended run (a background pass, a
+ * scheduled review, a headless session) must not park a tool call on a question nobody will answer.
+ * `ask` waits for as long as it takes, which is the deployment that wants the gate in the loop.
+ * `timeout` asks and cancels the write on its own deadline.
+ */
+// G1/1.1: the confirm vocabulary lives in write-authority.ts with the authority that carries it.
+// D-09 follow-up: this file used to RE-EXPORT it for compatibility, which made index.ts export the same
+// name from two modules (TS2308: WriteConfirmMode/WriteConfirmRequest/DEFAULT_WRITE_CONFIRM_MODE).
+// The names stay reachable through the package root via write-authority - one owner, no second export.
+/** A usable deadline: the configured value when it is a positive finite number, else the default. */
+function timeoutSecondsOf(configured) {
+    return configured !== undefined && Number.isFinite(configured) && configured >= 1
+        ? Math.floor(configured)
+        : DEFAULT_WRITE_CONFIRM_TIMEOUT_SECONDS;
+}
+/** The scalar fields the tool schema types as strings; the replay channel has no schema.
+ * `action` is one of them: a non-string action used to fall through to the library as "Unknown
+ * action" while the read gate re-defaulted it to `patch` and refused with E-318 (review
+ * 2026-09-26, P2), so the shape gate refuses it by name instead. */
+const SCALAR_ARG_FIELDS = ['action', 'name', 'content', 'old_string', 'new_string', 'file_path', 'file_content', 'absorbed_into'];
+/** The scalar fields the tool schema types as BOOLEANS; the replay channel has no schema either.
+ * T2-V3/A28: `args.replace_all === true` answered "false" for anything else, so a staged
+ * `replace_all: 'yes'` silently patched only the FIRST occurrence — a wrong count with no signal.
+ * The plan channel already refuses a non-boolean `replace_all` by name (S1-C1); this is the same
+ * rule on the replay channel, so the two channels cannot disagree about one flag. */
+const FLAG_ARG_FIELDS = ['replace_all'];
+/**
+ * Assemble a gate context from a caller's services. The protected list is read HERE, so no caller can
+ * forget it or read it from a second place.
+ * @param services - the four required services plus the optional registry knobs.
+ * @param request - the point asking, the arguments under test, and the write origin.
+ * @returns a context the shared sequence accepts.
+ */
+export function skillWriteGateContext(services, request) {
+    return {
+        point: request.point,
+        args: request.args,
+        origin: request.origin,
+        protectedNames: protectedSkillNamesOf(services.policy),
+        readNames: services.readNames,
+        confirm: services.confirm,
+        ...(services.confirmMode === undefined ? {} : { confirmMode: services.confirmMode }),
+        ...(services.confirmTimeoutSeconds === undefined ? {} : { confirmTimeoutSeconds: services.confirmTimeoutSeconds }),
+        ...(services.describeTarget === undefined ? {} : { describeTarget: services.describeTarget }),
+        warn: services.warn,
+    };
+}
+export function protectedSkillNamesOf(policy) {
+    const snapshot = policy?.get?.();
+    return snapshot?.protectedSkillNames;
+}
+/**
+ * Narrow the arguments once for every gate.
+ *
+ * The admission point reaches the gates AFTER the schema, the replay channel BEFORE any
+ * validation, so a gate reads only what it can prove: anything else counts as absent, exactly as
+ * the missing-argument check already treated a non-string action.
+ * @param args - the arguments as the caller sent them.
+ * @returns the narrowed view.
+ */
+function gateArgsOf(args) {
+    const scalars = (typeof args === 'object' && args !== null ? args : {});
+    const action = scalars.action;
+    const name = scalars.name;
+    const absorbedInto = scalars.absorbed_into;
+    return {
+        action: typeof action === 'string' ? action : undefined,
+        name: typeof name === 'string' ? name : '',
+        // A BLANK absorbed_into is absent: the plan validator reads it the same way
+        // (`!(op.absorbed_into ?? '').trim()`), and the archive call itself is truthiness-based
+        // (`args.absorbed_into ? { absorbedInto } : {}`) — so `''` performs a BARE archive and must not
+        // borrow the merge exemption (review 2026-09-26, P1).
+        absorbedInto: typeof absorbedInto === 'string' && absorbedInto.trim() !== '' ? absorbedInto : undefined,
+        scalars,
+    };
+}
+/**
+ * The scalar arguments must be strings before any other gate reads them as names.
+ *
+ * v20 (D-1, V8-09 sibling): the schema does not strictly guarantee scalar shapes (the F-07 class
+ * of garbage that slipped past it), and a non-string scalar used to escape as a bare TypeError
+ * from SkillLibrary (`name.trim()` / `md.includes(...)`). Family posture: a STRUCTURED refusal.
+ * Absent is legal — the branches that need a value have their own remedies.
+ */
+const ARGUMENT_SHAPE = {
+    id: 'argument-shape',
+    appliesTo: ['admission', 'execution'],
+    run: ({ view }) => {
+        for (const field of SCALAR_ARG_FIELDS) {
+            const value = view.scalars[field];
+            if (value === undefined || value === null || typeof value === 'string')
+                continue;
+            return `skill_manage: "${field}" must be a string (got ${typeof value}); refusing the write.`;
+        }
+        // T2-V3/A28: the FLAGS are shapes too. A non-boolean `replace_all` used to mean "false" at the
+        // patch site, so the write landed with a different count than the caller asked for.
+        for (const field of FLAG_ARG_FIELDS) {
+            const value = view.scalars[field];
+            if (value === undefined || value === null || typeof value === 'boolean')
+                continue;
+            return `skill_manage: "${field}" must be a boolean (got ${typeof value}); refusing the write.`;
+        }
+        return null;
+    },
+};
+/**
+ * V27 G5.1 (v27 T-2) / OPT-05 (2026-09): name the missing per-action arguments before anything is
+ * read or written. The table comes from core (the plan validator reads the same rows), and the
+ * OWN-property narrowing is required because a plain-object index resolves inherited members
+ * (`constructor`, `toString`, …) to truthy functions. An EMPTY string is deliberately NOT
+ * missing: it reaches the library, whose branch messages carry the more specific remedy.
+ */
+const MISSING_ARGS = {
+    id: 'missing-args',
+    appliesTo: ['admission', 'execution'],
+    run: ({ view }) => {
+        const action = view.action;
+        const required = action === undefined || !Object.hasOwn(SKILL_ACTION_REQUIRED_FIELDS, action)
+            ? []
+            : SKILL_ACTION_REQUIRED_FIELDS[action] ?? [];
+        const missing = required.filter(field => view.scalars[field] === undefined || view.scalars[field] === null);
+        if (missing.length === 0)
+            return null;
+        return `skill_manage ${action} requires ${missing.join(', ')}; the tool description lists the arguments per action.`;
+    },
+};
+/**
+ * v30 REV-02: the immutable policy's protected list is enforced at plan validation, but the
+ * replay channel executes STORED plans — one accepted under an older policy must not land on a
+ * skill the CURRENT policy protects. Foreground (operator) writes are deliberately not gated by
+ * this list, and a deployment without the policy row keeps the previous behavior.
+ */
+const POLICY_PROTECTION = {
+    id: 'policy-protection',
+    appliesTo: ['admission', 'execution'],
+    run: ({ view, origin, protectedNames }) => {
+        if (origin === 'foreground')
+            return null;
+        if (view.name === '' || !protectedNames?.includes(view.name))
+            return null;
+        return `skill_manage: "${view.name}" is protected by the current policy (protectedSkillNames); replayed/autonomous writes are refused.`;
+    },
+};
+/**
+ * Read-before-write (design §4.2): a non-foreground write must have read its target in the
+ * session that authored it, so a subagent or the review's own model cannot blind-overwrite a body
+ * it never saw. The read set comes from `collectReadSkillNames`, which counts only a read that did
+ * not fail — a failed or timed-out read does not pass this gate.
+ *
+ * Admission only. The reads belong to the WRITING session, and the replayed record has none: it
+ * passed this gate at its own staging point, or the review's plan filter on the plan path.
+ *
+ * An unreadable session log is NOT an empty read set: the write proceeds with one warning, the
+ * same soft-probe posture as the cross-source check, because a deployment whose sessions expose no
+ * log must not refuse every autonomous write.
+ */
+const READ_BEFORE_WRITE = {
+    id: 'read-before-write',
+    appliesTo: ['admission'],
+    run: ({ view, origin, readNames, warn }) => {
+        if (origin === 'foreground')
+            return null;
+        if (readNames === undefined) {
+            warn('skill_manage: the read-before-write check could not run for this call — the session log is not readable here, so the write is allowed.');
+            return null;
+        }
+        // A missing action is NOT this gate's business: the tool schema requires one, so an absent
+        // action is a malformed call whose refusal the LIBRARY owns ("Unknown action") — answering
+        // E-318 would send the model to read a skill for a call that cannot work (review 2026-09-26,
+        // P2). The rule's default-to-`patch` (V6-26) stays where it belongs, on the plan path.
+        if (view.action === undefined)
+            return null;
+        if (!isUnreadWrite({ action: view.action, name: view.name }, readNames))
+            return null;
+        return errorText('e-318-skill-write-without-a-read', { a1: view.name });
+    },
+};
+/**
+ * The confirm gate (design §4.1): a foreground create, or a bare foreground delete, is
+ * irreversible and gets ONE question. Admission only — a replayed record already carries the human
+ * release that staged it, so asking there would be the second interruption for one write.
+ *
+ * `delete` with `absorbed_into` is exempt: that is the merge protocol (an umbrella absorbs the source),
+ * and asking once per absorbed skill would turn one merge into N questions. A BARE delete is the
+ * destructive primitive the plan layer reserves for a human — a review may only delete into an
+ * umbrella (core's `SKILL_ACTION_REQUIRED_FIELDS` docblock).
+ *
+ * The gate is UX, not a security door (those are policy protection and read-before-write): the seam
+ * is required to be total, so an unmounted question service or a caller that is not the live root
+ * agent PROCEEDS — the operator's own session is the authority that asked for the write.
+ *
+ * Whether the question is put at all is CONFIGURED (`skillWriteConfirm`): `auto` writes without
+ * asking, `ask` waits for an answer indefinitely (what this gate did before the knob existed), and
+ * `timeout` asks but cancels the write on its own deadline. `auto` is the default because an
+ * unattended run — a background pass, a scheduled review, a headless session — must not park a tool
+ * call on a question nobody will answer.
+ */
+const HUMAN_CONFIRM = {
+    id: 'human-confirm',
+    appliesTo: ['admission'],
+    run: async ({ view, origin, confirm, warn, confirmMode, confirmTimeoutSeconds, describeTarget }) => {
+        const action = view.action;
+        if (action === undefined || origin !== 'foreground' || view.name === '')
+            return null;
+        const destructive = action === 'create' || (action === 'delete' && view.absorbedInto === undefined);
+        if (!destructive)
+            return null;
+        const mode = confirmMode ?? DEFAULT_WRITE_CONFIRM_MODE;
+        if (mode === 'auto')
+            return null;
+        if (confirm === undefined) {
+            warn('skill_manage: no confirmation channel is mounted, so the write proceeds unconfirmed.');
+            return null;
+        }
+        const confirmLabel = action === 'create' ? '创建' : '删除';
+        const seconds = timeoutSecondsOf(confirmTimeoutSeconds);
+        const cancel = new AbortController();
+        // The deadline is enforced HERE, not only carried by the signal: the signal lets the client
+        // take the card down, while the race guarantees the call returns even if nothing is listening
+        // to it — a prompt that outlives its deadline is the parked tool call this mode exists to
+        // prevent.
+        let timer;
+        const deadline = mode === 'timeout'
+            ? new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    cancel.abort();
+                    resolve(CONFIRM_TIMED_OUT);
+                }, seconds * 1000);
+                // Never hold the process open: a one-shot CLI run must not linger for the rest of the
+                // window after the write already returned. A server keeps the loop alive anyway, which is
+                // where the deadline does its work.
+                timer.unref();
+            })
+            : undefined;
+        // The question says what the OPERATOR needs: the consequence, then the target in its own words.
+        // Asking for a decision by name alone is asking someone to authorize an unknown artifact.
+        const context = await describeTarget?.();
+        const details = [
+            context?.description === undefined || context.description === '' ? null : '功能：' + context.description,
+            context?.versions === undefined ? null : '已记录的内容版本数：' + String(context.versions),
+        ].filter((line) => line !== null);
+        const consequence = action === 'create'
+            ? `创建技能 "${view.name}"？会在家族目录树里新建一个技能目录。`
+            : `删除技能 "${view.name}"？它会被归档到 .archive 并离开目录。`;
+        const asked = confirm({
+            action,
+            name: view.name,
+            confirmLabel,
+            question: {
+                id: CONFIRM_QUESTION_ID,
+                header: '确认',
+                // ONE line: the platform's question composer does not preserve newlines, so a multi-line
+                // question arrives as a run-on sentence. The facts are separated instead.
+                question: details.length === 0 ? consequence : consequence + ' ' + details.join(' · '),
+                options: [{ label: confirmLabel }, { label: CANCEL_LABEL }],
+            },
+            ...mode === 'timeout' ? { signal: cancel.signal } : {},
+        });
+        let outcome;
+        try {
+            outcome = deadline === undefined ? await asked : await Promise.race([asked, deadline]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+        if (outcome === true)
+            return null;
+        // Running out of time is not the same answer as being declined: the write was cancelled
+        // because nobody was there to decide, and the refusal names the knob that changes that. Which
+        // promise the race returned first is a microtask-order detail — a platform that answers the
+        // abort with its own dismissal can settle `asked` first — so the case is decided by the
+        // deadline's signal, which only this gate aborts.
+        if (outcome === CONFIRM_TIMED_OUT || cancel.signal.aborted) {
+            return errorText('e-319-skill-write-confirm-timed-out', {
+                a1: view.name,
+                a2: action === 'create' ? '创建' : '删除',
+                a3: String(seconds),
+            });
+        }
+        return errorText('e-317-skill-write-not-confirmed', {
+            a1: view.name,
+            a2: action === 'create' ? '创建' : '删除',
+        });
+    },
+};
+/** The sequence, in order. A gate whose `appliesTo` omits the asking point is skipped. */
+const GATES = [ARGUMENT_SHAPE, MISSING_ARGS, POLICY_PROTECTION, READ_BEFORE_WRITE, HUMAN_CONFIRM];
+/**
+ * Run the sequence for one write attempt.
+ * @param context - the asking point, the write, and the seams the human-facing gate needs.
+ * @returns the FIRST refusal, or null when every applicable gate passed. Both points return the
+ *   message as the tool result unchanged, so the two entries refuse with identical wording.
+ */
+export async function runWriteGates(context) {
+    const input = { ...context, view: gateArgsOf(context.args) };
+    for (const gate of GATES) {
+        if (!gate.appliesTo.includes(context.point))
+            continue;
+        const refusal = await gate.run(input);
+        if (refusal !== null)
+            return refusal;
+    }
+    return null;
+}
+//# sourceMappingURL=write-gates.js.map

package/lib/types/write-inventory.js

@@ -0,0 +1,158 @@
+/**
+ * B3 / G4 (0.3.78): the persisted-write inventory — WHICH file the family
+ * writes, WHO writes it, and WHAT keeps two writers apart.
+ *
+ * The table lives in `persisted-write-inventory.json` at the package root so
+ * the TypeScript side, the architecture gate (`verify-arch-guards` rule N20)
+ * and the regression specs read ONE file (the row-overrides.json pattern).
+ *
+ * "What keeps two writers apart" has exactly three answers in this family:
+ * - `transact`       — the IO backend's cross-process write lock (transactIo);
+ * - `write-lock`     — the per-target `<path>.lock` protocol of the skill tree;
+ * - `instance-claim` — the per-home single-instance claim (instance-scope.ts),
+ *   for a writer whose sweeps cannot be expressed as one locked file.
+ * A site that answers with NONE of them is the "two instances, one file" class:
+ * a per-instance serial queue looks like serialization and is not.
+ * @module @lmzhen/dsh-evolution-core/src/write-inventory
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const SITES_URL = new URL('../persisted-write-inventory.json', import.meta.url);
+const SERIALIZATIONS = ['transact', 'write-lock', 'instance-claim'];
+/** Parse + validate the table. A malformed table throws at import: a table the
+ * gate cannot read must never degrade into "no declared write sites". */
+function parseTable(raw) {
+    // The input is UNKNOWN JSON, so each narrowing below is a real runtime check (and each later check
+    // is written so the previous one already excluded its negation — the linter rejects tautologies).
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('evolution-core: persisted-write-inventory.json must be an object with { symbols, sites }');
+    }
+    const table = raw;
+    // typeof null === 'object', so the null test stays — and it comes FIRST: after `typeof !== 'object'`
+    // TypeScript has already dropped null, and the linter is right to call that test a tautology.
+    if (table.symbols === null || typeof table.symbols !== 'object' || Array.isArray(table.symbols)) {
+        throw new Error('evolution-core: persisted-write-inventory.json needs a symbols legend (the roots every path is written against)');
+    }
+    for (const [symbol, entry] of Object.entries(table.symbols)) {
+        const problems = [];
+        if (!symbol.startsWith('<') || !symbol.endsWith('>'))
+            problems.push('symbol name (must be <name>)');
+        if (entry === null || typeof entry !== 'object')
+            problems.push('entry');
+        else {
+            const symbolEntry = entry;
+            if (typeof symbolEntry.resolver !== 'string' || symbolEntry.resolver === '')
+                problems.push('resolver');
+            if (symbolEntry.segments !== undefined
+                && (!Array.isArray(symbolEntry.segments) || symbolEntry.segments.some(segment => typeof segment !== 'string')))
+                problems.push('segments');
+        }
+        if (problems.length > 0) {
+            throw new Error(`evolution-core: persisted-write-inventory.json symbol ${symbol} is malformed (missing/invalid: ${problems.join(', ')})`);
+        }
+    }
+    if (!Array.isArray(table.sites))
+        throw new Error('evolution-core: persisted-write-inventory.json needs a sites array');
+    const sites = [];
+    for (const [index, entry] of table.sites.entries()) {
+        const site = entry;
+        const problems = [];
+        if (typeof site.id !== 'string' || site.id === '')
+            problems.push('id');
+        if (typeof site.path !== 'string' || site.path === '')
+            problems.push('path');
+        if (typeof site.writer !== 'string' || site.writer === '')
+            problems.push('writer');
+        if (typeof site.marker !== 'string' || site.marker === '')
+            problems.push('marker');
+        if (typeof site.serializedBy !== 'string' || !SERIALIZATIONS.includes(site.serializedBy))
+            problems.push('serializedBy');
+        if (site.serializedBy === 'instance-claim' && typeof site.instance !== 'string')
+            problems.push('instance');
+        if (!Array.isArray(site.state))
+            problems.push('state');
+        if (problems.length > 0) {
+            throw new Error(`evolution-core: persisted-write-inventory.json entry ${index} is malformed (missing/invalid: ${problems.join(', ')})`);
+        }
+        sites.push({
+            id: site.id,
+            path: site.path,
+            writer: site.writer,
+            serializedBy: site.serializedBy,
+            marker: site.marker,
+            ...(typeof site.instance === 'string' ? { instance: site.instance } : {}),
+            state: site.state,
+            note: typeof site.note === 'string' ? site.note : '',
+        });
+    }
+    const ids = new Set(sites.map(site => site.id));
+    if (ids.size !== sites.length)
+        throw new Error('evolution-core: persisted-write-inventory.json declares duplicate site ids');
+    // Every entry was validated above, so the unknown JSON is now the table's own shape.
+    return { symbols: table.symbols, sites };
+}
+/** Instance keys held by writer services — the single source shared by the
+ * claim site and the inventory row that declares it (rule N20 checks the row's
+ * `instance` names one of these). */
+export const INSTANCE_KEYS = {
+    /** The per-home curator: report writing + the retention sweep. */
+    curator: 'evolution-curator',
+};
+// Both caches are READONLY on purpose: the table's own shape is readonly, and copying it into a
+// mutable array would be a second source of truth for the same rows.
+let cachedSites;
+let cachedSymbols;
+/**
+ * The declared persisted write sites, in file order.
+ *
+ * v43 audit (S2-3 / P1-10): this used to be a module-scope readFileSync plus
+ * parse, so an unshipped asset threw AT IMPORT — one absent file took the whole
+ * family's load down (0.3.79 shipped a tarball without this asset and every
+ * package failed to load). The read is lazy now: importing the package never
+ * fails on this asset, while the first caller still gets a loud, descriptive
+ * failure instead of an empty table ("no declared write sites" would silently
+ * disable rule N20).
+ * @internal S2.4 (PLAN 2026-09-16): no production caller — the arch guard
+ * reads the JSON asset directly; the tests are the only in-tree consumers.
+ * @returns the sites, in file order.
+ */
+export function persistedWriteSites() {
+    if (cachedSites !== undefined)
+        return cachedSites;
+    let raw;
+    try {
+        raw = readFileSync(fileURLToPath(SITES_URL), 'utf8');
+    }
+    catch (error) {
+        const cause = error instanceof Error ? error.message : String(error);
+        throw new Error(`evolution-core: persisted-write-inventory.json is unreadable (${cause}) — the package asset is missing or was not shipped; the write-inventory rules cannot be evaluated without it`);
+    }
+    const table = parseTable(JSON.parse(raw));
+    cachedSites = table.sites;
+    cachedSymbols = table.symbols;
+    return table.sites;
+}
+/** The inventory's symbol legend — the roots every declared path is written against, with the
+ * segments the gate checks against the resolver's source.
+ * @internal no production caller — the gates read the JSON asset directly. */
+export function writePathSymbols() {
+    persistedWriteSites();
+    return cachedSymbols ?? {};
+}
+/** Sites serialized by the per-home instance claim, with their instance keys.
+ * @internal S2.4 (PLAN 2026-09-16): no production caller — the arch guard
+ * reads the JSON asset directly; the tests are the only in-tree consumers. */
+export function instanceClaimedWriteSites() {
+    return persistedWriteSites().filter((site) => site.serializedBy === 'instance-claim');
+}
+/** One declared site by id. An undeclared id throws — a stale caller must fail
+ * loud rather than read "nothing is declared".
+ * @internal S2.4 (PLAN 2026-09-16): no production caller — the arch guard
+ * reads the JSON asset directly; the tests are the only in-tree consumers. */
+export function persistedWriteSite(id) {
+    const site = persistedWriteSites().find(candidate => candidate.id === id);
+    if (site === undefined)
+        throw new Error(`evolution-core: no persisted write site "${id}" in persisted-write-inventory.json`);
+    return site;
+}
+//# sourceMappingURL=write-inventory.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.26.26",
+  "version": "0.27.1",
   "publishConfig": {
     "access": "public"
   },
@@ -18,12 +18,28 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./composition": {
+      "types": "./lib/types/composition/index.d.ts",
+      "default": "./lib/composition/index.js"
+    },
+    "./subagent": {
+      "types": "./lib/types/subagent/index.d.ts",
+      "default": "./lib/subagent/index.js"
+    },
+    "./http-routes": {
+      "types": "./lib/types/http-routes.d.ts",
+      "default": "./lib/http-routes.js"
+    },
+    "./restrictor": {
+      "types": "./lib/types/restrictor.d.ts",
+      "default": "./lib/restrictor.js"
+    },
     "./package.json": "./package.json",
     "./row-overrides.json": "./row-overrides.json",
     "./persisted-write-inventory.json": "./persisted-write-inventory.json"
   },
   "files": [
-    "lib/*.js",
+    "lib/**/*.js",
     "lib/types/**/*.d.ts",
     "row-overrides.json",
     "persisted-write-inventory.json"
@@ -31,18 +47,30 @@
   "license": "MIT",
   "dependencies": {
     "yaml": "^2.4.2",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "js-yaml": "^4.1.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-scope": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-session": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-session-projection": "^0.2.0-rc.1"
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-scope": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-session-projection": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.2.1-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-scope": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-session": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-session-projection": "^0.2.0-rc.1"
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-scope": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-session-projection": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.2.1-rc.1",
+    "@types/js-yaml": "^4.0.9",
+    "js-yaml": "^4.1.0"
+  },
+  "engines": {
+    "dsh": ">=0.2.1-rc.1 <0.2.2-0"
   }
 }