@lmzhen/dsh-evolution-core 0.26.15 → 0.27.0

package/lib/types/skill-lint.js

@@ -0,0 +1,112 @@
+/*
+ * skill-lint — the FORM of a judgement, not a second judgement (G1, contract §3/§3b/§4, D1).
+ *
+ * The engine that DECIDES (token-scale line, /1024 stamp density, soft/2 support threshold) is
+ * `skill-health.ts`; this module only re-expresses the facts it already computed as findings, so a
+ * conclusion carries a rule id, a severity and a count instead of free text. Severity is declared
+ * HERE, per rule — never scored by a model, never derived from statistics — so the same facts always
+ * produce the same findings, on any machine, which is what lets CI replay a conclusion.
+ *
+ * Pure: no IO, no ctx, no thresholds of its own.
+ */
+import { SUPPORT_SPRAWL_FILES } from "./constants.js";
+const msg = (parts) => parts.map(p => (typeof p === 'string' ? p : String(p))).join('');
+/** One rule yields AT MOST one finding (contract §3). `body-oversize-2x` is the only rule whose
+ * severity can escalate a verdict to needs-restructure. */
+export const RULES = [
+    {
+        id: 'unreadable-skill',
+        severity: 'error',
+        run: facts => facts.readable && facts.dims.bodyChars !== null
+            ? null
+            : { severity: 'error', rule: 'unreadable-skill', message: msg([facts.skillName, ': SKILL.md could not be read — no health claim is possible']), count: 1 },
+    },
+    {
+        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 }
+            : 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 }
+            : null,
+    },
+    {
+        id: 'stamp-density',
+        severity: 'warn',
+        run: (facts) => {
+            const density = facts.dims.stampDensityPerKb;
+            const hits = facts.dims.stampHits;
+            if (density === null || hits === null || density < facts.stampLimitPerKb)
+                return null;
+            return { severity: 'warn', rule: 'stamp-density', message: msg([facts.skillName, ': stamp density ', density.toFixed(1), '/KB (rc/sha/date lines — log-like content)']), count: hits };
+        },
+    },
+    {
+        id: 'body-without-support',
+        severity: 'warn',
+        run: facts => facts.dims.supportGroups === 0 && facts.dims.bodyChars !== null && facts.dims.bodyChars >= facts.softLineChars / 2
+            ? { severity: 'warn', rule: 'body-without-support', message: msg([facts.skillName, ': large body (', facts.dims.bodyChars, ' chars) with NO support files']), count: 1 }
+            : null,
+    },
+    {
+        id: 'references-sprawl',
+        severity: 'warn',
+        run: (facts) => {
+            const files = facts.dims.supportFiles;
+            if (files === null || files < SUPPORT_SPRAWL_FILES)
+                return null;
+            return { severity: 'warn', rule: 'references-sprawl', message: msg([facts.skillName, ': ', files, ' support files']), count: files };
+        },
+    },
+    {
+        id: 'write-ghost',
+        severity: 'warn',
+        run: (facts) => {
+            const patches = facts.dims.churnPatches;
+            const reads = facts.dims.churnReads;
+            if (patches === null || reads === null || patches < facts.churnMinPatches || reads > 0)
+                return null;
+            return { severity: 'warn', rule: 'write-ghost', message: msg([facts.skillName, ': ', patches, ' patch(es), never read']), count: patches };
+        },
+    },
+];
+export function lintSkill(facts) {
+    const out = [];
+    for (const rule of RULES) {
+        const hit = rule.run(facts);
+        if (hit !== null)
+            out.push(hit);
+    }
+    return out;
+}
+/** What a write introduced, what got worse, what got fixed. A rule whose count grew (one site to
+ * nine) counts as worsened — comparing by rule name alone reported nothing. */
+export function diffFindings(before, after) {
+    const beforeByRule = new Map(before.map(f => [f.rule, f]));
+    const afterByRule = new Map(after.map(f => [f.rule, f]));
+    const introduced = after.filter(f => !beforeByRule.has(f.rule));
+    const worsened = after.filter((f) => {
+        const old = beforeByRule.get(f.rule);
+        return old !== undefined && f.count > old.count;
+    });
+    const resolved = before.filter(f => !afterByRule.has(f.rule)).map(f => f.rule);
+    return { introduced, worsened, resolved };
+}
+/** Support files = markdown files under references/ (contract §4: unit frozen, underscore-prefixed
+ * excluded). Paths are supplied by the caller — this module never touches the filesystem. */
+export function countReferenceFiles(paths) {
+    return paths.filter((p) => {
+        const n = p.replace(/\\/g, '/');
+        const inReferences = n.includes('/references/') || n.startsWith('references/');
+        if (!inReferences || !n.endsWith('.md'))
+            return false;
+        const base = n.slice(n.lastIndexOf('/') + 1);
+        return !base.startsWith('_');
+    }).length;
+}
+//# sourceMappingURL=skill-lint.js.map

