@lmzhen/dsh-evolution-core 0.1.0-rc.9 → 0.2.0-rc.1

package/lib/types/usage.d.ts

@@ -16,13 +16,63 @@ export interface UsageRecord {
     state: SkillState;
     pinned: boolean;
     archived_at: string | null;
-    quality_score?: number;
-    quality_warn?: boolean;
+    quality_score?: number | undefined;
+    quality_warn?: boolean | undefined;
 }
 export type UsageMap = Map<string, UsageRecord>;
 export declare function usageFile(root: string): string;
 export declare function emptyRecord(): UsageRecord;
+/**
+ * Field-level normalization for one sidecar record (rc.42 audit P2-3): the
+ * spread used to copy any junk through verbatim, so a corrupted file could
+ * carry `use_count: "3"` into the quality math and lifecycle comparisons as
+ * NaN. Every field falls back to its `emptyRecord()` baseline unless it has
+ * exactly the declared type; an invalid `created_at` anchors the age clock at
+ * now (first-sight defer semantics for a record whose age is unknowable).
+ * Timestamps additionally require a parseable date (N-3): `"not-a-date"`
+ * would otherwise survive the type check as Invalid Date.
+ * Pure — exported for unit tests; `loadUsage` is the production caller.
+ */
+export declare function normalizeUsageRecord(record: unknown): UsageRecord;
 export declare function loadUsage(root: string, io?: EvolutionIoLike): Promise<UsageMap>;
+/**
+ * Atomic read-modify-write on the usage sidecar (rc.50 P2-2): `task` receives
+ * the map parsed from the current on-disk state and may mutate it; the result
+ * is persisted inside the same transact so a second process sharing DSH_HOME
+ * cannot interleave its RMW and lose a counter update. Callers keep their own
+ * single-process serialize chain as the second layer.
+ */
+export declare function mutateUsage(root: string, io: EvolutionIoLike, task: (map: UsageMap) => void | Promise<void>): Promise<void>;
+/**
+ * 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;
+/** Copy only the lifecycle pair (state/archived_at) — see the ownership split
+ * rationale on {@link applyCuratorMetaFields}. */
+export declare function applyCuratorLifecycleFields(disk: UsageRecord, curated: UsageRecord): void;
+/**
+ * Copy the recomputed meta pair (quality_score/quality_warn + the
+ * marker-mirrored pin flag) — refreshed tree-wide each run by design, so a
+ * concurrent curator run's lifecycle changes are never reverted by them.
+ */
+export declare function applyCuratorMetaFields(disk: UsageRecord, curated: UsageRecord): void;
+/**
+ * Fold a curator run-start snapshot onto the current on-disk map (rc.67 K-2):
+ * each curated record is projected onto its disk peer by copying only the
+ * curator-owned fields, so a concurrent tool-side bump between snapshot and
+ * save survives. Records absent from the snapshot are left untouched; a
+ * curated record with no disk peer is seeded from the snapshot. `stateOwned`
+ * (rc.72 H-1) restricts the lifecycle pair to the names this run ACTUALLY
+ * transitioned — a concurrent curator run's archive/restore is never reverted
+ * by a stale snapshot; without it both pairs apply everywhere.
+ */
+export declare function foldCuratorFields(disk: UsageMap, curated: UsageMap, stateOwned?: ReadonlySet<string>): void;
 export declare function saveUsage(root: string, map: UsageMap, io?: EvolutionIoLike): Promise<void>;
 export declare function getRecord(map: UsageMap, name: string): UsageRecord;
 export declare function bumpView(map: UsageMap, name: string, when?: Date): void;
@@ -30,4 +80,29 @@ export declare function bumpUse(map: UsageMap, name: string, when?: Date): void;
 export declare function bumpPatch(map: UsageMap, name: string, when?: Date): void;
 export declare function markAgentCreated(map: UsageMap, name: string): void;
 export declare function latestActivityAt(record: UsageRecord): string | null;
+/**
+ * Whether the library has ANY observed read evidence (C observation window):
+ * reads were invisible to the usage sidecar before A2, so `view_count` zero
+ * means "never read" ONLY after the first observed read exists anywhere in
+ * the map. Before that, churn-based signals (write-ghost) are untrustworthy
+ * and callers must suppress them. Pure and derived — never persisted.
+ */
+export declare function usageObserved(usage: ReadonlyMap<string, UsageRecord>): boolean;
+/**
+ * Curator suppression sidecar: built-in skills the curator has archived stay
+ * suppressed across re-seeds, so the lifecycle never fights a re-created
+ * bundled skill. Best-effort load/save, mirroring the usage sidecar posture.
+ * Versioned shape ({ version, names }) with legacy plain-array compat.
+ */
+export declare const SUPPRESSED_FILE_VERSION = 1;
+export declare function suppressedFile(root: string): string;
+export declare function loadSuppressedNames(root: string, io?: EvolutionIoLike): Promise<ReadonlySet<string>>;
+export declare function saveSuppressedNames(root: string, names: ReadonlySet<string>, io?: EvolutionIoLike): Promise<void>;
+/**
+ * Atomic read-modify-write on the suppression sidecar (rc.50 P2-2): `task`
+ * receives the set parsed from the current on-disk state and may mutate it;
+ * the result is persisted inside the same transact so a second process
+ * sharing DSH_HOME cannot interleave its RMW. Best-effort posture unchanged.
+ */
+export declare function updateSuppressedNames(root: string, io: EvolutionIoLike, task: (names: Set<string>) => void | Promise<void>): Promise<void>;
 //# sourceMappingURL=usage.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.1.0-rc.9",
+  "version": "0.2.0-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -32,13 +32,13 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2"
   }
 }