@lmzhen/dsh-evolution-core 0.30.36 → 0.30.38

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

@@ -23,6 +23,8 @@ export interface SkillHealthThresholds {
     /** Patch count at/above this with zero reads -> 'warn' (write-ghost: the
      * skill is churned but nothing ever loads it). */
     churnMinPatches: number;
+    /** Hard-cap hits at/above this with a large support closure -> scope-overloaded advisory. */
+    hardCapMinHits: number;
 }
 export declare const DEFAULT_HEALTH_THRESHOLDS: SkillHealthThresholds;
 /**
@@ -67,6 +69,8 @@ interface SkillHealthSnapshot {
     patchCount?: number | undefined;
     /** Usage-side view count, when the caller has it (A2 churn dimension). */
     readCount?: number | undefined;
+    /** Mechanical hard-cap-hit count, when the caller has it; null = unknown. */
+    hardCapHits?: number | null | undefined;
 }
 interface SkillHealthDim {
     bodyChars: number;
@@ -81,6 +85,7 @@ interface SkillHealthDim {
     /** Usage churn facts; null when the caller supplied no counts. */
     churnPatches: number | null;
     churnReads: number | null;
+    hardCapHits: number | null;
 }
 export interface SkillHealthAssessment {
     verdict: SkillHealthVerdict;

package/lib/types/skill-health.js

@@ -23,6 +23,7 @@ export const DEFAULT_HEALTH_THRESHOLDS = {
     softBodyChars: AUTHORING_SPLIT_LINE_CHARS,
     stampDensityPerKb: 2,
     churnMinPatches: 20,
+    hardCapMinHits: 3,
 };
 /**
  * Stamp regex shared by health assessment and the maintenance probe (single
@@ -72,6 +73,7 @@ export function assessStructureHealth(snapshot, thresholds = DEFAULT_HEALTH_THRE
         supportFiles: snapshot.supportFiles ?? null,
         churnPatches: null,
         churnReads: null,
+        hardCapHits: snapshot.hardCapHits ?? null,
     };
     // V6: the JUDGMENT runs on the token scale. The configured number stays the
     // borrowed UPSTREAM character line, converted per body composition, so the
@@ -115,6 +117,7 @@ export function assessStructureHealth(snapshot, thresholds = DEFAULT_HEALTH_THRE
         overTwiceSoftLine: overTwice,
         stampLimitPerKb: thresholds.stampDensityPerKb,
         churnMinPatches: thresholds.churnMinPatches,
+        hardCapMinHits: thresholds.hardCapMinHits,
         // This engine's snapshot always carries a MEASURED body (its type has no null arm yet); the
         // unreadable case becomes expressible when the caller's type does, and the rule already waits.
         readable: true,

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

@@ -73,6 +73,8 @@ export interface SkillVersion {
      * can interleave (the index is appended after the content lock is released); this link is computed
      * from the bytes a write lock actually read, so it is the authoritative predecessor. */
     beforeHash?: string;
+    /** True on the synthetic entry that records a REMOVAL; its hash is the removed bytes. */
+    removed?: boolean;
     /** One line saying what this write changed, when the deployment turned the summarizer on
      * (registry `skillVersionSummary`). Absent is a first-class state: the faces say so instead of
      * inventing a sentence, and a version recorded before the feature existed simply has none. */

package/lib/types/skill-history.js

@@ -213,6 +213,7 @@ function readVersionEntry(entry) {
     const summary = typeof candidate.summary === 'string' && candidate.summary !== '' ? candidate.summary : undefined;
     const path = typeof candidate.path === 'string' && candidate.path !== '' ? candidate.path : undefined;
     const unitId = typeof candidate.unitId === 'string' && candidate.unitId !== '' ? candidate.unitId : undefined;
+    const removed = candidate.removed === true ? true : undefined;
     // The fold must carry unitHead or the next write drops it for good (the G3a lesson).
     const unitHead = candidate.unitHead;
     const base = {
@@ -224,6 +225,7 @@ function readVersionEntry(entry) {
         ...summary === undefined ? {} : { summary },
         ...path === undefined ? {} : { path },
         ...unitId === undefined ? {} : { unitId },
+        ...removed === undefined ? {} : { removed },
         ...unitHead === undefined ? {} : { unitHead },
     };
     return typeof candidate.beforeHash === 'string' && candidate.beforeHash !== ''
@@ -353,6 +355,7 @@ export function nextHistoryIndex(versions, input, keep) {
                 action: input.action,
                 hash: removalHash,
                 chars: input.before?.length ?? 0,
+                removed: true,
                 ...pathField,
                 ...input.unitId === undefined ? {} : { unitId: input.unitId },
                 // F-G3b-1: a removal-only landing IS the last entry of its unit, so it carries the head;

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

@@ -21,6 +21,7 @@ export interface SkillDims {
     stampHits: number | null;
     churnPatches: number | null;
     churnReads: number | null;
+    hardCapHits: number | null;
 }
 /** The judgement itself, computed by `skill-health.ts` on its own scales; this module never
  * recomputes it from raw numbers (that is exactly how a second set of thresholds appears). */
@@ -33,6 +34,7 @@ export interface LintFacts {
     stampLimitPerKb: number;
     /** The engine's own churn threshold — the rule must use the SAME number, not a literal. */
     churnMinPatches: number;
+    hardCapMinHits: number;
     /** True when the caller could read the body at all. */
     readable: boolean;
 }

package/lib/types/skill-lint.js

@@ -25,14 +25,14 @@ export const RULES = [
         id: 'body-oversize-2x',
         severity: 'error',
         run: facts => facts.overTwiceSoftLine
-            ? { severity: 'error', rule: 'body-oversize-2x', message: msg([facts.skillName, ': body is at or past twice the soft line (', facts.softLineChars, ' chars)']), count: 1 }
+            ? { severity: 'error', rule: 'body-oversize-2x', message: msg([facts.skillName, ': body is at or past twice the soft line (', facts.softLineChars, ' chars); keeping the current skill is valid']), count: 1 }
             : null,
     },
     {
         id: 'body-oversize',
         severity: 'warn',
         run: facts => !facts.overTwiceSoftLine && facts.overSoftLine
-            ? { severity: 'warn', rule: 'body-oversize', message: msg([facts.skillName, ': body is at or above the soft line (', facts.softLineChars, ' chars)']), count: 1 }
+            ? { severity: 'warn', rule: 'body-oversize', message: msg([facts.skillName, ': body is at or above the soft line (', facts.softLineChars, ' chars); keep is valid — size alone does not require a split']), count: 1 }
             : null,
     },
     {
@@ -63,6 +63,17 @@ export const RULES = [
             return { severity: 'warn', rule: 'references-sprawl', message: msg([facts.skillName, ': ', files, ' support files']), count: files };
         },
     },
+    {
+        id: 'scope-overloaded',
+        severity: 'warn',
+        run: (facts) => {
+            const hits = facts.dims.hardCapHits;
+            const files = facts.dims.supportFiles;
+            if (hits === null || files === null || hits < facts.hardCapMinHits || files < 3)
+                return null;
+            return { severity: 'warn', rule: 'scope-overloaded', message: msg([facts.skillName, ': ', hits, ' hard-cap hit(s) with ', files, ' support files — remaining growth may be scope']), count: hits };
+        },
+    },
     {
         id: 'write-ghost',
         severity: 'warn',

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

@@ -0,0 +1,45 @@
+import type { SkillSummary } from './skill-store.ts';
+export interface SkillListQuery {
+    withContent?: boolean;
+    withFrontmatter?: boolean;
+    withSupport?: boolean;
+}
+export interface SkillSupportFile {
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+export interface SkillDocumentHashes {
+    threeField: string;
+    content: string;
+    support: string;
+}
+export interface SkillDocument {
+    summary: SkillSummary;
+    content: string;
+    frontmatter: Record<string, unknown>;
+    support: SkillSupportFile[];
+    hashes: SkillDocumentHashes;
+    readable: boolean;
+}
+export interface SkillModelProvider {
+    list(query?: SkillListQuery): Promise<SkillSummary[]>;
+    read(name: string): Promise<string | null>;
+    listSupportFiles(name: string): Promise<readonly string[]>;
+    readSupportFile(name: string, path: string): Promise<string | null>;
+}
+/**
+ * Canonical read face for skill consumers.
+ *
+ * This is an adapter, not a second store: the provider owns IO and summary
+ * extraction. Every consumer reads the same SkillDocument contract so owner,
+ * health, panel and future domain/search surfaces cannot drift on parsing,
+ * whenToUse or support hashing.
+ */
+export declare class SkillModel {
+    private readonly provider;
+    constructor(provider: SkillModelProvider);
+    list(query?: SkillListQuery): Promise<SkillSummary[]>;
+    get(name: string): Promise<SkillDocument | null>;
+}
+//# sourceMappingURL=skill-model.d.ts.map

package/lib/types/skill-model.js

@@ -0,0 +1,74 @@
+import { contentHash } from "./mutations.js";
+function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    const record = value;
+    return '{' + Object.keys(record).sort().map(key => JSON.stringify(key) + ':' + canonical(record[key])).join(',') + '}';
+}
+function threeFieldHash(summary) {
+    return contentHash(canonical([
+        summary.name,
+        summary.description,
+        summary.whenToUse ?? '',
+    ]));
+}
+function supportHash(files) {
+    return contentHash(canonical(files.map(file => [file.path, file.sha256, file.bytes])));
+}
+/**
+ * Canonical read face for skill consumers.
+ *
+ * This is an adapter, not a second store: the provider owns IO and summary
+ * extraction. Every consumer reads the same SkillDocument contract so owner,
+ * health, panel and future domain/search surfaces cannot drift on parsing,
+ * whenToUse or support hashing.
+ */
+export class SkillModel {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    async list(query = {}) {
+        return await this.provider.list(query);
+    }
+    async get(name) {
+        const summaries = await this.provider.list({ withFrontmatter: true });
+        const summary = summaries.find(candidate => candidate.name === name);
+        if (summary === undefined)
+            return null;
+        let content = null;
+        let readable = true;
+        try {
+            content = await this.provider.read(name);
+        }
+        catch {
+            readable = false;
+        }
+        if (content === null)
+            readable = false;
+        const paths = readable ? await this.provider.listSupportFiles(name) : [];
+        const support = [];
+        for (const path of paths) {
+            const file = await this.provider.readSupportFile(name, path);
+            if (file === null)
+                continue;
+            support.push({ path, bytes: Buffer.byteLength(file, 'utf8'), sha256: contentHash(file) });
+        }
+        support.sort((a, b) => a.path.localeCompare(b.path));
+        return {
+            summary,
+            content: content ?? '',
+            frontmatter: summary.frontmatter ?? {},
+            support,
+            hashes: {
+                threeField: threeFieldHash(summary),
+                content: contentHash(content ?? ''),
+                support: supportHash(support),
+            },
+            readable,
+        };
+    }
+}
+//# sourceMappingURL=skill-model.js.map

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

@@ -36,6 +36,8 @@ import { type WriteAuthority } from './write-authority.ts';
 import { transactIo, type EvolutionIoLike } from './io.ts';
 import { type Probe } from './probe.ts';
 import type { SkillLimits } from './limits.ts';
+import { type MutationResult } from './mutation-unit.ts';
+import { SkillModel } from './skill-model.ts';
 import { type ExtractPlanDraft } from './extract-plan.ts';
 import { type MutationRecord } from './mutations.ts';
 import { type RevisionAnchor, type RevisionFile } from './skill-revision.ts';
@@ -326,6 +328,8 @@ export declare function validateRestructureTarget(filePath: string): string | nu
 export declare function validateSupportPath(filePath: string): string | null;
 export declare class SkillLibrary {
     readonly root: string;
+    /** The ONE read face owner/health/panel consume; a thin adapter, not a store. */
+    readonly model: SkillModel;
     readonly limits: SkillLimits;
     private readonly io;
     private readonly onMutation;
@@ -349,6 +353,20 @@ export declare class SkillLibrary {
      * but it is a deployment condition, not a per-write event, so it warns once per instance. */
     private historyWarned;
     constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits, onMutation?: (event: EvolutionSkillMutatedEvent) => void, transact?: typeof transactIo, threatExemptLabels?: readonly string[], authority?: WriteAuthority);
+    /**
+     * Transitional root lock for mutators that still own their write path. The
+     * extract/restructure path takes the same lock through MutationUnit, so those
+     * two paths cannot interleave with create/update/patch across processes.
+     */
+    private unitHeadForOps;
+    private withMutationLock;
+    private recovery;
+    /** Run the boot recovery once per library instance, before the first write. */
+    private ensureRecovered;
+    /** Public boot hook: idempotent with the first-write recovery. */
+    recoverOnBoot(): Promise<void>;
+    /** Recover every prepared tree-change snapshot in the shared unit store. */
+    recoverPreparedUnits(): Promise<MutationResult[]>;
     /**
      * Run one single-file read-modify-write for a mutator. When `transact` was
      * injected the read and the write run inside it (cross-process atomicity);
@@ -358,7 +376,6 @@ export declare class SkillLibrary {
      * mutation event are issued ONLY when a write actually lands, so a no-op
      * never inflates the mutation-maturity counter.
      */
-    private runSingleWrite;
     /**
      * v28 G1.1 (EVO-IO-02): shared compensating cleanup for a locked write that
      * found no SKILL.md — remove the possibly-resurrected directory ONLY when it
@@ -519,7 +536,10 @@ export declare class SkillLibrary {
     assessHealth(rawName: string, thresholds?: SkillHealthThresholds, counts?: {
         patchCount?: number;
         readCount?: number;
+        hardCapHits?: number | null;
     }): Promise<SkillHealthAssessment | null>;
+    /** S2: mechanical hard-cap event; failure must not change the refusal. */
+    private recordHardCapHit;
     /** Best-effort audit trail entry; never blocks the mutation.
      *
      * Two independent best-effort writes run here, because either one failing must not cost the
@@ -565,6 +585,7 @@ export declare class SkillLibrary {
     create(name: string, content: string, origin?: WriteOrigin, options?: {
         unitId?: string;
         unitHead?: UnitHead;
+        managed?: boolean;
     }): Promise<SkillActionResult>;
     private createCore;
     update(rawName: string, content: string, origin?: WriteOrigin, anchor?: WriteAnchor): Promise<SkillActionResult>;