@lmzhen/dsh-evolution-core 0.3.74 → 0.3.77

package/lib/types/constants.d.ts

@@ -88,8 +88,11 @@ export declare const DEFAULT_CURATOR_BOOT_GRACE_SECONDS = 10;
 export declare const DEFAULT_CURATOR_REVIEW_MAX_TOKENS = 2048;
 /** 0.3.17 (S3.10, T-1): control-plane fields a model-facing write call may
  * never carry — single source for plan-validator, evolution-policy and the
- * threat scanner (they used to each hardcode the list). */
-export declare const FORBIDDEN_CONTROL_KEYS: readonly ["policy", "threshold", "prompt_hash", "model_route", "evolution_config"];
+ * threat scanner (they used to each hardcode the list).
+ * P2-13 (v37): staged_from_sha256 joins the list — it is the replay's own
+ * staleness anchor, and the tool-arguments root is an OPEN object, so a model
+ * could otherwise choose the anchor that decides the write's outcome. */
+export declare const FORBIDDEN_CONTROL_KEYS: readonly ["policy", "threshold", "prompt_hash", "model_route", "evolution_config", "staged_from_sha256"];
 /** 0.3.17 (S3.10): the model-facing write tools the policy guard and threat
  * scanner cover. */
 export declare const EVOLUTION_WRITE_TOOLS: readonly ["memory", "skill_manage"];

package/lib/types/evolution-events.d.ts

@@ -49,6 +49,8 @@ export interface EvolutionEvent {
      * count snapshot at the moment the observation window opened), and
      * maintain scans (011: verdict + recommendation count + runId). */
     type: 'feedback' | 'learn' | 'usage' | 'maintain';
+    /** Fold key for a `feedback` event: required and non-empty there (P2-10),
+     * optional on the other tags and on a record this version only reads. */
     target?: string | undefined;
     kind?: 'skill' | 'session' | undefined;
     rating?: 'positive' | 'negative' | undefined;
@@ -70,6 +72,15 @@ export interface EvolutionEvent {
         opened?: string;
     } | undefined;
 }
+/** The durable-write shape of one event: `feedback` REQUIRES a `target` —
+ * the fold key the aggregate is keyed by (P2-10). The other tags keep every
+ * field optional, exactly as the runtime payload gate treats them. */
+export type EvolutionEventInput = (Omit<EvolutionEvent, 'seq' | 'at' | 'target'> & {
+    type: 'feedback';
+    target: string;
+}) | (Omit<EvolutionEvent, 'seq' | 'at'> & {
+    type: 'learn' | 'usage' | 'maintain';
+});
 export declare function eventsFile(home: string): string;
 /** I-5 (v18): one lightweight description of the durable event payload
  * contract. The log is a FILE boundary (a host, a script or an older version
@@ -108,7 +119,7 @@ export declare function listEventArchives(io: EvolutionIoLike, path: string): Pr
  * — the active restarts AFTER the highest archived seq, never at 1, so a new
  * event can never shadow an archived one in the seq-deduped timeline.
  */
-export declare function appendEvolutionEvent(io: EvolutionIoLike, path: string, event: Omit<EvolutionEvent, 'seq' | 'at'>, rotateAt?: number): Promise<number>;
+export declare function appendEvolutionEvent(io: EvolutionIoLike, path: string, event: EvolutionEventInput, rotateAt?: number): Promise<number>;
 /**
  * Prune old event archives (rc.71): keep the newest `EVENT_LOG_RETAIN_ARCHIVES`.
  * The name's numeric part is the last archived seq, so ordering is NUMERIC —

package/lib/types/index.d.ts

@@ -3,10 +3,9 @@
  *
  * Pure stores, prompts, signals, lifecycle logic, threat scanning, IO seam
  * types, and session-event augmentations. This package ships no runtime
- * plugin beyond the invariant companion entry (`./invariant` — the subpath
- * the host auto-assembles to register this package's no-op invariant);
- * consumers import named exports from the package root so published npm
- * bundles never depend on source subpaths.
+ * plugin and no `./invariant` companion (v37 S2.1); consumers import named
+ * exports from the package root so published npm bundles never depend on
+ * source subpaths.
  *
  * ## Layer map (OPT-28, 2026-09) — locate code by LAYER, not by directory
  *
@@ -39,14 +38,19 @@ export * from './preset-composition.ts';
 export * from './prompts.ts';
 export * from './quality.ts';
 export * from './redact.ts';
+export * from './review-channel.ts';
 export * from './serial.ts';
+export * from './probe.ts';
+export * from './scope.ts';
 export * from './skill-health.ts';
 export * from './signals.ts';
 export * from './drift-signals.ts';
 export * from './skill-store.ts';
 export * from './state-store.ts';
 export * from './threats.ts';
+export * from './tool-dispatch.ts';
 export * from './usage.ts';
 export * from './constants.ts';
 export * from './numeric.ts';
+export * from './opt-in.ts';
 //# sourceMappingURL=index.d.ts.map

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

@@ -18,6 +18,22 @@ export interface MemoryApplyResult {
     limit: number;
 }
 export declare function memoryRoot(env?: NodeJS.ProcessEnv): string;
+/**
+ * Neutralize the platform's `{{name}}` prompt-variable syntax in text that is
+ * about to be registered as a `systemPrompt.context` contribution.
+ *
+ * The platform interpolates every context/section text once per model step and
+ * THROWS on an unknown or malformed reference — so one stored memory entry
+ * containing `{{...}}` (a CI expression, a Jinja/Helm/Vue template, a doc
+ * placeholder) used to fail `assemble()` on EVERY later pre-step of every
+ * session under this DSH_HOME, while a registered name such as `{{cwd}}` was
+ * silently substituted into the "memory" the model reads. Only the INJECTED
+ * text is neutralized: stored entries keep their original bytes.
+ *
+ * @param text - rendered context text about to leave for the prompt surface.
+ * @returns the same text with every `{{` split so it cannot start a reference.
+ */
+export declare function neutralizePromptVariables(text: string): string;
 export interface MemoryStoreOptions {
     memoryCharLimit?: number;
     userCharLimit?: number;

package/lib/types/opt-in.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Variant-form opt-in: WHICH sessions the family's cross-session consumers act on.
+ *
+ * The family ships in two install forms. Mounted onto the original presets (the
+ * profile-level bundle), EVERY session is a family session and the consumers
+ * below keep acting on all of them. In the VARIANT form the family's model tools
+ * exist only inside a variant preset, so a session that did not select one never
+ * opted in — yet the cross-session consumers (review cadence and injection,
+ * skill-usage telemetry) live at profile root and used to act on every session
+ * anyway, including the platform's original presets: a user who installed a
+ * variant was still injected with review prompts and still counted in usage.
+ *
+ * The two forms are told apart WITHOUT a list of preset ids and WITHOUT a second
+ * source of truth: a session is a family session exactly when the family's own
+ * model tools are visible in its scope. Mounted at profile root they are visible
+ * to every session; mounted inside a variant preset they are visible only to the
+ * agents that joined that preset's standing scope — every registration inside a
+ * preset files into that agent's layer
+ * (packages/preset/agent-presets/src/mount.ts:4-13).
+ *
+ * `sessionScoped` is what a deployment declares: true means "act only on a
+ * session that carries the family's model tools", which is the right question in
+ * BOTH install forms — at profile root every session carries them, inside a
+ * variant preset only the sessions that selected one do. The shipped bundles set
+ * it; a bare library mount and the host-only infrastructure mode leave it false
+ * and keep the historical "every session" behavior.
+ * @module
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Tool names only a session that mounted the family's MODEL rows can see.
+ *
+ * Both are family packages (`tool-skill-manage`, `tool-memory`), so a session
+ * that merely carries the platform's own session-query tool is not mistaken for
+ * a family session. Two names, not one: a deployment may disable either row.
+ */
+export declare const FAMILY_SESSION_TOOL_NAMES: readonly string[];
+/**
+ * Does this session's scope see the family's model tools?
+ *
+ * The scope is the live agent's — the platform's own addressing for "what does
+ * this session see" (`tools.get(name, scope)`, packages/core/tools/src/index.ts:1194).
+ * A session with no live agent (a finished or cold session) has no scope to ask
+ * in, so it resolves to false; the consumers this gate serves only run for live
+ * agents.
+ * @param ctx - a context of the runtime (any plane; the services are read from the global store).
+ * @param sessionId - the session to ask about.
+ * @returns true when at least one family model tool is visible to that session.
+ */
+export declare function sessionSeesFamilyTools(ctx: Context, sessionId: string): boolean;
+/**
+ * The one decision every cross-session consumer calls before it acts.
+ * @param ctx - a context of the runtime.
+ * @param sessionId - the session the event belongs to.
+ * @param sessionScoped - the row's `sessionScoped` config.
+ * @returns true when the consumer may act on this session. A deployment that did
+ * not declare session scoping always answers true (the historical behavior);
+ * a scoped one answers true only for a session that carries the family's model
+ * tools.
+ */
+export declare function sessionAudited(ctx: Context, sessionId: string, sessionScoped: boolean | undefined): boolean;
+//# sourceMappingURL=opt-in.d.ts.map

package/lib/types/probe.d.ts

@@ -0,0 +1,38 @@
+/**
+ * V41 phase-1 follow-up: the read THREE-state (P2-25 sibling of N14).
+ *
+ * A read has three outcomes, not two: the value is there, it is genuinely not
+ * there, or we could not decide (IO error, unreadable store, missing
+ * provider). Collapsing the third into either of the others is how a broken
+ * store reads as "empty" and a guard silently passes — the class N14 registers.
+ * Migration target for the pre-existing two-state patches (protectionUnknown /
+ * unverifiable): constructors are prefixed so the type can never be confused
+ * with a value, and only `present` yields a value.
+ */
+export type Probe<T> = {
+    kind: 'present';
+    value: T;
+} | {
+    kind: 'absent';
+} | {
+    kind: 'unknown';
+    reason: string;
+};
+export declare function probePresent<T>(value: T): Probe<T>;
+export declare function probeAbsent<T>(): Probe<T>;
+export declare function probeUnknown<T>(reason: string): Probe<T>;
+export declare function isPresent<T>(probe: Probe<T>): probe is {
+    kind: 'present';
+    value: T;
+};
+export declare function isAbsent<T>(probe: Probe<T>): probe is {
+    kind: 'absent';
+};
+export declare function isUnknown<T>(probe: Probe<T>): probe is {
+    kind: 'unknown';
+    reason: string;
+};
+/** Only a PRESENT probe yields a value; absent and unknown both fall back. */
+export declare function valueOr<T>(probe: Probe<T>, fallback: T): T;
+export declare function mapProbe<T, U>(probe: Probe<T>, transform: (value: T) => U): Probe<U>;
+//# sourceMappingURL=probe.d.ts.map

package/lib/types/review-channel.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Family-internal mark for the review channel's INJECT delivery (v37 S2.2).
+ *
+ * With the default `reviewMode: 'inject'` the review prompt runs in the PARENT
+ * session, so the parent model's own `skill_manage` calls carry no origin the
+ * platform could attribute: `.pinned` and the `.hermes-managed` authorship mark
+ * were skipped for exactly the autonomous writes they exist for. The delivery
+ * marks the session here and the write path reads the mark.
+ *
+ * Window: after the review prompt, until the next REAL user message (a
+ * `user/message` with `source.kind === 'user'` clears it; plugin-sourced notices
+ * never do). Process-wide and keyed by session on purpose — the same
+ * "restart is a fresh conversation boundary" discipline as the review plugin's
+ * own per-session counters. This module is the ONE owner of the marker.
+ * @module @lmzhen/dsh-evolution-core/review-channel
+ */
+/**
+ * Mark one session as running the review channel's prompt; idempotent, and
+ * keyed by session so a mark can never leak into another session.
+ * @param sessionId - the session the review prompt was delivered to.
+ */
+export declare function markReviewChannel(sessionId: string): void;
+/**
+ * Clear the mark: the session's next prompt is human input again.
+ * @param sessionId - the session whose mark is dropped.
+ */
+export declare function clearReviewChannel(sessionId: string): void;
+/**
+ * Whether this session's current prompt came from the review channel. An
+ * execution without a session is never the review channel.
+ * @param sessionId - the executing session id, when the caller has one.
+ * @returns true only for a marked session.
+ */
+export declare function isReviewChannelSession(sessionId: string | undefined): boolean;
+/**
+ * Drop marks whose session is gone — a dead session cannot execute a write.
+ * @param isAlive - liveness probe for one session id.
+ * @returns the number of removed marks.
+ */
+export declare function sweepReviewChannelSessions(isAlive: (sessionId: string) => boolean): number;
+//# sourceMappingURL=review-channel.d.ts.map

package/lib/types/scope.d.ts

@@ -0,0 +1,27 @@
+/**
+ * V41 scope alignment: the ONE place that answers "in whose scope do we ask?".
+ *
+ * The platform's registry reads are scope-sensitive: `skills.list(options)`
+ * documents its `scope` as "the calling agent; OMITTED READS THE GLOBAL LAYER
+ * ALONE", and `tools.get(name, scope?)` resolves visibility the same way
+ * (packages/skill/skill/src/index.ts:113-120, packages/core/tools/src/index.ts:1194).
+ * A preset-mounted family row therefore lives in its PRESET'S STANDING SCOPE,
+ * so a scope-less read cannot see it — the asymmetry between "evolution mounted
+ * onto the original preset" and "the evolution variant preset".
+ *
+ * Resolution order (the single verdict; do not re-derive at call sites):
+ *   1. the scope the caller already holds (a tool invocation carrying one);
+ *   2. this plugin context's own scope — for a preset-mounted row that IS the
+ *      preset's standing scope, i.e. exactly where the family's provider lives;
+ *   3. undefined, which callers must treat as an EXPLICIT global-layer read
+ *      (registered per the arch guard's scope rule), never as a silent default.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** The platform's scope identity, kept structural so callers do not need the
+ * platform type (`ScopeKey` is `object`). */
+export type OpaqueScopeKey = object;
+export declare function callingScope(ctx: Context, held?: OpaqueScopeKey): OpaqueScopeKey | undefined;
+/** True when a read is deliberately scope-less (global layer only). Callers
+ * pass this to the register so the choice is reviewed, not accidental. */
+export declare function isGlobalRead(scope: OpaqueScopeKey | undefined): boolean;
+//# sourceMappingURL=scope.d.ts.map

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

@@ -50,7 +50,12 @@ export interface SkillSummary {
     protectedBy: string | null;
     /** A1-17 (v18): the marker probe itself failed (EACCES/EIO), so "no marker"
      * cannot be told apart from "directory unreadable". Consumers must treat this
-     * as protected, never as unprotected. */
+     * as protected, never as unprotected.
+     * v41: this flag and `protectedBy` ARE the read three-state —
+     * (null, false) = no marker, (X, false) = present, (_, true) = unreadable.
+     * Read them together, never this flag alone; it is a published field, so the
+     * encoding stays (core's `Probe<T>` is for internal decisions, not for this
+     * contract). */
     protectionUnknown: boolean;
     managed: boolean;
     /** E-11 (v18): the frontmatter `whenToUse` routing hint, published so the
@@ -221,20 +226,6 @@ export interface Frontmatter {
     description?: string;
     [key: string]: unknown;
 }
-/**
- * Shared frontmatter block detection (P3-3 single owner): opening line `---`
- * and closing line exactly `---`. Used by `parseFrontmatter`,
- * `frontmatterCatalogInvalid` and `normalizeFrontmatter` so the three can
- * never disagree about where the block ends (the loose `indexOf('\n---')`
- * form matched `\n----` and was replaced by this strict line rule).
- *
- * V27 G2.1: both fence lines are matched EXACTLY, tolerating only a trailing
- * `\r` — the same rule the upstream filesystem catalog uses
- * (`skill-filesystem.parseFrontmatter`). The former `.trim()` comparison
- * accepted ` --- `, so an indented fence loaded in the family while the
- * platform ignored the file: family visibility split from platform visibility,
- * which is exactly what a strict-YAML frontmatter is supposed to prevent.
- */
 export declare function frontmatterBlock(content: string): {
     block: string;
     lines: string[];
@@ -260,9 +251,23 @@ export interface FrontmatterRead {
     /** Whether the frontmatter is not valid AS WRITTEN for the strict platform
      * catalog: the strict parser rejects the block, or an unquoted value would
      * read as something other than its text (a dropped ` # ` comment, a
-     * number/bool shorthand the catalog refuses as a string field). The write
-     * path quotes such a value on its next edit. */
+     * number/bool shorthand the catalog refuses as a string field), or a
+     * platform string field carries a non-string value. The write path quotes
+     * such a value on its next edit. */
     catalogInvalid: boolean;
+    /** Platform string fields (`name`/`description`/`whenToUse`) whose YAML value
+     * is not a string: the strict catalog reads such a field as ABSENT and, for an
+     * absent name/description, ignores the whole file (P2-9/v37). */
+    platformStringSplit: PlatformStringSplit[];
+}
+/** One `name`/`description`/`whenToUse` entry the strict catalog cannot read as
+ * a string, with the YAML kind the parser found. */
+export interface PlatformStringSplit {
+    key: string;
+    /** The YAML type read for this field. `scalar` covers number/boolean (the
+     * E-47 auto-quote repair handles those); `sequence`/`mapping` are the shapes
+     * no rewrite can repair without inventing text — see `validateFrontmatter`. */
+    kind: 'sequence' | 'mapping' | 'scalar' | 'null';
 }
 /**
  * Parse a SKILL.md: its frontmatter values and body, or `null` when the file
@@ -341,7 +346,9 @@ export declare function normalizeFrontmatter(content: string): FrontmatterNormal
  * excluded. Pure and deduplicated.
  */
 export declare function relatedSkillNames(content: string, exclude?: string): string[];
-export declare function validateFrontmatter(content: string, expectedName?: string, limits?: SkillLimits): string | null;
+export declare function validateFrontmatter(content: string, expectedName?: string, limits?: SkillLimits, 
+/** On-disk bytes, so a NET SHRINK of an over-limit file is allowed (S1.2). */
+current?: string | null): string | null;
 /** Hermes authoring quality bar for descriptions — see constants.ts
  * (0.3.16 T-4 moved the single source there; the public re-export sits behind
  * the package root, which re-exports constants anyway). */
@@ -531,15 +538,16 @@ export declare class SkillLibrary {
      * each support dir (write_file's lock sits next to its file). Residual:
      * NESTED support-subdir locks and the probe→rename TOCTOU itself remain
      * fail-safe (renameWithRetry rides the write out; the writer's locked
-     * re-read refuses on the moved-away file), and a residue `.lock` from a
-     * CRASHED writer also refuses — correct: inspect, don't archive.
+     * re-read refuses on the moved-away file). v37 (P2-8): a residue `.lock` whose
+     * holder is GONE is not a writer — `decideTakeover` owns that verdict.
      */
     private hasWriteLock;
-    /** P2 (v17): a file only counts as a writer lock when its body has the
-     * `pid:token` shape the io layer writes. User support files legitimately
-     * named `*.lock` (allowed by SUPPORT_FILE_NAME_RE) must not trip the probe
-     * or be swept as residue — the v16 first cut matched on suffix alone,
-     * which permanently refused archiving and deleted user content on restore. */
+    /** P2 (v17): a `*.lock` file counts as a writer lock only when its body
+     * carries the io layer's protocol — `pid:token`, a bare pid, or an empty body
+     * (a creator between create and body write); anything else is user content
+     * (suffix-only matching refused archiving and deleted user files on restore).
+     * v37 (P2-8): the verdict is `decideTakeover`'s, so the mover refuses exactly
+     * the lock the io layer refuses to reclaim, the 30s empty window included. */
     private isWriterLock;
     /** P2 (v16): best-effort removal of lock residue inside a RESTORED tree.
      * A1-2/A1-7 (v18): the sweep now covers the marker locks the probe checks
@@ -684,4 +692,30 @@ export declare class SkillLibrary {
      */
     private restoreSnapshotIntoRoot;
 }
+/** The emit surface the helper needs — structurally the platform context's
+ * `emit`, so core states the contract without importing the platform type. */
+export interface SkillMutationSink {
+    emit: (type: 'evolution/skill-mutated', event: EvolutionSkillMutatedEvent) => unknown;
+}
+/** V41 P2-26 (0.3.75): the ONE SkillLibrary construction point.
+ *
+ * Eleven call sites used to re-derive the root and hand-roll the
+ * `evolution/skill-mutated` arrow (the catalog invalidates its cache on that
+ * exact string, so a second spelling is a silent divergence), and each one
+ * re-decided its own limits. `config` stays the RAW family config: resolving
+ * an empty `root` to the family default is `resolveSkillsRoot`'s policy, not
+ * a per-caller detail. */
+export interface NewSkillLibraryOptions {
+    /** Raw family config; only `root` is read, through resolveSkillsRoot. */
+    config?: {
+        root?: string | undefined;
+    } | undefined;
+    io: EvolutionIoLike;
+    limits?: SkillLimits | undefined;
+    /** Supplying it wires the mutation event HERE — never at the call site. */
+    ctx?: SkillMutationSink | undefined;
+    transact?: typeof transactIo | undefined;
+    threatExemptLabels?: readonly string[] | undefined;
+}
+export declare function newSkillLibrary(options: NewSkillLibraryOptions): SkillLibrary;
 //# sourceMappingURL=skill-store.d.ts.map

package/lib/types/tool-dispatch.d.ts

@@ -0,0 +1,212 @@
+/**
+ * The family's ONE reader of platform tool-dispatch events.
+ *
+ * The platform records a finished tool call under two different event
+ * vocabularies and only one of them is written per dispatch, chosen by the
+ * mounted tool runtime's mode:
+ *
+ * - native mode: \`tool/call\` (with \`callId\`) settled by \`tool/result\`, the
+ *   write sites being core/agent-loop/src/tool-calls.ts:264 and :282.
+ * - PTC mode: \`tool/ptc-dispatch-start\` and \`tool/ptc-dispatch\` (with
+ *   \`subCallId\`), the write sites being core/tools/src/ptc.ts:534 and :509.
+ *
+ * A consumer that matches a vocabulary directly therefore goes blind in the
+ * other mode while still appearing to work — the defect this module exists to
+ * make impossible. Every family consumer reads dispatches through
+ * \`ToolDispatchNormalizer\` (or the pure helpers below) and matches on
+ * \`ToolDispatchSignal\` fields only; \`verify-arch-guards\` rule N11 rejects a
+ * dispatch event-type comparison anywhere else.
+ *
+ * ## The one-dispatch invariant
+ *
+ * One dispatch produces exactly one \`ToolDispatchSignal\`, no matter how many
+ * events carry it: a start/settle pair for a PTC sub-dispatch, a call/result
+ * pair for a native call, or both vocabularies for the same call. Deduplication
+ * and outcome folding are keyed by the platform's own per-vocabulary call
+ * identity, which is stable across the pair (the platform's event JSDoc:
+ * "the pairing ids (matching the \`tool/ptc-dispatch-start\` with the same
+ * \`subCallId\`)").
+ *
+ * ## Layer
+ *
+ * Cross-cutting normalization: the reader half of the dispatch vocabulary,
+ * next to \`signals.ts\` (which folds the signals this module emits). Both are
+ * consumers; neither subscribes to the platform bus itself.
+ * @module
+ */
+/** How the platform delivered one dispatch. */
+export type ToolDispatchKind = 
+/** A model-authored call, logged as \`tool/call\` and settled by \`tool/result\`. */
+'native'
+/** A sub-dispatch of a code program, logged as the PTC dispatch pair. */
+ | 'program'
+/** A \`run_code\` call itself: a native call whose program dispatches sub-calls. */
+ | 'program-root';
+/** The platform event type carrying a PTC sub-dispatch start. */
+export declare const PTC_DISPATCH_START_EVENT = "tool/ptc-dispatch-start";
+/** The platform event type carrying a PTC sub-dispatch settle. */
+export declare const PTC_DISPATCH_EVENT = "tool/ptc-dispatch";
+/** The platform event type carrying a native tool call. */
+export declare const NATIVE_CALL_EVENT = "tool/call";
+/** The platform event type carrying a native tool result. */
+export declare const NATIVE_RESULT_EVENT = "tool/result";
+/**
+ * The dispatch vocabulary this module owns. A consumer must never compare
+ * against these literals itself (rule N11); it compares \`kind\` instead.
+ */
+export declare const DISPATCH_EVENT_TYPES: readonly string[];
+/**
+ * One normalized tool dispatch.
+ *
+ * Every field is derived from a platform event payload; the record is mutable
+ * and is updated in place when a later event of the same dispatch settles it,
+ * so a consumer that reacted at start already holds the outcome.
+ */
+export interface ToolDispatchSignal {
+    /** \`native\` | \`program\` (a code-program sub-dispatch) | \`program-root\` (the \`run_code\` call itself). */
+    readonly kind: ToolDispatchKind;
+    /** \`callId\` for a native call, \`subCallId\` for a PTC sub-dispatch — the platform's own identity. */
+    readonly callId: string;
+    /** The outer call: \`parentCallId\` for a PTC sub-dispatch, the call's own id for a native call. */
+    readonly rootCallId: string;
+    /** Dispatched tool name, always a non-empty string. */
+    readonly name: string;
+    /** Arguments as dispatched: a JSON string in native mode, the normalized object in PTC mode. */
+    readonly arguments: unknown;
+    /** Settled outcome: \`true\` succeeded, \`false\` failed, \`undefined\` still in flight. */
+    ok: boolean | undefined;
+}
+/**
+ * \`TypeError\` thrown when a payload that claims to be a dispatch event
+ * violates the platform's event declaration. Named so a deployment can tell this
+ * refusal apart from a generic failure in a log line.
+ */
+export declare class ToolDispatchPayloadError extends TypeError {
+    name: string;
+}
+/**
+ * The family's single dispatch ledger: absorbs platform events in log order,
+ * emits one \`ToolDispatchSignal\` per dispatch, and folds later events of the
+ * same dispatch into the record it already emitted.
+ *
+ * Consumers keep the \`ToolDispatchSignal\` object they received and re-read it
+ * later; no consumer needs to correlate events itself.
+ */
+export declare class ToolDispatchNormalizer {
+    private readonly records;
+    /** Call ids of \`run_code\`-class calls, i.e. of dispatches whose sub-dispatches are \`program\`. */
+    private readonly programRoots;
+    /**
+     * Absorb one session event.
+     * @param event - the event to absorb; any non-dispatch event is ignored.
+     * @returns the dispatch's signal when this event FIRST reveals the dispatch,
+     * otherwise \`null\` (the paired event of an already-emitted dispatch, or a
+     * non-dispatch event). A \`null\` return is never a dispatch to count again.
+     */
+    advance(event: {
+        type: string;
+        data?: unknown;
+    }): ToolDispatchSignal | null;
+    /** Every emitted dispatch, in first-seen order. */
+    get signals(): readonly ToolDispatchSignal[];
+    /**
+     * Fold every event of a session log, in order.
+     * @param events - the log, oldest first.
+     * @returns one signal per dispatch, in first-seen order.
+     */
+    foldAll(events: Iterable<{
+        type: string;
+        data?: unknown;
+    }>): ToolDispatchSignal[];
+}
+/**
+ * Read one event into a dispatch record without a ledger (the pure half of the
+ * fold). Unlike the ledger it does NOT dedupe: a caller that walks a log and
+ * emits its own lines needs the call line on the event that opens the result.
+ * @param event - one session event; an absent event (an over-advanced index)
+ * answers \`null\` rather than throwing.
+ * @returns the dispatch this event opens, or \`null\` for any other event.
+ */
+export declare function readDispatchSignal(event: {
+    type?: string;
+    data?: unknown;
+} | undefined): {
+    kind: ToolDispatchKind;
+    callId: string;
+    rootCallId: string;
+    name: string;
+    arguments: unknown;
+} | null;
+/**
+ * Is this dispatched tool name a single-skill read?
+ * @param name - the dispatched tool name.
+ * @returns \`true\` only for the read tool whose arguments name one skill.
+ */
+export declare function isSkillReadToolName(name: string): boolean;
+/**
+ * Does this signal read one skill, and did it not fail?
+ * @param signal - a normalized dispatch.
+ * @returns the skill name the dispatch read, or \`undefined\` when the dispatch
+ * is not a skill read or has failed. A dispatch whose outcome is still pending
+ * counts as a read: the platform settles every started sub-dispatch, so pending
+ * is a live-window state, not a failure.
+ */
+export declare function skillReadNameOf(signal: ToolDispatchSignal): string | undefined;
+/**
+ * Fold one session log into its deduplicated dispatches.
+ * @param events - the log, oldest first. Pass an array, not a live snapshot
+ * iterator, when the log can grow while folding.
+ * @returns one signal per dispatch, in first-seen order.
+ */
+export declare function foldToolDispatches(events: Iterable<{
+    type: string;
+    data?: unknown;
+}>): ToolDispatchSignal[];
+/**
+ * Every skill name this log read through a dispatch, deduplicated by dispatch.
+ * @param events - the log, oldest first.
+ * @returns the names read by at least one non-failed skill dispatch.
+ */
+export declare function collectReadSkillNames(events: Iterable<{
+    type: string;
+    data?: unknown;
+}>): Set<string>;
+/**
+ * Does this dispatched tool name touch the skill library (read or mutate)?
+ * @param name - the dispatched tool name.
+ * @returns \`true\` for any skill-library tool. This is the review cadence's
+ * skill signal, which has always covered reads and writes alike.
+ */
+export declare function isSkillToolName(name: string): boolean;
+/**
+ * Does this dispatched tool name open a code program?
+ * @param name - the dispatched tool name.
+ * @returns \`true\` for the tool whose sub-dispatches are \`program\` kind.
+ */
+export declare function isProgramToolName(name: string): boolean;
+/**
+ * Assert that a payload really is the dispatch event it claims to be.
+ *
+ * The normalizer is deliberately lenient (it also folds persisted logs, where a
+ * payload may predate the current declaration); this is the loud gate for the
+ * live path, where a malformed payload means the producer is broken. It never
+ * silently downgrades: an unrecognized event type or a payload missing a
+ * declared field throws a named \`ToolDispatchPayloadError\`.
+ * @param event - the session event to check.
+ * @returns nothing; throws when the payload violates the platform declaration.
+ */
+export declare function assertDispatchPayload(event: {
+    type: string;
+    data?: unknown;
+}): void;
+/**
+ * Total dispatches in a log, deduplicated.
+ * @param events - the log, oldest first.
+ * @returns the number of distinct dispatches, one per dispatch regardless of
+ * how many events carried it.
+ */
+export declare function countDispatches(events: Iterable<{
+    type: string;
+    data?: unknown;
+}>): number;
+//# sourceMappingURL=tool-dispatch.d.ts.map

package/lib/types/usage.d.ts

@@ -59,18 +59,15 @@ export interface UsageMutateOptions {
     onQuarantine?: ((message: string) => void) | undefined;
 }
 export declare function mutateUsage(root: string, io: EvolutionIoLike, task: (map: UsageMap) => void | Promise<void>, options?: UsageMutateOptions): Promise<void>;
-/**
- * Curator-owned usage fields (rc.67 K-2): the curator writes ONLY this set —
+/** Curator-owned usage fields (rc.67 K-2): the curator writes ONLY this set —
  * lifecycle state, archive stamp, the six-factor quality pair, and the
- * marker-mirrored pin flag. Counter and activity-stamp fields belong to the
- * tool-telemetry side (skill-usage / tool-skill-manage), which bumps them
- * through its own transact-backed RMW. A whole-record overwrite by either
- * side would clobber the other side's concurrent increment, so cross-side
- * folds copy this set only.
- */
-export declare function applyCuratorFields(disk: UsageRecord, curated: UsageRecord): void;
+ * marker-mirrored pin flag; counters and activity stamps belong to the
+ * tool-telemetry side and are never copied by a fold. P2-12 (v39): the
+ * combined `applyCuratorFields` wrapper had no production caller (folds go
+ * through {@link foldCuratorFields}), so the two field copies below are the
+ * whole contract. */
 /** Copy only the lifecycle pair (state/archived_at) — see the ownership split
- * rationale on {@link applyCuratorMetaFields}. */
+ * rationale above. */
 export declare function applyCuratorLifecycleFields(disk: UsageRecord, curated: UsageRecord): void;
 /**
  * Copy the recomputed meta pair (quality_score/quality_warn + the