@adammcarter/use-cases 0.1.0

package/packages/core/dist/markers/appendOnly.js

@@ -0,0 +1,75 @@
+// Append-only discipline check for JSONL ledgers (spec amendment 2; 4.3 rules
+// 9/10). The core `appendOnly` is pure and line-based: the old content must be an
+// unchanged PREFIX of the new content. Any edit, delete, or reorder of an
+// existing line is a violation. The only impure piece is the thin git helper that
+// reads the base-ref version of a file via `git show <base-ref>:<path>`.
+import { execFileSync } from "node:child_process";
+// Pure append-only check: oldLines must equal the leading prefix of newLines.
+export function appendOnly(oldLines, newLines) {
+    for (let i = 0; i < oldLines.length; i += 1) {
+        if (i >= newLines.length) {
+            return {
+                ok: false,
+                violation: {
+                    kind: "deleted",
+                    index: i,
+                    old_line: oldLines[i],
+                    new_line: null,
+                    message: `existing line ${i + 1} was deleted; the registry is append-only`
+                }
+            };
+        }
+        if (newLines[i] !== oldLines[i]) {
+            return {
+                ok: false,
+                violation: {
+                    kind: "edited",
+                    index: i,
+                    old_line: oldLines[i],
+                    new_line: newLines[i],
+                    message: `existing line ${i + 1} was edited or reordered; the registry is append-only`
+                }
+            };
+        }
+    }
+    return { ok: true };
+}
+// Split JSONL text into content lines, dropping a single trailing newline's empty
+// segment. Interior blank lines are preserved so a blank-line edit is not hidden.
+export function splitJsonlLines(text) {
+    if (text === "") {
+        return [];
+    }
+    const lines = text.split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    return lines;
+}
+const defaultRunner = (args, cwd) => execFileSync("git", args, { cwd, encoding: "utf8" });
+// Patterns git emits when a path does not exist at the given ref. Treated as
+// "old content is empty" (a brand-new file added on this branch).
+const ABSENT_AT_BASE = /does not exist in|exists on disk, but not in/i;
+// Read the base-ref version of a file (`git show <base-ref>:<path>`). Returns ""
+// when the path does not exist at the base ref (a newly added file). Any other
+// git failure is rethrown with context. Thin and impure by design.
+export function readBaseRefFile(baseRef, path, options = {}) {
+    const runner = options.runner ?? defaultRunner;
+    try {
+        return runner(["show", `${baseRef}:${path}`], options.cwd);
+    }
+    catch (error) {
+        const stderr = String(error.stderr ?? error.message ?? "");
+        if (ABSENT_AT_BASE.test(stderr)) {
+            return "";
+        }
+        throw new Error(`git show ${baseRef}:${path} failed: ${stderr.trim() || "unknown error"}`);
+    }
+}
+// Convenience: check current JSONL text against its base-ref version, splitting
+// both into lines first.
+export function appendOnlyAgainstBaseRef(baseRef, path, currentText, options = {}) {
+    const oldText = readBaseRefFile(baseRef, path, options);
+    return appendOnly(splitJsonlLines(oldText), splitJsonlLines(currentText));
+}
+//# sourceMappingURL=appendOnly.js.map

package/packages/core/dist/markers/appendOnly.js.map

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

package/packages/core/dist/markers/bindingSetHash.d.ts

@@ -0,0 +1,28 @@
+import { BINDING_SET_HASH_ID } from "./constants.js";
+export interface BindingSetInputMember {
+    binding_slug: string;
+    row_id: string;
+    file_path: string;
+    extent_kind: string;
+    recognizer_id: string;
+    span_canon_id: string;
+    span_sha256: string;
+    [key: string]: unknown;
+}
+export interface BindingSetMaterialMember {
+    binding_slug: string;
+    row_id: string;
+    file_path: string;
+    extent_kind: string;
+    recognizer_id: string;
+    span_canon_id: string;
+    span_sha256: string;
+}
+export interface BindingSetMaterial {
+    schema: typeof BINDING_SET_HASH_ID;
+    row_id: string;
+    bindings: BindingSetMaterialMember[];
+}
+export declare function buildBindingSetMaterial(rowId: string, bindings: ReadonlyArray<BindingSetInputMember>): BindingSetMaterial;
+export declare function computeBindingSetHash(rowId: string, bindings: ReadonlyArray<BindingSetInputMember>): string;
+//# sourceMappingURL=bindingSetHash.d.ts.map

package/packages/core/dist/markers/bindingSetHash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindingSetHash.d.ts","sourceRoot":"","sources":["../../src/markers/bindingSetHash.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAKrD,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAGD,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,mBAAmB,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,wBAAwB,EAAE,CAAC;CACtC;AAQD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,aAAa,CAAC,qBAAqB,CAAC,GAC7C,kBAAkB,CAqBpB;AAGD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,aAAa,CAAC,qBAAqB,CAAC,GAC7C,MAAM,CAER"}

package/packages/core/dist/markers/bindingSetHash.js

@@ -0,0 +1,33 @@
+import { canonicalJsonSha256 } from "./canonicalJson.js";
+import { BINDING_SET_HASH_ID } from "./constants.js";
+// Build the canonical binding-set material for a row.
+//
+// Included: binding_slug, row_id, file_path, extent_kind, recognizer_id,
+// span_canon_id, span_sha256 (spec 4.5 rules 2-6).
+// Excluded: line numbers, timestamps, proof status, marker text (rules 7-10).
+// Bindings are sorted by binding_slug before hashing (rule 1).
+export function buildBindingSetMaterial(rowId, bindings) {
+    const sorted = [...bindings].sort((left, right) => left.binding_slug < right.binding_slug
+        ? -1
+        : left.binding_slug > right.binding_slug
+            ? 1
+            : 0);
+    return {
+        schema: BINDING_SET_HASH_ID,
+        row_id: rowId,
+        bindings: sorted.map((binding) => ({
+            binding_slug: binding.binding_slug,
+            row_id: binding.row_id,
+            file_path: binding.file_path,
+            extent_kind: binding.extent_kind,
+            recognizer_id: binding.recognizer_id,
+            span_canon_id: binding.span_canon_id,
+            span_sha256: binding.span_sha256
+        }))
+    };
+}
+// binding_set_hash = sha256(canonical_json(binding_set_material)).
+export function computeBindingSetHash(rowId, bindings) {
+    return canonicalJsonSha256(buildBindingSetMaterial(rowId, bindings));
+}
+//# sourceMappingURL=bindingSetHash.js.map

package/packages/core/dist/markers/bindingSetHash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindingSetHash.js","sourceRoot":"","sources":["../../src/markers/bindingSetHash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAiCrD,sDAAsD;AACtD,EAAE;AACF,yEAAyE;AACzE,mDAAmD;AACnD,8EAA8E;AAC9E,+DAA+D;AAC/D,MAAM,UAAU,uBAAuB,CACrC,KAAa,EACb,QAA8C;IAE9C,MAAM,MAAM,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAChD,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY;QACpC,CAAC,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY;YACtC,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,CAAC,CACR,CAAC;IACF,OAAO;QACL,MAAM,EAAE,mBAAmB;QAC3B,MAAM,EAAE,KAAK;QACb,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACjC,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,qBAAqB,CACnC,KAAa,EACb,QAA8C;IAE9C,OAAO,mBAAmB,CAAC,uBAAuB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;AACvE,CAAC"}

package/packages/core/dist/markers/canonicalJson.d.ts

@@ -0,0 +1,4 @@
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256(input: string | Uint8Array): string;
+export declare function canonicalJsonSha256(value: unknown): string;
+//# sourceMappingURL=canonicalJson.d.ts.map

package/packages/core/dist/markers/canonicalJson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalJson.d.ts","sourceRoot":"","sources":["../../src/markers/canonicalJson.ts"],"names":[],"mappings":"AAUA,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAkCD,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAEzD;AAGD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE1D"}

