@deftai/directive-core 0.107.0 → 0.109.0

package/dist/delivery-attempt/evaluate.js

@@ -421,6 +421,75 @@ function evaluatePreDispatchNatural(ledger, input) {
         resume: null,
     });
 }
+/**
+ * Elapsed budget for a run already queued or running (#3983).
+ * Pre-dispatch cannot see this case: an active attempt is DENY_DUPLICATE_ACTIVE.
+ */
+export function evaluateInFlight(ledger, input = {}) {
+    const nowIso = utcIso(input.now);
+    const synthetic = {
+        scopeId: ledger.scopeId,
+        targetId: ledger.targetId,
+        workflowId: ledger.workflowId,
+        sourceRevision: ledger.lastSourceRevision ?? "in-flight",
+        trigger: "resume",
+        now: nowIso,
+        policy: input.policy,
+    };
+    const policy = mergePolicy(input.policy);
+    const active = activeAttempts(ledger);
+    if (active.length === 0) {
+        return result(synthetic, ledger, "ALLOW_FIRST_ATTEMPT", "no in-flight attempt", {
+            retryability: null,
+            fingerprint: null,
+            sameFailureCount: 0,
+            materialClass: "none",
+            resume: null,
+        });
+    }
+    const current = active[0];
+    if (current === undefined) {
+        return result(synthetic, ledger, "ALLOW_FIRST_ATTEMPT", "no in-flight attempt", {
+            retryability: null,
+            fingerprint: null,
+            sameFailureCount: 0,
+            materialClass: "none",
+            resume: null,
+        });
+    }
+    const startedMs = Date.parse(current.startedAt);
+    const nowMs = Date.parse(nowIso);
+    const liveSeconds = Number.isFinite(startedMs) && Number.isFinite(nowMs)
+        ? Math.max(0, (nowMs - startedMs) / 1000)
+        : 0;
+    const elapsed = ledger.totalElapsedSeconds + liveSeconds;
+    if (elapsed >= policy.maxElapsedSeconds) {
+        const resume = {
+            kind: "operator-override",
+            description: "elapsed budget exhausted on in-flight attempt; override or phase reset required",
+            satisfied: false,
+        };
+        return result(synthetic, ledger, "BLOCK_ELAPSED_BUDGET", "in-flight elapsed-time budget exhausted", {
+            retryability: ledger.lastFailure?.retryability ?? null,
+            fingerprint: ledger.lastFailure?.fingerprint ?? null,
+            sameFailureCount: 0,
+            materialClass: "none",
+            resume,
+            handoffLedger: {
+                ...ledger,
+                resumeCondition: resume,
+                blockedDecision: "BLOCK_ELAPSED_BUDGET",
+            },
+        });
+    }
+    return result(synthetic, ledger, "ALLOW_RESUME", "in-flight elapsed under budget", {
+        retryability: null,
+        fingerprint: null,
+        sameFailureCount: 0,
+        materialClass: "none",
+        resume: ledger.resumeCondition,
+    });
+}
 /**
  * Convenience: evaluate against ledger, and if blocked, return handoff suitable
  * for persistence via markBlocked + saveUnitLedger.

package/dist/delivery-attempt/handoff.js

@@ -8,7 +8,7 @@ import { utcIso } from "./types.js";
 export function nextSafeActionFor(decision) {
     switch (decision) {
         case "DENY_DUPLICATE_ACTIVE":
-            return "Wait for the active attempt to finish or cancel it; do not start a duplicate dispatch.";
+            return "A running attempt is not proof the worker is alive. Takeover: swarm:pre-dispatch --action cancel, then begin. REDISPATCH_OK does not lift this deny.";
         case "BLOCK_NON_RETRYABLE":
             return "Fix the deterministic configuration/schema/permission failure, record a relevant material delta, then resume.";
         case "BLOCK_NO_MATERIAL_PROGRESS":

package/dist/delivery-attempt/index.d.ts

@@ -8,7 +8,7 @@
  * @see content/docs/delivery-attempt.md
  */
 export { type BeginAttemptOnDiskInput, beginAttemptOnDisk, type CompleteAttemptOnDiskInput, completeAttemptOnDisk, } from "./disk-begin.js";
