spec-controller 0.1.0-alpha.9 → 0.1.0

package/dist/outputLocation.js

@@ -0,0 +1,139 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readlinkSync, realpathSync, statSync, unlinkSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+const USAGE_EXIT_CODE = 2;
+class UsageRefusal extends Error {
+    name = "UsageRefusal";
+    exitCode = USAGE_EXIT_CODE;
+}
+export function unwritableRefusal(subject, path, err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return `${subject}: ${path} (${reason})`;
+}
+export function writeOrRefuse(subject, path, write) {
+    try {
+        write();
+    }
+    catch (err) {
+        refuse(unwritableRefusal(subject, path, err));
+    }
+}
+export function refuse(message) {
+    process.stderr.write(message + "\n");
+    throw new UsageRefusal(message);
+}
+export function settlingRefusal(run, refused) {
+    try {
+        return run();
+    }
+    catch (err) {
+        if (!(err instanceof UsageRefusal))
+            throw err;
+        process.exitCode = err.exitCode;
+        return refused;
+    }
+}
+export function probeDestination(path) {
+    try {
+        return { identity: identityOf(openSync(path, constants.O_WRONLY)), created: undefined };
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    const identity = identityOf(openSync(path, constants.O_WRONLY | constants.O_CREAT));
+    return { identity, created: realpathSync(path) };
+}
+export function firstSharingFile(file, others) {
+    const created = [];
+    try {
+        const identity = identityOrNone(file, created);
+        if (identity === undefined)
+            return undefined;
+        return others.find((other) => sameIdentity(identityOrNone(other, created), identity));
+    }
+    finally {
+        for (const path of created)
+            unlinkSync(path);
+    }
+}
+function identityOrNone(path, created) {
+    try {
+        const probed = probeDestination(path);
+        if (probed.created !== undefined)
+            created.push(probed.created);
+        return probed.identity;
+    }
+    catch {
+        // A path that cannot be opened for writing shares no file with the one being checked.
+    }
+    return undefined;
+}
+function sameIdentity(a, b) {
+    return a !== undefined && a.dev === b.dev && a.ino === b.ino;
+}
+export function regularFileIdentity(path) {
+    try {
+        return regularIdentity(statSync(path, { bigint: true }));
+    }
+    catch {
+        // A path that cannot be stat'd is no file, so it is no input's file either.
+    }
+    return undefined;
+}
+export function inputAt(path, inputs) {
+    const identity = regularFileIdentity(path);
+    if (identity === undefined)
+        return undefined;
+    return inputs.find((input) => sameIdentity(regularFileIdentity(input.path), identity));
+}
+export function stdoutIdentity() {
+    try {
+        return regularIdentity(fstatSync(1, { bigint: true }));
+    }
+    catch {
+        // A closed stdout has no file for a destination to share.
+    }
+    return undefined;
+}
+function identityOf(fd) {
+    try {
+        return regularIdentity(fstatSync(fd, { bigint: true }));
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function regularIdentity(stats) {
+    return stats.isFile() ? { dev: stats.dev, ino: stats.ino } : undefined;
+}
+const STDOUT_SPELLINGS = new Set(["/dev/stdout", "/dev/fd/1", "/proc/self/fd/1", "/proc/thread-self/fd/1", `/proc/${process.pid}/fd/1`]);
+const MAX_LINKS_FOLLOWED = 40;
+export function namesStdout(path) {
+    let current = resolve(path);
+    for (let followed = 0; current !== undefined && followed <= MAX_LINKS_FOLLOWED; followed++) {
+        if (STDOUT_SPELLINGS.has(current))
+            return true;
+        current = withFirstLinkFollowed(current);
+    }
+    return false;
+}
+function withFirstLinkFollowed(path) {
+    const parts = path.split(sep).filter((part) => part !== "");
+    for (let length = 1; length <= parts.length; length++) {
+        const prefix = sep + parts.slice(0, length).join(sep);
+        const target = linkTarget(prefix);
+        if (target !== undefined)
+            return resolve(dirname(prefix), target, ...parts.slice(length));
+    }
+    return undefined;
+}
+function linkTarget(path) {
+    try {
+        return lstatSync(path).isSymbolicLink() ? readlinkSync(path) : undefined;
+    }
+    catch {
+        // A prefix that cannot be read is followed no further: the path names stdout only as spelled.
+    }
+    return undefined;
+}
+//# sourceMappingURL=outputLocation.js.map

package/dist/outputLocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputLocation.js","sourceRoot":"","sources":["../src/outputLocation.ts"],"names":[],"mappings":"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"}

package/dist/run-management/keptRun.d.ts

@@ -1,79 +1,22 @@
-/**
- * The KEPT-RUN scaffold — the thin app-layer that turns a bare tool invocation into a
- * STORED run (the run-management layer). A kept run is a consultancy / product-dev artefact (NOT CI):
- * it makes a per-run directory under a caller-INJECTED store root and routes the tool's
- * `--format` outputs into it. The tool holds no storage opinion (the `--format` surface); this
- * scaffold adds only the directory + the routing.
- *
- * Split by the three-layer architecture:
- *   - PURE planner (`planKeptRun`): given `{ storeRoot, target, runId }`, yields the run
- *     dir `<storeRoot>/<target>/<runId>/` and the two file-dest paths — no IO, proven
- *     `@unit`.
- *   - IMPURE runner (`executeKeptRun`): `mkdir -p` the run dir, then route the tool's
- *     `--format` outputs into the two files by handing an injected tool-invoker the two
- *     file-dest `--format` specs. The ONLY IO, proven `@integration` (the real on-disk
- *     files under a temp root + the repo untouched — never a planner re-run).
- *
- * The store root is an INJECTED parameter — never hardcoded — so the scaffold is
- * location-agnostic (proven against a temp root; the repo is never written). RMG-001 is
- * the dir + the routed outputs; the `run.yaml` stamp (RMG-002) and the `--run-id` mnemonic
- * override (RMG-003) land in later sub-issues.
- *
- * Parent: @SCN-RMG-001 — the run-management layer.
- */
-/** The two artefact filenames a kept run routes the tool's outputs into. */
-export declare const RECONCILIATION_DOCUMENT = "spec-reconciliation.md";
-/**
- * The machine artefact filename (@SCN-RMD-001) — renamed `ledger.json` →
- * `spec-reconciliation.json` (parity with `spec-reconciliation.md`): it is the machine form
- * of the WHOLE reconciliation document, not just the ledger.
- */
-export declare const RECONCILIATION_JSON = "spec-reconciliation.json";
-/** The manifest filename a kept run stamps in the run dir (RMG-002). */
+import { type ReadInput } from "../outputLocation.js";
 export declare const RUN_MANIFEST = "run.yaml";
-/**
- * The run.yaml schema version this scaffold stamps. Bumped 1 → 2 by 3F-1916, which added
- * the tool identity (`tool_sha` / `tool_version`) — so a reader can tell a run that
- * predates tool-identity recording (schema 1) from one that should carry it (schema 2).
- * run.yaml is write-only (no production reader), so the bump breaks no read path.
- */
-export declare const RUN_MANIFEST_SCHEMA_VERSION = 2;
-/** The stored-run modes (run.yaml `mode`). */
-export type RunMode = "balance" | "analyse" | "migrate";
-/**
- * The manifest-only metadata a kept run stamps that the path spec (`KeptRunSpec`) does not
- * carry — the source SHA, the run mode, and the ISO date.
- */
+type RunMode = "balance";
 export interface RunManifestMeta {
     readonly sourceSha: string;
-    /**
-     * The TOOL's own git SHA — which spec-controller produced this run (3F-1916), distinct
-     * from the target's `sourceSha`. A string ("unknown" when the tool is not a git
-     * checkout), mirroring `sourceSha`'s own "unknown" fallback — so run.yaml is internally
-     * consistent (both facts use the same absent-marker, never a bare null).
-     */
     readonly toolSha: string;
-    /** The tool's package version — always present. */
     readonly toolVersion: string;
     readonly mode: RunMode;
     readonly date: string;
 }
-/** The full manifest input: the path spec's run-id + target, plus the manifest-only meta. */
 export interface RunManifestInput extends RunManifestMeta {
     readonly runId: string;
     readonly target: string;
 }
-/**
- * The run.yaml manifest — the decided light field set. `purpose`/`links` default EMPTY (the ad-hoc default; slugs are
- * added by operator hand-edit afterward). `category`/`use_case` are NOT stamped (`purpose`
- * subsumes them). Keys are listed in the decided stamp order.
- */
 export interface RunManifest {
     readonly schema_version: number;
     readonly run_id: string;
     readonly target: string;
     readonly source_sha: string;
-    /** The TOOL's identity (3F-1916) — which spec-controller produced the run. */
     readonly tool_sha: string;
     readonly tool_version: string;
     readonly mode: RunMode;
@@ -85,72 +28,28 @@ export interface RunManifest {
         readonly reconciliation: string;
     };
 }
-/** The kept-run inputs: the injected store root, the target, and the run-id. */
 export interface KeptRunSpec {
     readonly storeRoot: string;
     readonly target: string;
     readonly runId: string;
+    readonly formatPaths?: readonly string[];
+    readonly inputs?: readonly ReadInput[];
 }
-/** The planned run: the run dir plus the two file-dest paths inside it. */
 export interface KeptRunPlan {
     readonly runDir: string;
     readonly documentPath: string;
     readonly reconciliationJsonPath: string;
 }
-/**
- * Invokes the reconciliation tool with the given `--format <fmt>:<path>` specs. INJECTED so
- * the scaffold stays the tool's black-box caller (the real CLI subprocess in the
- * `@integration` arm) and holds no opinion on HOW the tool is run — only WHERE its outputs
- * land (the two file-dest paths the runner hands it).
- */
-export type RouteOutputs = (formatSpecs: readonly string[]) => void;
-/**
- * PURE planner: yield the run dir `<storeRoot>/<target>/<runId>/` and the two file-dest
- * paths (`<dir>/spec-reconciliation.md`, `<dir>/spec-reconciliation.json`) from the spec. No
- * IO — the store root is threaded straight through `join`, so it is a parameter, never
- * hardcoded.
- */
+export type RouteOutputs = (formatSpecs: readonly string[], runDir: string) => boolean;
+export declare function earlierStoredRunDirOf(path: string, ownRunDir: string | undefined): string | undefined;
 export declare function planKeptRun(spec: KeptRunSpec): KeptRunPlan;
-/**
- * Options for the pure run-id resolver (RMG-003): the operator's OPTIONAL `--run-id` mnemonic
- * and the INJECTED clock instant the default timestamp derives from.
- */
 export interface ResolveRunIdOptions {
-    /** The operator's `--run-id` mnemonic when supplied; overrides the timestamp default, verbatim. */
     readonly runId?: string;
-    /**
-     * The injected instant the default ISO-timestamp run-id derives from — the deterministic-@unit
-     * seam. Never a bare `new Date()` inside the resolver, so the default run-id is pin-testable.
-     */
     readonly now: Date;
 }
-/**
- * PURE run-id resolver — the CLI/edge seam that turns an OPTIONAL `--run-id` into the concrete
- * run-id naming the run dir (feeds `KeptRunSpec.runId`). No `--run-id` → an ISO-8601 UTC
- * timestamp derived from the INJECTED `now` (filesystem-safe: no colons, no millis — matching
- * the existing store run dir); `--run-id <mnemonic>` → that mnemonic verbatim (`acme-q3`, `e1`
- * — an earlier precedent), which ignores the clock. No IO — proven `@unit` (RMG-003).
- * The clock is injected (never a bare `new Date()`) so the default timestamp is deterministic
- * under test (the discipline the old `formatRunTimestamp` used). Just default-vs-override — no
- * sanitisation / collision policy (deferred).
- */
 export declare function resolveRunId(options: ResolveRunIdOptions): string;
-/**
- * PURE: build the run.yaml manifest object from the run metadata (RMG-002). `purpose` and
- * `links` are stamped EMPTY (the ad-hoc default; slugs are added by operator hand-edit of
- * run.yaml afterward — the documented curation convention); `artefacts` carry the decided
- * filenames. No IO — proven `@unit`.
- */
 export declare function planRunManifest(input: RunManifestInput): RunManifest;
-/** PURE: serialise the manifest to YAML text the impure runner writes verbatim. */
 export declare function serialiseRunManifest(manifest: RunManifest): string;
-/**
- * IMPURE runner: `mkdir -p` the run dir, route the tool's `--format` outputs into the two
- * files via the injected `route` — the document as `md:<documentPath>`, the reconciliation
- * JSON as `json:<reconciliationJsonPath>` — and stamp `run.yaml` with the manifest built from the spec + `meta`
- * (RMG-002). Returns the plan it realised. The only IO. The `mkdir` is load-bearing: the
- * tool's writer uses `writeFileSync`, which needs the parent dir to exist — so the scaffold
- * creates the dir the location-agnostic tool writes into.
- */
-export declare function executeKeptRun(spec: KeptRunSpec, meta: RunManifestMeta, route: RouteOutputs): KeptRunPlan;
+export declare function executeKeptRun(spec: KeptRunSpec, meta: RunManifestMeta, route: RouteOutputs): KeptRunPlan | undefined;
+export {};
 //# sourceMappingURL=keptRun.d.ts.map

package/dist/run-management/keptRun.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keptRun.d.ts","sourceRoot":"","sources":["../../src/run-management/keptRun.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"keptRun.d.ts","sourceRoot":"","sources":["../../src/run-management/keptRun.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAKxG,eAAO,MAAM,YAAY,aAAa,CAAC;AAIvC,KAAK,OAAO,GAAG,SAAS,CAAC;AAEzB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KACjC,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;CACzC;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;AAEvF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAIrG;AA0BD,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAO1D;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;CACpB;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAKjE;AAMD,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAiBpE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAElE;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,YAAY,GAClB,WAAW,GAAG,SAAS,CAoBzB"}

package/dist/run-management/keptRun.js

@@ -1,52 +1,39 @@
-/**
- * The KEPT-RUN scaffold — the thin app-layer that turns a bare tool invocation into a
- * STORED run (the run-management layer). A kept run is a consultancy / product-dev artefact (NOT CI):
- * it makes a per-run directory under a caller-INJECTED store root and routes the tool's
- * `--format` outputs into it. The tool holds no storage opinion (the `--format` surface); this
- * scaffold adds only the directory + the routing.
- *
- * Split by the three-layer architecture:
- *   - PURE planner (`planKeptRun`): given `{ storeRoot, target, runId }`, yields the run
- *     dir `<storeRoot>/<target>/<runId>/` and the two file-dest paths — no IO, proven
- *     `@unit`.
- *   - IMPURE runner (`executeKeptRun`): `mkdir -p` the run dir, then route the tool's
- *     `--format` outputs into the two files by handing an injected tool-invoker the two
- *     file-dest `--format` specs. The ONLY IO, proven `@integration` (the real on-disk
- *     files under a temp root + the repo untouched — never a planner re-run).
- *
- * The store root is an INJECTED parameter — never hardcoded — so the scaffold is
- * location-agnostic (proven against a temp root; the repo is never written). RMG-001 is
- * the dir + the routed outputs; the `run.yaml` stamp (RMG-002) and the `--run-id` mnemonic
- * override (RMG-003) land in later sub-issues.
- *
- * Parent: @SCN-RMG-001 — the run-management layer.
- */
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { stringify } from "yaml";
-/** The two artefact filenames a kept run routes the tool's outputs into. */
-export const RECONCILIATION_DOCUMENT = "spec-reconciliation.md";
-/**
- * The machine artefact filename (@SCN-RMD-001) — renamed `ledger.json` →
- * `spec-reconciliation.json` (parity with `spec-reconciliation.md`): it is the machine form
- * of the WHOLE reconciliation document, not just the ledger.
- */
-export const RECONCILIATION_JSON = "spec-reconciliation.json";
-/** The manifest filename a kept run stamps in the run dir (RMG-002). */
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parse, stringify } from "yaml";
+import { APP_MESSAGES, AppMessage } from "../messages.js";
+import { firstSharingFile, inputAt, refuse, writeOrRefuse } from "../outputLocation.js";
+const RECONCILIATION_DOCUMENT = "spec-reconciliation.md";
+const RECONCILIATION_JSON = "spec-reconciliation.json";
 export const RUN_MANIFEST = "run.yaml";
-/**
- * The run.yaml schema version this scaffold stamps. Bumped 1 → 2 by 3F-1916, which added
- * the tool identity (`tool_sha` / `tool_version`) — so a reader can tell a run that
- * predates tool-identity recording (schema 1) from one that should carry it (schema 2).
- * run.yaml is write-only (no production reader), so the bump breaks no read path.
- */
-export const RUN_MANIFEST_SCHEMA_VERSION = 2;
-/**
- * PURE planner: yield the run dir `<storeRoot>/<target>/<runId>/` and the two file-dest
- * paths (`<dir>/spec-reconciliation.md`, `<dir>/spec-reconciliation.json`) from the spec. No
- * IO — the store root is threaded straight through `join`, so it is a parameter, never
- * hardcoded.
- */
+const RUN_MANIFEST_SCHEMA_VERSION = 2;
+export function earlierStoredRunDirOf(path, ownRunDir) {
+    const dir = existsSync(path) ? dirname(realpathSync(path)) : realpathSync(dirname(path));
+    if (ownRunDir !== undefined && dir === realpathSync(ownRunDir))
+        return undefined;
+    return holdsRunManifest(dir) ? dir : undefined;
+}
+function holdsRunManifest(dir) {
+    return readsAsRunManifest(runManifestDocumentIn(dir));
+}
+function runManifestDocumentIn(dir) {
+    try {
+        return parse(readFileSync(join(dir, RUN_MANIFEST), "utf8"));
+    }
+    catch {
+        // A run.yaml that is absent, unreadable or not YAML reads as no document.
+    }
+    return undefined;
+}
+function readsAsRunManifest(document) {
+    if (typeof document !== "object" || document === null)
+        return false;
+    const fields = document;
+    return (fields["schema_version"] !== undefined &&
+        fields["run_id"] !== undefined &&
+        typeof fields["artefacts"] === "object" &&
+        fields["artefacts"] !== null);
+}
 export function planKeptRun(spec) {
     const runDir = join(spec.storeRoot, spec.target, spec.runId);
     return {
@@ -55,39 +42,15 @@ export function planKeptRun(spec) {
         reconciliationJsonPath: join(runDir, RECONCILIATION_JSON),
     };
 }
-/**
- * PURE run-id resolver — the CLI/edge seam that turns an OPTIONAL `--run-id` into the concrete
- * run-id naming the run dir (feeds `KeptRunSpec.runId`). No `--run-id` → an ISO-8601 UTC
- * timestamp derived from the INJECTED `now` (filesystem-safe: no colons, no millis — matching
- * the existing store run dir); `--run-id <mnemonic>` → that mnemonic verbatim (`acme-q3`, `e1`
- * — an earlier precedent), which ignores the clock. No IO — proven `@unit` (RMG-003).
- * The clock is injected (never a bare `new Date()`) so the default timestamp is deterministic
- * under test (the discipline the old `formatRunTimestamp` used). Just default-vs-override — no
- * sanitisation / collision policy (deferred).
- */
 export function resolveRunId(options) {
-    // The operator mnemonic, when given, names the run dir verbatim — the clock is ignored.
     if (options.runId !== undefined) {
         return options.runId;
     }
-    // Otherwise the run-id defaults to the injected instant as a filesystem-safe timestamp.
     return formatRunTimestamp(options.now);
 }
-/**
- * Format an injected instant as a filesystem-safe ISO-8601 UTC timestamp: `toISOString()`
- * yields `2026-06-30T10:04:01.123Z`; drop the milliseconds, then swap the time-separator
- * colons for hyphens so the string is a safe directory name (`2026-06-30T10-04-01Z` — the
- * form the existing store run dir uses).
- */
 function formatRunTimestamp(instant) {
-    return instant.toISOString().replace(/\.\d+Z$/, "Z").replace(/:/g, "-");
+    return instant.toISOString().replace(/\.\d+Z/, "Z").replace(/:/g, "-");
 }
-/**
- * PURE: build the run.yaml manifest object from the run metadata (RMG-002). `purpose` and
- * `links` are stamped EMPTY (the ad-hoc default; slugs are added by operator hand-edit of
- * run.yaml afterward — the documented curation convention); `artefacts` carry the decided
- * filenames. No IO — proven `@unit`.
- */
 export function planRunManifest(input) {
     return {
         schema_version: RUN_MANIFEST_SCHEMA_VERSION,
@@ -98,8 +61,6 @@ export function planRunManifest(input) {
         tool_version: input.toolVersion,
         mode: input.mode,
         date: input.date,
-        // EMPTY defaults — the ad-hoc run; slugs/links are added by operator hand-edit of
-        // run.yaml afterward (no --purpose flag, no vocab enforcement — both deferred).
         purpose: [],
         links: [],
         artefacts: {
@@ -108,26 +69,25 @@ export function planRunManifest(input) {
         },
     };
 }
-/** PURE: serialise the manifest to YAML text the impure runner writes verbatim. */
 export function serialiseRunManifest(manifest) {
     return stringify(manifest);
 }
-/**
- * IMPURE runner: `mkdir -p` the run dir, route the tool's `--format` outputs into the two
- * files via the injected `route` — the document as `md:<documentPath>`, the reconciliation
- * JSON as `json:<reconciliationJsonPath>` — and stamp `run.yaml` with the manifest built from the spec + `meta`
- * (RMG-002). Returns the plan it realised. The only IO. The `mkdir` is load-bearing: the
- * tool's writer uses `writeFileSync`, which needs the parent dir to exist — so the scaffold
- * creates the dir the location-agnostic tool writes into.
- */
 export function executeKeptRun(spec, meta, route) {
     const plan = planKeptRun(spec);
-    mkdirSync(plan.runDir, { recursive: true });
-    route([`md:${plan.documentPath}`, `json:${plan.reconciliationJsonPath}`]);
-    // Stamp run.yaml from the spec's run-id/target (so it can't drift from the run dir) + the
-    // manifest-only meta. The serialised YAML is valid — the @integration parses it back.
+    writeOrRefuse(APP_MESSAGES[AppMessage.StoredRunDirectoryNotCreated](), plan.runDir, () => mkdirSync(plan.runDir, { recursive: true }));
+    const manifestPath = join(plan.runDir, RUN_MANIFEST);
+    const sharesManifest = firstSharingFile(manifestPath, spec.formatPaths ?? []);
+    if (sharesManifest !== undefined) {
+        refuse(APP_MESSAGES[AppMessage.FormatNamesStoredRunManifest](sharesManifest, manifestPath, plan.runDir));
+    }
+    const readManifest = inputAt(manifestPath, spec.inputs ?? []);
+    if (readManifest !== undefined) {
+        refuse(APP_MESSAGES[AppMessage.StoredRunReadsItsManifest](manifestPath, readManifest.path, readManifest.subject));
+    }
+    if (!route([`md:${plan.documentPath}`, `json:${plan.reconciliationJsonPath}`], plan.runDir))
+        return undefined;
     const manifest = planRunManifest({ runId: spec.runId, target: spec.target, ...meta });
-    writeFileSync(join(plan.runDir, RUN_MANIFEST), serialiseRunManifest(manifest));
+    writeOrRefuse(APP_MESSAGES[AppMessage.StoredRunManifestNotWritten](), manifestPath, () => writeFileSync(manifestPath, serialiseRunManifest(manifest)));
     return plan;
 }
 //# sourceMappingURL=keptRun.js.map

package/dist/run-management/keptRun.js.map

@@ -1 +1 @@
-{"version":3,"file":"keptRun.js","sourceRoot":"","sources":["../../src/run-management/keptRun.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"keptRun.js","sourceRoot":"","sources":["../../src/run-management/keptRun.ts"],"names":[],"mappings":"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"}

package/dist/run-management/resolveRunInputs.d.ts

@@ -1,82 +1,15 @@
-/**
- * Resolve a run's git-derived inputs — the target's source SHA and repo root. The
- * IMPURE half of the old run/runContext.ts: both shell out to `git` over the
- * target tree, so they live in the app's run-management layer, apart from the pure
- * provenance projection (packages/core/src/provenance/provenance.ts) they feed. The
- * CLI (cli-balance/cli.ts) calls these once to build the RunContext.
- *
- * Scenarios: @SCN-RPT-001 (the run-provenance slice); the --source-sha override;
- * @SCN-RPT-016 (target-root derivation); @SCN-RPT-026 / @SCN-RPT-029 (the tool's own identity).
- */
-/**
- * Resolve the target's source SHA (project design §4). An explicit non-empty
- * `sourceSha` wins — the override for non-git / zip / detached-HEAD targets (the
- * --source-sha flag). Otherwise `git -C <targetDir> rev-parse HEAD` (trimmed) as a
- * READ-ONLY pure read. On any throw —
- * a non-git target, git absent, an empty answer — resolve to `null` ("unknown")
- * rather than crashing. `targetDir` = dirname(--features) when given, else cwd.
- */
 export declare function resolveSourceSha(opts: {
     sourceSha?: string;
     targetDir?: string;
 }): string | null;
-/** The tool's own identity — which spec-controller produced a run (3F-1916). */
 export interface ToolIdentity {
-    /** The tool's own git HEAD, or null when the tool is not a git checkout (an installed package). */
     toolSha: string | null;
-    /** The tool's package version — always present (read from the tool's own package.json). */
     toolVersion: string;
 }
-/**
- * Resolve the TOOL's own identity (3F-1916) — which spec-controller produced this run,
- * distinct from the TARGET's `sourceSha`. Two facts, one call, threaded to both the
- * report provenance (RunContext) and the run.yaml manifest.
- *
- * **TWO TRAPS, AND THIS DOCBLOCK ONLY NAMED THE FIRST FOR ELEVEN WEEKS** (@SCN-RPT-029,
- * 3F-3418). Nothing typechecks a comment, and the sentence below — true, and the whole of
- * what was written here — is what made the second trap read as already-handled.
- *
- * **Trap one, cwd:** at run time the process cwd is the TARGET repo (reconcile runs
- * there), so a bare `git rev-parse HEAD` would re-record the TARGET's SHA. So the SHA is
- * read `git -C <the tool's OWN dir>`, derived from `import.meta.url`, never cwd (3F-1916).
- *
- * **Trap two, which the `-C` guard could not see:** the tool's own dir is ITSELF inside the
- * target. For an installed package that dir is `<consumer>/node_modules/…`, which is inside
- * the consumer's worktree, so `git -C` walks up to the consumer's `.git` and answers with
- * the consumer's HEAD — being `.gitignore`d makes no difference, git does not stop at
- * ignored directories. That is not an absent tool SHA, it is a WRONG one, and nothing on
- * the rendered report distinguishes it from a genuine one. It is also the only case a
- * consumer ever sees: every adopter installs into a git repository. `resolveToolSha`
- * therefore answers a `node_modules` SEGMENT before it asks git at all.
- *
- * `toolSha` is `null` for a tool resolved out of `node_modules`, and otherwise
- * `git -C <toolDir> rev-parse HEAD` (trimmed) or `null` on any throw — no `.git` above the
- * tool, git absent, or an empty answer — mirroring `resolveSourceSha`'s fail-soft.
- * `toolVersion` is read from the tool's own `package.json` (walked up from `toolDir`), or
- * `"unknown"` when none is found — so a run stays attributable by version even when no SHA
- * can be read. `toolDir` / `packageJsonPath` are injectable for the `@unit` teeth
- * (@SCN-RPT-026, @SCN-RPT-029).
- */
 export declare function resolveToolIdentity(opts?: {
     toolDir?: string;
     packageJsonPath?: string;
 }): ToolIdentity;
-/**
- * Resolve the TARGET repo root — the root the recorded input paths (`presentInputs`)
- * and the evidence-observation locators (`countRuntimeEvidenceObservationKinds`) are both made
- * portable against (@SCN-RPT-016). The bug it fixes: the prior CLI relativized
- * against `process.cwd()` — the TOOL's own repo — so a cross-repo reconcile
- * (cwd ≠ target) kept the target's absolute paths (they aren't under cwd → the
- * "absolute-not-under-root" branch of `relativizeToRoot` → leaked verbatim).
- *
- * The rule (mirrors `resolveSourceSha`'s targetDir derivation): the root is derived from
- * the TARGET, never the run cwd — the git top-level of `dirname(--features)` when the
- * target is a git repo (the robust case: `--features` may sit in a nested dir), else
- * `dirname(--features)` itself (a non-git target — a zip / extracted tree), else
- * `process.cwd()` for a self-reconcile with no `--features` (the legacy cwd = target
- * assumption, preserved as the fallback). A READ-ONLY `git -C … rev-parse --show-toplevel`
- * (read-only-target-safe); any throw falls back to `dirname(--features)`.
- */
 export declare function resolveTargetRoot(opts: {
     features?: string;
 }): string;

package/dist/run-management/resolveRunInputs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveRunInputs.d.ts","sourceRoot":"","sources":["../../src/run-management/resolveRunInputs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAiBhG;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,mGAAmG;IACnG,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,2FAA2F;IAC3F,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,YAAY,CAQ3G;AAiED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAerE"}
+{"version":3,"file":"resolveRunInputs.d.ts","sourceRoot":"","sources":["../../src/run-management/resolveRunInputs.ts"],"names":[],"mappings":"AAKA,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAQhG;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,mBAAmB,CAAC,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,YAAY,CAQ3G;AAgCD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAMrE"}