package/lib/types/skill-reads.js

@@ -0,0 +1,67 @@
+import { collectReadSkillNames } from "./tool-dispatch.js";
+import { sessionReadNames } from "./session-projection.js";
+/**
+ * The skill names ONE session read, or `undefined` when its log is not readable.
+ *
+ * Two readers, in this order: the family's `evolutionReads` projection for a platform `Session`
+ * (0.2.x's live read — the deprecated synchronous log read is gone from production), then the
+ * STRUCTURAL accessor for a view that is not a `Session` at all. The tool path's exec view may be a
+ * bare stub, which is what this module exists for; a real Session always takes the first path.
+ *
+ * `undefined` is NOT an empty set: a caller that must decide (the tool path's read-before-write
+ * gate) can then keep its previous behavior instead of refusing every write in a composition whose
+ * session objects expose no log at all.
+ * @param ctx - a context of the runtime.
+ * @param session - the session whose reads are wanted; `undefined` when the call carries none.
+ * @returns the names read through a non-failed `skill` dispatch, or `undefined` when unreadable.
+ */
+export function sessionReadSkillNames(ctx, session) {
+    if (session === undefined)
+        return undefined;
+    const projected = sessionReadNames(ctx, session);
+    if (projected !== undefined)
+        return projected;
+    const events = session.readEvents?.();
+    return events === undefined ? undefined : collectReadSkillNames(events);
+}
+/** Actions whose target must have been read first (create is authorship, so it is exempt). */
+export const READ_REQUIRED_ACTIONS = Object.freeze([
+    'edit', 'update', 'patch', 'delete', 'write_file', 'remove_file', 'restructure',
+]);
+/**
+ * Does this one op write a skill the caller never read?
+ *
+ * V6-26 (0.3.37): the validator normalizes a missing action to `patch`, so a missing action is a
+ * read-required write, never silently exempt.
+ * @param op - one skill operation (from a tool call or a review plan).
+ * @param readNames - names read this session, from {@link collectReadSkillNames}.
+ * @returns true when the op is a read-required write to an unread target.
+ */
+export function isUnreadWrite(op, readNames) {
+    if (!op.name)
+        return false;
+    return READ_REQUIRED_ACTIONS.includes(op.action ?? 'patch') && !readNames.has(op.name);
+}
+/**
+ * Drop mutating ops whose target was not read this session, in place.
+ *
+ * Covers the same mutating surface Hermes guards (edit/patch/write_file/remove_file), so a
+ * background review cannot blind-touch support files or edits of skills it never loaded.
+ * @param ops - the plan's ops; dropped entries are removed in place.
+ * @param readNames - names read this session.
+ * @returns the count of dropped ops, so the plan event can report them as rejected.
+ */
+export function filterUnreadSkillOps(ops, readNames) {
+    let dropped = 0;
+    for (let index = ops.length - 1; index >= 0; index -= 1) {
+        const op = ops[index];
+        if (!op)
+            continue;
+        if (isUnreadWrite(op, readNames)) {
+            ops.splice(index, 1);
+            dropped += 1;
+        }
+    }
+    return dropped;
+}
+//# sourceMappingURL=skill-reads.js.map