-export { evaluateAndPrepareBlock, evaluatePreDispatch, } from "./evaluate.js";
+export { evaluateAndPrepareBlock, evaluateInFlight, evaluatePreDispatch, } from "./evaluate.js";
 export { buildFailureInfo, computeFailureFingerprint, type FingerprintInput, inferRetryability, normalizeFailureMessage, } from "./fingerprint.js";
 export { buildTerminalHandoff, defaultResumeFor, formatHandoffReport, nextSafeActionFor, redactHandoffForPersist, } from "./handoff.js";
 export { activeAttempts, beginAttempt, clearBlockIfResumed, completeAttempt, deliveryAttemptsDir, emptyUnitLedger, hasActiveAttempt, isUnitLockReclaimable, type LoadUnitLedgerResult, listUnitLedgers, loadOrCreateUnitLedger, loadUnitLedger, loadUnitLedgerResult, MemoryLedgerStore, markBlocked, newAttemptId, parseUnitLedger, recordOperatorOverride, saveUnitLedger, UNIT_LOCK_STALE_MS, unitLedgerFilename, unitLedgerPath, withUnitLock, } from "./ledger.js";

package/dist/delivery-attempt/index.js

@@ -8,7 +8,7 @@
  * @see content/docs/delivery-attempt.md
  */
 export { beginAttemptOnDisk, completeAttemptOnDisk, } from "./disk-begin.js";
-export { evaluateAndPrepareBlock, evaluatePreDispatch, } from "./evaluate.js";
+export { evaluateAndPrepareBlock, evaluateInFlight, evaluatePreDispatch, } from "./evaluate.js";
 export { buildFailureInfo, computeFailureFingerprint, inferRetryability, normalizeFailureMessage, } from "./fingerprint.js";
 export { buildTerminalHandoff, defaultResumeFor, formatHandoffReport, nextSafeActionFor, redactHandoffForPersist, } from "./handoff.js";
 export { activeAttempts, beginAttempt, clearBlockIfResumed, completeAttempt, deliveryAttemptsDir, emptyUnitLedger, hasActiveAttempt, isUnitLockReclaimable, listUnitLedgers, loadOrCreateUnitLedger, loadUnitLedger, loadUnitLedgerResult, MemoryLedgerStore, markBlocked, newAttemptId, parseUnitLedger, recordOperatorOverride, saveUnitLedger, UNIT_LOCK_STALE_MS, unitLedgerFilename, unitLedgerPath, withUnitLock, } from "./ledger.js";

package/dist/deposit/live-procedure-exclusions.d.ts

@@ -0,0 +1,18 @@
+/**
+ * C3 live-procedure exclusion declaration (#3602 / #3899).
+ *
+ * History, examples, and prohibitions are skipped by this list, not by
+ * matching prose patterns. A file that names a deleted Python script in
+ * order to forbid treating it as a live path must appear here as
+ * `prohibition` or C3 will mis-fire.
+ */
+export type LiveProcedureExclusionKind = "history" | "example" | "prohibition";
+export interface LiveProcedureExclusion {
+    /** POSIX path relative to a flattened consumer deposit root. */
+    readonly path: string;
+    readonly kind: LiveProcedureExclusionKind;
+    readonly reason: string;
+}
+export declare const LIVE_PROCEDURE_EXCLUSIONS: readonly LiveProcedureExclusion[];
+export declare function isDeclaredLiveProcedureExclusion(relativePath: string): boolean;
+//# sourceMappingURL=live-procedure-exclusions.d.ts.map

package/dist/deposit/live-procedure-exclusions.js

@@ -0,0 +1,110 @@
+/**
+ * C3 live-procedure exclusion declaration (#3602 / #3899).
+ *
+ * History, examples, and prohibitions are skipped by this list, not by
+ * matching prose patterns. A file that names a deleted Python script in
+ * order to forbid treating it as a live path must appear here as
+ * `prohibition` or C3 will mis-fire.
+ */
+export const LIVE_PROCEDURE_EXCLUSIONS = [
+    {
+        path: "scm/github.md",
+        kind: "prohibition",
+        reason: "Names deleted Python scripts to forbid treating them as live implementation paths (#2022).",
+    },
+    {
+        path: "UPGRADING.md",
+        kind: "history",
+        reason: "Migration history of Python helpers on pinned pre-Python-free releases.",
+    },
+    {
+        path: "deployments/aws/via-elastic-beanstalk.md",
+        kind: "example",
+        reason: "Consumer AWS sample `scripts/create_admin.py` is not a deposit helper.",
+    },
+    {
+        path: "conventions/machine-generated-banner.md",
+        kind: "history",
+        reason: "Registry of historical Python writers that produced the banner; not a live consumer procedure.",
+    },
+    {
+        path: "docs/BROWNFIELD.md",
+        kind: "history",
+        reason: "Brownfield migration history of the Python migrator on pinned releases.",
+    },
+    {
+        path: "languages/python.md",
+        kind: "example",
+        reason: "Python language pack names consumer application files, not deposit helpers.",
+    },
+    {
+        path: "languages/kotlin.md",
+        kind: "example",
+        reason: "Kotlin stdlib `run` scoping function is not the deposit Python launcher.",
+    },
+    {
+        path: "deployments/aws/via-lambda.md",
+        kind: "example",
+        reason: "AWS Lambda sample `src/app.py` is a consumer application, not a deposit helper.",
+    },
+    {
+        path: "deployments/fly-io/via-dockerfile.md",
+        kind: "example",
+        reason: "Fly.io sample `app.py` / `manage.py` are consumer application files.",
+    },
+    {
+        path: "coding/toolchain.md",
+        kind: "example",
+        reason: "Cites framework test paths that pin the toolchain contract; not a live helper.",
+    },
+    {
+        path: "coding/testing.md",
+        kind: "example",
+        reason: "Documents `_test.py` naming for consumer Python tests, not a deposit helper.",
+    },
+    {
+        path: "contracts/deterministic-questions.md",
+        kind: "example",
+        reason: "Cites the contract's own test path; not a live consumer helper.",
+    },
+    {
+        path: "conventions/task-caching.md",
+        kind: "example",
+        reason: "Cites framework tests that pin task-caching; not a live helper.",
+    },
+    {
+        path: "events/README.md",
+        kind: "history",
+        reason: "Maintainer event-registry history naming retired Python writers and their tests.",
+    },
+    {
+        path: "templates/agents-entry.placeholders.md",
+        kind: "example",
+        reason: "Cites the agents-entry contract test; not a live helper.",
+    },
+    {
+        path: "templates/swarm-greptile-poller-prompt.md",
+        kind: "example",
+        reason: "Cites the poller-template contract test; not a live helper.",
+    },
+    {
+        path: "verification/plan-checking.md",
+        kind: "example",
+        reason: "Swarm-spec example names `tests/test_auth.py` as consumer test layout.",
+    },
+    {
+        path: "swarm/swarm.md",
+        kind: "example",
+        reason: "Swarm-spec example names `src/auth.py` / `tests/test_auth.py` as consumer files.",
+    },
+    {
+        path: "skills/deft-directive-setup/SKILL.md",
+        kind: "example",
+        reason: "Setup skill Python example names `src/ui.py` as a consumer application file.",
+    },
+];
+const EXCLUSION_PATHS = new Set(LIVE_PROCEDURE_EXCLUSIONS.map((entry) => entry.path));
+export function isDeclaredLiveProcedureExclusion(relativePath) {
+    return EXCLUSION_PATHS.has(relativePath.replace(/\\/g, "/"));
+}
+//# sourceMappingURL=live-procedure-exclusions.js.map

package/dist/deposit/live-procedure-targets.d.ts

@@ -0,0 +1,45 @@
+/**
+ * C3 live-procedure target validation (#3602 / #3899).
+ *
+ * A shipped live procedure must not name a helper the deposit does not
+ * contain. Python helpers are identified via python-free; markdown is
+ * walked with the validate-links skip set and extractLinkTargets. History,
+ * examples, and prohibitions are skipped by declaration.
+ *
+ * Metric: unique live-invalid helper targets (not occurrences, not matching
+ * lines). Prefer a zero unique-target assertion; do not freeze raw counts.
+ */
+export interface LiveProcedureHit {
+    readonly file: string;
+    readonly line: number;
+    readonly target: string;
+}
+export interface ExtraMarkdownFile {
+    readonly relativePath: string;
+    readonly absolutePath: string;
+}
+export interface EvaluateLiveProcedureTargetsOptions {
+    readonly stagedRoot: string;
+    readonly extraFiles?: readonly ExtraMarkdownFile[];
+}
+/**
+ * Metric used by C3: unique live-invalid helper targets.
+ * Not occurrence count, not matching-line count.
+ */
+export declare const LIVE_PROCEDURE_METRIC: "unique-targets";
+export interface LiveProcedureEvaluation {
+    readonly metric: typeof LIVE_PROCEDURE_METRIC;
+    readonly hits: readonly LiveProcedureHit[];
+    readonly uniqueTargets: readonly string[];
+}
+export declare function normalizePythonHelperTarget(raw: string): string | null;
+export declare function evaluateLiveProcedureTargets(options: EvaluateLiveProcedureTargetsOptions): LiveProcedureEvaluation;
+export declare function extraDepositMarkdownFiles(root: string): ExtraMarkdownFile[];
+export declare class LiveProcedureTargetsError extends Error {
+    readonly evaluation: LiveProcedureEvaluation;
+    constructor(evaluation: LiveProcedureEvaluation);
+}
+/** Fail closed when a deposit's live procedures name pruned Python helpers (#3602 C3). */
+export declare function assertLiveProcedureDepositClean(depositDir: string): void;
+export declare function formatLiveProcedureFailure(result: LiveProcedureEvaluation): string;
+//# sourceMappingURL=live-procedure-targets.d.ts.map

package/dist/deposit/live-procedure-targets.js

@@ -0,0 +1,274 @@
+/**
+ * C3 live-procedure target validation (#3602 / #3899).
+ *
+ * A shipped live procedure must not name a helper the deposit does not
+ * contain. Python helpers are identified via python-free; markdown is
+ * walked with the validate-links skip set and extractLinkTargets. History,
+ * examples, and prohibitions are skipped by declaration.
+ *
+ * Metric: unique live-invalid helper targets (not occurrences, not matching
+ * lines). Prefer a zero unique-target assertion; do not freeze raw counts.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { NON_PRODUCT_DIRS } from "../fs/non-product-dirs.js";
+import { extractLinkTargets, shouldSkipLinkTarget } from "../validate-content/link-parser.js";
+import { isDeclaredLiveProcedureExclusion } from "./live-procedure-exclusions.js";
+import { isPrunedPythonArtifactPath } from "./python-free.js";
+const SKIP_DIRS = new Set([...NON_PRODUCT_DIRS, ".planning", "specs"]);
+/**
+ * Metric used by C3: unique live-invalid helper targets.
+ * Not occurrence count, not matching-line count.
+ */
+export const LIVE_PROCEDURE_METRIC = "unique-targets";
+function shouldSkipPath(parts) {
+    if (parts.some((p) => SKIP_DIRS.has(p)))
+        return true;
+    return parts.includes("history") && parts.includes("archive");
+}
+function toPosix(rel) {
+    return rel.split(sep).join("/");
+}
+function collectMarkdownFiles(root) {
+    const out = [];
+    const walk = (dir, parts) => {
+        if (shouldSkipPath(parts))
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const full = join(dir, entry.name);
+            const nextParts = [...parts, entry.name];
+            if (shouldSkipPath(nextParts))
+                continue;
+            if (entry.isDirectory()) {
+                walk(full, nextParts);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                out.push(full);
+            }
+        }
+    };
+    walk(root, []);
+    return out.sort();
+}
+const PATH_CHAR = /[A-Za-z0-9_.-]/;
+const PY_HELPER_TOKEN = /^(?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+\.py[c]?$/;
+const RUN_SHIM_TOKEN = /^(?:\.deft\/core\/run|deft\/run|run)$/;
+/** Known pruned deposit helpers named without a directory. Not consumer app.py. */
+const PRUNED_BARE_HELPER_BASENAMES = new Set([
+    "gh_rest.py",
+    "ip_risk.py",
+    "preflight_implementation.py",
+    "preflight_gh.py",
+    "migrate_vbrief.py",
+    "slug_normalize.py",
+    "slice_record.py",
+    "validate_strategy_output.py",
+    "_precutover.py",
+    "swarm_mint_jwt.py",
+]);
+function stripRelativePrefix(posix) {
+    let out = posix;
+    while (out.startsWith("./"))
+        out = out.slice(2);
+    while (out.startsWith("../"))
+        out = out.slice(3);
+    return out;
+}
+export function normalizePythonHelperTarget(raw) {
+    const clean = (raw.split("#")[0] ?? "").split("?")[0] ?? "";
+    const posix = clean.replace(/\\/g, "/");
+    if (posix.includes("://"))
+        return null;
+    const stripped = stripRelativePrefix(posix);
+    if (stripped.includes(".."))
+        return null;
+    const scriptsIdx = stripped.lastIndexOf("scripts/");
+    const token = scriptsIdx >= 0 ? stripped.slice(scriptsIdx) : stripped;
+    if (RUN_SHIM_TOKEN.test(token) || RUN_SHIM_TOKEN.test(stripped)) {
+        if (stripped === ".deft/core/run" || stripped.endsWith("/.deft/core/run")) {
+            return ".deft/core/run";
+        }
+        if (stripped === "deft/run" || stripped.endsWith("/deft/run"))
+            return "deft/run";
+        if (token === "run" || stripped === "run")
+            return "run";
+    }
+    if (!token.includes("/") && PRUNED_BARE_HELPER_BASENAMES.has(token)) {
+        return token;
+    }
+    if (!PY_HELPER_TOKEN.test(token))
+        return null;
+    return token;
+}
+function isPathChar(ch) {
+    if (ch === undefined)
+        return false;
+    return PATH_CHAR.test(ch) || ch === "/" || ch === "\\";
+}
+function extractBacktickPythonHelpers(line) {
+    const out = [];
+    const suffixes = [".pyc", ".py"];
+    for (const suffix of suffixes) {
+        let from = 0;
+        while (from < line.length) {
+            const idx = line.indexOf(suffix, from);
+            if (idx < 0)
+                break;
+            const after = line[idx + suffix.length];
+            if (isPathChar(after)) {
+                from = idx + suffix.length;
+                continue;
+            }
+            let start = idx;
+            while (start > 0 && isPathChar(line[start - 1]))
+                start -= 1;
+            const token = line.slice(start, idx + suffix.length);
+            from = idx + suffix.length;
+            const normalized = normalizePythonHelperTarget(token);
+            if (normalized)
+                out.push(normalized);
+        }
+    }
+    for (const spelling of [".deft/core/run", "deft/run"]) {
+        if (line.includes(spelling)) {
+            const normalized = normalizePythonHelperTarget(spelling);
+            if (normalized)
+                out.push(normalized);
+        }
+    }
+    let tick = 0;
+    while (tick < line.length) {
+        const open = line.indexOf("`", tick);
+        if (open < 0)
+            break;
+        const close = line.indexOf("`", open + 1);
+        if (close < 0)
+            break;
+        const inner = line.slice(open + 1, close).trim();
+        const parts = inner.split(/\s+/).filter((p) => p.length > 0);
+        const first = (parts[0] ?? "").replace(/^\.\//, "");
+        const arg = parts[1];
+        const launcherArgs = new Set([
+            "bootstrap",
+            "spec",
+            "init",
+            "project",
+            "upgrade",
+            "doctor",
+            "validate",
+            "reset",
+        ]);
+        if (first === "run" && (arg === undefined || launcherArgs.has(arg))) {
+            const normalized = normalizePythonHelperTarget("run");
+            if (normalized)
+                out.push(normalized);
+        }
+        tick = close + 1;
+    }
+    return out;
+}
+function extractLineTargets(line) {
+    const found = new Set();
+    for (const raw of extractLinkTargets(line)) {
+        if (raw.startsWith("http://") ||
+            raw.startsWith("https://") ||
+            raw.startsWith("mailto:") ||
+            raw.startsWith("#")) {
+            continue;
+        }
+        if (shouldSkipLinkTarget(raw))
+            continue;
+        const normalized = normalizePythonHelperTarget(raw);
+        if (normalized)
+            found.add(normalized);
+    }
+    for (const token of extractBacktickPythonHelpers(line))
+        found.add(token);
+    return [...found];
+}
+function scanMarkdownFile(absolutePath, relativePath) {
+    if (isDeclaredLiveProcedureExclusion(relativePath))
+        return [];
+    let text;
+    try {
+        text = readFileSync(absolutePath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const hits = [];
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        for (const target of extractLineTargets(line)) {
+            if (!isPrunedPythonArtifactPath(target))
+                continue;
+            hits.push({ file: relativePath, line: i + 1, target });
+        }
+    }
+    return hits;
+}
+export function evaluateLiveProcedureTargets(options) {
+    const stagedRoot = resolve(options.stagedRoot);
+    const hits = [];
+    if (existsSync(stagedRoot)) {
+        for (const md of collectMarkdownFiles(stagedRoot)) {
+            const rel = toPosix(relative(stagedRoot, md));
+            hits.push(...scanMarkdownFile(md, rel));
+        }
+    }
+    for (const extra of options.extraFiles ?? []) {
+        const rel = extra.relativePath.replace(/\\/g, "/");
+        hits.push(...scanMarkdownFile(extra.absolutePath, rel));
+    }
+    const unique = [...new Set(hits.map((h) => h.target))].sort();
+    return { metric: LIVE_PROCEDURE_METRIC, hits, uniqueTargets: unique };
+}
+export function extraDepositMarkdownFiles(root) {
+    const extras = [];
+    for (const name of ["main.md", "SKILL.md"]) {
+        const absolutePath = join(root, name);
+        if (existsSync(absolutePath)) {
+            extras.push({ relativePath: name, absolutePath });
+        }
+    }
+    return extras;
+}
+export class LiveProcedureTargetsError extends Error {
+    evaluation;
+    constructor(evaluation) {
+        super(formatLiveProcedureFailure(evaluation));
+        this.name = "LiveProcedureTargetsError";
+        this.evaluation = evaluation;
+    }
+}
+/** Fail closed when a deposit's live procedures name pruned Python helpers (#3602 C3). */
+export function assertLiveProcedureDepositClean(depositDir) {
+    const result = evaluateLiveProcedureTargets({
+        stagedRoot: depositDir,
+        extraFiles: extraDepositMarkdownFiles(depositDir),
+    });
+    if (result.uniqueTargets.length > 0) {
+        throw new LiveProcedureTargetsError(result);
+    }
+}
+export function formatLiveProcedureFailure(result) {
+    const lines = [
+        `C3 live-procedure target validation failed: ${result.uniqueTargets.length} unique live-invalid helper target(s) (metric=${result.metric}).`,
+    ];
+    for (const hit of result.hits.slice(0, 40)) {
+        lines.push(`  ${hit.file}:${hit.line} -> ${hit.target}`);
+    }
+    if (result.hits.length > 40) {
+        lines.push(`  ... ${result.hits.length - 40} more occurrence(s)`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=live-procedure-targets.js.map

package/dist/deposit/python-free.d.ts

@@ -5,6 +5,12 @@
  * Python-only artifacts that must not ship to npm consumers: the legacy
  * `scripts/` tree, `.py` files, and Python `run` shims.
  */
+/** True when a named helper path is a Python artifact the deposit prunes (#3602 C3). */
+export declare function isPythonHelperPath(relPath: string): boolean;
+/** Path spellings of the Python `run` launcher python-free removes (#3602 C3). */
+export declare function isPythonRunShimPath(relPath: string): boolean;
+/** True when C3 should treat a named path as a pruned Python deposit helper. */
+export declare function isPrunedPythonArtifactPath(relPath: string): boolean;
 export interface PythonArtifact {
     readonly path: string;
     readonly kind: "py-file" | "scripts-tree" | "run-shim";

package/dist/deposit/python-free.js

@@ -11,6 +11,21 @@ import { join, relative } from "node:path";
 import { containedRemove } from "../fs/contained-write.js";
 const PY_SUFFIX = ".py";
 const PYC_SUFFIX = ".pyc";
+/** True when a named helper path is a Python artifact the deposit prunes (#3602 C3). */
+export function isPythonHelperPath(relPath) {
+    const posix = relPath.replace(/\\/g, "/");
+    const base = posix.split("/").pop() ?? posix;
+    return base.endsWith(PY_SUFFIX) || base.endsWith(PYC_SUFFIX);
+}
+/** Path spellings of the Python `run` launcher python-free removes (#3602 C3). */
+export function isPythonRunShimPath(relPath) {
+    const posix = relPath.replace(/\\/g, "/").replace(/^\.\//, "");
+    return posix === "run" || posix === ".deft/core/run" || posix === "deft/run";
+}
+/** True when C3 should treat a named path as a pruned Python deposit helper. */
+export function isPrunedPythonArtifactPath(relPath) {
+    return isPythonHelperPath(relPath) || isPythonRunShimPath(relPath);
+}
 function isPythonRunShim(_path, head) {
     if (!head.startsWith("#!"))
         return false;

package/dist/deposit/rewrite-deposit-links.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Flatten-aware rewrite of relative markdown links from the source tree onto
+ * the C1 packed layout (#3937).
+ *
+ * Source checkout: content/X lives under content/; root main.md / SKILL.md stay
+ * at the repo root. Deposit: content/ children flatten to the payload root, and
+ * harness entries land beside them. A naive `./content/` strip cannot express
+ * the reverse `../../main.md` escape. This rewrite maps each relative target
+ * through the source path, then emits a deposit-relative href.
+ */
+export declare const DEPOSIT_LINK_REWRITE_VERSION = "1";
+export declare const REWRITE_MARKER_PREFIX = "<!-- deft:deposit-link-rewrite";
+export declare function isUrlLikeTarget(target: string): boolean;
+/** Map a repo-relative source path to its packed-deposit relative path. */
+export declare function mapSourceToPackRelative(sourceRel: string): string | null;
+/** Inverse: packed path -> source path the file was copied from. */
+export declare function sourceRelForPackRel(packRel: string): string;
+export declare function resolveSourceTargetRel(sourceFileRel: string, rawPath: string): string;
+export declare function splitLinkHash(target: string): {
+    path: string;
+    suffix: string;
+};
+export interface RewriteLinkResult {
+    readonly next: string;
+    readonly rewritten: boolean;
+    readonly packMapped: boolean;
+}
+export declare function rewriteRelativeLink(options: {
+    readonly sourceFileRel: string;
+    readonly packFileRel: string;
+    readonly target: string;
+}): RewriteLinkResult;
+export declare function rewriteMarker(sourceRel: string): string;
+export declare function rewriteMarkdownDepositLinks(options: {
+    readonly content: string;
+    readonly sourceFileRel: string;
+    readonly packFileRel: string;
+}): {
+    content: string;
+    rewriteCount: number;
+};
+//# sourceMappingURL=rewrite-deposit-links.d.ts.map