@lmzhen/dsh-evolution-core 0.4.0 → 0.5.0

package/lib/types/reference-rewrite.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Reference re-homing plans (0.5.0 V1, design §16.7).
+ *
+ * A consolidation moves one skill's body under ANOTHER skill root, where every
+ * support-dir reference resolves against that other root (design §2.1). This
+ * module plans what has to happen to the support files and to the body's
+ * references for the move to leave no dangling link. Pure: the caller owns IO,
+ * decides the destination names, and decides whether the plan is applied (V2)
+ * or only reported (V1). Cross-skill rewriting is out of scope by design (§14) —
+ * a plan covers ONE body.
+ */
+/** One re-homed support file: source-relative path -> target-relative path. */
+export interface ReferenceMove {
+    /** Path inside the skill the body comes FROM. */
+    from: string;
+    /** Path inside the skill the body moves TO. */
+    to: string;
+}
+/** One reference the plan rewrites, in body line order. */
+export interface ReferenceRewriteEdit {
+    /** 1-based line in the body being moved. */
+    line: number;
+    /** The resolved target before the move. */
+    from: string;
+    /** The resolved target after the move. */
+    to: string;
+    /** The verbatim token as it appears in the body (`raw`), so a rewrite replaces
+     * exactly what is there and leaves a trailing `#fragment` in place. */
+    raw: string;
+}
+/** What one consolidation plan does to one body's references. */
+export interface ReferenceRewritePlan {
+    /** References whose target changes (a re-homed file). */
+    edits: readonly ReferenceRewriteEdit[];
+    /** Cited files the moves give no destination: applying this plan would dangle. */
+    unresolved: readonly string[];
+    /** Targets still absent from the target file list after the moves. */
+    residualDangling: readonly string[];
+    /** The moves the body actually NEEDS: a support file the body never cites stays
+     * with the archived package instead of being copied into the target for
+     * nothing (upstream's wording is "every needed support file"). */
+    moves: readonly ReferenceMove[];
+}
+/**
+ * Provisional re-homing rule. The naming style for re-homed files is still an
+ * open decision (design §16.3 B5); this rule only fires on a COLLISION, where
+ * something has to give: a path that the target already occupies gets the source
+ * name as a prefix (`references/a.md` -> `references/<source>-a.md`). Nested
+ * destinations are deliberately avoided: the support listing is one level deep,
+ * so a file moved into a subdirectory would drop out of the listing entirely.
+ * @param sourceFiles - the moving skill's support files.
+ * @param targetFiles - the destination skill's support files.
+ * @param sourceName - the moving skill's name, used as the collision prefix.
+ * @returns the moves plus the paths that collided (for the report).
+ */
+export declare function planRehoming(sourceFiles: readonly string[], targetFiles: readonly string[], sourceName: string): {
+    moves: ReferenceMove[];
+    collisions: string[];
+};
+/**
+ * Plan the reference rewrites for one body that is moving into another root.
+ * @param input - the body, the MOVING skill's file list, the re-homing moves and
+ *   the destination's file list (with the moved paths already included).
+ * @returns the edits, the cited files without a destination, and any target that
+ *   the destination file list cannot prove (applying such a plan would dangle).
+ */
+export declare function planReferenceRewrite(input: {
+    content: string;
+    files: readonly string[];
+    moves: readonly ReferenceMove[];
+    targetFiles: readonly string[];
+}): ReferenceRewritePlan;
+/**
+ * Apply a plan's edits to the body (V2). Line-wise and literal: line N gets its
+ * FIRST occurrence of the recorded token replaced, everything else is copied
+ * byte for byte — no regex, so a token that happens to contain regex
+ * metacharacters cannot rewrite more than it matched.
+ * @param content - the body the plan was computed against.
+ * @param edits - the plan's edits.
+ * @returns the rewritten body (identical to the input when there is nothing to do).
+ */
+export declare function applyReferenceRewrite(content: string, edits: readonly ReferenceRewriteEdit[]): string;
+/**
+ * One-line, model-facing summary of a plan, for the consolidation refusal and
+ * for the V2 apply path's audit text.
+ * @param plan - the plan to describe.
+ * @returns a compact sentence naming counts, the moves and any residual risk.
+ */
+export declare function describeReferenceRewrite(plan: ReferenceRewritePlan): string;
+//# sourceMappingURL=reference-rewrite.d.ts.map

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