package/lib/types/skill-row-cells.js

@@ -0,0 +1,123 @@
+/**
+ * The cells one row shows, decided here and rendered by the client.
+ *
+ * Why it exists: until 0.14.1 a row's information architecture lived inside one JSX expression
+ * (description + ' · ' + state + ' · ' + age), so which facts survived the browser's single-line
+ * ellipsis was an accident of concatenation order — on a real library the skill row's age and
+ * curation state were clipped away on EVERY row (measured 2026-09-28: 6 skills, descriptions
+ * 49–61 characters, ~240px of line). A row now arrives as an ORDERED list of cells, each declaring
+ * its slot, and the renderer lays them out: `aside` cells are right-aligned and never truncate, so a
+ * decision fact cannot be eaten by a long description again.
+ *
+ * Invariants: no words live here. A cell carries either a locale key (`copy`, with the values its
+ * template needs) or a verbatim fact (`literal` — numbers, hashes, recorded paths). Facts come from
+ * the host; the dictionary owns every sentence and every number format, including the ones the panel
+ * used to build itself (`row.delta.up`, `time.<unit>.one`, `versions.count`).
+ * @module @lmzhen/dsh-evolution-core/skill-row-cells
+ */
+/** The actions whose row carries an explanatory hover text. */
+const ACTION_NOTES = {
+    delete: 'action.delete.note',
+    archive: 'action.archive.note',
+};
+/** The actions whose bytes come from a support file rather than from SKILL.md. */
+const SUPPORT_ACTIONS = ['support-write', 'support-remove'];
+/**
+ * The relative-time key for one bucket: a count of one is spelled on its own.
+ * @param age - the bucket the host reported.
+ * @returns the locale key, singular or plural.
+ */
+export function ageCopyKey(age) {
+    // 'now' is its own sentence: there is no count to spell, and no `time.now.one`.
+    if (age.unit === 'now')
+        return 'time.now';
+    return age.n === 1 ? 'time.' + age.unit + '.one' : 'time.' + age.unit;
+}
+/**
+ * The state word one skill row carries, from the facts the listing reported.
+ * @param skill - the row's facts.
+ * @returns the locale key for its state.
+ */
+export function skillStateKey(skill) {
+    if (skill.protectionUnknown)
+        return 'state.unknown';
+    if (skill.protectedBy !== null)
+        return 'state.protected';
+    return skill.managed ? 'state.managed' : 'state.foreign';
+}
+/** The hover text one action word needs, or nothing when it needs none. */
+function actionNote(actionKind) {
+    const note = ACTION_NOTES[actionKind];
+    return note === undefined ? {} : { note };
+}
+/**
+ * The cells of one version row: the facts on the title line, the summary (if any) under it.
+ * @param row - the row's facts.
+ * @returns both lines.
+ */
+export function versionRowCells(row) {
+    const title = [
+        { key: 'v', copy: 'row.version', values: { n: row.v }, tone: 'tertiary', slot: 'meta' },
+        { key: 'action', copy: 'action.' + row.actionKind, tone: 'primary', slot: 'lead', ...actionNote(row.actionKind) },
+        { key: 'time', copy: ageCopyKey(row.age), values: { n: row.age.n }, tone: 'tertiary', slot: 'meta' },
+    ];
+    if (row.path !== undefined) {
+        title.push({ key: 'path', literal: row.path, tone: 'tertiary', slot: 'meta', note: row.path });
+    }
+    else if (SUPPORT_ACTIONS.includes(row.actionKind)) {
+        title.push({ key: 'path', copy: 'path.unrecorded', tone: 'tertiary', slot: 'meta' });
+    }
+    const delta = row.charsDelta;
+    if (delta !== undefined && delta !== 0) {
+        title.push({
+            key: 'delta',
+            copy: delta > 0 ? 'row.delta.up' : 'row.delta.down',
+            values: { n: Math.abs(delta) },
+            tone: 'tertiary',
+            slot: 'meta',
+        });
+    }
+    // U-5: the recorded hash, as a SHORT code (seven chars) whose hover carries the full value — the
+    // platform already puts `hash` on the row; nothing rendered it, so the fact was declared and unused.
+    if (row.hash !== undefined && row.hash !== '') {
+        title.push({ key: 'hash', literal: row.hash.slice(0, 7), tone: 'tertiary', slot: 'meta', note: row.hash });
+    }
+    const meta = [];
+    // The summary is the one line a deployment may or may not generate; the host sends it already
+    // verbatim, so it needs no dictionary key.
+    if (row.summary !== undefined && row.summary !== '') {
+        meta.push({ key: 'summary', literal: row.summary, tone: 'secondary', slot: 'lead' });
+    }
+    return { title, meta };
+}
+/**
+ * The cells of one skill row: the name line, then the facts that describe it.
+ *
+ * The description is a `lead` cell (it is the one allowed to truncate, with the full text on hover),
+ * while the version count and the last-changed time are `aside` cells — they survive any description.
+ * The description is NOT pre-truncated in JavaScript: the browser's ellipsis already clips it at the
+ * layout's real width, and a character cut on top of that only hides where the fact ends.
+ * @param skill - the row's facts.
+ * @returns both lines.
+ */
+export function skillRowCells(skill) {
+    const title = [
+        { key: 'name', literal: skill.name, tone: 'primary', slot: 'lead', note: skill.name },
+        { key: 'count', copy: 'versions.count', values: { n: skill.versions }, tone: 'tertiary', slot: 'aside' },
+    ];
+    const meta = [
+        { key: 'description', literal: skill.description, tone: 'tertiary', slot: 'lead', note: skill.description },
+        { key: 'state', copy: skillStateKey(skill), tone: 'tertiary', slot: 'meta' },
+    ];
+    // U-5 (history half): a protected skill says WHO holds it, not only that it is held. The state cell
+    // above answers 'protected or not' from the same field; this cell carries the guard's own name, a
+    // verbatim fact (no dictionary key — literals are values the host owns).
+    if (skill.protectedBy !== null) {
+        meta.push({ key: 'protectedBy', literal: skill.protectedBy, tone: 'tertiary', slot: 'meta', note: skill.protectedBy });
+    }
+    if (skill.age !== null) {
+        meta.push({ key: 'age', copy: ageCopyKey(skill.age), values: { n: skill.age.n }, tone: 'tertiary', slot: 'aside' });
+    }
+    return { title, meta };
+}
+//# sourceMappingURL=skill-row-cells.js.map

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

