@lmzhen/dsh-evolution-core 0.30.31 → 0.30.33

package/lib/types/external-support.d.ts

@@ -0,0 +1,19 @@
+import type { ExternalSupportFile } from './extract-plan.ts';
+/**
+ * Read and annotate external support files under one explicit root. The caller owns
+ * the root choice; this module only enforces containment, target-path safety, size
+ * limits and determinism.
+ * @param body - selected source markdown body.
+ * @param sourceDir - source skill directory.
+ * @param allowedRoot - canonical root external files must stay under.
+ * @param targetFiles - existing target support paths.
+ * @returns resolved external entries, or a refusal.
+ */
+export declare function readExternalSupport(body: string, sourceDir: string, allowedRoot: string, targetFiles: readonly string[]): Promise<{
+    ok: true;
+    files: ExternalSupportFile[];
+} | {
+    ok: false;
+    message: string;
+}>;
+//# sourceMappingURL=external-support.d.ts.map

package/lib/types/external-support.js

@@ -0,0 +1,96 @@
+import { createHash } from 'node:crypto';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { basename, isAbsolute, relative, resolve } from 'node:path';
+import { externalRefs } from "./support-refs.js";
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_TOTAL_BYTES = 4 * 1024 * 1024;
+function targetPathFor(ref) {
+    let value = ref.replace(/^\/+/, '');
+    while (value.startsWith('../'))
+        value = value.slice(3);
+    const support = value.match(/(?:^|\/)(references|templates|scripts|assets)\/(.+)$/);
+    if (support !== null)
+        return support[1] + '/' + support[2];
+    return 'references/' + basename(value);
+}
+function annotate(content, originalPath) {
+    const note = 'external source: ' + originalPath;
+    const extension = originalPath.slice(originalPath.lastIndexOf('.')).toLowerCase();
+    if (extension === '.md')
+        return '<!-- ' + note + ' -->' + String.fromCharCode(10) + String.fromCharCode(10) + content;
+    const prefix = extension === '.py' || extension === '.sh' || extension === '.rb' ? '# ' : '// ';
+    if (extension === '.js' || extension === '.mjs' || extension === '.cjs' || extension === '.ts' || extension === '.tsx' || extension === '.py' || extension === '.sh' || extension === '.rb') {
+        if (content.startsWith('#!')) {
+            const end = content.indexOf(String.fromCharCode(10));
+            if (end >= 0)
+                return content.slice(0, end + 1) + prefix + note + String.fromCharCode(10) + content.slice(end + 1);
+        }
+        return prefix + note + String.fromCharCode(10) + content;
+    }
+    return content;
+}
+function inside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+/**
+ * Read and annotate external support files under one explicit root. The caller owns
+ * the root choice; this module only enforces containment, target-path safety, size
+ * limits and determinism.
+ * @param body - selected source markdown body.
+ * @param sourceDir - source skill directory.
+ * @param allowedRoot - canonical root external files must stay under.
+ * @param targetFiles - existing target support paths.
+ * @returns resolved external entries, or a refusal.
+ */
+export async function readExternalSupport(body, sourceDir, allowedRoot, targetFiles) {
+    const refs = externalRefs(body);
+    if (refs.length === 0)
+        return { ok: true, files: [] };
+    let root;
+    try {
+        root = await realpath(allowedRoot);
+    }
+    catch {
+        return { ok: false, message: 'external support 根目录不可读：' + allowedRoot };
+    }
+    const files = [];
+    const targets = new Set(targetFiles);
+    let total = 0;
+    for (const ref of refs) {
+        const candidate = isAbsolute(ref) ? resolve(ref) : resolve(sourceDir, ref);
+        let canonical;
+        try {
+            canonical = await realpath(candidate);
+        }
+        catch {
+            return { ok: false, message: 'external support 文件不存在：' + ref };
+        }
+        if (!inside(root, canonical))
+            return { ok: false, message: 'external support 越界：' + ref };
+        const info = await stat(canonical);
+        if (!info.isFile())
+            return { ok: false, message: 'external support 不是普通文件：' + ref };
+        if (info.size > MAX_FILE_BYTES)
+            return { ok: false, message: 'external support 超过单文件上限：' + ref };
+        total += info.size;
+        if (total > MAX_TOTAL_BYTES)
+            return { ok: false, message: 'external support 超过总上限：' + ref };
+        const targetPath = targetPathFor(ref);
+        if (targets.has(targetPath))
+            return { ok: false, message: 'external support 目标冲突：' + targetPath };
+        targets.add(targetPath);
+        const raw = await readFile(canonical, 'utf8');
+        const annotated = annotate(raw, canonical);
+        files.push({
+            ref,
+            originalPath: canonical,
+            targetPath,
+            content: annotated,
+            sha256: createHash('sha256').update(annotated).digest('hex'),
+            provenance: 'external:' + canonical,
+        });
+    }
+    return { ok: true, files };
+}
+//# sourceMappingURL=external-support.js.map

