@lmzhen/dsh-evolution-skill-discovery 0.32.2 → 0.32.4

package/lib/types/description-refresh.d.ts

@@ -1,4 +1,25 @@
-import type { DomainMapStore } from './domain-map.ts';
+import { type DomainMapStore } from './domain-map.ts';
+/**
+ * Mark aged fresh descriptions stale so the refresh pass has a producer.
+ * @param store - domain map store.
+ * @param maxAgeHours - age threshold; undefined disables the producer.
+ * @param now - clock for deterministic tests.
+ * @returns number of domains marked stale.
+ */
+export declare function markStaleDescriptions(store: DomainMapStore, maxAgeHours: number | undefined, now?: number): Promise<number>;
+/**
+ * Mark aged descriptions stale AND refresh every stale description in ONE
+ * read/commit. Session start used to call the two producers back to back, so a
+ * single start bumped mapVersion twice (P2-14).
+ * @param store - domain map store.
+ * @param maxAgeHours - age threshold; undefined disables the producer.
+ * @param now - clock for deterministic tests.
+ * @returns counts of marked and refreshed domains.
+ */
+export declare function refreshAgedDescriptions(store: DomainMapStore, maxAgeHours: number | undefined, now?: number): Promise<{
+    marked: number;
+    refreshed: number;
+}>;
 /**
  * Re-render stale domain descriptions from their definition fields.
  * @param store - domain map store.

package/lib/types/domain-bootstrap.d.ts

@@ -1,4 +1,4 @@
-import type { DomainMapSnapshot, DomainMapStore } from './domain-map.ts';
+import { type DomainMapSnapshot, type DomainMapStore } from './domain-map.ts';
 import type { DomainGenerationProposal, GenerationSkillFact } from './domain-generation.ts';
 import type { SkillKey } from './identity.ts';
 /** Real fact used by the production initial-map writer. */

package/lib/types/domain-map.d.ts

@@ -13,12 +13,17 @@ export interface DomainNode {
     readonly version: number;
     readonly createdAt: number;
     readonly updatedAt: number;
+    /** When the description last changed; absent on maps written before this field. */
+    readonly descriptionUpdatedAt?: number | undefined;
     readonly descriptionHash: string;
     readonly descriptionVersion: number;
     readonly descriptionStatus: 'fresh' | 'stale' | 'failed';
     readonly provenance: Readonly<Record<string, string>>;
     readonly quality: Readonly<Record<string, number>>;
 }
+/** The next CAS version. ONE implementation: non-numeric versions get a suffix,
+ * never NaN, and every writer advances the same way. */
+export declare function nextMapVersion(version: string): string;
 /** One skill-domain edge; skillKey is the global identity, not a display name. */
 export interface SkillDomainEdge {
     readonly skillKey: SkillKey;

package/lib/types/domain-policy.d.ts

@@ -1,5 +1,5 @@
 /** One policy layer; only these fields are user-editable. */
-export type DomainPolicyMode = 'off' | 'auto' | 'on';
+export type DomainPolicyMode = 'off' | 'on';
 export interface DomainPolicyLayer {
     readonly mode?: DomainPolicyMode | undefined;
     readonly pinDomains?: readonly string[] | undefined;

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

@@ -9,7 +9,7 @@ export interface DomainProjectionInput {
     readonly complete: boolean;
     readonly mapStale?: boolean | undefined;
     readonly searchAvailable?: boolean | undefined;
-    readonly mode?: 'off' | 'shadow' | 'on' | undefined;
+    readonly mode?: 'off' | 'on' | undefined;
     readonly snapshot: DomainMapSnapshot;
     readonly policy: EffectiveDomainPolicy;
     readonly viewKey: string;
@@ -25,14 +25,6 @@ export interface DomainProjectionInput {
     readonly now?: number | undefined;
     readonly staleAfterHours?: number | undefined;
     readonly descriptionStaleAfterHours?: number | undefined;
-    readonly maxVisibleDepth?: number | undefined;
 }
-/**
- * Build L1 cards and the hidden set for one view, then delegate the pure
- * catalog rewrite. Structural staleness fails open; description staleness does not.
- * @param input - rows, domain facts, policy, and identity inputs.
- * @returns projection result with cards and hidden names.
- */
-export declare function hiddenRecoverable(hiddenNames: readonly string[], searchResultNames: ReadonlySet<string>): boolean;
 export declare function buildDomainProjection(input: DomainProjectionInput): ProjectionResult;
 //# sourceMappingURL=domain-projection.d.ts.map

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

@@ -4,7 +4,7 @@ import type { GenerationRequest } from './domain-generation-coordinator.ts';
 import type { SkillIndexRow } from './identity.ts';
 /** Inputs for the production generation port composition. */
 export interface GenerationCompositionInput {
-    readonly mode: 'off' | 'shadow' | 'on';
+    readonly mode: 'off' | 'on';
     readonly llm?: LlmStreamService | undefined;
     readonly provider: string;
     readonly model: string;

package/lib/types/index.d.ts

@@ -18,16 +18,13 @@ export * from './domain-map-store.ts';
 export * from './domain-policy.ts';
 export * from './domain-generation.ts';
 export * from './domain-description.ts';
+export * from './description-refresh.ts';
 export * from './domain-quality.ts';
 export * from './domain-projection.ts';
 export * from './tool.ts';
-export * from './assignment.ts';
 export * from './security.ts';
-export * from './assignment-sidecar.ts';
 export * from './awareness.ts';
-export * from './worker.ts';
 export * from './domain-bootstrap.ts';
 export * from './domain-generation-service.ts';
-export * from './assignment-queue.ts';
 export * from './domain-generation-prompt.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/types/main-entry.d.ts

@@ -5,14 +5,11 @@ import type { DomainPolicyLayer } from './domain-policy.ts';
 /** Main production config. */
 export interface Config {
     readonly featureEpoch: string;
-    readonly mode?: 'off' | 'shadow' | 'on' | undefined;
+    readonly mode?: 'off' | 'on' | undefined;
     readonly searchEnabled?: boolean | undefined;
     readonly domainMapPath?: string | undefined;
     readonly projectionJournalPath?: string | undefined;
     readonly viewSnapshotPath?: string | undefined;
-    readonly assignmentQueuePath?: string | undefined;
-    readonly createClassificationEnabled?: boolean | undefined;
-    readonly provisionalThreshold?: number | undefined;
     readonly mapReferenceCwd?: string | undefined;
     readonly mapReferenceScope?: string | undefined;
     readonly generationProvider?: string | undefined;

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

@@ -37,7 +37,7 @@ export declare function restoreCapturedProjection(decision: PreStepDecision, cap
  * @param result - projection result.
  * @returns decision with replacement catalog plus optional context.
  */
-export declare function applyReplacementDecision(decision: PreStepDecision, sourceEntries: readonly CatalogEntry[], result: ProjectionResult): PreStepDecision;
+export declare function applyReplacementDecision(decision: PreStepDecision, sourceEntries: readonly CatalogEntry[], result: ProjectionResult, seen?: ReadonlySet<string> | undefined): PreStepDecision;
 /**
  * Append a full replacement catalog without a current catalog message.
  * @param decision - current pre-step decision.
@@ -56,5 +56,5 @@ export declare function renderProjectionContext(result: ProjectionResult): UserM
  * @param result - complete projection.
  * @returns new decision; unchanged when no catalog exists.
  */
-export declare function applyProjectedDecision(decision: PreStepDecision, capture: CatalogCapture, result: ProjectionResult): PreStepDecision;
+export declare function applyProjectedDecision(decision: PreStepDecision, capture: CatalogCapture, result: ProjectionResult, seen?: ReadonlySet<string> | undefined): PreStepDecision;
 //# sourceMappingURL=projection-adapter.d.ts.map

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

@@ -30,5 +30,7 @@ export declare class ProjectionJournal {
     latest(sessionId: string, viewKey: string, codecVersion: string): Promise<ProjectionJournalRecord | undefined>;
     /** Delete one record after a successful restore. */
     remove(sessionId: string, viewKey: string, projectionDigest: string, codecVersion: string): Promise<void>;
+    /** Delete every record for one session/view after a successful restore. */
+    removeView(sessionId: string, viewKey: string, _codecVersion: string): Promise<void>;
 }
 //# sourceMappingURL=projection-journal.d.ts.map

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

@@ -8,6 +8,18 @@ import { type ViewState } from './view-state.ts';
 export interface WorkingDirectoryPort {
     ensure(agent: Agent, signal?: AbortSignal | undefined): Promise<string>;
 }
+/** Bounded catalog/projection history from the evolution-core projection unit. */
+export interface ProjectionHistoryView {
+    readonly catalogs: readonly {
+        readonly text: string;
+        readonly entries: readonly {
+            readonly name: string;
+            readonly description: string;
+        }[];
+        readonly update: boolean;
+    }[];
+    readonly digests: readonly string[];
+}
 /** Inputs for the per-view projection runtime. */
 export interface ProjectionRuntimePorts {
     readonly skillIndexSource: SkillIndexSource;
@@ -16,11 +28,14 @@ export interface ProjectionRuntimePorts {
     readonly policyFor?: ((cwd: string) => Promise<DomainPolicyStore>) | undefined;
     readonly journal: ProjectionJournal;
     readonly workingDirectory: WorkingDirectoryPort;
+    readonly history?: ((agent: Agent) => ProjectionHistoryView | undefined) | undefined;
+    /** Degraded-path warning sink; absence is silent for tests that do not care. */
+    readonly warn?: ((message: string) => void) | undefined;
     readonly featureEpoch: string;
     readonly codecVersion: string;
     readonly adapterVersion: string;
     readonly projectionSchemaVersion: string;
-    readonly mode: 'off' | 'shadow' | 'on';
+    readonly mode: 'off' | 'on';
     readonly maxCards?: number | undefined;
     readonly tokenBudget?: number | undefined;
     readonly searchAvailable?: (() => boolean) | undefined;
@@ -41,9 +56,12 @@ export declare class ProjectionRuntime {
     private readonly states;
     private last;
     private readonly lastByAgent;
+    private warnedMissingHistory;
     constructor(ports: ProjectionRuntimePorts);
     /** @returns last action for one agent, or the latest process-wide action. */
     report(agent?: Agent | undefined): ProjectionReport;
+    private hasStructuralLog;
+    private warnMissingHistory;
     private mark;
     /** @returns current state for diagnostics, if this process has seen the view. */
     stateFor(viewKey: string, mapVersion: string, policyDigest: string): ViewState | undefined;

package/lib/types/search.d.ts

@@ -65,6 +65,12 @@ export interface SearchIndexCacheKey {
 /** Per-view cache keyed by searchIndexKey; never shares one engine across views. */
 export declare class SkillSearchCache {
     private readonly entries;
+    private readonly maxEntries;
+    constructor(options?: {
+        readonly maxEntries?: number | undefined;
+    });
+    /** @returns the current number of cached view indices (bounded by maxEntries). */
+    get size(): number;
     /**
      * Get or build one view index. A failed rebuild retains the previous engine
      * and marks it stale; no previous engine means undefined.

package/lib/types/view-snapshot-store.d.ts

@@ -14,12 +14,14 @@ export interface ViewSnapshot {
 export declare class ViewSnapshotStore {
     private readonly io;
     private readonly path;
+    private serial;
     constructor(io: EvolutionIoLike, path: string);
     private read;
     /** Persist one session snapshot; first writer wins unless overwrite is explicit. */
     put(snapshot: ViewSnapshot, options?: {
         readonly overwrite?: boolean | undefined;
     }): Promise<void>;
+    private decode;
     /** @returns frozen snapshot for one session, if recorded. */
     get(sessionId: string): Promise<ViewSnapshot | undefined>;
     /**

package/lib/types/view-state.d.ts

@@ -18,7 +18,7 @@ export interface ViewState {
 /** Inputs used to derive one view state. */
 export interface ViewStateInput {
     readonly viewKey: string;
-    readonly mode: 'off' | 'shadow' | 'on';
+    readonly mode: 'off' | 'on';
     readonly map: MapState;
     readonly search: SearchState;
     readonly policy: PolicyState;
@@ -31,11 +31,9 @@ export interface ViewStateInput {
 /**
  * Derive one view's state without consulting another view.
  * @param input - per-view health and identity.
- * @returns state with reasons; hidden safety is evaluated by canHide.
+ * @returns state with reasons; card rendering is gated by canProject.
  */
 export declare function deriveViewState(input: ViewStateInput): ViewState;
-/** @returns true only when this view may hide catalog entries. */
-export declare function canHide(state: ViewState): boolean;
 /** @returns true when this view may render cards, even if hiding is blocked. */
 export declare function canProject(state: ViewState): boolean;
 /** Bounded view-state cache keyed by view identity and codec version. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-skill-discovery",
   "description": "Read model and view identity for evolution skill discovery (community build)",
-  "version": "0.32.2",
+  "version": "0.32.4",
   "publishConfig": {
     "access": "public"
   },
@@ -32,9 +32,8 @@
     "@deepseek-ai/dsh-llm": "^0.2.1-rc.2",
     "@deepseek-ai/dsh-tools": "^0.2.1-rc.2",
     "@deepseek-ai/dsh-system-prompt": "^0.2.1-rc.2",
-    "@lmzhen/dsh-evolution-contract": "^0.32.2",
-    "@lmzhen/dsh-evolution-core": "^0.32.2",
-    "@lmzhen/dsh-evolution-io": "^0.32.2"
+    "@lmzhen/dsh-evolution-core": "^0.32.4",
+    "@lmzhen/dsh-evolution-io": "^0.32.4"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-skill": "^0.2.1-rc.2",
@@ -44,9 +43,8 @@
     "@deepseek-ai/dsh-agent-loop-testkit": "^0.2.1-rc.2",
     "@deepseek-ai/dsh-system-prompt": "^0.2.1-rc.2",
     "@deepseek-ai/dsh-tools": "^0.2.1-rc.2",
-    "@lmzhen/dsh-evolution-contract": "^0.32.2",
-    "@lmzhen/dsh-evolution-core": "^0.32.2",
-    "@lmzhen/dsh-evolution-io": "^0.32.2"
+    "@lmzhen/dsh-evolution-core": "^0.32.4",
+    "@lmzhen/dsh-evolution-io": "^0.32.4"
   },
   "dependencies": {
     "@deepseek-ai/dsh-llm": "^0.2.1-rc.2",

package/lib/types/assignment-queue.d.ts

@@ -1,26 +0,0 @@
-import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
-import type { EvolutionStateStore } from '@lmzhen/dsh-evolution-contract';
-import type { AssignmentQueue, AssignmentQueueEntry, AssignmentSubmission } from './assignment.ts';
-/** Durable assignment queue; process-local cache over one JSON file. */
-export declare class JsonAssignmentQueue implements AssignmentQueue {
-    private readonly entries;
-    private loadPromise;
-    private readonly io;
-    private readonly path;
-    private readonly store;
-    constructor(io: EvolutionIoLike, path: string, store?: EvolutionStateStore);
-    load(): Promise<void>;
-    private persist;
-    enqueue(input: {
-        key: string;
-        submission: AssignmentSubmission;
-        proposalDigest: string;
-        createdAt: number;
-    }): Promise<{
-        entry: AssignmentQueueEntry;
-        duplicate: boolean;
-    }>;
-    update(key: string, status: AssignmentQueueEntry['status'], pendingReason?: AssignmentQueueEntry['pendingReason']): Promise<void>;
-    list(): readonly AssignmentQueueEntry[];
-}
-//# sourceMappingURL=assignment-queue.d.ts.map

package/lib/types/assignment-sidecar.d.ts

@@ -1,33 +0,0 @@
-import type { Context as CordisContext } from '@deepseek-ai/cordis';
-import type { Context as HostContext } from '@deepseek-ai/cordis/src/context.ts';
-type Context = CordisContext & HostContext;
-import type { DomainAssignmentService } from './assignment.ts';
-declare module '@deepseek-ai/cordis' {
-    interface Events {
-        'evolution/approval-decided'(payload: {
-            readonly record: {
-                readonly kind: string;
-                readonly args: unknown;
-            };
-            readonly action: 'approve' | 'reject';
-            readonly ok: boolean;
-        }): void;
-    }
-}
-/** Options for the create sidecar; it never writes skill content. */
-export interface AssignmentSidecarOptions {
-    readonly provider?: string | undefined;
-    readonly source?: string | undefined;
-    readonly onSubmitted?: (() => void) | undefined;
-}
-/**
- * Observe successful create calls and submit their optional domain proposal.
- * Direct creates submit immediately; staged creates submit only after approval.
- * @param ctx - plugin context with tools and approval events.
- * @param service - the one assignment service.
- * @param options - provider/source identity for skillKey.
- * @returns disposer for both listeners.
- */
-export declare function installAssignmentSidecar(ctx: Context, service: DomainAssignmentService, options?: AssignmentSidecarOptions): () => void;
-export {};
-//# sourceMappingURL=assignment-sidecar.d.ts.map

package/lib/types/assignment.d.ts

@@ -1,131 +0,0 @@
-import type { DomainMapStore, DomainNode } from './domain-map.ts';
-import type { SkillKey } from './identity.ts';
-/** Closed technical pending set; semantic uncertainty is not pending. */
-export type AssignmentPendingReason = 'invalid-id' | 'unknown-domain' | 'map-version-stale' | 'new-domain-conflict' | 'schema-invalid' | 'queue-unavailable';
-/** LLM proposal accepted by skill_manage create; code validates/mints. */
-export interface AssignmentProposal {
-    readonly mode: 'existing' | 'new';
-    readonly id?: string | undefined;
-    readonly proposed?: {
-        readonly title: string;
-        readonly purpose: string;
-        readonly inScope: readonly string[];
-        readonly outOfScope: readonly string[];
-        readonly triggers: readonly string[];
-        readonly evidenceSkillKeys: readonly string[];
-    } | undefined;
-    readonly secondaryDomainIds?: readonly string[] | undefined;
-    readonly confidence: number;
-    readonly reason: string;
-    readonly needsReview?: boolean | undefined;
-    readonly mapVersion: string;
-}
-/** One create-side queue submission. */
-export interface AssignmentSubmission {
-    readonly skillKey: SkillKey;
-    readonly threeFieldHash: string;
-    readonly modelInvocable: boolean;
-    readonly whenToUse?: string | undefined;
-    readonly proposal?: AssignmentProposal | undefined;
-    readonly now?: number | undefined;
-}
-/** Queue entry; key is the idempotency key. */
-export interface AssignmentQueueEntry {
-    readonly key: string;
-    readonly submission: AssignmentSubmission;
-    readonly proposalDigest: string;
-    readonly createdAt: number;
-    status: 'queued' | 'pending' | 'applied' | 'provisional';
-    pendingReason?: AssignmentPendingReason | undefined;
-}
-/** Queue abstraction used by the one assignment service. */
-export interface AssignmentQueue {
-    enqueue(entry: {
-        readonly key: string;
-        readonly submission: AssignmentSubmission;
-        readonly proposalDigest: string;
-        readonly createdAt: number;
-    }): Promise<{
-        entry: AssignmentQueueEntry;
-        duplicate: boolean;
-    }>;
-    update(key: string, status: AssignmentQueueEntry['status'], pendingReason?: AssignmentPendingReason): Promise<void>;
-}
-/** In-memory idempotent queue; production adapter can persist by key. */
-export declare class MemoryAssignmentQueue implements AssignmentQueue {
-    private readonly entries;
-    enqueue(input: {
-        key: string;
-        submission: AssignmentSubmission;
-        proposalDigest: string;
-        createdAt: number;
-    }): Promise<{
-        entry: AssignmentQueueEntry;
-        duplicate: boolean;
-    }>;
-    update(key: string, status: AssignmentQueueEntry['status'], pendingReason?: AssignmentPendingReason): Promise<void>;
-    list(): readonly AssignmentQueueEntry[];
-}
-/** Staged create: no queue entry until approval. */
-export interface StagedAssignment {
-    readonly id: string;
-    readonly submission: AssignmentSubmission;
-}
-/** Result of submit/process; create failure never appears here. */
-export type AssignmentResult = {
-    readonly kind: 'unclassified';
-    readonly reason: 'feature-off' | 'no-proposal' | 'not-model-invocable';
-} | {
-    readonly kind: 'queued';
-    readonly entry: AssignmentQueueEntry;
-    readonly duplicate: boolean;
-} | {
-    readonly kind: 'applied' | 'provisional';
-    readonly entry: AssignmentQueueEntry;
-    readonly mapVersion: string;
-} | {
-    readonly kind: 'pending';
-    readonly entry: AssignmentQueueEntry;
-    readonly reason: AssignmentPendingReason;
-};
-/** @returns idempotency key for one proposal observation. */
-export declare function assignmentKey(input: {
-    skillKey: SkillKey;
-    threeFieldHash: string;
-    proposalDigest: string;
-    mapVersion: string;
-}): string;
-/** @returns stable proposal digest; undefined proposal is digest of null. */
-export declare function proposalDigest(proposal: AssignmentProposal | undefined): string;
-/** @returns a closed-set pending reason or undefined when the proposal can enqueue. */
-export declare function validateProposal(proposal: AssignmentProposal): AssignmentPendingReason | undefined;
-/** @returns true only when whenToUse is covered by in/out/triggers; names alone do not count. */
-export declare function coveredByDomain(whenToUse: string, domain: Pick<DomainNode, 'inScope' | 'outOfScope' | 'triggers'>): boolean;
-/** One assignment sidecar service; the only map write path for create. */
-export declare class DomainAssignmentService {
-    private readonly queue;
-    private readonly store;
-    private readonly options;
-    constructor(queue: AssignmentQueue, store: DomainMapStore, options: {
-        readonly createClassificationEnabled: boolean;
-        readonly createCardsAvailable?: boolean;
-        readonly provisionalThreshold?: number;
-        readonly now?: () => number;
-    });
-    /** Stage a create proposal without queueing it. */
-    stage(submission: AssignmentSubmission): StagedAssignment;
-    /** Approve a staged create; only this call enqueues. */
-    approve(staged: StagedAssignment): Promise<AssignmentResult>;
-    /**
-     * Submit a create proposal after SkillLibrary.create succeeded.
-     * @param submission - skill identity, three-field hash, permission, proposal.
-     * @returns queue/pending/unclassified; never rolls back create.
-     */
-    submit(submission: AssignmentSubmission): Promise<AssignmentResult>;
-    /** Process one queued entry with the current map; CAS failure becomes pending. */
-    process(entry: AssignmentQueueEntry): Promise<AssignmentResult>;
-    /** Manually confirm one provisional domain; no semantic reclassification. */
-    confirm(domainId: string): Promise<boolean>;
-    private now;
-}
-//# sourceMappingURL=assignment.d.ts.map

package/lib/types/worker.d.ts

@@ -1,14 +0,0 @@
-import type { AssignmentQueueEntry, DomainAssignmentService } from './assignment.ts';
-/** Queue view needed by the worker. */
-export interface AssignmentQueueReader {
-    list(): readonly AssignmentQueueEntry[];
-}
-/** Drivable worker; the composition may call drain on a schedule. */
-export declare class AssignmentWorker {
-    private readonly service;
-    private readonly queue;
-    constructor(service: DomainAssignmentService, queue: AssignmentQueueReader);
-    /** Process queued entries once; returns processed count. */
-    drain(limit?: number): Promise<number>;
-}
-//# sourceMappingURL=worker.d.ts.map