@nanobpm/urban 0.63.1 → 0.65.0

package/dist/context/binding/backend.d.ts

@@ -0,0 +1,58 @@
+import type { ContextIdentity } from "./identity.ts";
+/**
+ * A concrete, resolved handle to a context substrate: a local working copy
+ * pinned to `ref`, plus its repo/ref identity. This is the value S3 and S4
+ * build on.
+ */
+export interface ResolvedContextHandle {
+    /** Canonical identity of the bound context (see {@link ContextIdentity}). */
+    readonly identity: ContextIdentity;
+    /** Absolute path to the local working copy of the substrate. */
+    readonly localPath: string;
+    /** The concrete substrate repo URL/path that was cloned. */
+    readonly repo: string;
+    /**
+     * The ref the working copy is pinned to. This records the *intended* pin
+     * (`identity.ref`). It is a re-verified fact only when the working copy was
+     * just cloned or refreshed; on the `refresh: false` reuse path the existing
+     * working copy is trusted as-is and NOT re-pinned, so `ref` reflects the
+     * requested pin rather than a freshly-validated checkout (see
+     * {@link SubstrateResolveOptions.refresh}).
+     */
+    readonly ref: string;
+}
+/** Options passed to a backend when materialising a substrate working copy. */
+export interface SubstrateResolveOptions {
+    /**
+     * Absolute path the working copy MUST live at. The resolver derives this
+     * deterministically from the identity so that the same name maps to the same
+     * on-disk substrate (shared-on-same-name). A backend rejects a relative path
+     * (see {@link SubstrateBackend.materialise}).
+     */
+    readonly localPath: string;
+    /**
+     * When `true`, refresh an already-present working copy (fetch + re-pin to
+     * `ref`). When `false`, an existing working copy is reused as-is without
+     * touching the network AND without running git at all — it is trusted as the
+     * requested substrate; no fetch, pin, or checkout validation is enforced, so
+     * the returned handle's `ref` reflects the intended pin rather than a
+     * re-verified checkout. Defaults to `true`.
+     */
+    readonly refresh?: boolean;
+}
+/**
+ * A pluggable substrate backend. The default is git (see `./git-backend.ts`),
+ * but this interface is the seam for a future PII/mutable or self-hosted
+ * backend — the resolver and its callers depend only on this contract.
+ */
+export interface SubstrateBackend {
+    /**
+     * Materialise (clone on first use, refresh thereafter) the substrate for
+     * `identity` at `options.localPath`, pinned to `identity.ref`, and return the
+     * resolved handle. The pin is enforced on the clone and `refresh: true` paths;
+     * `refresh: false` reuses an existing working copy as-is without re-pinning
+     * (see {@link SubstrateResolveOptions.refresh}). `options.localPath` must be
+     * absolute; a relative path is rejected before any git command runs.
+     */
+    materialise(identity: ContextIdentity, options: SubstrateResolveOptions): Promise<ResolvedContextHandle>;
+}

package/dist/context/binding/backend.js

@@ -0,0 +1,15 @@
+// Slice S1 (binding) — the resolution seam: types shared by the resolver and
+// any substrate backend.
+//
+// Resolution turns a validated binding into a concrete local working copy of
+// the substrate, returning a **resolved handle** (local path + repo/ref
+// identity). Downstream slices consume the handle: S3 (git substrate /
+// governance) writes append-via-commit into `localPath`, and S4 (retrieval)
+// reads from it. S1 owns clone/pull wiring ONLY — it exposes a clean handle and
+// deliberately contains no commit/PR/write or governance logic.
+//
+// The `SubstrateBackend` interface is the seam that keeps resolution from
+// hard-coding "the substrate is exclusively a public git repo": the default
+// backend is git, but a future PII/mutable or self-hosted backend can implement
+// the same interface without touching the resolver or callers.
+export {};

