@lmzhen/dsh-evolution-core 0.16.1 → 0.17.0

package/lib/types/session-projection.d.ts

@@ -0,0 +1,147 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
+import { type EvidenceIndex } from './evidence.ts';
+import { type TurnFoldState, type TurnSignals } from './signals.ts';
+/** Time of the newest event folded for one session; 0 for a log with no event. */
+export interface EvolutionActivityState {
+    /** Milliseconds of the newest event, or 0 when nothing was folded. */
+    readonly lastEventTime: number;
+}
+/**
+ * Which session frames carry content, in complement form.
+ *
+ * `sequenced` counts the frames that carry an integer seq, so 0 is the "this log cannot tell a
+ * boundary from a message" answer the evidence reader reports as `undefined` (a stub session, a
+ * log whose events carry no seq).
+ *
+ * `through` is the highest seq folded, so a citation BEYOND the log answers false exactly as the
+ * dense set does. Platform logs number their frames densely from 0 (a seq is a frame's index), so
+ * complement and enumeration agree; a sparse hand-built log is not a Session and reaches the unit
+ * through neither path.
+ */
+export interface EvolutionEvidenceState {
+    /** Frames folded that carried an integer seq. */
+    readonly sequenced: number;
+    /** Highest seq folded; -1 before the first sequenced frame. */
+    readonly through: number;
+    /** Boundary seqs, ascending. Every other seq at or below `through` carries content. */
+    readonly bookkeeping: readonly number[];
+}
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionStateMap {
+        /** The curator's idleness gate input: the newest event time of one session. */
+        evolutionActivity: EvolutionActivityState;
+        /** The plan path's evidence-class input: the boundary seqs of one session. */
+        evolutionEvidence: EvolutionEvidenceState;
+    }
+}
+/** The `evolutionActivity` unit (host-only: no client view is registered for it). */
+export declare const evolutionActivityProjection: ProjectionDefinition<'evolutionActivity'>;
+/** The `evolutionEvidence` unit (host-only: no client view is registered for it). */
+export declare const evolutionEvidenceProjection: ProjectionDefinition<'evolutionEvidence'>;
+/**
+ * The skill names one session read through a non-failed dispatch, as a fold state.
+ *
+ * One entry per READ-CAPABLE dispatch (`isSkillReadToolName`), in first-seen order: the ledger
+ * key, the skill the arguments name (null when they name none), and whether a settle failed it.
+ * A pending dispatch counts as read — the platform settles every started sub-dispatch, so pending
+ * is a live-window state, not a failure (`skillReadNameOf` documents the same rule).
+ */
+export interface EvolutionReadsState {
+    /** Read dispatches seen so far, in first-seen order. */
+    readonly reads: readonly {
+        readonly key: string;
+        readonly skill: string | null;
+        readonly failed: boolean;
+    }[];
+}
+/**
+ * The current turn's window signals plus the facts a turn boundary needs.
+ *
+ * `turn` is the SAME state `foldTurnEvent` folds for `observeEvent`; it resets at `turn/start`, so
+ * the state after the newest event is exactly the window `foldTurn(session, turnStartSeq)` reads.
+ * `through`/`lastEventTime` serve readers that only need progress (the curator's idleness gate has
+ * its own unit, but a consumer holding this one gets the same answers).
+ */
+export interface EvolutionSignalsState {
+    /** Seq of the last folded event; -1 before the first. */
+    readonly through: number;
+    /** Time of the last folded event; 0 before the first. */
+    readonly lastEventTime: number;
+    /** Seq of the open turn's `turn/start`; -1 when none was seen. */
+    readonly turnStartSeq: number;
+    /** The open turn's window fold. */
+    readonly turn: TurnFoldState;
+}
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionStateMap {
+        /** The skill names one session read, for the read-before-write gate and the review plan path. */
+        evolutionReads: EvolutionReadsState;
+        /** The open turn's window signals, for the review cadence. */
+        evolutionSignals: EvolutionSignalsState;
+    }
+}
+/** The `evolutionReads` unit (host-only: no client view is registered for it). */
+export declare const evolutionReadsProjection: ProjectionDefinition<'evolutionReads'>;
+/** The `evolutionSignals` unit (host-only: no client view is registered for it). */
+export declare const evolutionSignalsProjection: ProjectionDefinition<'evolutionSignals'>;
+/**
+ * Register the family's units on the calling context's fiber.
+ *
+ * Called by the READERS (not by a plugin's mount) and idempotent by the registry's own reference
+ * count: the first read of a foldable session installs the definitions, later reads count as
+ * co-owners, and the keys survive until the last registrant unloads
+ * (`session-projection/src/index.ts:273-292`). Registering at the read is what keeps a session
+ * view the registry cannot fold (`isProjectableSession`) from ever reaching its drive — the
+ * registry folds the in-memory log on first touch, so a unit that appears mid-session is still
+ * correct (`:602-630`).
+ *
+ * Idempotent by design, so a plugin mounting later does not need its own call.
+ * @param ctx - the mounting plugin's context.
+ */
+export declare function installEvolutionProjections(ctx: Context): void;
+/**
+ * Time of one session's newest event, or `undefined` when the unit is not installed.
+ *
+ * The curator's idleness gate reads this instead of folding the session log; `undefined` is a
+ * measurement that did not happen, which the gate answers with the deployment's fail-open policy.
+ * @param ctx - a context of the runtime (the service is read from the global store).
+ * @param session - the session to ask about.
+ * @returns the newest event's milliseconds, or undefined with no unit or no event.
+ */
+export declare function sessionLastEventTime(ctx: Context, session: Session): number | undefined;
+/**
+ * The skill names one session read through a non-failed dispatch, or `undefined` when the session
+ * cannot be projected (a structural view, or a host without the registry).
+ *
+ * `undefined` is NOT an empty set: the tool path's read-before-write gate keeps its previous
+ * behavior rather than refusing every write in a composition whose session object is a bare stub
+ * (`skill-reads.ts` documents that three-state posture).
+ * @param ctx - a context of the runtime.
+ * @param session - the session whose reads are wanted.
+ * @returns the names read, or undefined when the log cannot be folded.
+ */
+export declare function sessionReadNames(ctx: Context, session: Session): ReadonlySet<string> | undefined;
+/**
+ * The open turn's window signals, or `undefined` when the session cannot be projected.
+ *
+ * The window is the events since the newest `turn/start`, folded by the same `foldTurnEvent`
+ * `observeEvent` uses; `undefined` means the caller has no measurement (a structural view), not
+ * that the turn was empty.
+ * @param ctx - a context of the runtime.
+ * @param session - the session whose open turn is being judged.
+ * @returns the window signals, or undefined when the log cannot be folded.
+ */
+export declare function sessionTurnSignals(ctx: Context, session: Session): TurnSignals | undefined;
+/**
+ * The evidence index of one session, or `undefined` when the log cannot be classified.
+ *
+ * `undefined` covers both the missing unit and a log whose frames carry no seq: the plan path's
+ * `EVIDENCE_CLASS` row is report-only and must stay silent rather than report every op.
+ * @param ctx - a context of the runtime.
+ * @param session - the session the review plan is authored against.
+ * @returns an index answering "does this seq carry content?".
+ */
+export declare function sessionEvidenceIndex(ctx: Context, session: Session): EvidenceIndex | undefined;
+//# sourceMappingURL=session-projection.d.ts.map