package/packages/core/dist/markers/canonicalJson.js

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+// Deterministic JSON canonicalization for hashing.
+//
+// Rules:
+//   - object keys sorted by UTF-16 code unit (stable across hosts)
+//   - array order is preserved exactly as given (the caller decides ordering)
+//   - keys whose value is `undefined` are dropped (JSON has no undefined)
+//   - no insignificant whitespace
+//   - non-finite numbers are rejected (they cannot round-trip through JSON)
+export function canonicalJson(value) {
+    return serialize(value);
+}
+function serialize(value) {
+    if (value === null) {
+        return "null";
+    }
+    const type = typeof value;
+    if (type === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("canonical_json: non-finite numbers are not serializable");
+        }
+        return JSON.stringify(value);
+    }
+    if (type === "boolean" || type === "string") {
+        return JSON.stringify(value);
+    }
+    if (type === "bigint") {
+        throw new Error("canonical_json: bigint is not serializable");
+    }
+    if (type !== "object") {
+        throw new Error(`canonical_json: unsupported value type: ${type}`);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => serialize(item)).join(",")}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    return `{${entries
+        .map(([key, item]) => `${JSON.stringify(key)}:${serialize(item)}`)
+        .join(",")}}`;
+}
+// sha256 of UTF-8 string bytes or raw bytes, returned as "sha256:<hex>".
+export function sha256(input) {
+    return `sha256:${createHash("sha256").update(input).digest("hex")}`;
+}
+// Convenience: canonicalize a value then hash it.
+export function canonicalJsonSha256(value) {
+    return sha256(canonicalJson(value));
+}
+//# sourceMappingURL=canonicalJson.js.map

package/packages/core/dist/markers/canonicalJson.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalJson.js","sourceRoot":"","sources":["../../src/markers/canonicalJson.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,mDAAmD;AACnD,EAAE;AACF,SAAS;AACT,mEAAmE;AACnE,8EAA8E;AAC9E,0EAA0E;AAC1E,kCAAkC;AAClC,4EAA4E;AAC5E,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC;IAC1B,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAe,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;QAC7E,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,2CAA2C,IAAI,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAC/D,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;SAC7D,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC;SACxC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,IAAI,OAAO;SACf,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;SACjE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,MAAM,CAAC,KAA0B;IAC/C,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACtE,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;AACtC,CAAC"}

package/packages/core/dist/markers/ciAuthority.d.ts

@@ -0,0 +1,17 @@
+export interface CiAuthority {
+    type: "ci" | "local";
+    provider: "github-actions" | "gitlab-ci" | "circleci" | "generic";
+    repository?: string;
+    ref?: string;
+    commit?: string;
+    run_id?: string;
+    actor?: string;
+    protected_ref?: boolean | null;
+    event?: string;
+}
+export type CiEnv = Readonly<Record<string, string | undefined>>;
+export interface DetectCiAuthorityOptions {
+    protectedRef?: boolean | null;
+}
+export declare function detectCiAuthority(env: CiEnv, options?: DetectCiAuthorityOptions): CiAuthority;
+//# sourceMappingURL=ciAuthority.d.ts.map

package/packages/core/dist/markers/ciAuthority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ciAuthority.d.ts","sourceRoot":"","sources":["../../src/markers/ciAuthority.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;IACrB,QAAQ,EAAE,gBAAgB,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAGD,MAAM,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEjE,MAAM,WAAW,wBAAwB;IAIvC,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B;AAkED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,GAAE,wBAA6B,GAAG,WAAW,CAsDjG"}

package/packages/core/dist/markers/ciAuthority.js

@@ -0,0 +1,131 @@
+// CI-neutral provenance authority detection (public-v1, Phase 2).
+//
+// The trust model is CI-NEUTRAL: GitHub Actions is only the reference provider.
+// `detectCiAuthority` reads a provider-agnostic `CiAuthority` record off a CI
+// environment map — recognising GitHub Actions, GitLab CI, and CircleCI — and
+// falls back to a `local` / `generic` record when no CI is present.
+//
+// It is PURE: the environment is passed in (never read from process.env here),
+// so callers (the `prove` CLI) own the impurity and tests stay deterministic.
+//
+// The record is OPTIONAL and ADDITIVE on a proof event: it does not influence
+// freshness (FRESH matches row/binding/context hashes, not provenance). When the
+// `prove` command embeds it, it is built INTO the event before signing, so the
+// signature covers it. The shape mirrors schemas/v1/authority.schema.json.
+// A non-empty trimmed string, or undefined. Used to omit absent optional fields.
+function str(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+// Parse a provider's boolean-ish protected-branch signal into the tri-state:
+// "true" -> true, "false" -> false, anything else (incl. absent) -> null.
+function triBool(value) {
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    return null;
+}
+// Assemble a record, dropping optional fields whose value is undefined so the
+// emitted authority block carries only fields that are actually present.
+function build(record) {
+    const out = { type: record.type, provider: record.provider };
+    if (record.repository !== undefined)
+        out.repository = record.repository;
+    if (record.ref !== undefined)
+        out.ref = record.ref;
+    if (record.commit !== undefined)
+        out.commit = record.commit;
+    if (record.run_id !== undefined)
+        out.run_id = record.run_id;
+    if (record.actor !== undefined)
+        out.actor = record.actor;
+    if (record.protected_ref !== undefined)
+        out.protected_ref = record.protected_ref;
+    if (record.event !== undefined)
+        out.event = record.event;
+    return out;
+}
+// Is this a GitHub Actions environment? GITHUB_ACTIONS is set to "true" on every
+// runner; we also accept its mere presence defensively.
+function isGitHubActions(env) {
+    return env.GITHUB_ACTIONS !== undefined && env.GITHUB_ACTIONS !== "";
+}
+function isGitLabCi(env) {
+    return env.GITLAB_CI !== undefined && env.GITLAB_CI !== "";
+}
+function isCircleCi(env) {
+    return env.CIRCLECI !== undefined && env.CIRCLECI !== "";
+}
+// Detect the CI-neutral provenance authority from an environment map.
+//
+//   - GitHub Actions (GITHUB_ACTIONS): repository/ref/commit/run_id/actor/event
+//     from GITHUB_REPOSITORY/GITHUB_REF/GITHUB_SHA/GITHUB_RUN_ID/GITHUB_ACTOR/
+//     GITHUB_EVENT_NAME. protected_ref is unknowable from the runner env, so it
+//     is null unless an explicit override is supplied.
+//   - GitLab CI (GITLAB_CI): CI_PROJECT_PATH/CI_COMMIT_REF_NAME/CI_COMMIT_SHA/
+//     CI_PIPELINE_ID/GITLAB_USER_LOGIN, event from CI_PIPELINE_SOURCE.
+//     protected_ref reads GitLab's explicit CI_COMMIT_REF_PROTECTED signal.
+//   - CircleCI (CIRCLECI): CIRCLE_PROJECT_USERNAME/CIRCLE_PROJECT_REPONAME ->
+//     "owner/repo", CIRCLE_BRANCH/CIRCLE_SHA1/CIRCLE_BUILD_NUM/CIRCLE_USERNAME.
+//     protected_ref is null (no signal).
+//   - otherwise -> { type: "local", provider: "generic" }.
+//
+// `options.protectedRef`, when provided, overrides the detected tri-state.
+export function detectCiAuthority(env, options = {}) {
+    const overrideProtected = Object.prototype.hasOwnProperty.call(options, "protectedRef");
+    if (isGitHubActions(env)) {
+        return build({
+            type: "ci",
+            provider: "github-actions",
+            repository: str(env.GITHUB_REPOSITORY),
+            ref: str(env.GITHUB_REF),
+            commit: str(env.GITHUB_SHA),
+            run_id: str(env.GITHUB_RUN_ID),
+            actor: str(env.GITHUB_ACTOR),
+            protected_ref: overrideProtected ? options.protectedRef : null,
+            event: str(env.GITHUB_EVENT_NAME)
+        });
+    }
+    if (isGitLabCi(env)) {
+        return build({
+            type: "ci",
+            provider: "gitlab-ci",
+            repository: str(env.CI_PROJECT_PATH),
+            ref: str(env.CI_COMMIT_REF_NAME),
+            commit: str(env.CI_COMMIT_SHA),
+            run_id: str(env.CI_PIPELINE_ID),
+            actor: str(env.GITLAB_USER_LOGIN),
+            protected_ref: overrideProtected
+                ? options.protectedRef
+                : triBool(env.CI_COMMIT_REF_PROTECTED),
+            event: str(env.CI_PIPELINE_SOURCE)
+        });
+    }
+    if (isCircleCi(env)) {
+        const owner = str(env.CIRCLE_PROJECT_USERNAME);
+        const repo = str(env.CIRCLE_PROJECT_REPONAME);
+        const repository = owner && repo ? `${owner}/${repo}` : (repo ?? owner);
+        return build({
+            type: "ci",
+            provider: "circleci",
+            repository,
+            ref: str(env.CIRCLE_BRANCH),
+            commit: str(env.CIRCLE_SHA1),
+            run_id: str(env.CIRCLE_BUILD_NUM),
+            actor: str(env.CIRCLE_USERNAME),
+            protected_ref: overrideProtected ? options.protectedRef : null
+        });
+    }
+    return build({
+        type: "local",
+        provider: "generic",
+        protected_ref: overrideProtected ? options.protectedRef : undefined
+    });
+}
+//# sourceMappingURL=ciAuthority.js.map

package/packages/core/dist/markers/ciAuthority.js.map

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

package/packages/core/dist/markers/cli/bind.d.ts

@@ -0,0 +1,48 @@
+import type { ResolvedWorkspaceContext } from "../../roots.js";
+import { type CommentPrefixConfig } from "../commentPrefix.js";
+import { type CurrentBindingRecord } from "../scanner.js";
+import { type MarkerFs } from "./io.js";
+export type BindMode = "explicit" | "swift-func";
+export interface BindCommandOptions {
+    context: ResolvedWorkspaceContext;
+    productRoot: string;
+    bindingsPath: string;
+    rowId: string;
+    suffix?: string;
+    file: string;
+    mode: BindMode;
+    line?: number;
+    startLine?: number;
+    endLine?: number;
+    commentPrefix?: string;
+    registerExisting?: boolean;
+    dryRun?: boolean;
+    clock: () => string;
+    idFactory: () => string;
+    version?: string;
+    fs?: MarkerFs;
+    commentConfig?: CommentPrefixConfig;
+}
+export interface BindCommandError {
+    code: string;
+    message: string;
+}
+export interface BindCommandResult {
+    exit_code: number;
+    ok: boolean;
+    command: "bind";
+    row_id: string;
+    binding_slug: string;
+    file_path: string;
+    mode: BindMode;
+    registry_event_appended: boolean;
+    scan_result?: {
+        extent_kind: CurrentBindingRecord["extent_kind"];
+        span_start_line: number;
+        span_end_line: number;
+        span_sha256: string;
+    };
+    errors: BindCommandError[];
+}
+export declare function runBindCommand(options: BindCommandOptions): BindCommandResult;
+//# sourceMappingURL=bind.d.ts.map

package/packages/core/dist/markers/cli/bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../../../src/markers/cli/bind.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAiC,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGvE,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC;AAEjD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,wBAAwB,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IAGf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,aAAa,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,QAAQ,CAAC;IACf,uBAAuB,EAAE,OAAO,CAAC;IACjC,WAAW,CAAC,EAAE;QACZ,WAAW,EAAE,oBAAoB,CAAC,aAAa,CAAC,CAAC;QACjD,eAAe,EAAE,MAAM,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAgBD,wBAAgB,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,CA+I7E"}

package/packages/core/dist/markers/cli/bind.js

@@ -0,0 +1,198 @@
+import { resolveCommentPrefix } from "../commentPrefix.js";
+import { BINDING_REGISTRY_SCHEMA_ID } from "../constants.js";
+import { UCM_VERSION } from "../../version.js";
+import { isValidSlug } from "../markerLine.js";
+import { validateBindingsJsonl } from "../registry.js";
+import { scanFileForMarkers } from "../scanner.js";
+import { appendJsonlLine, nodeMarkerFs } from "./io.js";
+import { findRow, loadMarkerRows, resolveUnderRoot, toPosix } from "./shared.js";
+function fail(base, exitCode, error) {
+    return {
+        ...base,
+        exit_code: exitCode,
+        ok: false,
+        registry_event_appended: false,
+        errors: [error]
+    };
+}
+export function runBindCommand(options) {
+    const fs = options.fs ?? nodeMarkerFs;
+    const bindingSlug = options.suffix ? `${options.rowId}#${options.suffix}` : options.rowId;
+    const relFile = toPosix(options.file);
+    const base = {
+        command: "bind",
+        row_id: options.rowId,
+        binding_slug: bindingSlug,
+        file_path: relFile,
+        mode: options.mode
+    };
+    // 1. Slug grammar (identity only; spec 1.3).
+    if (!isValidSlug(bindingSlug)) {
+        return fail(base, 3, {
+            code: "MALFORMED_MARKER",
+            message: `binding slug ${bindingSlug} is not a valid use-case slug`
+        });
+    }
+    // 2. Row must exist.
+    const loaded = loadMarkerRows(options.context);
+    if (!findRow(loaded.rows, options.rowId)) {
+        return fail(base, 2, {
+            code: "ROW_NOT_FOUND",
+            message: `row ${options.rowId} is not a known use-case row`
+        });
+    }
+    // 3. Read the source first so the comment prefix can be resolved from a
+    //    shebang for extensionless scripts, then resolve the prefix.
+    const absFile = resolveUnderRoot(options.productRoot, options.file);
+    const current = fs.readText(absFile);
+    if (current === null) {
+        return fail(base, 2, {
+            code: "FILE_NOT_FOUND",
+            message: `source file ${relFile} does not exist`
+        });
+    }
+    const commentPrefix = options.commentPrefix ?? resolveCommentPrefix(relFile, options.commentConfig, current);
+    if (commentPrefix === null || commentPrefix === undefined) {
+        return fail(base, 2, {
+            code: "NO_COMMENT_PREFIX",
+            message: `no comment prefix is configured for ${relFile}; pass --comment-prefix`
+        });
+    }
+    // 4. Registry pre-checks (append-only log must already be valid).
+    const bindingsText = fs.readText(options.bindingsPath) ?? "";
+    const registryValidation = validateBindingsJsonl(bindingsText, loaded.rowIds);
+    if (!registryValidation.ok) {
+        return fail(base, 4, {
+            code: "REGISTRY_INVALID",
+            message: `binding registry is not valid: ${registryValidation.errors
+                .map((error) => error.message)
+                .join("; ")}`
+        });
+    }
+    if (registryValidation.registry.slugToRow.has(bindingSlug)) {
+        return fail(base, 4, {
+            code: "DUPLICATE_REGISTRATION",
+            message: `binding slug ${bindingSlug} is already registered`
+        });
+    }
+    // 5. Compute the new source (or use existing for --register-existing).
+    //    `current`/`absFile` were read above so the prefix could honour a shebang.
+    let nextContents;
+    if (options.registerExisting) {
+        nextContents = current;
+    }
+    else {
+        const edit = insertMarker(current, commentPrefix, bindingSlug, options);
+        if ("error" in edit) {
+            return fail(base, 2, edit.error);
+        }
+        nextContents = edit.contents;
+    }
+    // 6. Validate the resulting marker by scanning the affected file (spec 8.1
+    // steps 7/8). Fail closed: any error tied to this slug, or no matching binding,
+    // aborts WITHOUT writing source or appending to the registry.
+    const scan = scanFileForMarkers(relFile, nextContents, { config: options.commentConfig });
+    const matching = scan.bindings.find((binding) => binding.binding_slug === bindingSlug);
+    const slugError = scan.errors.find((error) => error.slug === bindingSlug);
+    if (slugError || !matching) {
+        return fail(base, 3, {
+            code: slugError ? slugError.code : "MARKER_NOT_RESOLVED",
+            message: slugError
+                ? slugError.message
+                : `the placed marker for ${bindingSlug} did not resolve to a valid span`
+        });
+    }
+    const scanResult = {
+        extent_kind: matching.extent_kind,
+        span_start_line: matching.span.start_line,
+        span_end_line: matching.span.end_line,
+        span_sha256: matching.span.sha256
+    };
+    if (options.dryRun) {
+        return {
+            ...base,
+            exit_code: 0,
+            ok: true,
+            registry_event_appended: false,
+            scan_result: scanResult,
+            errors: []
+        };
+    }
+    // 7. Transactional commit: write source first (if edited), THEN append the
+    // registry event (spec 8.1 transactional rule).
+    if (!options.registerExisting) {
+        // Preserve the source file's existing permission bits: rewriting a bound
+        // shell script / hook must not drop its executable bit (100755 -> 100644).
+        fs.writeText(absFile, nextContents, { preserveMode: true });
+    }
+    const event = {
+        schema: BINDING_REGISTRY_SCHEMA_ID,
+        event_type: "binding_registered",
+        event_id: options.idFactory(),
+        created_at: options.clock(),
+        created_by: {
+            tool: "use-cases",
+            command: "bind",
+            version: options.version ?? UCM_VERSION
+        },
+        row_id: options.rowId,
+        binding_slug: bindingSlug,
+        reason: options.registerExisting ? "register_existing" : "initial_bind"
+    };
+    appendJsonlLine(fs, options.bindingsPath, JSON.stringify(event));
+    return {
+        ...base,
+        exit_code: 0,
+        ok: true,
+        registry_event_appended: true,
+        scan_result: scanResult,
+        errors: []
+    };
+}
+function insertMarker(source, commentPrefix, slug, options) {
+    const { lines, terminator } = splitKeepingTerminator(source);
+    const marker = `${commentPrefix}: @use-case: ${slug}`;
+    if (options.mode === "swift-func") {
+        if (options.line === undefined || options.line < 1) {
+            return { error: { code: "BIND_LINE_REQUIRED", message: "--line is required for swift-func bind" } };
+        }
+        const insertAt = options.line - 1;
+        if (insertAt > lines.length) {
+            return { error: { code: "BIND_LINE_OUT_OF_RANGE", message: `--line ${options.line} is past end of file` } };
+        }
+        lines.splice(insertAt, 0, marker);
+        return { contents: joinWithTerminator(lines, terminator) };
+    }
+    // explicit
+    if (options.startLine === undefined || options.endLine === undefined) {
+        return { error: { code: "BIND_SPAN_REQUIRED", message: "--start-line and --end-line are required for explicit bind" } };
+    }
+    if (options.startLine < 1 || options.endLine < options.startLine || options.endLine > lines.length) {
+        return {
+            error: {
+                code: "BIND_SPAN_OUT_OF_RANGE",
+                message: `explicit span ${options.startLine}-${options.endLine} is out of range`
+            }
+        };
+    }
+    const endMarker = `${commentPrefix}: @use-case: end ${slug}`;
+    // Insert end first (higher index) so the start insertion does not shift it.
+    lines.splice(options.endLine, 0, endMarker);
+    lines.splice(options.startLine - 1, 0, marker);
+    return { contents: joinWithTerminator(lines, terminator) };
+}
+// Split into logical lines, remembering whether the file ended with a newline so
+// a marker insertion does not silently add/remove the trailing terminator.
+function splitKeepingTerminator(source) {
+    if (source === "") {
+        return { lines: [], terminator: false };
+    }
+    const terminator = source.endsWith("\n");
+    const body = terminator ? source.slice(0, -1) : source;
+    return { lines: body.split("\n"), terminator };
+}
+function joinWithTerminator(lines, terminator) {
+    const joined = lines.join("\n");
+    return terminator ? `${joined}\n` : joined;
+}
+//# sourceMappingURL=bind.js.map

package/packages/core/dist/markers/cli/bind.js.map

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