package/lib/types/extract-plan.d.ts

@@ -0,0 +1,127 @@
+import { type SectionSelectionRequest } from './section-selection.ts';
+/** Semantic outcome carried by a plan; the agent decides it, this module records it. */
+export type ExtractOutcome = 'extract' | 'mixed' | 'owner-gap';
+/** Owner coverage supplied by the owner resolver; a missing owner is owner-gap, not a guess. */
+export interface OwnerDecision {
+    mode: 'covered' | 'owner-gap';
+    name?: string;
+    neededOwner?: string;
+    triggerCovers: boolean;
+    outcomeCovers: boolean;
+    reason: string;
+}
+export type ExtractPartRequest = SectionSelectionRequest;
+export interface ExtractPart {
+    heading: string;
+    anchor: {
+        heading: string;
+        start?: string;
+        end?: string;
+    };
+    sourceText: string;
+    movedText: string;
+    bytes: number;
+    sha256: string;
+}
+export interface ExternalSupportFile {
+    ref: string;
+    originalPath: string;
+    targetPath: string;
+    content: string;
+    sha256: string;
+    provenance: string;
+}
+export interface SupportClosure {
+    exclusive: Array<{
+        from: string;
+        to: string;
+    }>;
+    shared: Array<{
+        from: string;
+        to: string;
+        provenance: string;
+    }>;
+    external: Array<{
+        from: string;
+        to: string;
+        provenance: string;
+        originalPath: string;
+        content?: string;
+        sha256?: string;
+    }>;
+    unresolved: string[];
+    dangling: string[];
+}
+export interface ExtractAnchors {
+    sourceMdSha256: string;
+    targetMdSha256: string;
+}
+export interface ExtractPlanDraft {
+    source: string;
+    target: {
+        name: string;
+        exists: boolean;
+    };
+    outcome: ExtractOutcome;
+    parts: ExtractPart[];
+    residual: string;
+    pointer: string;
+    owner: OwnerDecision;
+    support: SupportClosure;
+    warnings: string[];
+    /** Plan-time full-document hashes; the write adapter refuses when either drifts. */
+    anchors?: ExtractAnchors;
+}
+export interface PlanExtractInput {
+    body: string;
+    sourceName: string;
+    targetName: string;
+    targetExists: boolean;
+    outcome: ExtractOutcome;
+    owner: OwnerDecision;
+    requests: readonly ExtractPartRequest[];
+    sourceFiles: readonly string[];
+    targetFiles: readonly string[];
+    /** Bounded external files the caller read and resolved under its allowed root. */
+    external?: readonly ExternalSupportFile[];
+    /** Optional plan-time full-document hashes, threaded by the tool/CLI caller. */
+    anchors?: ExtractAnchors;
+}
+export type ExtractPlanResult = {
+    ok: true;
+    plan: ExtractPlanDraft;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Build a pure extract plan. No IO, no writes: selection, residual, support
+ * closure and the moved text are computed from the supplied bodies/file lists.
+ * @param input - source body, target identity, owner decision and support lists.
+ * @returns a plan, or a refusal with a stable code.
+ */
+export declare function planExtract(input: PlanExtractInput): ExtractPlanResult;
+export interface ExtractProjection {
+    sourceAfter: string;
+    targetAfter: string;
+}
+/**
+ * Project one plan onto the current source/target SKILL.md bytes.
+ *
+ * This is the one place that composes frontmatter + residual + target additions;
+ * preview and the write adapter both call it so they cannot advertise different
+ * bytes. Pure: no IO.
+ * @param plan - plan from planExtract.
+ * @param sourceMd - current source SKILL.md.
+ * @param targetMd - current target SKILL.md.
+ * @returns both next documents, or the refusal that makes projection impossible.
+ */
+export declare function projectExtractBodies(plan: ExtractPlanDraft, sourceMd: string, targetMd: string): {
+    ok: true;
+    projection: ExtractProjection;
+} | {
+    ok: false;
+    message: string;
+};
+//# sourceMappingURL=extract-plan.d.ts.map

package/lib/types/extract-plan.js

@@ -0,0 +1,232 @@
+import { createHash } from 'node:crypto';
+import { applyReferenceRewrite, planReferenceRewrite, planRehoming } from "./reference-rewrite.js";
+import { selectSections } from "./section-selection.js";
+import { externalRefs, supportRefs } from "./support-refs.js";
+import { frontmatterBlock } from "./frontmatter.js";
+const LF = String.fromCharCode(10);
+function sha256(text) {
+    return createHash('sha256').update(text).digest('hex');
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function computeSupport(parts, residual, sourceName, sourceFiles, targetFiles, externalFiles) {
+    const selectedText = parts.map(part => part.sourceText).join(LF + LF);
+    const selectedRefs = unique(supportRefs(selectedText));
+    const residualRefs = new Set(supportRefs(residual));
+    const unresolved = selectedRefs.filter(ref => !sourceFiles.includes(ref));
+    if (unresolved.length > 0)
+        return { error: 'support-unresolved: ' + unresolved.join(', ') };
+    const candidates = selectedRefs.filter(ref => sourceFiles.includes(ref));
+    const rehome = planRehoming(candidates, targetFiles, sourceName);
+    const moves = rehome.moves;
+    const byFrom = new Map(moves.map(move => [move.from, move.to]));
+    const exclusive = [];
+    const shared = [];
+    for (const from of candidates) {
+        const to = byFrom.get(from);
+        if (to === undefined)
+            continue;
+        if (residualRefs.has(from))
+            shared.push({ from, to, provenance: sourceName + ':' + from });
+        else
+            exclusive.push({ from, to });
+    }
+    const targetFilesWithMoves = unique([...targetFiles, ...moves.map(move => move.to)]);
+    const external = unique(externalRefs(selectedText));
+    const suppliedRefs = new Set(externalFiles.map(file => file.ref));
+    const missingExternal = external.filter(ref => !suppliedRefs.has(ref));
+    const warnings = [];
+    if (missingExternal.length > 0)
+        warnings.push('external-support-not-copied: ' + missingExternal.join(', '));
+    const externalClosure = [];
+    for (const file of externalFiles) {
+        if (!external.includes(file.ref))
+            return { error: 'external-ref-not-selected: ' + file.ref };
+        if (file.targetPath.startsWith('/') || file.targetPath.includes('..') || !/^(?:references|templates|scripts|assets)\//.test(file.targetPath)) {
+            return { error: 'external-target-unsafe: ' + file.targetPath };
+        }
+        if (targetFilesWithMoves.includes(file.targetPath))
+            return { error: 'external-collision: ' + file.targetPath };
+        externalClosure.push({
+            from: file.ref,
+            to: file.targetPath,
+            provenance: file.provenance,
+            originalPath: file.originalPath,
+            content: file.content,
+            sha256: file.sha256,
+        });
+    }
+    const rewritten = new Map();
+    for (const part of parts) {
+        const partRefs = supportRefs(part.sourceText);
+        const rewrite = planReferenceRewrite({
+            content: part.sourceText,
+            files: sourceFiles,
+            moves: moves.filter(move => partRefs.includes(move.from)),
+            targetFiles: targetFilesWithMoves,
+        });
+        rewritten.set(part.heading, applyReferenceRewrite(part.sourceText, rewrite.edits));
+        warnings.push(...rewrite.unresolved.map(ref => 'support-unresolved: ' + ref));
+        warnings.push(...rewrite.residualDangling.map(ref => 'support-dangling: ' + ref));
+    }
+    for (const part of parts) {
+        let text = rewritten.get(part.heading) ?? part.sourceText;
+        for (const file of externalClosure)
+            text = text.split(file.from).join(file.to);
+        part.movedText = text;
+    }
+    const exclusiveSet = new Set(exclusive.map(entry => entry.from));
+    const parentExclusive = supportRefs(residual).filter(ref => exclusiveSet.has(ref));
+    if (parentExclusive.length > 0)
+        return { error: 'support-exclusive-referenced-by-parent: ' + parentExclusive.join(', ') };
+    const dangling = unique(warnings.filter(item => item.startsWith('support-dangling: ')).map(item => item.slice('support-dangling: '.length)));
+    return {
+        support: {
+            exclusive,
+            shared,
+            external: externalClosure,
+            unresolved: warnings.filter(item => item.startsWith('support-unresolved: ')),
+            dangling,
+        },
+        warnings,
+    };
+}
+/**
+ * Build a pure extract plan. No IO, no writes: selection, residual, support
+ * closure and the moved text are computed from the supplied bodies/file lists.
+ * @param input - source body, target identity, owner decision and support lists.
+ * @returns a plan, or a refusal with a stable code.
+ */
+export function planExtract(input) {
+    if (input.outcome === 'owner-gap') {
+        if (input.owner.mode !== 'owner-gap')
+            return { ok: false, code: 'owner-gap-mismatch', message: 'outcome owner-gap requires an owner-gap decision' };
+        if (input.owner.neededOwner === undefined || input.owner.neededOwner.trim() === '') {
+            return { ok: false, code: 'owner-gap-needed-owner', message: 'owner-gap requires neededOwner' };
+        }
+    }
+    else {
+        if (input.owner.mode !== 'covered' || !input.owner.triggerCovers || !input.owner.outcomeCovers) {
+            return { ok: false, code: 'owner-not-covered', message: 'extract/mixed requires a covering owner' };
+        }
+        if (!input.targetExists)
+            return { ok: false, code: 'target-missing', message: 'covered owner target does not exist' };
+    }
+    const selection = selectSections(input.body, input.requests);
+    if (!selection.ok)
+        return { ok: false, code: selection.code, message: selection.message };
+    if (selection.sections.length === 0)
+        return { ok: false, code: 'part-empty', message: 'at least one part is required' };
+    const parts = selection.sections.map(section => ({
+        heading: section.heading,
+        anchor: {
+            heading: section.heading,
+            ...(section.anchorStart === undefined ? {} : { start: section.anchorStart }),
+            ...(section.anchorEnd === undefined ? {} : { end: section.anchorEnd }),
+        },
+        sourceText: section.text,
+        movedText: section.text,
+        bytes: Buffer.byteLength(section.text, 'utf8'),
+        sha256: sha256(section.text),
+    }));
+    const ownerName = input.owner.mode === 'covered' ? (input.owner.name ?? input.targetName) : (input.owner.neededOwner ?? input.targetName);
+    const pointer = 'This capability now lives in ' + ownerName + '; project-specific facts stay here.';
+    const ordered = [...selection.sections].sort((a, b) => a.start - b.start);
+    const first = ordered[0];
+    if (first === undefined)
+        return { ok: false, code: 'part-empty', message: 'at least one part is required' };
+    const byStart = new Map(ordered.map(section => [section.start, section]));
+    const lines = input.body.split(LF);
+    const rebuilt = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const section = byStart.get(index);
+        if (section !== undefined) {
+            if (index === first.start)
+                rebuilt.push(pointer);
+            index = section.end - 1;
+        }
+        else {
+            rebuilt.push(lines[index] ?? '');
+        }
+    }
+    const residual = rebuilt.join(LF);
+    if (residual.trim().length === 0)
+        return { ok: false, code: 'parent-empty', message: 'parent residual is empty' };
+    const substantive = residual.split(LF).filter(line => line.trim() !== '' && line !== pointer && !line.trimStart().startsWith('#'));
+    if (substantive.length === 0)
+        return { ok: false, code: 'parent-hollow-heading', message: 'parent residual has no substantive content' };
+    if (input.outcome === 'owner-gap') {
+        return {
+            ok: true,
+            plan: {
+                source: input.sourceName,
+                target: { name: input.targetName, exists: input.targetExists },
+                outcome: input.outcome,
+                parts,
+                residual,
+                pointer,
+                owner: input.owner,
+                support: { exclusive: [], shared: [], external: [], unresolved: [], dangling: [] },
+                warnings: [],
+                ...(input.anchors === undefined ? {} : { anchors: input.anchors }),
+            },
+        };
+    }
+    const supportResult = computeSupport(parts, residual, input.sourceName, input.sourceFiles, input.targetFiles, input.external ?? []);
+    if ('error' in supportResult) {
+        const code = supportResult.error.split(':')[0] ?? 'support-invalid';
+        return { ok: false, code, message: supportResult.error };
+    }
+    if (supportResult.support.dangling.length > 0) {
+        return { ok: false, code: 'support-dangling', message: 'support-dangling: ' + supportResult.support.dangling.join(', ') };
+    }
+    return {
+        ok: true,
+        plan: {
+            source: input.sourceName,
+            target: { name: input.targetName, exists: input.targetExists },
+            outcome: input.outcome,
+            parts,
+            residual,
+            pointer,
+            owner: input.owner,
+            support: supportResult.support,
+            warnings: unique(supportResult.warnings),
+            ...(input.anchors === undefined ? {} : { anchors: input.anchors }),
+        },
+    };
+}
+/**
+ * Project one plan onto the current source/target SKILL.md bytes.
+ *
+ * This is the one place that composes frontmatter + residual + target additions;
+ * preview and the write adapter both call it so they cannot advertise different
+ * bytes. Pure: no IO.
+ * @param plan - plan from planExtract.
+ * @param sourceMd - current source SKILL.md.
+ * @param targetMd - current target SKILL.md.
+ * @returns both next documents, or the refusal that makes projection impossible.
+ */
+export function projectExtractBodies(plan, sourceMd, targetMd) {
+    const sourceBlock = frontmatterBlock(sourceMd);
+    const targetBlock = frontmatterBlock(targetMd);
+    if (!sourceBlock)
+        return { ok: false, message: 'source 没有有效 frontmatter' };
+    if (!targetBlock)
+        return { ok: false, message: 'target 没有有效 frontmatter' };
+    const sourceHeader = sourceBlock.lines.slice(0, sourceBlock.end + 1).join(LF);
+    const targetNormalized = targetMd.replace(/\r\n/g, LF);
+    const targetLines = targetNormalized.split(LF);
+    for (const part of plan.parts) {
+        if (targetLines.some(line => line.trim() === '## ' + part.heading))
+            return { ok: false, message: 'target 已有同名 heading「' + part.heading + '」。' };
+    }
+    const additions = plan.parts.map(part => part.movedText).join(LF + LF);
+    const targetRaw = targetNormalized.trimEnd() + LF + LF + additions + LF;
+    const targetAfter = targetBlock.nl === '\r\n' ? targetRaw.replace(/\n/g, '\r\n') : targetRaw;
+    const sourceRaw = (sourceHeader + plan.residual).replace(/\r\n/g, LF);
+    const sourceAfter = sourceBlock.nl === '\r\n' ? sourceRaw.replace(/\n/g, '\r\n') : sourceRaw;
+    return { ok: true, projection: { sourceAfter, targetAfter } };
+}
+//# sourceMappingURL=extract-plan.js.map

package/lib/types/extract-prompt.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The frozen semantic prompt for skill extraction. One constant, consumed by
+ * explicit extract agents and tests; it is deliberately not part of the review
+ * prompt bundle, and no review path injects it.
+ */
+export declare const EXTRACT_PROMPT_VERSION = "v1";
+export declare const EXTRACT_PROMPT_V1 = "Inspect the source skill, its linked support files, and the candidate owners\nin the library. A part of the skill (one or more sections) is a separate\ncapability when it has its own trigger and outcome, can be used without the\nparent context, and leaves the parent coherent. If it is separate and a\nclass-level owner covers it, extract that part. If no owner covers it, report\nthe owner gap and name the class-level owner that would be needed. If it mixes\na reusable capability with parent-specific facts, return mixed and name only\nthe reusable part. Otherwise keep it. Keep, extract, mixed, and owner-gap are\nall valid outcomes; no split is required.";
+//# sourceMappingURL=extract-prompt.d.ts.map

package/lib/types/extract-prompt.js

@@ -0,0 +1,16 @@
+/**
+ * The frozen semantic prompt for skill extraction. One constant, consumed by
+ * explicit extract agents and tests; it is deliberately not part of the review
+ * prompt bundle, and no review path injects it.
+ */
+export const EXTRACT_PROMPT_VERSION = 'v1';
+export const EXTRACT_PROMPT_V1 = `Inspect the source skill, its linked support files, and the candidate owners
+in the library. A part of the skill (one or more sections) is a separate
+capability when it has its own trigger and outcome, can be used without the
+parent context, and leaves the parent coherent. If it is separate and a
+class-level owner covers it, extract that part. If no owner covers it, report
+the owner gap and name the class-level owner that would be needed. If it mixes
+a reusable capability with parent-specific facts, return mixed and name only
+the reusable part. Otherwise keep it. Keep, extract, mixed, and owner-gap are
+all valid outcomes; no split is required.`;
+//# sourceMappingURL=extract-prompt.js.map

package/lib/types/index.d.ts

@@ -41,6 +41,14 @@ export * from './package-identity.ts';
 export * from './write-authority.ts';
 export * from './write-gates.ts';
 export * from './reference-rewrite.ts';
+export * from './support-refs.ts';
+export * from './section-selection.ts';
+export * from './extract-plan.ts';
+export * from './owner-resolver.ts';
+export * from './proposal-view.ts';
+export * from './proposal-report.ts';
+export * from './external-support.ts';
+export * from './extract-prompt.ts';
 export * from './cost.ts';
 export * from './skill-lint.ts';
 export * from './health-baseline.ts';

package/lib/types/index.js

@@ -42,6 +42,14 @@ export * from "./package-identity.js";
 export * from "./write-authority.js";
 export * from "./write-gates.js";
 export * from "./reference-rewrite.js";
+export * from "./support-refs.js";
+export * from "./section-selection.js";
+export * from "./extract-plan.js";
+export * from "./owner-resolver.js";
+export * from "./proposal-view.js";
+export * from "./proposal-report.js";
+export * from "./external-support.js";
+export * from "./extract-prompt.js";
 export * from "./cost.js";
 export * from "./skill-lint.js";
 export * from "./health-baseline.js";

package/lib/types/owner-resolver.d.ts

@@ -0,0 +1,40 @@
+import type { SkillSummary } from './skill-store.ts';
+/** One existing class-level owner candidate, with the routing facts a semantic adjudicator needs. */
+export interface OwnerCandidate {
+    name: string;
+    description: string;
+    whenToUse?: string;
+    headings: string[];
+    protectedBy: string | null;
+    protectionUnknown: boolean;
+    managed: boolean;
+}
+export interface OwnerExclusion {
+    name: string;
+    reason: 'source' | 'unreadable';
+}
+export interface OwnerLookup {
+    source: string;
+    candidates: OwnerCandidate[];
+    excluded: OwnerExclusion[];
+}
+/**
+ * Project the current library listing into owner candidates.
+ *
+ * The source is excluded; a skill with an empty description is named in
+ * excluded rather than silently dropped. Protected candidates remain visible
+ * (so a caller can explain why it refused), but are marked for the writer's
+ * protection gate. Headings reuse h2Sections; no second heading scanner.
+ * @param source - skill being extracted from.
+ * @param summaries - SkillLibrary.list({ withContent: true, withFrontmatter: true }).
+ * @returns stable-name-ordered candidates plus explicit exclusions.
+ */
+export declare function ownerCandidatesFromSummaries(source: string, summaries: readonly SkillSummary[]): OwnerLookup;
+/**
+ * Find one named candidate in a lookup.
+ * @param lookup - projection from ownerCandidatesFromSummaries.
+ * @param name - exact skill name.
+ * @returns the candidate, or undefined when absent.
+ */
+export declare function findOwnerCandidate(lookup: OwnerLookup, name: string): OwnerCandidate | undefined;
+//# sourceMappingURL=owner-resolver.d.ts.map

package/lib/types/owner-resolver.js

@@ -0,0 +1,49 @@
+import { h2Sections } from "./document-body.js";
+/**
+ * Project the current library listing into owner candidates.
+ *
+ * The source is excluded; a skill with an empty description is named in
+ * excluded rather than silently dropped. Protected candidates remain visible
+ * (so a caller can explain why it refused), but are marked for the writer's
+ * protection gate. Headings reuse h2Sections; no second heading scanner.
+ * @param source - skill being extracted from.
+ * @param summaries - SkillLibrary.list({ withContent: true, withFrontmatter: true }).
+ * @returns stable-name-ordered candidates plus explicit exclusions.
+ */
+export function ownerCandidatesFromSummaries(source, summaries) {
+    const normalized = source.trim();
+    const candidates = [];
+    const excluded = [];
+    for (const summary of summaries) {
+        if (summary.name === normalized) {
+            excluded.push({ name: summary.name, reason: 'source' });
+            continue;
+        }
+        if (summary.description.trim() === '') {
+            excluded.push({ name: summary.name, reason: 'unreadable' });
+            continue;
+        }
+        candidates.push({
+            name: summary.name,
+            description: summary.description,
+            ...(summary.whenToUse === undefined ? {} : { whenToUse: summary.whenToUse }),
+            headings: h2Sections(summary.content ?? '').map(section => section.title),
+            protectedBy: summary.protectedBy,
+            protectionUnknown: summary.protectionUnknown,
+            managed: summary.managed,
+        });
+    }
+    candidates.sort((left, right) => left.name.localeCompare(right.name));
+    excluded.sort((left, right) => left.name.localeCompare(right.name));
+    return { source: normalized, candidates, excluded };
+}
+/**
+ * Find one named candidate in a lookup.
+ * @param lookup - projection from ownerCandidatesFromSummaries.
+ * @param name - exact skill name.
+ * @returns the candidate, or undefined when absent.
+ */
+export function findOwnerCandidate(lookup, name) {
+    return lookup.candidates.find(candidate => candidate.name === name);
+}
+//# sourceMappingURL=owner-resolver.js.map

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

@@ -0,0 +1,23 @@
+import type { EvolutionIoLike } from './io.ts';
+import type { ProposalView } from './proposal-view.ts';
+/** Directory for the one proposal lane; reports are retention-swept with the other run reports. */
+export declare function proposalReportDir(): string;
+/** Stable report filename for one proposal; the id may carry path separators. */
+export declare function proposalReportName(proposal: ProposalView): string;
+/**
+ * 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 declare function writeProposalReport(io: EvolutionIoLike, proposal: ProposalView, dir?: string): Promise<string>;
+/**
+ * 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 declare function readProposalReports(io: EvolutionIoLike, dir?: string, limit?: number): Promise<ProposalView[]>;
+//# sourceMappingURL=proposal-report.d.ts.map