@lmzhen/dsh-evolution-core 0.4.1 → 0.5.0

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

@@ -368,6 +368,18 @@ 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
@@ -465,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
@@ -482,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';
@@ -528,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
@@ -615,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.1",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },