@lmzhen/dsh-evolution-core 0.30.31 → 0.30.33

package/lib/types/proposal-report.js

@@ -0,0 +1,61 @@
+import { join } from 'node:path';
+import { isPresent, isUnknown, probeList, probeText } from "./probe.js";
+import { evolutionHome } from "./state-store.js";
+/** Directory for the one proposal lane; reports are retention-swept with the other run reports. */
+export function proposalReportDir() {
+    return join(evolutionHome(), 'reports');
+}
+/** Stable report filename for one proposal; the id may carry path separators. */
+export function proposalReportName(proposal) {
+    return 'extract-proposal-' + encodeURIComponent(proposal.id) + '.json';
+}
+/**
+ * Persist one proposal as a report. Best-effort: a failed write never blocks the extract.
+ * @param io - evolution IO seam.
+ * @param proposal - proposal to persist.
+ * @param dir - reports directory (tests pass a temp dir).
+ * @returns the written path.
+ */
+export async function writeProposalReport(io, proposal, dir = proposalReportDir()) {
+    const path = join(dir, proposalReportName(proposal));
+    await io.writeText(path, JSON.stringify(proposal));
+    return path;
+}
+function isProposal(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return candidate.version === 1 && typeof candidate.id === 'string' && typeof candidate.source === 'string'
+        && (candidate.outcome === 'keep' || candidate.outcome === 'extract' || candidate.outcome === 'mixed' || candidate.outcome === 'owner-gap');
+}
+/**
+ * Read the newest proposals. Missing/unreadable reports are skipped, never guessed.
+ * @param io - evolution IO seam.
+ * @param dir - reports directory.
+ * @param limit - newest rows to return.
+ * @returns valid proposals, newest filename first.
+ */
+export async function readProposalReports(io, dir = proposalReportDir(), limit = 10) {
+    const listed = await probeList(io, dir);
+    if (isUnknown(listed) || !isPresent(listed))
+        return [];
+    const names = listed.value.filter(name => name.startsWith('extract-proposal-') && name.endsWith('.json'));
+    names.sort((a, b) => b.localeCompare(a));
+    const proposals = [];
+    for (const name of names.slice(0, limit)) {
+        const raw = await probeText(io, join(dir, name));
+        if (!isPresent(raw))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.value);
+        }
+        catch {
+            continue;
+        }
+        if (isProposal(parsed))
+            proposals.push(parsed);
+    }
+    return proposals;
+}
+//# sourceMappingURL=proposal-report.js.map

package/lib/types/proposal-view.d.ts

@@ -0,0 +1,42 @@
+import type { ExtractOutcome, ExtractPlanDraft, OwnerDecision, SupportClosure } from './extract-plan.ts';
+/** The semantic outcome a proposal may carry; keep is valid even though planExtract only plans a split. */
+export type ProposalOutcome = ExtractOutcome | 'keep';
+/** One semantic proposal carried to health/panel/audit surfaces. */
+export interface ProposalView {
+    version: 1;
+    id: string;
+    source: string;
+    outcome: ProposalOutcome;
+    parts: Array<{
+        heading: string;
+        anchor: {
+            heading: string;
+            start?: string;
+            end?: string;
+        };
+        reason: string;
+    }>;
+    owner: OwnerDecision;
+    support?: SupportClosure;
+    warnings: string[];
+    provenance: {
+        promptVersion: 'v1';
+        runId: string;
+        at: number;
+    };
+    status: 'proposed' | 'previewed' | 'stale' | 'dismissed';
+}
+/**
+ * Project a pure ExtractPlan into the proposal record every read-only surface consumes.
+ *
+ * This is a projection, not a second evaluator: it keeps the plan's owner decision,
+ * support closure and warnings. It never writes and never invents coverage.
+ * @param plan - plan produced by planExtract.
+ * @param provenance - run id and timestamp for the proposing pass.
+ * @returns a proposal with status proposed.
+ */
+export declare function proposalFromPlan(plan: ExtractPlanDraft, provenance: {
+    runId: string;
+    at?: number;
+}): ProposalView;
+//# sourceMappingURL=proposal-view.d.ts.map

package/lib/types/proposal-view.js

@@ -0,0 +1,24 @@
+/**
+ * Project a pure ExtractPlan into the proposal record every read-only surface consumes.
+ *
+ * This is a projection, not a second evaluator: it keeps the plan's owner decision,
+ * support closure and warnings. It never writes and never invents coverage.
+ * @param plan - plan produced by planExtract.
+ * @param provenance - run id and timestamp for the proposing pass.
+ * @returns a proposal with status proposed.
+ */
+export function proposalFromPlan(plan, provenance) {
+    return {
+        version: 1,
+        id: 'extract-' + provenance.runId + '-' + plan.source,
+        source: plan.source,
+        outcome: plan.outcome,
+        parts: plan.parts.map(part => ({ heading: part.heading, anchor: part.anchor, reason: part.sourceText.slice(0, 160) })),
+        owner: plan.owner,
+        support: plan.support,
+        warnings: plan.warnings,
+        provenance: { promptVersion: 'v1', runId: provenance.runId, at: provenance.at ?? Date.now() },
+        status: 'proposed',
+    };
+}
+//# sourceMappingURL=proposal-view.js.map

package/lib/types/section-selection.d.ts

@@ -0,0 +1,38 @@
+/** One section/block selection request. Heading is exact; start/end select a content sub-block. */
+export interface SectionSelectionRequest {
+    heading: string;
+    start?: string;
+    end?: string;
+}
+/** One selected range. Whole-H2 selections omit anchorStart/anchorEnd. */
+export interface SelectedSection {
+    heading: string;
+    start: number;
+    end: number;
+    text: string;
+    requestIndex: number;
+    anchorStart?: string;
+    anchorEnd?: string;
+}
+/** Selection result; failure messages preserve the restructure planner's wording. */
+export type SectionSelectionResult = {
+    ok: true;
+    sections: SelectedSection[];
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Select whole H2 sections or exact content sub-blocks from one body.
+ *
+ * The H2 scan is document-body's h2Sections, so restructure and extract share
+ * one boundary rule. A start/end pair selects an inclusive, contiguous run of
+ * exact lines inside that heading; it cannot select the heading itself, overlap
+ * another request, or leave a selected range empty.
+ * @param body - markdown after frontmatter.
+ * @param requests - exact heading plus optional start/end line pairs.
+ * @returns selected ranges in request order, or the first refusal.
+ */
+export declare function selectSections(body: string, requests: readonly SectionSelectionRequest[]): SectionSelectionResult;
+//# sourceMappingURL=section-selection.d.ts.map

package/lib/types/section-selection.js

@@ -0,0 +1,78 @@
+import { h2Sections } from "./document-body.js";
+const LF = String.fromCharCode(10);
+/**
+ * Select whole H2 sections or exact content sub-blocks from one body.
+ *
+ * The H2 scan is document-body's h2Sections, so restructure and extract share
+ * one boundary rule. A start/end pair selects an inclusive, contiguous run of
+ * exact lines inside that heading; it cannot select the heading itself, overlap
+ * another request, or leave a selected range empty.
+ * @param body - markdown after frontmatter.
+ * @param requests - exact heading plus optional start/end line pairs.
+ * @returns selected ranges in request order, or the first refusal.
+ */
+export function selectSections(body, requests) {
+    const lines = body.split(LF);
+    const sections = h2Sections(body);
+    const selected = [];
+    for (let requestIndex = 0; requestIndex < requests.length; requestIndex += 1) {
+        const request = requests[requestIndex];
+        if (request === undefined)
+            continue;
+        const wanted = request.heading.trim();
+        const matching = sections.filter(section => section.title === wanted);
+        if (matching.length === 0)
+            return { ok: false, code: 'heading-missing', message: 'no "## ' + wanted + '" heading in the body' };
+        if (matching.length > 1)
+            return { ok: false, code: 'heading-ambiguous', message: 'heading "## ' + wanted + '" appears ' + matching.length + ' times (ambiguous anchor)' };
+        const section = matching[0];
+        if (section === undefined)
+            return { ok: false, code: 'heading-missing', message: 'no "## ' + wanted + '" heading in the body' };
+        if (selected.some(entry => entry.start === section.start)) {
+            return { ok: false, code: 'heading-duplicate', message: 'heading "## ' + wanted + '" is moved twice' };
+        }
+        const partial = request.start !== undefined || request.end !== undefined;
+        if (!partial) {
+            if (section.end === section.start + 1)
+                return { ok: false, code: 'heading-empty', message: 'heading "## ' + wanted + '" has an empty section' };
+            selected.push({ heading: wanted, start: section.start, end: section.end, text: lines.slice(section.start, section.end).join(LF), requestIndex });
+            continue;
+        }
+        if (request.start === undefined || request.end === undefined) {
+            return { ok: false, code: 'part-anchor-incomplete', message: 'heading "## ' + wanted + '" needs both start and end anchors' };
+        }
+        const startMatches = [];
+        const endMatches = [];
+        for (let index = 0; index < lines.length; index += 1) {
+            if (index <= section.start || index >= section.end)
+                continue;
+            if (lines[index] === request.start)
+                startMatches.push(index);
+            if (lines[index] === request.end)
+                endMatches.push(index);
+        }
+        if (startMatches.length !== 1)
+            return { ok: false, code: 'part-anchor-not-found', message: 'heading "## ' + wanted + '" start anchor must match exactly one content line' };
+        if (endMatches.length !== 1)
+            return { ok: false, code: 'part-anchor-not-found', message: 'heading "## ' + wanted + '" end anchor must match exactly one content line' };
+        const start = startMatches[0];
+        const end = endMatches[0];
+        if (start === undefined || end === undefined || start > end) {
+            return { ok: false, code: 'part-anchor-order', message: 'heading "## ' + wanted + '" start anchor is after end anchor' };
+        }
+        if (selected.some(entry => start < entry.end && end + 1 > entry.start)) {
+            return { ok: false, code: 'part-anchor-overlaps', message: 'heading "## ' + wanted + '" selection overlaps another selected block' };
+        }
+        selected.push({
+            heading: wanted,
+            start,
+            end: end + 1,
+            text: lines.slice(start, end + 1).join(LF),
+            requestIndex,
+            anchorStart: request.start,
+            anchorEnd: request.end,
+        });
+    }
+    return { ok: true, sections: selected };
+}
+//# sourceMappingURL=section-selection.js.map

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

@@ -300,7 +300,7 @@ export declare function loadVersionContent(root: string, io: EvolutionIoLike, na
  */
 export declare function recordVersions(root: string, io: EvolutionIoLike, input: VersionRecordInput, keep: number): Promise<RecordedVersions | null>;
 /** What kind of change one recorded version carries, as a CLOSED set. */
-export type VersionActionKind = 'baseline' | 'create' | 'patch' | 'update' | 'restore' | 'delete' | 'archive' | 'consolidate' | 'restructure' | 'merge' | 'support-write' | 'support-remove' | 'other';
+export type VersionActionKind = 'baseline' | 'create' | 'patch' | 'update' | 'restore' | 'delete' | 'archive' | 'consolidate' | 'restructure' | 'extract' | 'merge' | 'support-write' | 'support-remove' | 'other';
 /**
  * Classify one version action for display. Fail-closed like {@link versionTarget}: an action this
  * module does not know reads as `other` rather than being guessed, and `tests/skill-history.spec.ts`

package/lib/types/skill-history.js

@@ -85,7 +85,7 @@ export function orderVersions(versions) {
 /** The actions that record a SUPPORT FILE's bytes (they share the skill's version index). */
 const SUPPORT_ACTIONS = ['write_file', 'remove_file'];
 /** The actions that record the skill's own SKILL.md body. */
-const CONTENT_ACTIONS = ['create', 'update', 'patch', 'consolidate', 'restructure', 'restore', 'merge'];
+const CONTENT_ACTIONS = ['create', 'update', 'patch', 'consolidate', 'restructure', 'extract', 'restore', 'merge'];
 /**
  * Which artifact one recorded version holds, from the action that produced it.
  * @param action - the entry's action label.
@@ -610,6 +610,7 @@ export function versionActionKind(action) {
         case 'archive': return 'archive';
         case 'consolidate': return 'consolidate';
         case 'restructure': return 'restructure';
+        case 'extract': return 'extract';
         case 'merge': return 'merge';
         case 'write_file': return 'support-write';
         case 'remove_file': return 'support-remove';

package/lib/types/skill-reads.js

@@ -26,7 +26,7 @@ export function sessionReadSkillNames(ctx, session) {
 }
 /** 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',
+    'edit', 'update', 'patch', 'delete', 'write_file', 'remove_file', 'restructure', 'extract',
 ]);
 /**
  * Does this one op write a skill the caller never read?

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

@@ -36,6 +36,7 @@ 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 ExtractPlanDraft } from './extract-plan.ts';
 import { type MutationRecord } from './mutations.ts';
 import { type RevisionAnchor, type RevisionFile } from './skill-revision.ts';
 import { type UnitHead, type SkillVersion } from './skill-history.ts';
@@ -323,18 +324,6 @@ export declare function markerEntryName(marker: 'bundled' | 'hub-installed' | 'p
  * Single source shared with the plan validator. */
 export declare function validateRestructureTarget(filePath: string): string | null;
 export declare function validateSupportPath(filePath: string): string | null;
-/**
- * Support-directory references in a markdown body (009 kernel): `references/…`,
- * `templates/…`, `scripts/…`, `assets/…` relative links — any extension and
- * nested paths (v7 audit P3-1: `.md`-only matching missed `scripts/run.sh` and
- * `references/sub/x.md`, both of which dangle just like a `.md` link once the
- * source package is archived). Pure — who checks them and what the verdict is
- * belongs to the caller's context (a moved/appended body whose references
- * travel with an archived source is a dangling link; a restructure pointer is
- * a fresh link to a file written in the same plan). `..` traversal is a
- * different defect class (path validation owns it) and is not a support link.
- */
-export declare function supportRefs(content: string): string[];
 export declare class SkillLibrary {
     readonly root: string;
     readonly limits: SkillLimits;
@@ -681,6 +670,15 @@ export declare class SkillLibrary {
      * restructure (and future reference-mode consolidations) never implement
      * two-phase commit themselves.
      */
+    /**
+     * Apply one G1 ExtractPlan as one cross-skill unit. This is a thin adapter:
+     * selection, residual, pointer and support closure were already decided by
+     * planExtract; this method only projects them into ordered kernel operations.
+     * @param plan - pure plan from extract-plan.ts.
+     * @param origin - write face recorded in the audit ledger.
+     * @returns the kernel result; a refusal writes nothing.
+     */
+    extract(plan: ExtractPlanDraft, origin?: WriteOrigin): Promise<SkillActionResult>;
     private applyTreeChange;
     /**
      * Restore one skill from `.archive/` back to the active root. Hermes-style