@lmzhen/dsh-evolution-core 0.25.9 → 0.26.26

package/lib/types/curator.d.ts

@@ -93,6 +93,7 @@ export interface CuratorRunReport {
     llmReviewEnabled?: boolean;
     /** V6-35 (0.3.36): lenient-parse shape notes from the LLM nomination block. */
     nominationsWarnings?: string[];
+    scanWarnings?: string[];
     /** 0.5.0 V1 (design §16.6-④): archived entries past the retention window that
      * the CURRENT policy keeps rather than deletes. Present (even empty) only when
      * the retention policy was `report`, so a report cannot read as "nothing
@@ -117,6 +118,7 @@ export interface CuratorReportInput {
     snapshotPath?: string;
     llmReviewEnabled?: boolean;
     nominationsWarnings?: readonly string[];
+    scanWarnings?: readonly string[];
     wouldPrune?: readonly string[] | null;
 }
 export declare function buildCuratorRunReport(input: CuratorReportInput): CuratorRunReport;

package/lib/types/index.d.ts

@@ -32,6 +32,10 @@
  * @module @lmzhen/dsh-evolution-core
  */
 export * from './citations.ts';
+export * from './tree-write.ts';
+export * from './package-identity.ts';
+export * from './write-authority.ts';
+export * from './write-gates.ts';
 export * from './reference-rewrite.ts';
 export * from './cost.ts';
 export * from './skill-lint.ts';
@@ -74,6 +78,8 @@ export * from './drift-signals.ts';
 export * from './skill-history.ts';
 export * from './unit-members.ts';
 export * from './skill-store.ts';
+export * from './store-ledger.ts';
+export * from './reachability.ts';
 export * from './state-store.ts';
 export * from './threats.ts';
 export * from './tool-dispatch.ts';

package/lib/types/package-identity.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The scope segment of the nearest `package.json` at or above `from`.
+ * @param from - the calling module URL (its own manifest is the answer).
+ * @returns the scope, e.g. `@deepseek-ai` or `@lmzhen`; an unscoped manifest yields an empty string.
+ */
+export declare function scopeOfNearestManifest(from: string | URL): string;
+/**
+ * One family/platform package name under the RUNNING scope.
+ * @param bareName - the name without any scope, e.g. `dsh-agent-preset`.
+ * @param from - the calling module URL.
+ * @returns `scope/bareName`, or `bareName` when the manifest carries no scope.
+ */
+export declare function scopedPackageName(bareName: string, from: string | URL): string;
+//# sourceMappingURL=package-identity.d.ts.map

package/lib/types/preset-composition.d.ts

@@ -82,7 +82,7 @@ export declare function loadRowOverrides(path?: string): RowOverride[];
  */
 export declare function compositionRowIds(composition: string): Set<string>;
 /** The platform package a DECLARATIVE preset row names (0.2.x replaced preset directories with it). */
-export declare const AGENT_PRESET_PACKAGE = "@deepseek-ai/dsh-agent-preset";
+export declare const AGENT_PRESET_PACKAGE: string;
 /** Identity and display metadata of one generated preset row. */
 export interface PresetRowIdentity {
     /** The composition row id (`- id:`); what {@link mergePresetRow} replaces by. */

package/lib/types/probe.d.ts

@@ -10,6 +10,12 @@
  * with a value, and only `present` yields a value.
  */
 import type { EvolutionIoLike } from './io.ts';
+/**
+ * The io surface the three-state probes actually use: three READS. Narrowing it here is deliberate -
+ * a probe cannot write, and typing these parameters as the full `EvolutionIoLike` made every read-only
+ * caller (e.g. reachability.ts) fail to compile for a capability it must not have.
+ */
+export type ProbeIo = Pick<EvolutionIoLike, 'list' | 'readText' | 'mtime'>;
 export type Probe<T> = {
     kind: 'present';
     value: T;
@@ -51,7 +57,7 @@ export declare function isMissingPath(error: unknown): boolean;
  * reads as absent, an EACCES/EIO reads as unknown — where a bare
  * `catch { return [] }` served a broken store as an empty one (the N14 class).
  */
-export declare function probeList(io: EvolutionIoLike, dir: string): Promise<Probe<string[]>>;
+export declare function probeList(io: ProbeIo, dir: string): Promise<Probe<string[]>>;
 /**
  * Three-state TEXT read of one file. A missing path (ENOENT/ENOTDIR, or a backend whose read
  * answers null) is `absent`; every other failure is `unknown` with its reason. The distinction is
@@ -62,13 +68,13 @@ export declare function probeList(io: EvolutionIoLike, dir: string): Promise<Pro
  * @param path - the file to read.
  * @returns the probe.
  */
-export declare function probeText(io: EvolutionIoLike, path: string): Promise<Probe<string>>;
+export declare function probeText(io: ProbeIo, path: string): Promise<Probe<string>>;
 /**
  * Three-state mtime read. Absent covers both "the path is missing" and "this
  * backend has no mtime probe" — the seam cannot tell those apart, so consumers
  * that must know say so in their own log line. A stat that FAILS is unknown.
  */
-export declare function probeMtime(io: EvolutionIoLike, path: string): Promise<Probe<number>>;
+export declare function probeMtime(io: ProbeIo, path: string): Promise<Probe<number>>;
 /** The timestamp a curator run report DECLARES: `startedAt` (the run's own start), then `at` (the
  * stamp the error writer sets on every report — F-327/P2-4).
  * @param parsed - the parsed report, or anything else.

package/lib/types/reachability.d.ts

@@ -0,0 +1,46 @@
+/** The io surface the reconciliation needs. */
+export interface ReachabilityIo {
+    list(path: string): Promise<string[]>;
+    readText(path: string): Promise<string | null>;
+    exists(path: string): Promise<boolean>;
+}
+/** One domain's reading. `baseline` is the audit's measured value, quoted for comparison, never a target. */
+export interface DomainReading {
+    readonly domain: string;
+    readonly unit: 'bytes' | 'files';
+    readonly total: number;
+    readonly reachable: number;
+    readonly unreachable: number;
+    /** The audit baseline this line is checked against, verbatim, so a drift is visible without a lookup. */
+    readonly baseline: string;
+    /** Set when a read FAILURE made this domain unmeasurable: not "nothing unreachable", but "not read". */
+    readonly unmeasured?: string | undefined;
+}
+/** Every sha256 any skill index references, across the whole history root. */
+export declare function referencedBlobs(io: ReachabilityIo, historyRoot: string): Promise<Set<string> | undefined>;
+/**
+ * The history domain: blobs on disk minus the blobs the indexes still reference.
+ * @param io - the tree reader.
+ * @param historyRoot - the history root (`.history`), passed in, never guessed.
+ * @returns the reading, with the audit baseline quoted for comparison.
+ */
+export declare function historyReachability(io: ReachabilityIo, historyRoot: string): Promise<DomainReading>;
+/**
+ * The reports domain: files no run record points at. A record WITHOUT a `resultRef` still owns the
+ * conventional path (`reports/maintain-<id>.json`), so that path counts as reachable - counting only
+ * explicit refs would report compliant files as orphans and the number could never match the baseline.
+ * @param io - the tree reader.
+ * @param reportsDir - the reports directory, passed in.
+ * @param runIds - every run id the run records carry.
+ * @param resultRefs - every explicit resultRef those records carry.
+ */
+export declare function reportsReachability(io: ReachabilityIo, reportsDir: string, runIds: readonly string[], resultRefs: readonly string[]): Promise<DomainReading>;
+/**
+ * The backups domain: snapshot trees and how much each holds. `skillsPerSnapshot` is measured by the
+ * caller (it already reads manifests); an empty tree is one whose manifest lists no skill.
+ * @param io - the tree reader.
+ * @param backupsRoot - the snapshot root, passed in.
+ * @param skillsPerSnapshot - the caller's manifest reading, one entry per snapshot directory.
+ */
+export declare function backupsReachability(io: ReachabilityIo, backupsRoot: string, skillsPerSnapshot: readonly number[]): Promise<DomainReading>;
+//# sourceMappingURL=reachability.d.ts.map

package/lib/types/skill-store.d.ts

@@ -32,6 +32,7 @@
  * re-probes after its copies so a mid-copy writer demotes to `skipped`
  * (OPT-07); the movers' probe→rename window is owned by the io.ts protocol.
  */
+import { type WriteAuthority } from './write-authority.ts';
 import { transactIo, type EvolutionIoLike } from './io.ts';
 import { type Probe } from './probe.ts';
 import type { SkillLimits } from './limits.ts';
@@ -287,10 +288,13 @@ export declare class SkillLibrary {
     /** V10-03 (P2-18): see the constructor's threatExemptLabels. Empty by
      * default — the strict ANY-hit-blocks policy is unchanged. */
     private readonly threatExemptLabels;
+    /** G1/1.1: default authority; a call may override (origin is per-invocation). */
+    /** G1/1.1/Stage 2: the ONE default every mutator reads. Per-call overrides still win. */
+    private readonly authority;
     /** skill-history.ts: the content history is best-effort, so a failure must not be SILENT —
      * but it is a deployment condition, not a per-write event, so it warns once per instance. */
     private historyWarned;
-    constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits, onMutation?: (event: EvolutionSkillMutatedEvent) => void, transact?: typeof transactIo, threatExemptLabels?: readonly string[]);
+    constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits, onMutation?: (event: EvolutionSkillMutatedEvent) => void, transact?: typeof transactIo, threatExemptLabels?: readonly string[], authority?: WriteAuthority);
     /**
      * Run one single-file read-modify-write for a mutator. When `transact` was
      * injected the read and the write run inside it (cross-process atomicity);
@@ -328,6 +332,21 @@ export declare class SkillLibrary {
      * a swallowed error would silently downgrade the anchor to
      * last-writer-wins.
      */
+    /**
+     * S4-01 (G0/0.7): the ONE three-state read the staging/replay anchors use.
+     *
+     * The two absorbing reads below absorb ENOENT/EISDIR and rethrow everything else, and the callers then
+     * each wrote their own try/catch to turn a rethrow into a decision - three near-copies of one posture,
+     * and the newest of them silently dropped the anchor instead of refusing. A read failure is its own
+     * state, so it gets its own name here: `unknown` with the reason, next to `present` and `absent`.
+     * Failing closed is then the CALLER decision (they refuse on unknown), not something each call site has
+     * to re-derive from a thrown error.
+     */
+    readSkillProbe(rawName: string): Promise<Probe<string>>;
+    /** The support-file face of {@link readSkillProbe}. */
+    readSupportFileProbe(rawName: string, filePath: string): Promise<Probe<string>>;
+    /** One place that turns the absorbing reads into three states. `null` is absent; a throw is unknown. */
+    private probeOf;
     readSupportFile(name: string, filePath: string): Promise<string | null>;
     /**
      * Summarize the skill tree.
@@ -499,7 +518,7 @@ export declare class SkillLibrary {
      * P2-4 (v19): a non-string entry (`skills: [123]`) is refused structurally
      * instead of throwing `name.includes is not a function`. */
     private safeSnapshotEntryName;
-    archive(rawName: string, options?: ArchiveOptions): Promise<SkillActionResult>;
+    archive(rawName: string, options?: ArchiveOptions, origin?: WriteOrigin): Promise<SkillActionResult>;
     /**
      * V2 (design §16.7): what an apply-mode consolidation would do for ONE source,
      * computed BEFORE any side effect. `blocked` means behaviour is exactly the
@@ -567,7 +586,7 @@ export declare class SkillLibrary {
      * recoverability: archival never deletes, and this is the control-plane
      * path back. The `.archive-reason` marker is dropped on restore.
      */
-    restoreFromArchive(rawName: string): Promise<SkillActionResult>;
+    restoreFromArchive(rawName: string, origin?: WriteOrigin): Promise<SkillActionResult>;
     writeSupportFile(rawName: string, filePath: string, content: string, origin?: WriteOrigin, anchor?: WriteAnchor): Promise<SkillActionResult>;
     private writeSupportFileCore;
     removeSupportFile(rawName: string, filePath: string, origin?: WriteOrigin, anchor?: WriteAnchor, unitId?: string): Promise<SkillActionResult>;
@@ -624,6 +643,16 @@ export declare class SkillLibrary {
     private sanitizeExtraNames;
     readSnapshotManifest(path: string): Promise<SnapshotManifest | null>;
     /** Keep only the newest N snapshots (Hermes keep=5 parity); older ones are removed outright. */
+    /**
+     * G3/3.4: can a snapshot actually be used right now?
+     *
+     * The recovery messages used to promise "restore it from a snapshot" without asking whether a usable
+     * snapshot exists (audit S1-01: the message promised recoverability from a chain that is five deep and
+     * whose newest member held 9 of 35 skills). Three states, like every other reading here: a fragment
+     * naming the usable snapshot, a fragment saying there is none, or a fragment saying the directory could
+     * not be read - the caller embeds whichever it gets, so the sentence is generated by the capability.
+     */
+    private snapshotRecoveryAvailability;
     private retainSnapshots;
     /** Snapshots as a THREE-state read (N14): absent = no .backups directory,
      * unknown = it exists but could not be listed (a caller must not read a
@@ -680,6 +709,8 @@ export interface NewSkillLibraryOptions {
     ctx?: SkillMutationSink | undefined;
     transact?: typeof transactIo | undefined;
     threatExemptLabels?: readonly string[] | undefined;
+    /** G1/1.1: WHO writes through this library. Required: no call site can omit it. */
+    authority: WriteAuthority;
 }
 export declare function newSkillLibrary(options: NewSkillLibraryOptions): SkillLibrary;
 export { DEFAULT_SKILL_LIMITS, DEFAULT_CITATION_POLICY, DEFAULT_REFERENCE_REWRITE_POLICY, DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_SUPPORT_FILE_CHAR_POLICY, POLICY_STAGE_DEFAULTS, policyStageLimits, } from './limits.ts';

package/lib/types/store-ledger.d.ts

@@ -0,0 +1,44 @@
+/**
+ * G3/3.2 (audit 06-performance.md 接缝 C): ONE declaration for every bounded store.
+ *
+ * Before this file the family had eight retention rules scattered across four packages and no place
+ * that could answer "how long does this record live under the current policy" (S1.md 4.3): six caps
+ * were named constants, three lived inline (snapshots 5, reports 20/20/10, archive 365d). Each entry
+ * below states its bound AND the code that declares it, so a gate can compare the two sets.
+ *
+ * `declare` is an ARRAY because one store may have several declaration sites (the report buckets are
+ * kept by two packages). The `inline` branch matches a CODE SNIPPET rather than a line number: line
+ * numbers rot on every edit above them, a snippet survives (and a snippet that stops matching is the
+ * detector the gate wants). No naming convention is assumed anywhere - that is the whole point of a
+ * ledger: the list IS the declaration.
+ */
+/** How one bound is declared in code. `named` resolves a constant; `inline` matches a snippet in a file. */
+export type StoreBoundDeclare = {
+    readonly kind: 'named';
+    readonly module: string;
+    readonly name: string;
+    readonly value: number | string;
+} | {
+    readonly kind: 'inline';
+    readonly file: string;
+    readonly contains: string;
+    readonly value: string;
+};
+/** One bounded store: what it is, who owns it, what bounds it, and where that bound is declared. */
+export interface StoreSpec {
+    readonly id: string;
+    /** The package that keeps the store (the one a reclamation change belongs to). */
+    readonly owner: string;
+    readonly unit: 'bytes' | 'files' | 'entries';
+    /** The bound itself, as a person reads it (a cap, or a policy phrase when removal is report-only). */
+    readonly bound: string;
+    /** What makes an entry removable - the cutoff the bound counts over. */
+    readonly cutoff: string;
+    readonly trigger: 'write' | 'run-end' | 'pass-end' | 'manual';
+    /** Where a footprint reading for this store comes from (the field 3.3 reports). */
+    readonly artifact: string;
+    readonly declare: readonly StoreBoundDeclare[];
+}
+/** The one list. A new bounded store that is not registered here is what the G3 gate refuses. */
+export declare const STORE_LEDGER: readonly StoreSpec[];
+//# sourceMappingURL=store-ledger.d.ts.map

package/lib/types/tree-write.d.ts

@@ -0,0 +1,53 @@
+/**
+ * G1/1.5 (S7-09): the TYPED critical section around a tree write.
+ *
+ * The control-plane lock used to wrap a whole pass, LLM call and all: an operator undo/restore waited up to
+ * one `curatorReviewTimeoutMs` (~120s) for a review that was merely thinking. The fix is to give the critical
+ * section a shape that a review cannot be squeezed into.
+ *
+ * WHAT THIS TYPE CAN AND CANNOT DO (the plan wording says "cannot be put inside the lock by TYPE" - that is
+ * only half true and the half that is false is the half people rely on): a callback is a CLOSURE, so even
+ * with `view` as its only parameter it can still reach `this.io` / `this.ctx` / `this.llm` from the enclosing
+ * scope. TypeScript cannot stop that, and a criterion claiming it would never go red.
+ *
+ * What the type DOES give: new code has no other entry - the callback is handed a `SnapshotView` and nothing
+ * else, so a phase that needs `io` or `llm` has to stay OUTSIDE and be passed its result in. What the type
+ * CANNOT give is covered by the companion source guard (see the family gates): an `io` / `llm` / `this.`
+ * / `ctx.` reference inside a `withTreeWrite` callback is a violation, and that guard is the executable form
+ * of "cannot be put inside the lock".
+ *
+ * @module @lmzhen/dsh-evolution-core/tree-write
+ */
+/**
+ * What a tree write may see: the mutation surface, and nothing that can think or read the medium directly.
+ * Deliberately carries NO `io`, NO `llm`, NO context handle - a phase needing those runs outside the section
+ * and hands its plan in.
+ */
+export interface SnapshotView {
+    /** The skill names the snapshot covers, in list order. */
+    readonly names: readonly string[];
+    /** One skill body, as read when the section opened. Async because the store read is: the view must not
+     * pretend a synchronous read of a medium it does not own. */
+    read(name: string): Promise<string | undefined>;
+    /**
+     * The ONLY write a section gets: one skill body, by name. Deliberately not an io handle - the point of
+     * the view is that a section CAN mutate (that is its job) without also being able to reach the medium,
+     * the model, or the context. The implementation is bound by the caller OUTSIDE the callback, so the
+     * callback body itself never names `this` / `io` / `llm` (which is what rule N40 checks).
+     */
+    writeSkill(name: string, content: string): Promise<void>;
+    /** A record of what this section intends to change, for the audit line. */
+    note(text: string): void;
+}
+/**
+ * Run one tree-writing section under a caller-owned serial queue, exposing ONLY a {@link SnapshotView}.
+ *
+ * The queue is passed in rather than owned here: the lock belongs to whoever serializes the control plane
+ * (the curator), and a second lock would be a second answer to one question.
+ * @param acquire - the caller serial queue (e.g. the curator mutex), returning its release.
+ * @param view - what this section sees while it holds the lock.
+ * @param fn - the section. It may only use the view.
+ * @returns whatever the section returns.
+ */
+export declare function withTreeWrite<T>(acquire: () => Promise<() => void>, view: SnapshotView, fn: (view: SnapshotView) => Promise<T>): Promise<T>;
+//# sourceMappingURL=tree-write.d.ts.map

package/lib/types/write-authority.d.ts

@@ -0,0 +1,87 @@
+/**
+ * G1/1.1: the ONE authority behind a write.
+ *
+ * Before this type existed the inputs of the can-I-write decision came from two places with two
+ * lifecycles: `origin` (plus the policy snapshot and the confirm seam) travelled in the tool
+ * package gate context, while `threatExemptLabels` rode the SkillLibrary constructor. Callers that
+ * reached the bytes through another path built neither, and the mutators defaulted `origin` to
+ * foreground - so an omitted authority silently read as the operator acting, and no mechanism said
+ * otherwise (measured: two entry points in the same curator file, one passing background_review and
+ * one defaulting).
+ *
+ * The shape below is where those inputs converge. The follow-up batch makes it a REQUIRED argument
+ * of every mutator (content and lifecycle alike) and deletes the defaults, so an omission is a
+ * compile error instead of a silent claim about who wrote the bytes.
+ */
+import type { WriteOrigin } from './skill-store.ts';
+/**
+ * The confirmation contract, HOISTED here from tool-skill-manage (G1/1.1 follow-up): the authority
+ * carries the confirm seam, so the seam's vocabulary lives with it. tool-skill-manage re-exports
+ * these names from write-gates.ts unchanged, so nothing importing them from there moves.
+ */
+export type WriteConfirmMode = 'auto' | 'ask' | 'timeout';
+/** The mode a deployment that configures nothing gets. */
+export declare const DEFAULT_WRITE_CONFIRM_MODE: WriteConfirmMode;
+/** Seconds a timeout-mode prompt waits before the write is cancelled. */
+export declare const DEFAULT_WRITE_CONFIRM_TIMEOUT_SECONDS = 120;
+/** What the operator is told about the target before answering. */
+export interface ConfirmContext {
+    readonly description?: string | undefined;
+    readonly versions?: number | undefined;
+}
+/** One confirm question, as the gate writes it and the seam asks it. */
+export interface WriteConfirmRequest {
+    readonly action: string;
+    readonly name: string;
+    readonly question: {
+        readonly id: string;
+        readonly header: string;
+        readonly question: string;
+        readonly options: readonly {
+            readonly label: string;
+        }[];
+    };
+    readonly confirmLabel: string;
+    readonly signal?: AbortSignal;
+}
+/** Ask the human to confirm one irreversible skill write. MUST be total: every unavailability
+ * resolves to true, so no failure of the question service blocks the operator's own write. */
+export type WriteConfirm = (request: WriteConfirmRequest) => Promise<boolean>;
+/**
+ * The batch-one migration aid: every call site becomes ONE of these instead of hand-building the
+ * object - so the shape cannot drift between callers, and each site still has to say its own
+ * origin out loud (origin is required here on purpose: the whole point is that no caller inherits
+ * a default identity).
+ */
+export declare function authorityFrom(input: {
+    origin: WriteOrigin;
+    threatExemptLabels?: readonly string[];
+    protectedNames?: readonly string[] | undefined;
+    readNames?: ReadonlySet<string> | undefined;
+    confirm?: WriteConfirm;
+    confirmMode?: WriteConfirmMode;
+    confirmTimeoutSeconds?: number;
+    /** Optional: a call site that has nothing to report may leave it out, and the gates then stay
+     * silent instead of forcing every one of the twelve construction points to invent a logger. */
+    warn?: (message: string) => void;
+}): WriteAuthority;
+export interface WriteAuthority {
+    /** Who is asking: the operator own session, a background review, the curator, the graph face. */
+    readonly origin: WriteOrigin;
+    /** Labels the threat scan must not refuse (P2-18). Migrated here from the library constructor:
+     * one decision must not read its policy from two objects. */
+    readonly threatExemptLabels: readonly string[];
+    /** The policy snapshot protected list; undefined when no policy row is mounted. */
+    readonly protectedNames: readonly string[] | undefined;
+    /** Names this session read successfully; undefined when the session log is not readable. */
+    readonly readNames: ReadonlySet<string> | undefined;
+    /** The human confirm seam, read only where a question is actually asked. */
+    readonly confirm?: WriteConfirm;
+    /** skillWriteConfirm: auto (the default) skips the question entirely. */
+    readonly confirmMode?: WriteConfirmMode;
+    /** skillWriteConfirmTimeoutSeconds, read only in timeout mode. */
+    readonly confirmTimeoutSeconds?: number;
+    /** Report a degraded gate; must not throw. */
+    readonly warn: (message: string) => void;
+}
+//# sourceMappingURL=write-authority.d.ts.map

package/lib/types/write-gates.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 { type WriteConfirm, type WriteConfirmMode } from './write-authority.ts';
+import type { ConfirmContext } from './write-authority.ts';
+import { type WriteOrigin } from './index.ts';
+/** The point whose verdict is being taken. */
+export type WriteGatePoint = 'admission' | 'execution';
+/** What every gate reads. */
+/**
+ * G1/1.2: the policy snapshot's protected list, read through an `unknown` boundary.
+ *
+ * This used to be package-private to tool-skill-manage, which is why the graph commands could not ask
+ * the same question and ended up enforcing nothing. It lives here so every write entry point reads the
+ * SAME list from the SAME place; the `unknown` boundary stays because the Context augmentation types the
+ * getter non-optionally while at runtime the policy row may be absent.
+ * @param policy - `ctx.get('evolutionPolicy')`, or anything else when the row is not mounted.
+ * @returns the protected names, or undefined when no policy snapshot is readable.
+ */
+/**
+ * G1/1.2: what a write entry point must supply for the shared admission sequence.
+ *
+ * The gates need policy, confirm, the session's read set and a warn sink; every caller can obtain those
+ * from its own `ctx`, but assembling them into a valid `WriteGateContext` is the seam's business, not each
+ * caller's. Without this, "all five entry points call the same entry" means five hand-built contexts and
+ * five chances to leave `protectedNames` out - which is exactly how the graph commands ended up enforcing
+ * nothing.
+ */
+export interface SkillWriteGateServices {
+    /** `ctx.get('evolutionPolicy')`, or anything else when the row is not mounted. */
+    readonly policy: unknown;
+    /** The human confirm seam; `undefined` refuses to ask (the gates then refuse the write). */
+    readonly confirm: WriteConfirm | undefined;
+    /** Names this session read successfully; `undefined` when the session log is not readable. */
+    readonly readNames: ReadonlySet<string> | undefined;
+    /** Report a degraded gate; must not throw. */
+    readonly warn: (message: string) => void;
+    /** The registry's `skillWriteConfirm`; `auto` (the default) skips the question. */
+    readonly confirmMode?: WriteConfirmMode;
+    /** The registry's `skillWriteConfirmTimeoutSeconds`, read only in `timeout` mode. */
+    readonly confirmTimeoutSeconds?: number;
+    /** Lazily read the target's own words for the confirmation card. */
+    readonly describeTarget?: (() => Promise<ConfirmContext | undefined>) | undefined;
+}
+/**
+ * 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 declare function skillWriteGateContext(services: SkillWriteGateServices, request: {
+    readonly point: WriteGatePoint;
+    readonly args: unknown;
+    readonly origin: WriteOrigin;
+}): WriteGateContext;
+export declare function protectedSkillNamesOf(policy: unknown): readonly string[] | undefined;
+export interface WriteGateContext {
+    /** The point asking: the tool's admission of a call, or its execution at the bytes. */
+    readonly point: WriteGatePoint;
+    /** The parsed (admission) or stored (replay) arguments — unvalidated, hence the shape gate. */
+    readonly args: unknown;
+    /** The library write origin: `foreground` is the operator's own session. */
+    readonly origin: WriteOrigin;
+    /** The policy snapshot's protected list; `undefined` when no policy row is mounted. */
+    readonly protectedNames: readonly string[] | undefined;
+    /** Names this session read successfully; `undefined` when the session log is not readable. */
+    readonly readNames: ReadonlySet<string> | undefined;
+    /** The human confirm seam — read only by the gates that apply to `'admission'`. */
+    readonly confirm: WriteConfirm | undefined;
+    /** The registry's `skillWriteConfirm`: `auto` (the default) skips the question entirely. */
+    readonly confirmMode?: WriteConfirmMode;
+    /** The registry's `skillWriteConfirmTimeoutSeconds`, read only in `timeout` mode. */
+    readonly confirmTimeoutSeconds?: number;
+    /** Read the target's own words for the confirmation card. LAZY on purpose: a write that is not
+     * asked about must not pay a read for a question nobody sees. Absent means "say nothing extra". */
+    readonly describeTarget?: (() => Promise<ConfirmContext | undefined>) | undefined;
+    /** Report a degraded gate; must not throw. The implementation decides how often it speaks — the
+     * shipped seam latches once per PROCESS, because the conditions it reports (no question service,
+     * an unreadable session log) belong to the deployment, not to one write. */
+    readonly warn: (message: string) => void;
+}
+/**
+ * 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 declare function runWriteGates(context: WriteGateContext): Promise<string | null>;
+//# sourceMappingURL=write-gates.d.ts.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.25.9",
+  "version": "0.26.26",
   "publishConfig": {
     "access": "public"
   },