@@ -67,6 +67,8 @@ interface SkillHealthSnapshot {
 }
 interface SkillHealthDim {
     bodyChars: number;
+    /** The same body on the token scale (limit basis) — the judged quantity. */
+    bodyTokens: number;
     stampDensityPerKb: number | null;
     supportGroups: number;
     /** Usage churn facts; null when the caller supplied no counts. */

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

@@ -368,11 +368,27 @@ export declare class SkillLibrary {
      * promises the present branch is complete (011 §7 enrichment, probe reads).
      */
     listSupportFiles(rawName: string): Promise<Probe<string[]>>;
+    /**
+     * V4 (design §16.6): exact character counts of the support files that can
+     * POSSIBLY exceed the content cap. The pre-filter is BYTE size, and that is
+     * sound rather than approximate: a UTF-16 code unit never costs less than one
+     * UTF-8 byte, so a file whose bytes are within the cap provably cannot exceed
+     * the cap in characters. The returned map is therefore COMPLETE for the
+     * oversize question without reading the small files.
+     * @param rawName - the skill's name.
+     * @returns path -> character count (possibly empty), or null when the listing or
+     *   a size probe cannot answer — unknown is never an empty map.
+     */
+    supportFileChars(rawName: string): Promise<Record<string, number> | null>;
     /**
      * Structure-health facts for one skill (rc.73 A1, 008 design): body
      * chars/density from SKILL.md, support groups from countSupportDirs, plus
      * optional usage counts (A2 churn dimension) when the caller has them.
-     * Derived, never persisted; null when the skill is unreadable.
+     * Derived, never persisted. CONTRACT: `null` whenever the skill cannot be
+     * read — a missing file AND any read failure (EACCES/EIO/…) both answer
+     * null, so a whole health view degrades one ROW instead of throwing out of
+     * its per-skill loop (A6, audit P2-10: the former code absorbed only
+     * missing/EISDIR and let a transient win32 hold kill the entire view).
      */
     assessHealth(rawName: string, thresholds?: SkillHealthThresholds, counts?: {
         patchCount?: number;
@@ -436,9 +452,19 @@ export declare class SkillLibrary {
      * stolen by the sweep. A dead-pid residue would otherwise permanently
      * refuse archive/restore. */
     private deleteStrandedLocks;
+    /** R2 follow-up (audit of A2): the recycled-pid window from io's
+     * `ALIVE_LOCK_TAKEOVER_MS`, applied to the stranded-lock sweepers. A lock
+     * whose holder pid probes alive but whose mtime is older than the alive
+     * window is a recycled pid, not a live writer (no write in this family
+     * holds a lock for more than minutes) — without this, one recycled pid
+     * blocked whole-tree snapshot recovery forever with a "retry once the
+     * write completes" message that could never become true. A backend without
+     * `mtime` keeps the conservative refuse-on-alive posture. */
+    private lockHolderAgedOut;
     /** Remove `lockPath` only when its body has the writer-lock `pid:token`
-     * shape AND the holder pid is not alive; anything else (a user support file
-     * or a live writer's lock) is left untouched. */
+     * shape AND the holder pid is not alive (or is an aged-out recycled pid —
+     * R2 follow-up); anything else (a user support file or a live writer's
+     * lock) is left untouched. */
     private sweepLockIfStranded;
     /** A1-4 (v18): a manifest-declared name is copied with `join(root, name)`;
      * only a single, non-traversing path component is safe. Dotfiles
@@ -451,6 +477,17 @@ export declare class SkillLibrary {
      * recovery. A non-lock body shape is left alone (user file). */
     private refuseLiveLockOrSweep;
     archive(rawName: string, options?: ArchiveOptions): 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
+     * plan-mode refusal (with the reason named); `apply` carries the rewritten body
+     * and the support files that must be copied into the target.
+     * @param source - the moving skill's name.
+     * @param targetName - the destination skill's name.
+     * @param body - the moving body (frontmatter stripped).
+     * @returns the decision plus the note to append to a refusal.
+     */
+    private planSourceRehoming;
     /**
      * Merge the bodies of `sources` into `target` and archive the sources with
      * an absorbed-into marker. Hermes-style consolidation: overlapping skills
@@ -468,6 +505,14 @@ export declare class SkillLibrary {
      * `target/references/<source>.md` and archives the source — the demote path
      * (009-II). A source body with support-directory links is refused there too
      * (the references file would carry links whose files were archived).
+     *
+     * V2 (design §16.7) lifts that refusal when `referenceRewrite:'apply'` and the
+     * plan proves the move is safe: the support files the body NEEDS are copied into
+     * the target under their own paths (renamed only on a collision) and the body's
+     * references are rewritten to match, in the same commit. Anything the plan
+     * cannot place — a cited file the source no longer has, an unreadable listing —
+     * still refuses, and the refusal names it. The archived source keeps whatever
+     * the body did not need.
      */
     consolidate(target: string, sources: string[], origin?: WriteOrigin, options?: {
         mode?: 'append' | 'reference';
@@ -514,6 +559,19 @@ export declare class SkillLibrary {
      * Backends without the mtime probe skip pruning (no false deletes on
      * unknown age).
      */
+    /**
+     * 0.5.0 V1 (design §16.6-④): the retention window's READ half. Names every
+     * archived entry past the window without touching it — the report path the
+     * default policy uses, and the input the curator's run report carries.
+     * @returns the expired entry names ([] when the backend has no mtime probe,
+     *   because an unknown age must never read as expired).
+     */
+    expiredArchives(): Promise<string[] | null>;
+    /** V4 (design §16.6): support-file char policy, resolved at the call site. */
+    supportFileCharPolicy(): 'report' | 'enforce';
+    /** Retention policy resolved at the call site (absent limits object = report).
+     * Public so a run report can say WHICH policy produced its numbers. */
+    archiveRetentionPolicy(): 'report' | 'prune';
     private pruneExpiredArchives;
     /**
      * Snapshot the recoverable skills state: active tree, usage/suppression
@@ -601,8 +659,8 @@ export interface NewSkillLibraryOptions {
     threatExemptLabels?: readonly string[] | undefined;
 }
 export declare function newSkillLibrary(options: NewSkillLibraryOptions): SkillLibrary;
-export { DEFAULT_SKILL_LIMITS } from './limits.ts';
-export type { SkillLimits } from './limits.ts';
+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';
+export type { SkillLimits, CitationPolicy, ReferenceRewritePolicy, ArchiveRetentionPolicy, SupportFileCharPolicy, PolicyStageFields, } from './limits.ts';
 export { authoringFeedback, frontmatterBlock, frontmatterCatalogInvalid, normalizeFrontmatter, parseFrontmatter, relatedSkillNames, validateFrontmatter, yamlPlainScalarNeedsQuotes } from './frontmatter.ts';
 export type { AuthoringFeedback, Frontmatter, FrontmatterNormalizeResult, FrontmatterRead, PlatformStringSplit } from './frontmatter.ts';
 //# sourceMappingURL=skill-store.d.ts.map

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

@@ -186,6 +186,29 @@ export declare function isSkillReadToolName(name: string): boolean;
  * counts as a read: the platform settles every started sub-dispatch, so pending
  * is a live-window state, not a failure.
  */
+/** Tool names whose dispatch reads one FILE — the deployment's file tool
+ * (default `read`). A differently named tool is configured, not guessed. */
+export declare const DEFAULT_SUPPORT_READ_TOOL_NAMES: readonly string[];
+/** One support-file read attributed to a skill (design §5.5). */
+export interface SupportReadHit {
+    skill: string;
+    /** Skill-root-relative path, e.g. `references/design-x.md`. */
+    rel: string;
+}
+/**
+ * Read one dispatch as a SUPPORT-FILE read attributed to a skill: a read of
+ * `<root>/<skill>/<support dir>/…` is demand evidence for that one file, the
+ * way `skillReadNameOf` is demand evidence for a whole body.
+ * @param signal - a settled dispatch.
+ * @param options - the deployment's file-tool names and its skills root; an
+ *   empty root falls back to the `/skills/` marker in the path.
+ * @returns the skill name and the skill-root-relative path, or `null` when the
+ *   dispatch is not a support-file read. Pure: no IO, no service lookup.
+ */
+export declare function supportFileReadOf(signal: ToolDispatchSignal, options: {
+    toolNames: readonly string[];
+    root: string;
+}): SupportReadHit | null;
 export declare function skillReadNameOf(signal: ToolDispatchSignal): string | undefined;
 /**
  * Fold one session log into its deduplicated dispatches.

package/lib/types/usage.d.ts

@@ -28,6 +28,11 @@ export interface UsageRecord {
      * relevant again. */
     feedback_score?: number | undefined;
     feedback_warn?: boolean | undefined;
+    /** Demand evidence per SUPPORT FILE (design §5.5): how many observed reads
+     * landed on each `references/…`-style path of this skill. Absent on every
+     * record written before this field existed, and on skills whose support
+     * files were never read — absence means "no evidence", never "zero demand". */
+    support_reads?: Record<string, number> | undefined;
 }
 export type UsageMap = Map<string, UsageRecord>;
 export declare function usageFile(root: string): string;
@@ -44,6 +49,8 @@ export declare function emptyRecord(): UsageRecord;
  * Pure — exported for unit tests; `loadUsage` is the production caller.
  */
 export declare function normalizeUsageRecord(record: unknown): UsageRecord;
+/** Sidecar bound: a pathological path set must not grow the usage file forever. */
+export declare const MAX_SUPPORT_READ_PATHS = 200;
 export declare function loadUsage(root: string, io?: EvolutionIoLike): Promise<UsageMap>;
 /**
  * Atomic read-modify-write on the usage sidecar (rc.50 P2-2): `task` receives
@@ -100,8 +107,19 @@ export declare function getRecord(map: UsageMap, name: string): UsageRecord;
 export declare function bumpView(map: UsageMap, name: string, when?: Date): void;
 export declare function bumpUse(map: UsageMap, name: string, when?: Date): void;
 export declare function bumpPatch(map: UsageMap, name: string, when?: Date): void;
+/** Count one observed support-file read (design §5.5). The map is created on
+ * first evidence only — a skill with no support reads keeps the field absent. */
+export declare function bumpSupportRead(map: UsageMap, name: string, rel: string, when?: Date): void;
 export declare function markAgentCreated(map: UsageMap, name: string): void;
 export declare function latestActivityAt(record: UsageRecord): string | null;
+/** Days between an ISO timestamp (falling back to `created`) and `now`. An
+ * unparseable date counts as 0 days: NaN silently froze every age comparison
+ * (A2-9). */
+export declare function daysSinceIso(iso: string | null, created: string, nowMs: number): number;
+/** Idle days of one skill since its lifecycle age anchor (`last activity ??
+ * created_at`) — the SAME anchor the curator's transitions use, so the
+ * maintenance view and the lifecycle can never disagree about staleness. */
+export declare function idleDays(record: UsageRecord, now?: Date): number;
 /**
  * Whether the library has ANY observed read evidence (C observation window):
  * reads were invisible to the usage sidecar before A2, so `view_count` zero

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.4.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },