@nanobpm/urban 0.64.0 → 0.65.0

package/dist/context/binding/identity.js

@@ -0,0 +1,159 @@
+// Slice S1 (binding) — context *identity*: the private-per-app /
+// shared-on-same-name semantics.
+//
+// A context is named by its `(repo, ref)` pair. Two apps (or two Nano
+// instances) that name the SAME context — the same normalised repo and the same
+// ref — resolve to the SAME shared substrate; a distinct name stays private.
+// This module turns a binding into a stable, canonical **identity key** that
+// the resolver uses both to memoise in-process and to derive an on-disk
+// location, so "same name ⇒ same substrate" holds within a process AND across
+// processes/instances that share a cache root.
+import { createHash } from "node:crypto";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+const SHORTHAND = /^[\w.-]+\/[\w.-]+$/;
+const SCHEME_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+const SCP_LIKE = /^[\w.-]+@([\w.-]+):(.+)$/; // git@github.com:owner/name.git
+function stripGitSuffix(value) {
+    // Trim trailing slashes BEFORE stripping `.git` so a trailing-slash spelling
+    // (`owner/name.git/`, a URL pathname ending `.git/`) still has its `.git`
+    // suffix removed — otherwise `.git$` would not match and equivalent repo
+    // spellings would canonicalise to different identities (different substrates).
+    // Trim once more afterwards to drop any slash exposed by removing the suffix.
+    return value.replace(/\/+$/, "").replace(/\.git$/i, "").replace(/\/+$/, "");
+}
+// A URL's scheme-default port is equivalent to omitting the port, so it must not
+// split identity. `URL` already strips the default port for the web schemes it
+// knows (http/https/ws/…), but NOT for git transports like ssh:// and git://, so
+// their defaults are normalised here explicitly.
+const DEFAULT_PORTS = {
+    "http:": "80",
+    "https:": "443",
+    "ssh:": "22",
+    "git:": "9418",
+    "ftp:": "21",
+};
+/**
+ * The canonical authority (`host` or `host:port`) for a scheme URL identity.
+ * Excludes any `user:pass@` userinfo (uses `hostname`, never `host`) so
+ * credentials never affect identity, and drops a scheme's DEFAULT port while
+ * retaining any NON-default port as a distinguishing factor.
+ */
+function canonicalAuthority(parsed) {
+    const host = parsed.hostname.toLowerCase();
+    const defaultPort = DEFAULT_PORTS[parsed.protocol.toLowerCase()];
+    if (parsed.port && parsed.port !== defaultPort) {
+        return `${host}:${parsed.port}`;
+    }
+    return host;
+}
+/**
+ * Resolve a `file://` URL to an absolute filesystem path, honouring the host
+ * component and percent-encoding. Falls back to naive `file://` stripping for a
+ * malformed URL so identity stays stable rather than throwing.
+ */
+function fileUrlToAbsPath(raw) {
+    try {
+        return resolvePath(fileURLToPath(raw));
+    }
+    catch {
+        return resolvePath(raw.slice("file://".length));
+    }
+}
+/**
+ * Classify a binding `repo` field into a concrete clone URL plus a normalised
+ * canonical form for identity. Public git is NOT hard-coded: local/`file://`
+ * paths and arbitrary git hosts are first-class, leaving a seam for a future
+ * PII/mutable or self-hosted substrate backend.
+ */
+function classifyRepo(repo) {
+    const raw = repo.trim();
+    // Local filesystem path or file:// URL — used for tests and self-hosted
+    // substrates. Canonicalised by absolute path so two spellings of one path
+    // share identity. `file://` URLs are parsed via `fileURLToPath` so the host
+    // component (e.g. `file://localhost/…`) and percent-encoding are handled and
+    // equivalent spellings map to one identity.
+    if (raw.startsWith("file://")) {
+        const abs = fileUrlToAbsPath(raw);
+        return { url: raw, canonical: `file:${abs}` };
+    }
+    if (raw.startsWith(".") || isAbsolute(raw)) {
+        const abs = resolvePath(raw);
+        return { url: abs, canonical: `file:${abs}` };
+    }
+    // owner/name shorthand ⇒ GitHub HTTPS clone URL.
+    if (SHORTHAND.test(raw)) {
+        const canonical = `github.com/${stripGitSuffix(raw).toLowerCase()}`;
+        return { url: `https://github.com/${stripGitSuffix(raw)}.git`, canonical };
+    }
+    // scp-like git URL: git@host:owner/name(.git)
+    const scp = SCP_LIKE.exec(raw);
+    if (scp) {
+        const host = scp[1].toLowerCase();
+        const path = stripGitSuffix(scp[2]).toLowerCase();
+        return { url: raw, canonical: `${host}/${path}` };
+    }
+    // scheme URL: https://, ssh://, git://, http://
+    if (SCHEME_URL.test(raw)) {
+        try {
+            const parsed = new URL(raw);
+            // Build the authority from `hostname` (never `host`) so any `user:pass@`
+            // userinfo is excluded — credentials never affect identity. The port is
+            // *normalised*, not dropped: a scheme's DEFAULT port collapses to the
+            // portless spelling (so `https://h:443/o/n` ≡ `https://h/o/n` and
+            // `ssh://h:22/o/n` ≡ `ssh://h/o/n`), but a NON-default port is retained as
+            // a distinguishing factor — two remotes on the same host but different
+            // ports are genuinely different repos and MUST NOT share a substrate.
+            const host = canonicalAuthority(parsed);
+            const path = stripGitSuffix(parsed.pathname).replace(/^\/+/, "").toLowerCase();
+            return { url: raw, canonical: `${host}/${path}` };
+        }
+        catch {
+            // Fall through to the opaque case below.
+        }
+    }
+    // Anything else: treat opaquely but still stable.
+    return { url: raw, canonical: stripGitSuffix(raw).toLowerCase() };
+}
+function toSlug(canonical, ref, hash) {
+    const readable = `${canonical}@${ref}`
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+    // Suffix with the FULL identity key (sha256 hex), not a truncated prefix: the
+    // on-disk location is derived from the slug, so a truncated suffix would make
+    // two distinct keys collide onto one `localPath` (breaking "distinct names
+    // stay private") far sooner than the key itself collides. Deriving the suffix
+    // from the whole key keeps on-disk uniqueness exactly as strong as the
+    // in-process sharing key — a single source of truth, distinct keys ⇒ distinct
+    // slugs.
+    return `${readable || "context"}-${hash}`;
+}
+/**
+ * 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 function resolveContextIdentity(binding) {
+    const { url, canonical } = classifyRepo(binding.repo);
+    const ref = binding.ref.trim();
+    const canonicalName = `${canonical}#${ref}`;
+    const key = createHash("sha256").update(canonicalName, "utf8").digest("hex");
+    return { key, repo: url, ref, slug: toSlug(canonical, ref, key) };
+}
+/**
+ * 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 function contextIdentityKey(binding) {
+    return resolveContextIdentity(binding).key;
+}
+/** `true` iff two bindings name the same shared context (same substrate). */
+export function sameContext(a, b) {
+    return contextIdentityKey(a) === contextIdentityKey(b);
+}

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

@@ -1 +1,5 @@
-export {};
+export { type ContextBinding, ContextBindingError, isContextBinding, parseContextBinding, } from "./descriptor.ts";
+export { type ContextIdentity, contextIdentityKey, resolveContextIdentity, sameContext, } from "./identity.ts";
+export { type ResolvedContextHandle, type SubstrateBackend, type SubstrateResolveOptions, } from "./backend.ts";
+export { GitSubstrateBackend, type GitRunner, GIT_SAFETY_CONFIG, hardenedGitArgs, SubstrateResolveError, } from "./git-backend.ts";
+export { ContextResolver, type ContextResolverOptions, type ResolveOptions, defaultContextCacheRoot, resolveContextBinding, } from "./resolver.ts";

package/dist/context/binding/index.js

@@ -1 +1,14 @@
-export {};
+// @nanobpm/urban/context/binding — slice S1.
+//
+// The bindable `context` resource: the binding descriptor (`uses: context:
+// { repo, ref }`) plus local↔remote resolution to a resolved handle, with
+// private-per-app / shared-on-same-name identity semantics. This is one half of
+// the published contract nanobpm/nano-workforce#291 builds against.
+//
+// Downstream: S3 (git substrate/governance) and S4 (retrieval) consume the
+// ResolvedContextHandle; the SubstrateBackend interface is the seam for a
+// future PII/mutable or self-hosted backend.
+export { ContextBindingError, isContextBinding, parseContextBinding, } from "./descriptor.js";
+export { contextIdentityKey, resolveContextIdentity, sameContext, } from "./identity.js";
+export { GitSubstrateBackend, GIT_SAFETY_CONFIG, hardenedGitArgs, SubstrateResolveError, } from "./git-backend.js";
+export { ContextResolver, defaultContextCacheRoot, resolveContextBinding, } from "./resolver.js";

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

@@ -0,0 +1,61 @@
+import type { ResolvedContextHandle, SubstrateBackend } from "./backend.ts";
+/** Options for a {@link ContextResolver}. */
+export interface ContextResolverOptions {
+    /**
+     * Root directory under which per-context working copies are cloned. Two
+     * resolvers sharing a `cacheRoot` share substrates on disk. Defaults to
+     * {@link defaultContextCacheRoot}.
+     */
+    readonly cacheRoot?: string;
+    /**
+     * The substrate backend. Defaults to a git backend ({@link GitSubstrateBackend}).
+     * Injecting a different backend is the seam for a future PII/mutable or
+     * self-hosted substrate.
+     */
+    readonly backend?: SubstrateBackend;
+}
+/** Per-resolution overrides. */
+export interface ResolveOptions {
+    /**
+     * Controls whether a re-resolution re-fetches the substrate. Note the
+     * {@link ContextResolver} memoises per identity: once an identity has resolved,
+     * repeat resolves return the cached handle and do **not** re-fetch unless you
+     * explicitly pass `refresh: true`, which forces a fresh materialisation (a
+     * fetch + re-pin on the backend). While a materialisation is still in flight,
+     * concurrent resolves — including `refresh: true` — coalesce onto it rather
+     * than starting a second one. The backend's own default (fetch on an existing
+     * clone) therefore only applies the first time an identity is materialised or
+     * when `refresh: true` is passed. Defaults to `undefined` (reuse the memoised
+     * handle).
+     */
+    readonly refresh?: boolean;
+}
+/**
+ * The default cache root for context working copies. Honours
+ * `URBAN_CONTEXT_CACHE_DIR`, then `XDG_CACHE_HOME`, then `~/.cache`, falling
+ * back to the OS temp dir when no home directory is available.
+ */
+export declare function defaultContextCacheRoot(env?: Record<string, string | undefined>): string;
+/**
+ * Resolves context bindings to concrete local working copies. A single resolver
+ * instance enforces shared-on-same-name in-process by memoising per identity
+ * key; distinct names stay private.
+ */
+export declare class ContextResolver {
+    #private;
+    constructor(options?: ContextResolverOptions);
+    /** The cache root this resolver clones into. */
+    get cacheRoot(): string;
+    /**
+     * Resolve a binding (validated first) to a {@link ResolvedContextHandle}. Two
+     * bindings that name the same context return the identical handle from this
+     * resolver; distinct names return distinct handles.
+     */
+    resolve(binding: unknown, options?: ResolveOptions): Promise<ResolvedContextHandle>;
+}
+/**
+ * One-shot convenience: resolve a single binding with a fresh resolver. Prefer a
+ * long-lived {@link ContextResolver} when resolving many bindings so sharing is
+ * memoised across calls.
+ */
+export declare function resolveContextBinding(binding: unknown, options?: ContextResolverOptions & ResolveOptions): Promise<ResolvedContextHandle>;

package/dist/context/binding/resolver.js

@@ -0,0 +1,125 @@
+// Slice S1 (binding) — the resolver: bind → validate → identity → resolved
+// handle, with private-per-app / shared-on-same-name semantics enforced two
+// ways:
+//
+//  1. In-process: a ContextResolver memoises by identity key, so two resolves of
+//     the same name return the SAME handle (and never double-clone), while
+//     distinct names get distinct handles.
+//  2. Across processes/instances: the on-disk location is derived
+//     deterministically from the identity slug under a shared cache root, so two
+//     Nano instances naming the same context share one working copy on disk.
+//     Known first-use limitation (deferred past slice S1): the single-flight in
+//     (1) is in-process only, so concurrent *first* resolves of the same context
+//     across instances can race materialisation (clone/pin). Sharing is reliable
+//     once the substrate exists; a follow-up slice adds an inter-process lock to
+//     make concurrent first-use safe too — see GitSubstrateBackend.materialise.
+import { homedir, tmpdir } from "node:os";
+import { join, resolve as resolvePath } from "node:path";
+import { parseContextBinding } from "./descriptor.js";
+import { resolveContextIdentity } from "./identity.js";
+import { GitSubstrateBackend } from "./git-backend.js";
+/**
+ * The default cache root for context working copies. Honours
+ * `URBAN_CONTEXT_CACHE_DIR`, then `XDG_CACHE_HOME`, then `~/.cache`, falling
+ * back to the OS temp dir when no home directory is available.
+ */
+export function defaultContextCacheRoot(env = process.env) {
+    if (env.URBAN_CONTEXT_CACHE_DIR)
+        return env.URBAN_CONTEXT_CACHE_DIR;
+    if (env.XDG_CACHE_HOME)
+        return join(env.XDG_CACHE_HOME, "urban", "context");
+    const home = safeHomedir();
+    if (home)
+        return join(home, ".cache", "urban", "context");
+    return join(tmpdir(), "urban", "context");
+}
+/** `os.homedir()`, but tolerant: returns `undefined` if the home dir can't be
+ * determined (Node can throw here) so callers fall back to the temp dir. */
+function safeHomedir() {
+    try {
+        return homedir() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolves context bindings to concrete local working copies. A single resolver
+ * instance enforces shared-on-same-name in-process by memoising per identity
+ * key; distinct names stay private.
+ */
+export class ContextResolver {
+    #cacheRoot;
+    #backend;
+    // Per-identity resolution record. Despite serving the single-flight guarantee,
+    // this map is NOT purged once a resolution settles: the settled record is
+    // retained as the long-lived memoisation cache backing shared-on-same-name, so
+    // repeat resolves return the identical handle. Entries are removed only on
+    // rejection (so a failed materialise can be retried); a fulfilled entry lives
+    // for the resolver's lifetime. Do not add "drop settled entries" cleanup here
+    // without also giving up memoisation.
+    #resolutions = new Map();
+    constructor(options = {}) {
+        // Normalise to an absolute path so a relative `cacheRoot` (or a relative
+        // `URBAN_CONTEXT_CACHE_DIR`) still yields an absolute `localPath`, honouring
+        // `SubstrateResolveOptions.localPath` ("Absolute path…"). Note this resolves
+        // a relative `cacheRoot` against *this* process's CWD, so the cross-process
+        // sharing promised in the module header only holds for an ABSOLUTE
+        // `cacheRoot`; a relative one is shared only among instances that happen to
+        // share a working directory.
+        this.#cacheRoot = resolvePath(options.cacheRoot ?? defaultContextCacheRoot());
+        this.#backend = options.backend ?? new GitSubstrateBackend();
+    }
+    /** The cache root this resolver clones into. */
+    get cacheRoot() {
+        return this.#cacheRoot;
+    }
+    /**
+     * Resolve a binding (validated first) to a {@link ResolvedContextHandle}. Two
+     * bindings that name the same context return the identical handle from this
+     * resolver; distinct names return distinct handles.
+     */
+    async resolve(binding, options = {}) {
+        const parsed = parseContextBinding(binding);
+        const identity = resolveContextIdentity(parsed);
+        const localPath = join(this.#cacheRoot, identity.slug);
+        // Shared-on-same-name: concurrent or repeated resolves of one identity share
+        // a single materialisation. Coalesce onto an in-flight one regardless of
+        // `refresh` — it is already producing a fresh working copy, so starting a
+        // second `materialise()` would double-clone into the same `localPath` and
+        // break the single-in-flight guarantee. Only re-materialise once the prior
+        // resolution has settled AND the caller explicitly asked to `refresh`.
+        const existing = this.#resolutions.get(identity.key);
+        if (existing && (!existing.settled || options.refresh !== true)) {
+            return existing.promise;
+        }
+        const record = {
+            promise: this.#backend
+                .materialise(identity, { localPath, refresh: options.refresh })
+                .catch((error) => {
+                if (this.#resolutions.get(identity.key) === record) {
+                    this.#resolutions.delete(identity.key);
+                }
+                throw error;
+            }),
+            settled: false,
+        };
+        this.#resolutions.set(identity.key, record);
+        record.promise.then(() => {
+            record.settled = true;
+        }, () => {
+            // Rejection is surfaced to the caller via the returned promise; the map
+            // entry is already removed in the catch above.
+        });
+        return record.promise;
+    }
+}
+/**
+ * One-shot convenience: resolve a single binding with a fresh resolver. Prefer a
+ * long-lived {@link ContextResolver} when resolving many bindings so sharing is
+ * memoised across calls.
+ */
+export function resolveContextBinding(binding, options = {}) {
+    const { cacheRoot, backend, ...resolveOptions } = options;
+    return new ContextResolver({ cacheRoot, backend }).resolve(binding, resolveOptions);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.64.0",
+	"version": "0.65.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/context/binding/backend.ts

@@ -0,0 +1,79 @@
+// 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.
+
+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/src/context/binding/descriptor.test.ts

@@ -0,0 +1,51 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  ContextBindingError,
+  isContextBinding,
+  parseContextBinding,
+} from "./descriptor.ts";
+
+test("parseContextBinding accepts a well-formed { repo, ref } and trims", () => {
+  const binding = parseContextBinding({ repo: "  owner/name  ", ref: "  main  " });
+  assert.deepEqual(binding, { repo: "owner/name", ref: "main" });
+});
+
+test("parseContextBinding ignores unknown extra fields (forward-compatible)", () => {
+  const binding = parseContextBinding({ repo: "owner/name", ref: "v1", future: 42 });
+  assert.deepEqual(binding, { repo: "owner/name", ref: "v1" });
+});
+
+test("parseContextBinding rejects non-objects with a clear message", () => {
+  assert.throws(() => parseContextBinding(null), ContextBindingError);
+  assert.throws(() => parseContextBinding("owner/name#main"), /must be an object/);
+  assert.throws(() => parseContextBinding(undefined), ContextBindingError);
+});
+
+test("parseContextBinding rejects arrays as not-an-object (typeof [] === 'object')", () => {
+  assert.throws(() => parseContextBinding([]), /must be an object/);
+  assert.throws(() => parseContextBinding(["owner/name", "main"]), /must be an object/);
+  assert.equal(isContextBinding([]), false);
+});
+
+test("parseContextBinding names arrays as 'array', not 'object', in the error message", () => {
+  assert.throws(() => parseContextBinding([]), /received array/);
+  assert.throws(() => parseContextBinding(["owner/name", "main"]), /received array/);
+});
+
+test("parseContextBinding rejects a missing or empty repo", () => {
+  assert.throws(() => parseContextBinding({ ref: "main" }), /"repo" is required/);
+  assert.throws(() => parseContextBinding({ repo: "   ", ref: "main" }), /"repo" is required/);
+  assert.throws(() => parseContextBinding({ repo: 5, ref: "main" }), /"repo" is required/);
+});
+
+test("parseContextBinding rejects a missing or empty ref", () => {
+  assert.throws(() => parseContextBinding({ repo: "owner/name" }), /"ref" is required/);
+  assert.throws(() => parseContextBinding({ repo: "owner/name", ref: "" }), /"ref" is required/);
+});
+
+test("isContextBinding is a total type guard", () => {
+  assert.equal(isContextBinding({ repo: "owner/name", ref: "main" }), true);
+  assert.equal(isContextBinding({ repo: "owner/name" }), false);
+  assert.equal(isContextBinding(42), false);
+});

package/src/context/binding/descriptor.ts

@@ -0,0 +1,108 @@
+// 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.
+
+/**
+ * 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 class ContextBindingError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ContextBindingError";
+  }
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  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: unknown): ContextBinding {
+  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: unknown): value is ContextBinding {
+  try {
+    parseContextBinding(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function describe(value: unknown): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}