package/dist/context/binding/descriptor.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A declared binding to an Urban **context** resource — the manifest shape
+ * authored under `uses: { context: { repo, ref } }`.
+ *
+ * A context is a git-backed, governed memory substrate (see ADR 0051 — a
+ * context behaves like an Urban datasource: a declared, bindable resource). The
+ * pair `(repo, ref)` is the *name* of the context: two apps that declare the
+ * same pair bind the same shared substrate; a different pair is a different,
+ * private context (see {@link contextIdentityKey} in `./identity.ts`).
+ *
+ * The type is intentionally small and additive-friendly — treat it as a stable
+ * contract. Unknown extra fields on input are tolerated by the validator but
+ * are not part of the guaranteed shape.
+ */
+export interface ContextBinding {
+    /**
+     * The substrate repository that stores the context.
+     *
+     * Accepts an `owner/name` GitHub shorthand (resolved to
+     * `https://github.com/owner/name.git`), a full git URL
+     * (`https://…`, `ssh://…`, `git@host:owner/name.git`), or a local/`file://`
+     * path (used chiefly for tests and self-hosted substrates). A local path must
+     * be spelled unambiguously so it is not mistaken for the `owner/name`
+     * shorthand: use an absolute path, a `file://…` URL, or a `./`- or
+     * `../`-prefixed relative path. A bare relative path such as `subdir/repo`
+     * matches the shorthand and is treated as GitHub, not a local path. The MVP
+     * substrate is git-only, but resolution does not hard-code *public* git — see
+     * the backend seam in `./resolver.ts`.
+     */
+    readonly repo: string;
+    /**
+     * The ref the context is **pinned** to: a branch, tag, or commit SHA. First
+     * resolution clones the substrate; later resolutions refresh it to this ref.
+     */
+    readonly ref: string;
+}
+/** Error thrown when an untrusted value is not a valid {@link ContextBinding}. */
+export declare class ContextBindingError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate an untrusted value as a {@link ContextBinding}, throwing a
+ * {@link ContextBindingError} with a clear, field-scoped message on failure.
+ *
+ * Returns a *normalised* binding: `repo` and `ref` are trimmed. Extra fields on
+ * the input object are ignored (forward-compatible) — only `repo` and `ref` are
+ * carried through.
+ */
+export declare function parseContextBinding(value: unknown): ContextBinding;
+/** Type guard: `true` iff `value` is a valid {@link ContextBinding}. */
+export declare function isContextBinding(value: unknown): value is ContextBinding;

package/dist/context/binding/descriptor.js

@@ -0,0 +1,62 @@
+// Slice S1 (binding) — the binding *descriptor*: the manifest shape
+// `uses: context: { repo, ref }`.
+//
+// This is one half of the published contract that the consumer repo
+// (nanobpm/nano-workforce#291) builds against, so the shape and the exported
+// type name are deliberately **minimal and version-friendly**: a context is
+// named by the substrate `repo` it lives in and the `ref` it is pinned to, and
+// nothing more is required to bind it. Additional, backward-compatible fields
+// may be layered on later without breaking existing manifests.
+/** Error thrown when an untrusted value is not a valid {@link ContextBinding}. */
+export class ContextBindingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ContextBindingError";
+    }
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Validate an untrusted value as a {@link ContextBinding}, throwing a
+ * {@link ContextBindingError} with a clear, field-scoped message on failure.
+ *
+ * Returns a *normalised* binding: `repo` and `ref` are trimmed. Extra fields on
+ * the input object are ignored (forward-compatible) — only `repo` and `ref` are
+ * carried through.
+ */
+export function parseContextBinding(value) {
+    if (!isObjectRecord(value)) {
+        throw new ContextBindingError(`context binding must be an object of the form { repo, ref }, received ${describe(value)}`);
+    }
+    const record = value;
+    if (!("repo" in record) || !isNonEmptyString(record.repo)) {
+        throw new ContextBindingError(`context binding "repo" is required and must be a non-empty string, received ${describe(record.repo)}`);
+    }
+    if (!("ref" in record) || !isNonEmptyString(record.ref)) {
+        throw new ContextBindingError(`context binding "ref" is required and must be a non-empty string, received ${describe(record.ref)}`);
+    }
+    return { repo: record.repo.trim(), ref: record.ref.trim() };
+}
+/** Type guard: `true` iff `value` is a valid {@link ContextBinding}. */
+export function isContextBinding(value) {
+    try {
+        parseContextBinding(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function describe(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}

package/dist/context/binding/git-backend.d.ts

@@ -0,0 +1,65 @@
+import type { ContextIdentity } from "./identity.ts";
+import type { ResolvedContextHandle, SubstrateBackend, SubstrateResolveOptions } from "./backend.ts";
+/** Runs a git subcommand. Injectable so tests can stub git without a network. */
+export type GitRunner = (args: readonly string[], cwd?: string) => Promise<string>;
+/** Error thrown when a git operation fails during resolution. */
+export declare class SubstrateResolveError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Redact URL userinfo (`scheme://user:pass@host` → `scheme://***@host`) from a
+ * single git argv token. A manifest-supplied remote URL can embed credentials
+ * (e.g. `https://x-access-token:TOKEN@github.com/owner/repo`); scrubbing them
+ * before the argv is placed in an error message keeps secrets out of logs,
+ * telemetry, and user-facing errors. The raw, unredacted args stay on the
+ * error's `cause` for local debugging only.
+ */
+export declare const redactUrlUserinfo: (arg: string) => string;
+/**
+ * `git` runs against a working copy that lives in a shared, potentially
+ * tampered-with cache. Commands like `fetch` and especially `checkout` execute
+ * local hooks (e.g. `post-checkout`, `post-merge`) from the working copy's
+ * `.git/hooks` if they exist — so a planted hook in a poisoned cache entry is a
+ * code-execution vector. Pinning `core.hooksPath` to a path that cannot contain
+ * an executable hook (`/dev/null` is not a directory, so `<hooksPath>/<hook>`
+ * never resolves) disables hooks entirely for every automated invocation, so
+ * resolution can never execute a script from the cached substrate. Single
+ * source of truth for the flag: prepended by {@link hardenedGitArgs} to every
+ * argv the default runner spawns. `-c <name>=<value>` must precede the
+ * subcommand, so it is prepended (not appended).
+ */
+export declare const GIT_SAFETY_CONFIG: readonly string[];
+/** Prepend the hook-disabling safety config to a git argv (single source of truth). */
+export declare const hardenedGitArgs: (args: readonly string[]) => string[];
+/**
+ * The default, git-only substrate backend. Clones the substrate on first use
+ * and, on subsequent resolutions, fetches and re-pins the working copy to the
+ * requested ref (branch tip, tag, or SHA) without clobbering unrelated state.
+ */
+export declare class GitSubstrateBackend implements SubstrateBackend {
+    #private;
+    constructor(gitRunner?: GitRunner);
+    /**
+     * Materialise the working copy at `options.localPath`: clone on first use,
+     * fetch + re-pin thereafter. `refresh: false` reuses an already-present
+     * working copy as-is — no fetch, no re-pin, no git invocation — so the
+     * returned handle's `ref` records the intended pin rather than a re-validated
+     * checkout (see {@link SubstrateResolveOptions.refresh}).
+     *
+     * Known limitation (deferred past slice S1): materialisation is NOT guarded by
+     * an inter-process lock. The resolver's single-flight coalescing only
+     * serialises resolves *within one process*, so two Nano instances that share a
+     * `cacheRoot` and resolve the same context concurrently can race the
+     * first-use `mkdir → clone → pin` (or `fetch → pin`) sequence for the same
+     * `localPath` — one process may observe the path as absent or
+     * partially-initialised while the other is still cloning, surfacing a spurious
+     * "not a git working copy" error or (worse) a half-written working copy.
+     * Cross-process sharing is therefore reliable only once the substrate is
+     * already materialised; the concurrent *first-use* case is a documented gap. A
+     * follow-up slice will add a per-`localPath` inter-process lock (bounded retry
+     * + stale-lock reclamation) to close it. See PR #309 / nano-ide binding notes.
+     */
+    materialise(identity: ContextIdentity, options: SubstrateResolveOptions): Promise<ResolvedContextHandle>;
+}

package/dist/context/binding/git-backend.js

@@ -0,0 +1,318 @@
+// Slice S1 (binding) — the default git substrate backend: clone on first use,
+// fetch + re-pin to `ref` thereafter. No write/commit/PR logic lives here (that
+// is S3); this only materialises a working copy pinned to the requested ref.
+import { execFile } from "node:child_process";
+import { lstat, mkdir, readFile, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/** Error thrown when a git operation fails during resolution. */
+export class SubstrateResolveError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "SubstrateResolveError";
+    }
+}
+/**
+ * Redact URL userinfo (`scheme://user:pass@host` → `scheme://***@host`) from a
+ * single git argv token. A manifest-supplied remote URL can embed credentials
+ * (e.g. `https://x-access-token:TOKEN@github.com/owner/repo`); scrubbing them
+ * before the argv is placed in an error message keeps secrets out of logs,
+ * telemetry, and user-facing errors. The raw, unredacted args stay on the
+ * error's `cause` for local debugging only.
+ */
+export const redactUrlUserinfo = (arg) => arg.replace(/(\/\/)[^/@\s]+@/g, "$1***@");
+/**
+ * `git` runs against a working copy that lives in a shared, potentially
+ * tampered-with cache. Commands like `fetch` and especially `checkout` execute
+ * local hooks (e.g. `post-checkout`, `post-merge`) from the working copy's
+ * `.git/hooks` if they exist — so a planted hook in a poisoned cache entry is a
+ * code-execution vector. Pinning `core.hooksPath` to a path that cannot contain
+ * an executable hook (`/dev/null` is not a directory, so `<hooksPath>/<hook>`
+ * never resolves) disables hooks entirely for every automated invocation, so
+ * resolution can never execute a script from the cached substrate. Single
+ * source of truth for the flag: prepended by {@link hardenedGitArgs} to every
+ * argv the default runner spawns. `-c <name>=<value>` must precede the
+ * subcommand, so it is prepended (not appended).
+ */
+export const GIT_SAFETY_CONFIG = ["-c", "core.hooksPath=/dev/null"];
+/** Prepend the hook-disabling safety config to a git argv (single source of truth). */
+export const hardenedGitArgs = (args) => [
+    ...GIT_SAFETY_CONFIG,
+    ...args,
+];
+const defaultGitRunner = async (args, cwd) => {
+    const hardened = hardenedGitArgs(args);
+    try {
+        const { stdout } = await execFileAsync("git", hardened, {
+            cwd,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch (cause) {
+        const label = `git ${hardened.map(redactUrlUserinfo).join(" ")}`;
+        throw new SubstrateResolveError(`substrate git command failed: ${label}`, { cause });
+    }
+};
+/**
+ * True iff `path` exists as any filesystem entry. Uses `lstat` (not `stat`) so
+ * the entry itself is inspected without following symlinks — a symlink counts as
+ * a pre-existing entry even when its target is missing (a dangling symlink),
+ * which `git clone` would otherwise fail on with an opaque error.
+ *
+ * Only a genuine "not there" (`ENOENT`/`ENOTDIR`) counts as absent; any other
+ * error (e.g. `EACCES`/`EPERM` on an existing-but-unreadable entry) is
+ * re-thrown rather than silently reported as "missing", so an unreadable path
+ * is never mistaken for a clean slate to clone into.
+ */
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (cause) {
+        if (isNodeErrno(cause, "ENOENT") || isNodeErrno(cause, "ENOTDIR")) {
+            return false;
+        }
+        throw new SubstrateResolveError(`substrate path is not accessible: ${path}`, { cause });
+    }
+}
+function isNodeErrno(error, code) {
+    return (error instanceof Error && "code" in error && error.code === code);
+}
+/**
+ * True iff `path` exists and is itself a symlink (inspected with `lstat`, so the
+ * link — not its target — is examined). A missing entry (`ENOENT`/`ENOTDIR`) is
+ * not a symlink; any other error is re-thrown rather than silently swallowed.
+ */
+async function isSymlink(path) {
+    try {
+        return (await lstat(path)).isSymbolicLink();
+    }
+    catch (cause) {
+        if (isNodeErrno(cause, "ENOENT") || isNodeErrno(cause, "ENOTDIR")) {
+            return false;
+        }
+        throw new SubstrateResolveError(`substrate path is not accessible: ${path}`, { cause });
+    }
+}
+/**
+ * True iff `path` exists and is a real directory (inspected with `lstat`, so a
+ * symlink to a directory does not count). A missing entry (`ENOENT`/`ENOTDIR`)
+ * is not a directory; any other error is re-thrown rather than silently
+ * swallowed, so an unreadable path is never mistaken for "not a directory".
+ */
+async function isDirectory(path) {
+    try {
+        return (await lstat(path)).isDirectory();
+    }
+    catch (cause) {
+        if (isNodeErrno(cause, "ENOENT") || isNodeErrno(cause, "ENOTDIR")) {
+            return false;
+        }
+        throw new SubstrateResolveError(`substrate path is not accessible: ${path}`, { cause });
+    }
+}
+/** True iff `child` is `root` itself or nested within it (no `..`/absolute escape). */
+function isWithin(root, child) {
+    const rel = relative(root, child);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+/**
+ * A `.git` *file* (git worktree/submodule marker) points at the real gitdir via
+ * a `gitdir: <path>` line rather than being a `.git` directory. Trusting such a
+ * working copy as "already cloned" is only safe when that gitdir stays inside
+ * the cache root: a marker whose `gitdir:` resolves OUTSIDE the cache root would
+ * make every subsequent `git fetch`/`checkout` operate on an out-of-cache
+ * repository — a cache escape of the same class as a `.git` symlink.
+ *
+ * A string-only containment check is insufficient: an in-cache `gitdir:` path
+ * can itself be a *symlink* to an out-of-cache repository (git follows it), and a
+ * broken/missing `gitdir:` target must not be trusted as a clone either. So the
+ * resolved target is canonicalised through `realpath` (collapsing every symlink
+ * along the path — including the gitdir itself) and the cache root is likewise
+ * canonicalised, before checking containment. Resolves when the marker is
+ * well-formed AND its fully-resolved gitdir is a real directory within the
+ * canonical `cacheRoot`. Otherwise it throws a `SubstrateResolveError` whose
+ * message names the *actual* reason — a malformed marker (no `gitdir:` line), a
+ * missing/broken target, one resolving to a non-directory, or one that genuinely
+ * escapes the cache root — rather than collapsing every rejection into a single
+ * "points outside the cache root" message that would mislead incident triage.
+ */
+async function assertGitFileMarkerWithinRoot(gitFile, localPath, cacheRoot) {
+    // Read the marker file through the same error-wrapping discipline as the rest
+    // of this module's access guards: a filesystem failure (e.g. EACCES/EPERM on
+    // an unreadable marker, or a race that removes it) surfaces as a
+    // SubstrateResolveError rather than leaking a raw Node error to the caller.
+    let content;
+    try {
+        content = await readFile(gitFile, "utf8");
+    }
+    catch (cause) {
+        throw new SubstrateResolveError(`substrate .git marker is not readable: ${gitFile}`, { cause });
+    }
+    const match = content.match(/^gitdir:[ \t]*(.+?)[ \t]*$/m);
+    if (match === null) {
+        throw new SubstrateResolveError(`substrate .git marker is malformed (no \`gitdir:\` line): ${gitFile}`);
+    }
+    // A relative `gitdir:` is interpreted by git relative to the working copy, so
+    // resolve it against `localPath` before checking cache-root containment.
+    const target = resolve(localPath, match[1]);
+    // Canonicalise both sides through `realpath` so any symlink along the path —
+    // notably an in-cache `gitdir:` symlinked to an out-of-cache repository that a
+    // string check would wrongly trust — is collapsed before the comparison. A
+    // missing/broken target (ENOENT/ENOTDIR) is not a real gitdir and is rejected.
+    let realTarget;
+    let realRoot;
+    try {
+        realTarget = await realpath(target);
+        realRoot = await realpath(cacheRoot);
+    }
+    catch (cause) {
+        if (isNodeErrno(cause, "ENOENT") || isNodeErrno(cause, "ENOTDIR")) {
+            throw new SubstrateResolveError(`substrate .git gitdir target is missing or broken: ${target}`, { cause });
+        }
+        throw new SubstrateResolveError(`substrate .git target is not accessible: ${target}`, { cause });
+    }
+    if (!isWithin(realRoot, realTarget)) {
+        throw new SubstrateResolveError(`substrate .git points outside the cache root and would escape it: ${gitFile}`);
+    }
+    if (!(await isDirectory(realTarget))) {
+        throw new SubstrateResolveError(`substrate .git gitdir target is not a directory: ${realTarget}`);
+    }
+}
+/**
+ * The default, git-only substrate backend. Clones the substrate on first use
+ * and, on subsequent resolutions, fetches and re-pins the working copy to the
+ * requested ref (branch tip, tag, or SHA) without clobbering unrelated state.
+ */
+export class GitSubstrateBackend {
+    #git;
+    constructor(gitRunner = defaultGitRunner) {
+        this.#git = gitRunner;
+    }
+    /**
+     * Materialise the working copy at `options.localPath`: clone on first use,
+     * fetch + re-pin thereafter. `refresh: false` reuses an already-present
+     * working copy as-is — no fetch, no re-pin, no git invocation — so the
+     * returned handle's `ref` records the intended pin rather than a re-validated
+     * checkout (see {@link SubstrateResolveOptions.refresh}).
+     *
+     * Known limitation (deferred past slice S1): materialisation is NOT guarded by
+     * an inter-process lock. The resolver's single-flight coalescing only
+     * serialises resolves *within one process*, so two Nano instances that share a
+     * `cacheRoot` and resolve the same context concurrently can race the
+     * first-use `mkdir → clone → pin` (or `fetch → pin`) sequence for the same
+     * `localPath` — one process may observe the path as absent or
+     * partially-initialised while the other is still cloning, surfacing a spurious
+     * "not a git working copy" error or (worse) a half-written working copy.
+     * Cross-process sharing is therefore reliable only once the substrate is
+     * already materialised; the concurrent *first-use* case is a documented gap. A
+     * follow-up slice will add a per-`localPath` inter-process lock (bounded retry
+     * + stale-lock reclamation) to close it. See PR #309 / nano-ide binding notes.
+     */
+    async materialise(identity, options) {
+        const { localPath } = options;
+        const refresh = options.refresh ?? true;
+        // `SubstrateResolveOptions.localPath` is contractually absolute — the resolver
+        // derives it that way. Enforce it here too: a relative `localPath` from a
+        // direct backend caller would run clone/fetch/checkout relative to the process
+        // CWD, at an unpredictable location that also sidesteps the cache-root
+        // containment guards below. Reject it before any git command runs.
+        if (!isAbsolute(localPath)) {
+            throw new SubstrateResolveError(`substrate localPath must be absolute: ${localPath}`);
+        }
+        // A symlink AT `localPath` would make every subsequent `join(localPath, …)`
+        // and git invocation operate on the link's target — which can point outside
+        // the cache root at an arbitrary pre-existing working copy. Reject it before
+        // it is ever trusted as a clone, so resolution can never escape the cache
+        // root via a planted symlink.
+        if (await isSymlink(localPath)) {
+            throw new SubstrateResolveError(`substrate path is a symlink and would escape the cache root: ${localPath}`);
+        }
+        // Likewise, a `.git` symlink *inside* an otherwise-legitimate `localPath`
+        // would make git treat an arbitrary out-of-cache gitdir as this working
+        // copy's repository (cache escape). A real clone never has a symlinked
+        // `.git`, so reject one before it is trusted as "already cloned".
+        const gitDir = join(localPath, ".git");
+        if (await isSymlink(gitDir)) {
+            throw new SubstrateResolveError(`substrate .git is a symlink and would escape the cache root: ${gitDir}`);
+        }
+        // A genuine clone's `.git` is a *directory*. A `.git` that exists as
+        // anything else is a git worktree/submodule marker *file* pointing at a real
+        // gitdir elsewhere, which must be validated before it is trusted — an
+        // out-of-cache gitdir would be a cache escape of the same class as the
+        // `.git`-symlink case above.
+        let alreadyCloned = await isDirectory(gitDir);
+        if (!alreadyCloned && (await pathExists(gitDir))) {
+            // `.git` exists but is not a directory: a git worktree/submodule marker
+            // *file* pointing at a real gitdir elsewhere. Trust it as "already cloned"
+            // only when that gitdir is well-formed and stays inside the cache root;
+            // otherwise this throws a precise error naming the actual reason (malformed
+            // marker, missing/broken target, non-directory, or genuine cache escape).
+            await assertGitFileMarkerWithinRoot(gitDir, localPath, dirname(localPath));
+            alreadyCloned = true;
+        }
+        if (!alreadyCloned) {
+            // A pre-existing entry at `localPath` that is not a git working copy — a
+            // non-git directory, or a file/symlink — would make `git clone` fail with
+            // an opaque wrapped error. Detect any such entry and report it clearly.
+            if (await pathExists(localPath)) {
+                throw new SubstrateResolveError(`substrate path already exists but is not a git working copy: ${localPath}`);
+            }
+            await mkdir(dirname(localPath), { recursive: true });
+            // `--` separates options from operands so a `repo` starting with `-`
+            // (untrusted manifest input) can't be parsed as a git option.
+            await this.#git(["clone", "--", identity.repo, localPath]);
+            await this.#pin(localPath, identity.ref);
+        }
+        else if (refresh) {
+            // Cache reuse must NOT trust the recorded `origin`: an equivalent repo
+            // spelling with different auth (e.g. SSH vs HTTPS/token) won't take effect
+            // once the entry exists, and a tampered cache entry could point `origin`
+            // at an attacker-chosen remote that the resolver would then fetch from.
+            // Re-point `origin` at the manifest's `identity.repo` before every fetch
+            // so refreshes always operate on the expected remote. `--` separates
+            // options from the operand so a `repo` starting with `-` (untrusted
+            // manifest input) can't be parsed as a git option.
+            await this.#git(["remote", "set-url", "origin", "--", identity.repo], localPath);
+            await this.#git(["fetch", "--tags", "--prune", "--force", "origin"], localPath);
+            await this.#pin(localPath, identity.ref);
+        }
+        // On the `alreadyCloned && !refresh` path neither branch above ran, so the
+        // existing working copy is returned untouched (no fetch/pin). `ref` here is
+        // therefore the *requested* pin, not a re-verified checkout — the documented
+        // `refresh: false` contract (trust the existing working copy as-is).
+        return { identity, localPath, repo: identity.repo, ref: identity.ref };
+    }
+    /**
+     * Pin the working copy to `ref`. If `ref` names a remote branch, pin to the
+     * fetched remote tip (so a refresh moves the branch forward); otherwise treat
+     * `ref` as a tag or SHA and check it out detached.
+     */
+    async #pin(cwd, ref) {
+        const remoteBranch = await this.#hasRef(cwd, `origin/${ref}`);
+        if (remoteBranch) {
+            await this.#git(["checkout", "--force", "-B", ref, `origin/${ref}`], cwd);
+        }
+        else {
+            // `--detach` pins to the exact commit rather than attaching to any local
+            // branch that happens to share `ref`'s name; `--end-of-options` stops an
+            // option-style `ref` from being parsed as a git flag.
+            await this.#git(["checkout", "--force", "--detach", "--end-of-options", ref], cwd);
+        }
+    }
+    async #hasRef(cwd, ref) {
+        try {
+            // `--end-of-options` stops an option-style `ref` (manifest-controlled)
+            // from being parsed as a git flag — the same injection guard used by the
+            // `clone`/`checkout` paths.
+            await this.#git(["rev-parse", "--verify", "--quiet", "--end-of-options", `${ref}^{commit}`], cwd);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/context/binding/identity.d.ts

@@ -0,0 +1,42 @@
+import type { ContextBinding } from "./descriptor.ts";
+/**
+ * The resolved, canonical identity of a context binding.
+ *
+ * `key` is a stable, collision-resistant string: two bindings share a substrate
+ * **iff** their `key`s are equal. `repo` is the concrete clone URL derived from
+ * the binding's (possibly shorthand) `repo`, and `ref` is the pinned ref.
+ */
+export interface ContextIdentity {
+    /**
+     * Stable canonical identity key. Equal keys ⇒ same shared substrate; distinct
+     * keys ⇒ private substrates. Safe to use as a map key.
+     */
+    readonly key: string;
+    /** The concrete clone URL (or local/`file://` path) for the substrate. */
+    readonly repo: string;
+    /** The pinned ref (branch / tag / SHA). */
+    readonly ref: string;
+    /**
+     * Filesystem-safe directory name derived deterministically from {@link key}.
+     * Two identities with the same key yield the same directory name, so a shared
+     * cache root gives them the same on-disk working copy.
+     */
+    readonly slug: string;
+}
+/**
+ * Compute the canonical {@link ContextIdentity} for a binding. Deterministic and
+ * pure: equal `(repo, ref)` names (after normalisation) always produce an equal
+ * `key` and `slug`. Distinct names are collision-resistant, not collision-proof:
+ * both `key` and `slug` are sha256-derived, so two distinct names collide only on
+ * a full sha256 collision (the `slug` embeds the whole `key`, so it is exactly as
+ * strong as the `key`).
+ */
+export declare function resolveContextIdentity(binding: ContextBinding): ContextIdentity;
+/**
+ * The stable identity key of a binding — the sharing primitive. Two bindings
+ * resolve to the same shared substrate iff this returns the same value for
+ * both.
+ */
+export declare function contextIdentityKey(binding: ContextBinding): string;
+/** `true` iff two bindings name the same shared context (same substrate). */
+export declare function sameContext(a: ContextBinding, b: ContextBinding): boolean;