package/lib/types/signals.d.ts

@@ -5,7 +5,7 @@
  * is spent. `turn/end` calls `observeEvent`; the returned review kind is
  * accumulated until a configured interval fires.
  */
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
 export type ReviewKind = 'memory' | 'skill' | 'combined';
 export interface SignalConfig {
     memoryInterval: number;
@@ -33,10 +33,51 @@ export interface ReviewState {
     turnsSinceSkill: number;
     lastTurn: number;
 }
-/** Fold one session event into the current turn observation. */
+/**
+ * The turn-window fold state: what {@link TurnSignals} carries plus its dispatch ledger.
+ *
+ * `opened` holds one ledger key per dispatch this window already counted
+ * ({@link dispatchStepOf}). It lives in the state — not in a side table — because the state is
+ * what a live projection unit and a whole-log fold both carry between events.
+ */
+export interface TurnFoldState extends TurnSignals {
+    /** Ledger keys this window already counted, in first-seen order. */
+    opened: string[];
+}
+/** The empty turn-window fold state. */
+export declare function initialTurnFold(): TurnFoldState;
+/**
+ * Fold ONE session event into a turn-window state, purely.
+ *
+ * The one fold behind all three readers: `observeEvent` (the mutating face the live `turn/end`
+ * path uses), `foldTurn` (a whole-log window fold, kept for structural test sessions) and the
+ * family's `evolutionSignals` projection unit. P1-1/N4 guards stay: events arrive from disk, so
+ * a persisted `data: null` / non-object or a malformed `content` skips instead of throwing.
+ * @param state - the window so far.
+ * @param event - the next committed session event.
+ * @returns the next state; the same reference when the event carries nothing this fold reads.
+ */
+export declare function foldTurnEvent(state: TurnFoldState, event: SessionEvent): TurnFoldState;
+/**
+ * Fold one session event into the current turn observation (the mutating face of
+ * {@link foldTurnEvent}: every reader shares the one fold, this one copies the result back onto
+ * the caller's signal object and keeps its ledger for the next event).
+ * @param signal - the turn observation to advance.
+ * @param event - the next committed session event.
+ */
 export declare function observeEvent(signal: TurnSignals, event: SessionEvent): void;
 /** Compute review cadence after `turn/end`. */
 export declare function advanceReview(state: ReviewState, turn: number, signal: TurnSignals, config: SignalConfig): ReviewKind | null;
-/** Fold all events between two sequence boundaries into one TurnSignals. */
-export declare function foldTurn(session: Session, fromSeq: number): TurnSignals;
+/**
+ * Fold a log slice into one turn window, purely.
+ *
+ * The whole-log reference for {@link foldTurnEvent}: a caller that holds events (a fixture, a
+ * structural view, a replay) reads a window without touching a platform Session. Production reads
+ * the same window live from the family's `evolutionSignals` projection (`sessionTurnSignals`),
+ * which folds `foldTurnEvent` once per committed event.
+ * @param events - the log, oldest first. Pass an array, not a live iterator, when it can grow.
+ * @param fromSeq - index of the first event of the window (0 for the whole log).
+ * @returns the window's signals.
+ */
+export declare function foldTurnEvents(events: Iterable<SessionEvent>, fromSeq?: number): TurnSignals;
 //# sourceMappingURL=signals.d.ts.map

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

@@ -1,3 +1,28 @@
+/**
+ * The read-before-write RULE: which writes need a prior read, and which targets count as read.
+ *
+ * ONE rule for TWO enforcement points (design `dsh-evolution-write-gate-design.md` §4.2): the
+ * tool path refuses an unread mutating write (E-318), and the plan path drops such an op from a
+ * background review's plan. Before this module the rule lived in `evolution-review` only, so the
+ * tool path could not see it at all.
+ *
+ * The READER is not here either: `tool-dispatch.collectReadSkillNames(events)` folds a session log
+ * into the names read through a non-failed dispatch — the review's old session-shaped copy was a
+ * line-for-line duplicate of it. What this module adds over it is the session-shaped ADAPTER
+ * (`sessionReadSkillNames`), for the ONE caller that holds a session only STRUCTURALLY (the tool
+ * path's gate, whose exec view may be a bare stub): it answers "which accessor, and what does an
+ * unreadable session mean" — `undefined`, so the gate keeps its previous behavior instead of
+ * refusing every write. The review path reads a real platform `Session` and calls the reader
+ * directly; a fallback there would be dead code for an impossible case.
+ *
+ * v32 REV-06(a) is preserved by the dispatch normalizer: a skill counts as READ only when its read
+ * did not fail, so a failed/timeout read cannot pass the gate and let a writer blind-overwrite
+ * content the model never saw. Matching `tool/call` directly (the pre-v37 form) meant every PTC
+ * session (`tool/ptc-dispatch*`) collected an EMPTY set, so every mutating op the model HAD read
+ * was dropped — and nothing reported the loss.
+ * @module @lmzhen/dsh-evolution-core
+ */
+import type { Context } from '@deepseek-ai/cordis';
 /** The session-log accessor the platform exposes (0.1.5 on; `session.events` before it). */
 export interface EvolutionSessionLogView {
     /** @returns the session's events, oldest first. */
@@ -9,13 +34,19 @@ export interface EvolutionSessionLogView {
 /**
  * The skill names ONE session read, or `undefined` when its log is not readable.
  *
+ * Two readers, in this order: the family's `evolutionReads` projection for a platform `Session`
+ * (0.2.x's live read — the deprecated synchronous log read is gone from production), then the
+ * STRUCTURAL accessor for a view that is not a `Session` at all. The tool path's exec view may be a
+ * bare stub, which is what this module exists for; a real Session always takes the first path.
+ *
  * `undefined` is NOT an empty set: a caller that must decide (the tool path's read-before-write
  * gate) can then keep its previous behavior instead of refusing every write in a composition whose
  * session objects expose no log at all.
+ * @param ctx - a context of the runtime.
  * @param session - the session whose reads are wanted; `undefined` when the call carries none.
  * @returns the names read through a non-failed `skill` dispatch, or `undefined` when unreadable.
  */
-export declare function sessionReadSkillNames(session: EvolutionSessionLogView | undefined): ReadonlySet<string> | undefined;
+export declare function sessionReadSkillNames(ctx: Context, session: EvolutionSessionLogView | undefined): ReadonlySet<string> | undefined;
 /** Actions whose target must have been read first (create is authorship, so it is exempt). */
 export declare const READ_REQUIRED_ACTIONS: readonly string[];
 /**

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

@@ -82,6 +82,55 @@ export interface ToolDispatchSignal {
 export declare class ToolDispatchPayloadError extends TypeError {
     name: string;
 }
+/**
+ * The ledger key of one dispatch: a scope-qualified call id.
+ *
+ * v43 audit (FLOW4-4): a normalizer shared by every session (skill-usage's live listener holds ONE
+ * process-wide instance) used the bare call id, so two sessions that produced the same id — PTC
+ * sub-call ids are short, and an id-less payload falls back to a type+payload key that is not
+ * unique by construction — collided: the second session's read was absorbed as "already seen" and
+ * never counted, and a settle in one session flipped the other's `ok`. Callers that span sessions
+ * pass the session id as `scope`.
+ * @param callId - the dispatch's call id (or its payload-derived fallback).
+ * @param scope - the owning session id, or '' for a fold that never leaves one session.
+ * @returns the key both the ledger and every projection fold dedupe on.
+ */
+export declare function dispatchKeyOf(callId: string, scope?: string): string;
+/**
+ * The pure half of the ledger: what one event says about one dispatch.
+ *
+ * The DECISION (which dispatch, and whether this event is the one that opens it) lives here and
+ * only here; carriers differ in what they keep — the class below keeps consumer-visible mutable
+ * signals, the family's `evolutionReads`/`evolutionSignals` projection units keep plain-JSON
+ * ledgers. `name` is empty on an event that only settles an already-opened dispatch (a native
+ * `tool/result`), and `outcome` is present exactly when the event carried one.
+ * @param event - one session event; any non-dispatch event answers `null`.
+ * @param scope - the owning session id, or '' for a single-session fold.
+ * @returns the step, or `null` when the event is not a dispatch.
+ */
+export declare function dispatchStepOf(event: {
+    type: string;
+    data?: unknown;
+}, scope?: string): DispatchStep | null;
+/** One ledger step: what one event tells a fold about one dispatch. */
+export interface DispatchStep {
+    /** The scoped ledger key ({@link dispatchKeyOf}). */
+    readonly key: string;
+    /** How the platform logged this dispatch (native call or PTC program). */
+    readonly kind: ToolDispatchKind;
+    /** The dispatch's call id, unscoped. */
+    readonly callId: string;
+    /** The program root this dispatch belongs to (its own id for a native call). */
+    readonly rootCallId: string;
+    /** The dispatched tool name; empty when the event only settles a dispatch. */
+    readonly name: string;
+    /** Raw arguments as logged (a JSON string natively, an object in PTC mode). */
+    readonly arguments: unknown;
+    /** Present exactly when the event carried an outcome. */
+    readonly outcome?: {
+        readonly ok: boolean;
+    };
+}
 /**
  * The family's single dispatch ledger: absorbs platform events in log order,
  * emits one \`ToolDispatchSignal\` per dispatch, and folds later events of the
@@ -105,16 +154,6 @@ export declare class ToolDispatchNormalizer {
     constructor(options?: {
         maxTracked?: number;
     });
-    /**
-     * v43 audit (FLOW4-4): the ledger key. A normalizer shared by every session
-     * (skill-usage's live listener holds ONE process-wide instance) used the bare
-     * call id, so two sessions that produced the same id — PTC sub-call ids are
-     * short, and an id-less payload falls back to a type+payload key that is not
-     * unique by construction — collided: the second session's read was absorbed as
-     * "already seen" and never counted, and a settle in one session flipped the
-     * other's `ok`. Callers that span sessions pass the session id as `scope`.
-     */
-    private keyOf;
     /**
      * Absorb one session event.
      * @param event - the event to absorb; any non-dispatch event is ignored.

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.16.1",
+  "version": "0.17.0",
   "publishConfig": {
     "access": "public"
   },
@@ -30,16 +30,19 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "yaml": "^2.4.2"
+    "yaml": "^2.4.2",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-scope": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.2"
+    "@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"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-scope": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.2"
+    "@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"
   }
 }