@@ -32,6 +32,7 @@
  * re-probes after its copies so a mid-copy writer demotes to `skipped`
  * (OPT-07); the movers' probe→rename window is owned by the io.ts protocol.
  */
+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';
@@ -287,10 +288,13 @@ export declare class SkillLibrary {
     /** V10-03 (P2-18): see the constructor's threatExemptLabels. Empty by
      * default — the strict ANY-hit-blocks policy is unchanged. */
     private readonly threatExemptLabels;
+    /** G1/1.1: default authority; a call may override (origin is per-invocation). */
+    /** G1/1.1/Stage 2: the ONE default every mutator reads. Per-call overrides still win. */
+    private readonly authority;
     /** skill-history.ts: the content history is best-effort, so a failure must not be SILENT —
      * 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[]);
+    constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits, onMutation?: (event: EvolutionSkillMutatedEvent) => void, transact?: typeof transactIo, threatExemptLabels?: readonly string[], authority?: WriteAuthority);
     /**
      * 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);
@@ -328,6 +332,21 @@ export declare class SkillLibrary {
      * a swallowed error would silently downgrade the anchor to
      * last-writer-wins.
      */
+    /**
+     * S4-01 (G0/0.7): the ONE three-state read the staging/replay anchors use.
+     *
+     * The two absorbing reads below absorb ENOENT/EISDIR and rethrow everything else, and the callers then
+     * each wrote their own try/catch to turn a rethrow into a decision - three near-copies of one posture,
+     * and the newest of them silently dropped the anchor instead of refusing. A read failure is its own
+     * state, so it gets its own name here: `unknown` with the reason, next to `present` and `absent`.
+     * Failing closed is then the CALLER decision (they refuse on unknown), not something each call site has
+     * to re-derive from a thrown error.
+     */
+    readSkillProbe(rawName: string): Promise<Probe<string>>;
+    /** The support-file face of {@link readSkillProbe}. */
+    readSupportFileProbe(rawName: string, filePath: string): Promise<Probe<string>>;
+    /** One place that turns the absorbing reads into three states. `null` is absent; a throw is unknown. */
+    private probeOf;
     readSupportFile(name: string, filePath: string): Promise<string | null>;
     /**
      * Summarize the skill tree.
@@ -499,7 +518,7 @@ export declare class SkillLibrary {
      * P2-4 (v19): a non-string entry (`skills: [123]`) is refused structurally
      * instead of throwing `name.includes is not a function`. */
     private safeSnapshotEntryName;
-    archive(rawName: string, options?: ArchiveOptions): Promise<SkillActionResult>;
+    archive(rawName: string, options?: ArchiveOptions, origin?: WriteOrigin): 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
@@ -567,7 +586,7 @@ export declare class SkillLibrary {
      * recoverability: archival never deletes, and this is the control-plane
      * path back. The `.archive-reason` marker is dropped on restore.
      */
-    restoreFromArchive(rawName: string): Promise<SkillActionResult>;
+    restoreFromArchive(rawName: string, origin?: WriteOrigin): Promise<SkillActionResult>;
     writeSupportFile(rawName: string, filePath: string, content: string, origin?: WriteOrigin, anchor?: WriteAnchor): Promise<SkillActionResult>;
     private writeSupportFileCore;
     removeSupportFile(rawName: string, filePath: string, origin?: WriteOrigin, anchor?: WriteAnchor, unitId?: string): Promise<SkillActionResult>;
@@ -624,6 +643,16 @@ export declare class SkillLibrary {
     private sanitizeExtraNames;
     readSnapshotManifest(path: string): Promise<SnapshotManifest | null>;
     /** Keep only the newest N snapshots (Hermes keep=5 parity); older ones are removed outright. */
+    /**
+     * G3/3.4: can a snapshot actually be used right now?
+     *
+     * The recovery messages used to promise "restore it from a snapshot" without asking whether a usable
+     * snapshot exists (audit S1-01: the message promised recoverability from a chain that is five deep and
+     * whose newest member held 9 of 35 skills). Three states, like every other reading here: a fragment
+     * naming the usable snapshot, a fragment saying there is none, or a fragment saying the directory could
+     * not be read - the caller embeds whichever it gets, so the sentence is generated by the capability.
+     */
+    private snapshotRecoveryAvailability;
     private retainSnapshots;
     /** Snapshots as a THREE-state read (N14): absent = no .backups directory,
      * unknown = it exists but could not be listed (a caller must not read a
@@ -680,6 +709,8 @@ export interface NewSkillLibraryOptions {
     ctx?: SkillMutationSink | undefined;
     transact?: typeof transactIo | undefined;
     threatExemptLabels?: readonly string[] | undefined;
+    /** G1/1.1: WHO writes through this library. Required: no call site can omit it. */
+    authority: WriteAuthority;
 }
 export declare function newSkillLibrary(options: NewSkillLibraryOptions): SkillLibrary;
 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';