spec-controller 0.1.0-alpha.1

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

@@ -0,0 +1,156 @@
+/**
+ * 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). */
+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.
+ */
+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;
+    readonly date: string;
+    readonly purpose: readonly string[];
+    readonly links: readonly string[];
+    readonly artefacts: {
+        readonly document: string;
+        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;
+}
+/** 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 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;
+//# sourceMappingURL=keptRun.d.ts.map

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

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

package/dist/run-management/keptRun.js

@@ -0,0 +1,133 @@
+/**
+ * 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). */
+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.
+ */
+export function planKeptRun(spec) {
+    const runDir = join(spec.storeRoot, spec.target, spec.runId);
+    return {
+        runDir,
+        documentPath: join(runDir, RECONCILIATION_DOCUMENT),
+        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, "-");
+}
+/**
+ * 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,
+        run_id: input.runId,
+        target: input.target,
+        source_sha: input.sourceSha,
+        tool_sha: input.toolSha,
+        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: {
+            document: RECONCILIATION_DOCUMENT,
+            reconciliation: RECONCILIATION_JSON,
+        },
+    };
+}
+/** 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.
+    const manifest = planRunManifest({ runId: spec.runId, target: spec.target, ...meta });
+    writeFileSync(join(plan.runDir, RUN_MANIFEST), serialiseRunManifest(manifest));
+    return plan;
+}
+//# sourceMappingURL=keptRun.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,70 @@
+/**
+ * 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).
+ */
+/**
+ * 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.
+ *
+ * **The correctness trap this exists to avoid:** 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 — the exact bug this ticket fixes. So the SHA is read `git -C <the tool's
+ * OWN dir>`, derived from `import.meta.url`, never cwd.
+ *
+ * `toolSha` is `git -C <toolDir> rev-parse HEAD` (trimmed), or `null` on any throw — the
+ * tool installed as a package with no `.git`, 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).
+ */
+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;
+//# sourceMappingURL=resolveRunInputs.d.ts.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,YAAY,CAQ3G;AA2CD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAerE"}

package/dist/run-management/resolveRunInputs.js

@@ -0,0 +1,144 @@
+/**
+ * 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).
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * 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 function resolveSourceSha(opts) {
+    if (opts.sourceSha !== undefined && opts.sourceSha.trim() !== "") {
+        return opts.sourceSha.trim();
+    }
+    try {
+        const dir = opts.targetDir !== undefined && opts.targetDir.trim() !== ""
+            ? opts.targetDir
+            : process.cwd();
+        const out = execFileSync("git", ["-C", dir, "rev-parse", "HEAD"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const sha = out.trim();
+        return sha === "" ? null : sha;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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.
+ *
+ * **The correctness trap this exists to avoid:** 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 — the exact bug this ticket fixes. So the SHA is read `git -C <the tool's
+ * OWN dir>`, derived from `import.meta.url`, never cwd.
+ *
+ * `toolSha` is `git -C <toolDir> rev-parse HEAD` (trimmed), or `null` on any throw — the
+ * tool installed as a package with no `.git`, 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).
+ */
+export function resolveToolIdentity(opts = {}) {
+    const toolDir = opts.toolDir !== undefined && opts.toolDir.trim() !== ""
+        ? opts.toolDir
+        : dirname(fileURLToPath(import.meta.url));
+    return {
+        toolSha: resolveToolSha(toolDir),
+        toolVersion: resolveToolVersion(opts.packageJsonPath ?? findPackageJson(toolDir)),
+    };
+}
+/** The tool's own git HEAD, read `-C <toolDir>` (never cwd), null on any throw. */
+function resolveToolSha(toolDir) {
+    try {
+        const out = execFileSync("git", ["-C", toolDir, "rev-parse", "HEAD"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const sha = out.trim();
+        return sha === "" ? null : sha;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the `version` from a package.json, or "unknown" when the path is null / unreadable / versionless. */
+function resolveToolVersion(packageJsonPath) {
+    if (packageJsonPath === null)
+        return "unknown";
+    try {
+        const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        return typeof pkg.version === "string" && pkg.version !== "" ? pkg.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Walk up from a dir to the nearest package.json, or null when the filesystem root is reached. */
+function findPackageJson(fromDir) {
+    let dir = fromDir;
+    for (;;) {
+        const candidate = join(dir, "package.json");
+        try {
+            readFileSync(candidate, "utf8");
+            return candidate;
+        }
+        catch {
+            const parent = dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+    }
+}
+/**
+ * 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 function resolveTargetRoot(opts) {
+    if (opts.features === undefined || opts.features.trim() === "") {
+        return process.cwd();
+    }
+    const targetDir = dirname(opts.features);
+    try {
+        const out = execFileSync("git", ["-C", targetDir, "rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const root = out.trim();
+        return root === "" ? targetDir : root;
+    }
+    catch {
+        return targetDir;
+    }
+}
+//# sourceMappingURL=resolveRunInputs.js.map

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

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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "spec-controller",
+  "version": "0.1.0-alpha.1",
+  "description": "Reconcile the behaviour your scenarios name against the evidence that actually ran — the deterministic `balance` CLI.",
+  "keywords": [
+    "reconciliation",
+    "gherkin",
+    "bdd",
+    "evidence",
+    "double-entry",
+    "cli"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "spec-controller": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@cucumber/gherkin": "^41.0.0",
+    "@cucumber/messages": "^34.0.1",
+    "yaml": "^2.9.0",
+    "@3f-consulting/spec-controller-core": "0.1.0-alpha.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
+}