@eir-labs/coltrane 0.10.0 → 0.12.0

package/dist/src/worker_env.d.ts

@@ -0,0 +1,79 @@
+/** Which host a value addresses — or "none" when it names no host at all. */
+export type EnvHost = "service" | "store" | "none";
+/** What kind of thing it is. A url is the only role that MUST name a host. */
+export type EnvRole = "url" | "credential" | "identity" | "tuning";
+/** When a worker must have it. "venue"/"player" are the two credential modes (Gap 4). */
+export type EnvRequired = "always" | "venue" | "player" | "conditional" | "never";
+/**
+ * The answer to "which credential mode is this worker in", carrying what the answer needs so a call
+ * site consumes it instead of re-reading the environment and re-deciding (Gap 4). `why` is the
+ * refusal text, single-sourced: the CLI prints exactly this string.
+ */
+export type WorkerCredentialMode = {
+    mode: "venue";
+    drainKey: string;
+    instance: string;
+} | {
+    mode: "player";
+    agentToken: string;
+} | {
+    mode: "none";
+    why: string;
+};
+export interface WorkerEnvVar {
+    name: string;
+    host: EnvHost;
+    role: EnvRole;
+    required: EnvRequired;
+    /** one sentence: what it means and, for a url, WHICH host it names. */
+    meaning: string;
+    /** names tolerated for compatibility and normalized onto `name`. */
+    legacy_names?: readonly string[];
+}
+/**
+ * THE ENUMERATED TABLE. Every environment variable the worker path reads appears here exactly once,
+ * as a `name` or as one entry's `legacy_names`. Exactly one always-required url names each host
+ * (store, service); no name is listed twice; no legacy alias is also someone's canonical name.
+ */
+export declare const WORKER_ENV_CONTRACT: readonly WorkerEnvVar[];
+/**
+ * Normalize a worker environment onto its canonical shape — it NORMALIZES, it never appends.
+ *
+ *   * strips a legacy `/rest/v1` path suffix from the service url rather than building on top of it;
+ *   * maps the legacy name (`COLTRANE_DRAIN_URL`) onto the canonical `COLTRANE_SERVICE_URL`;
+ *   * treats the hosting provider's app name (`FLY_APP_NAME`) as a legacy alias of `COLTRANE_INSTANCE`;
+ *   * is IDEMPOTENT — applying it to its own output changes nothing.
+ *
+ * The legacy keys are dropped from the output: a normalized environment carries only canonical
+ * names, which is what makes re-application a no-op.
+ */
+export declare function normalizeWorkerEnv(env: Record<string, string | undefined>): Record<string, string>;
+/**
+ * Which credential mode a worker is in — the SINGLE derivation of it (Gap 4). Both the CLI door and
+ * the claim path ask this one function instead of each recomputing `drainKey && instance`; the
+ * answer carries the fields the answer needs, so no call site re-reads the environment to fill them
+ * in, and its refusal (`why`) is the refusal the CLI prints. It is the only place that decides.
+ *
+ * Reads the RAW environment for the same reason `assertWorkerEnv` does: the instance may arrive
+ * under the legacy `FLY_APP_NAME` alias, and normalizing first would drop that alias, so a
+ * venue-key-without-instance could no longer be told apart from a properly named venue.
+ *
+ * Precedence, and the reasons:
+ *   * A drain key present makes this a venue box. With an instance it is venue mode; WITHOUT one it
+ *     REFUSES — even when a player token is sitting right there. A half-configured venue that quietly
+ *     ran as a player would claim a different set of gigs under a different identity, and the operator
+ *     would see a queue that merely looked empty. Venue therefore wins over player, and its own
+ *     misconfiguration is a refusal, not a downgrade.
+ *   * A player token alone is player mode.
+ *   * Neither credential is a refusal that names BOTH doors, because either one would work.
+ */
+export declare function workerCredentialMode(env: Record<string, string | undefined>): WorkerCredentialMode;
+/**
+ * Refuse a misconfigured worker at STARTUP, naming the offending variable in the error — never
+ * silently picking a winner, and never learning it from a status code at the first write.
+ *
+ * Reads the RAW environment. The legacy-alias contradiction check in particular must NOT normalize
+ * first: normalizing collapses `COLTRANE_DRAIN_URL` onto `COLTRANE_SERVICE_URL`, leaving nothing to
+ * contradict — so the check would pass on exactly the environment it exists to refuse.
+ */
+export declare function assertWorkerEnv(env: Record<string, string | undefined>): void;

package/dist/src/worker_env.js

@@ -0,0 +1,322 @@
+// The worker environment contract, written down in ONE place — the fix for Gap 3 of
+// SPEC-worker-contract.md.
+//
+// ONE VARIABLE, THREE READERS, TWO MEANINGS. `COLTRANE_DRAIN_URL` was read by callers that did not
+// agree on what host it named — two treated it as the database's PostgREST base, one as the
+// Coltrane service origin. Pointed at the database, rows wrote and the artifact 401'd forever;
+// repointed at the service, provisioning broke against a 307. Every fix moved the failure because
+// the variable had never named one thing.
+//
+// This module pins the general form of the fix rather than that instance of it:
+//   * one variable names one host; two hosts are two variables (`WORKER_ENV_CONTRACT`);
+//   * `COLTRANE_SERVICE_URL` is canonical and `COLTRANE_DRAIN_URL` survives only as a normalized
+//     legacy alias — a role name is not a host name, which is how one variable came to hold both;
+//   * a legacy shape NORMALIZES, never appends (`normalizeWorkerEnv`) — appending is what produced
+//     `/rest/v1/rest/v1`;
+//   * a misconfigured worker refuses at STARTUP in its own voice (`assertWorkerEnv`), rather than
+//     learning it is pointed at the wrong host from a status code at its first write.
+//
+// The contract enumerates every variable the worker path reads. `tests/spec_worker_environment.test.ts`
+// scans the real source of the WORKER_PATH files and fails if any `process.env["…"]` read is absent
+// from this table — so the table is a declaration the code is held to, not a comment. This file
+// therefore reads NO environment itself; its three functions take the environment as an argument.
+/**
+ * THE ENUMERATED TABLE. Every environment variable the worker path reads appears here exactly once,
+ * as a `name` or as one entry's `legacy_names`. Exactly one always-required url names each host
+ * (store, service); no name is listed twice; no legacy alias is also someone's canonical name.
+ */
+export const WORKER_ENV_CONTRACT = [
+    {
+        name: "COLTRANE_STORE_URL",
+        host: "store",
+        role: "url",
+        required: "always",
+        meaning: "The PostgREST base URL of the store — the database host that persists gigs, outputs and ledger rows and that the claim path reads directly.",
+    },
+    {
+        name: "COLTRANE_STORE_ANON",
+        host: "none",
+        role: "credential",
+        required: "always",
+        meaning: "The store's public anon API key, presented to the store on the claim path as its `apikey`; it is not a write credential.",
+    },
+    {
+        name: "COLTRANE_SERVICE_URL",
+        host: "service",
+        role: "url",
+        required: "always",
+        meaning: "The origin of the Coltrane service that brokers drain writes and boot-time provisioning — names the service host, and never the managed database.",
+        legacy_names: ["COLTRANE_DRAIN_URL"],
+    },
+    {
+        name: "COLTRANE_DRAIN_KEY",
+        host: "none",
+        role: "credential",
+        required: "venue",
+        meaning: "The venue's org-scoped `cdk_` drain credential authorizing output writes through the service on behalf of the whole instance.",
+    },
+    {
+        name: "COLTRANE_AGENT_TOKEN",
+        host: "none",
+        role: "credential",
+        required: "player",
+        meaning: "A single agent's own `ctk_` bearer token, identifying the player to the store in player mode instead of a shared venue key.",
+    },
+    {
+        name: "COLTRANE_INSTANCE",
+        host: "none",
+        role: "identity",
+        required: "conditional",
+        meaning: "The name this worker box answers to, stamped on every drain write so the store can gate the write against a live lease; absent for an unleased local run.",
+        legacy_names: ["FLY_APP_NAME"],
+    },
+    {
+        name: "COLTRANE_DRAIN_PG",
+        host: "none",
+        role: "credential",
+        required: "never",
+        meaning: "Legacy direct-Postgres connection string for the drain — a fallback sink reached only when no service drain key is configured.",
+    },
+    {
+        name: "COLTRANE_DRAIN_BUCKET",
+        host: "none",
+        role: "tuning",
+        required: "never",
+        meaning: "Name of the storage bucket that drain artifacts are written into; defaults to `coltrane-artifacts` when unset.",
+    },
+    {
+        name: "COLTRANE_DRAIN_OPENING",
+        host: "none",
+        role: "tuning",
+        required: "never",
+        meaning: "Milliseconds the drain waits for a gig's opening header before proceeding; tunes drain startup latency.",
+    },
+    {
+        name: "COLTRANE_MIRROR_DIR",
+        host: "none",
+        role: "tuning",
+        required: "never",
+        meaning: "Local directory the output mirror writes a copy of every sealed artifact into for offline inspection.",
+    },
+    {
+        name: "COLTRANE_GIT_CREDENTIALS_URL",
+        host: "none",
+        role: "tuning",
+        required: "never",
+        meaning: "Endpoint the worker asks for a short-lived git credential when cloning a lease's repository; unset outside a leased drain.",
+    },
+    {
+        name: "COLTRANE_MODEL",
+        host: "none",
+        role: "tuning",
+        required: "never",
+        meaning: "Overrides the model version a chair invokes and is recorded on outputs as the model that produced them.",
+    },
+    {
+        name: "COLTRANE_CHAIR_TIMEOUT_MS",
+        host: "none",
+        role: "tuning",
+        required: "never",
+        meaning: "Per-chair wall-clock timeout in milliseconds before a running chair invocation is abandoned.",
+    },
+    {
+        name: "COLTRANE_GIG_TIMEOUT_MS",
+        host: "none",
+        role: "tuning",
+        required: "never",
+        meaning: "Overall wall-clock timeout in milliseconds for a single gig before the worker abandons it.",
+    },
+    {
+        name: "COLTRANE_WORKER_CHECKPOINTS",
+        host: "none",
+        role: "tuning",
+        required: "never",
+        meaning: "Overrides the worker's checkpoint cadence, controlling how often in-progress run state is persisted to disk.",
+    },
+    {
+        name: "COLTRANE_WORKER_STATE_TTL_DAYS",
+        host: "none",
+        role: "tuning",
+        required: "never",
+        meaning: "Days a worker retains persisted run state before it is considered stale and eligible for pruning.",
+    },
+    {
+        name: "COLTRANE_TOOL_PROVIDERS",
+        host: "none",
+        role: "tuning",
+        required: "never",
+        meaning: "Comma-separated list of tool providers the worker is permitted to load, narrowing the tool surface a chair may reach.",
+    },
+];
+/** The canonical service-url entry — the one host the legacy `COLTRANE_DRAIN_URL` normalizes onto. */
+const SERVICE_URL = "COLTRANE_SERVICE_URL";
+/** The canonical store-url entry — the database host, which must never be the same as the service. */
+const STORE_URL = "COLTRANE_STORE_URL";
+/** The legacy role-name that once held both meanings; now a normalized alias of the service url. */
+const DRAIN_URL = "COLTRANE_DRAIN_URL";
+/** The managed database's host shape. A service url naming this is the defect in its purest form. */
+const MANAGED_DB_HOST = /(^|\.)supabase\.(co|in|net)$/i;
+/** Parseable as an http(s) URL — the shape a `role: "url"` variable must have. */
+function isHttpUrl(value) {
+    try {
+        const u = new URL(value);
+        return u.protocol === "http:" || u.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/** The host a url addresses, or "" when it does not parse — for comparing two urls' hosts. */
+function urlHost(value) {
+    try {
+        return new URL(value).host.toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Strip the legacy `/rest/v1` suffix an origin may carry from when it named a database. Mirrors
+ * `src/output_mirror.ts:317-320`: build from the ORIGIN, so a suffix that survives a redeploy can
+ * never be appended-to and produce `/rest/v1/rest/v1`.
+ */
+function serviceOrigin(value) {
+    return value.replace(/\/+$/, "").replace(/\/rest\/v1$/, "");
+}
+/**
+ * Normalize a worker environment onto its canonical shape — it NORMALIZES, it never appends.
+ *
+ *   * strips a legacy `/rest/v1` path suffix from the service url rather than building on top of it;
+ *   * maps the legacy name (`COLTRANE_DRAIN_URL`) onto the canonical `COLTRANE_SERVICE_URL`;
+ *   * treats the hosting provider's app name (`FLY_APP_NAME`) as a legacy alias of `COLTRANE_INSTANCE`;
+ *   * is IDEMPOTENT — applying it to its own output changes nothing.
+ *
+ * The legacy keys are dropped from the output: a normalized environment carries only canonical
+ * names, which is what makes re-application a no-op.
+ */
+export function normalizeWorkerEnv(env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    // A legacy name fills the canonical one only when the canonical is not already set, then is
+    // dropped — mapping, not appending.
+    const legacyService = out[DRAIN_URL];
+    if (legacyService !== undefined && out[SERVICE_URL] === undefined) {
+        out[SERVICE_URL] = legacyService;
+    }
+    delete out[DRAIN_URL];
+    const legacyInstance = out["FLY_APP_NAME"];
+    if (legacyInstance !== undefined && out["COLTRANE_INSTANCE"] === undefined) {
+        out["COLTRANE_INSTANCE"] = legacyInstance;
+    }
+    delete out["FLY_APP_NAME"];
+    const service = out[SERVICE_URL];
+    if (service !== undefined) {
+        out[SERVICE_URL] = serviceOrigin(service);
+    }
+    return out;
+}
+/**
+ * Which credential mode a worker is in — the SINGLE derivation of it (Gap 4). Both the CLI door and
+ * the claim path ask this one function instead of each recomputing `drainKey && instance`; the
+ * answer carries the fields the answer needs, so no call site re-reads the environment to fill them
+ * in, and its refusal (`why`) is the refusal the CLI prints. It is the only place that decides.
+ *
+ * Reads the RAW environment for the same reason `assertWorkerEnv` does: the instance may arrive
+ * under the legacy `FLY_APP_NAME` alias, and normalizing first would drop that alias, so a
+ * venue-key-without-instance could no longer be told apart from a properly named venue.
+ *
+ * Precedence, and the reasons:
+ *   * A drain key present makes this a venue box. With an instance it is venue mode; WITHOUT one it
+ *     REFUSES — even when a player token is sitting right there. A half-configured venue that quietly
+ *     ran as a player would claim a different set of gigs under a different identity, and the operator
+ *     would see a queue that merely looked empty. Venue therefore wins over player, and its own
+ *     misconfiguration is a refusal, not a downgrade.
+ *   * A player token alone is player mode.
+ *   * Neither credential is a refusal that names BOTH doors, because either one would work.
+ */
+export function workerCredentialMode(env) {
+    const drainKey = env["COLTRANE_DRAIN_KEY"];
+    const agentToken = env["COLTRANE_AGENT_TOKEN"];
+    const instance = env["COLTRANE_INSTANCE"] ?? env["FLY_APP_NAME"];
+    if (drainKey) {
+        if (instance)
+            return { mode: "venue", drainKey, instance };
+        return {
+            mode: "none",
+            why: "COLTRANE_DRAIN_KEY is set but no instance is named — the key is bound to one venue and the " +
+                "store cannot tell which. Set COLTRANE_INSTANCE (or FLY_APP_NAME) so the drain key can be presented.",
+        };
+    }
+    if (agentToken)
+        return { mode: "player", agentToken };
+    return {
+        mode: "none",
+        why: "work needs a credential: EITHER a venue drain key (COLTRANE_DRAIN_KEY with COLTRANE_INSTANCE " +
+            "or FLY_APP_NAME) OR a player token (COLTRANE_AGENT_TOKEN). A drain should hold the venue " +
+            "credential: it claims any gig dispatched to its org and runs each as that gig's own acting_for.",
+    };
+}
+/**
+ * Refuse a misconfigured worker at STARTUP, naming the offending variable in the error — never
+ * silently picking a winner, and never learning it from a status code at the first write.
+ *
+ * Reads the RAW environment. The legacy-alias contradiction check in particular must NOT normalize
+ * first: normalizing collapses `COLTRANE_DRAIN_URL` onto `COLTRANE_SERVICE_URL`, leaving nothing to
+ * contradict — so the check would pass on exactly the environment it exists to refuse.
+ */
+export function assertWorkerEnv(env) {
+    // (a) Every always-required variable must be present. A legacy alias satisfies its canonical.
+    for (const v of WORKER_ENV_CONTRACT) {
+        if (v.required !== "always")
+            continue;
+        const present = env[v.name] ?? (v.legacy_names ?? []).map((n) => env[n]).find((x) => x != null && x !== "");
+        if (present == null || present === "") {
+            throw new Error(`${v.name} is required but absent — ${v.meaning}`);
+        }
+    }
+    // (b) Every url-role variable that is present must actually be a url. Checked before any host
+    // comparison so the parsing below is safe.
+    for (const v of WORKER_ENV_CONTRACT) {
+        if (v.role !== "url")
+            continue;
+        const value = env[v.name] ?? (v.legacy_names ?? []).map((n) => env[n]).find((x) => x != null);
+        if (value != null && value !== "" && !isHttpUrl(value)) {
+            throw new Error(`${v.name} is a url but does not parse as one: ${value}`);
+        }
+    }
+    const serviceRaw = env[SERVICE_URL] ?? env[DRAIN_URL];
+    const storeRaw = env[STORE_URL];
+    // (c) The service url must not name the managed database — checked BEFORE the first request, the
+    // diagnostic moved from output_mirror.ts to startup where it belongs.
+    if (serviceRaw != null && serviceRaw !== "" && MANAGED_DB_HOST.test(urlHost(serviceRaw))) {
+        throw new Error(`${SERVICE_URL} names the managed database (${serviceRaw}). It must name the Coltrane service, ` +
+            "which brokers both halves of a write; a drain key is not a project credential and Storage will refuse it.");
+    }
+    // (d) The store and the service must not name the same host — the general form of "pointed at the
+    // database", detectable without knowing which of the two is wrong.
+    if (serviceRaw != null &&
+        serviceRaw !== "" &&
+        storeRaw != null &&
+        storeRaw !== "" &&
+        urlHost(serviceRaw) !== "" &&
+        urlHost(serviceRaw) === urlHost(storeRaw)) {
+        throw new Error(`${STORE_URL} and ${SERVICE_URL} name the same host (${urlHost(serviceRaw)}) — a store and a ` +
+            "service are two hosts, and one url pointed at both is how three readers came to disagree.");
+    }
+    // (e) A legacy alias that CONTRADICTS the canonical name refuses, naming both — read raw, because
+    // normalization would erase the disagreement. Agreement is the ordinary post-redeploy case.
+    const drainRaw = env[DRAIN_URL];
+    const serviceCanonical = env[SERVICE_URL];
+    if (drainRaw != null &&
+        drainRaw !== "" &&
+        serviceCanonical != null &&
+        serviceCanonical !== "" &&
+        serviceOrigin(drainRaw) !== serviceOrigin(serviceCanonical)) {
+        throw new Error(`${DRAIN_URL} (${drainRaw}) disagrees with ${SERVICE_URL} (${serviceCanonical}). ${DRAIN_URL} is a ` +
+            `legacy alias of ${SERVICE_URL}; set one, or make them agree.`);
+    }
+}
+//# sourceMappingURL=worker_env.js.map

package/dist/src/worker_env.js.map

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

package/dist/src/workspace.d.ts

@@ -69,8 +69,15 @@ export declare function fetchGitCredential(endpoint: string, drainKey: string, i
  * The helper is supplied through GIT_CONFIG_* rather than `-c`, because `git clone -c k=v` writes k
  * into the NEW clone's .git/config — see the note at the call site. Scoped to `https://github.com`
  * so a URL naming any other host is never offered the token.
+ *
+ * `targetDir`, when given, is WHERE the clone lands — a caller-supplied directory instead of this
+ * function's own throwaway tmpdir. It is the one addition a venue room needs over the drain: the room
+ * clones into `<realizationDir>/workspace` (the seat's cwd, subsumed by the realizer's own teardown)
+ * rather than a detached tmpdir. Everything else — the token-never-on-disk GIT_CONFIG_* path, cleanup,
+ * revoke — is IDENTICAL, because a room's working tree and the drain's must be the same thing prepared
+ * the same way. Omitted (the drain's call) keeps the original mkdtempSync behaviour byte-for-byte.
  */
-export declare function cloneInto(repoUrl: string, token: string): PreparedWorkspace;
+export declare function cloneInto(repoUrl: string, token: string, targetDir?: string): PreparedWorkspace;
 /**
  * Everything above, for one claimed gig — or null when the claim names no repository.
  *
@@ -86,4 +93,8 @@ export declare function prepareWorkspace(opts: {
     drainKey: string | undefined;
     instance: string | undefined;
     endpoint: string | undefined;
+    /** Where the clone lands. Omitted (the drain) → cloneInto's own throwaway tmpdir. Supplied (a venue
+     *  room) → `<realizationDir>/workspace`, so the seat's cwd is the room's tree and the realizer's
+     *  existing teardown subsumes the clone. The credential path is unchanged either way. */
+    target?: string | undefined;
 }): Promise<PreparedWorkspace | null>;

package/dist/src/workspace.js

@@ -64,9 +64,16 @@ export async function fetchGitCredential(endpoint, drainKey, instance, gigId) {
  * The helper is supplied through GIT_CONFIG_* rather than `-c`, because `git clone -c k=v` writes k
  * into the NEW clone's .git/config — see the note at the call site. Scoped to `https://github.com`
  * so a URL naming any other host is never offered the token.
+ *
+ * `targetDir`, when given, is WHERE the clone lands — a caller-supplied directory instead of this
+ * function's own throwaway tmpdir. It is the one addition a venue room needs over the drain: the room
+ * clones into `<realizationDir>/workspace` (the seat's cwd, subsumed by the realizer's own teardown)
+ * rather than a detached tmpdir. Everything else — the token-never-on-disk GIT_CONFIG_* path, cleanup,
+ * revoke — is IDENTICAL, because a room's working tree and the drain's must be the same thing prepared
+ * the same way. Omitted (the drain's call) keeps the original mkdtempSync behaviour byte-for-byte.
  */
-export function cloneInto(repoUrl, token) {
-    const dir = mkdtempSync(join(tmpdir(), "coltrane-gig-"));
+export function cloneInto(repoUrl, token, targetDir) {
+    const dir = targetDir ?? mkdtempSync(join(tmpdir(), "coltrane-gig-"));
     const cleanup = () => {
         try {
             rmSync(dir, { recursive: true, force: true });
@@ -136,6 +143,6 @@ export async function prepareWorkspace(opts) {
             `nowhere to obtain a credential scoped to this gig`);
     }
     const cred = await fetchGitCredential(opts.endpoint, opts.drainKey, opts.instance, opts.gigId);
-    return cloneInto(opts.repoUrl, cred.token);
+    return cloneInto(opts.repoUrl, cred.token, opts.target);
 }
 //# sourceMappingURL=workspace.js.map

package/dist/src/workspace.js.map

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

package/domain_types/change-context.json

@@ -1,32 +1,78 @@
 {
   "slug": "change-context",
-  "version": 1,
+  "version": 2,
   "extends": "Interpretation",
   "domain": "software-change",
   "status": "active",
-  "description": "The exhaustive read of the material a change lands in, produced before any decision is taken. Records what is present AND what is absent: unknowns is required because an incomplete reading that omits its gaps is indistinguishable from a complete one, and every downstream seat would treat it as complete.",
   "schema": {
     "type": "object",
     "properties": {
-      "repository":          { "type": "string", "description": "Repository or working-tree the reading covers." },
-      "boundary":            { "type": "array", "items": { "type": "string" }, "description": "The declared extent of the read: paths and artefacts inside it, and those deliberately outside it." },
-      "entry_points":        { "type": "array", "items": { "type": "string" }, "description": "Where control or data enters the region under change." },
-      "relevant_files":      {
+      "repository": {
+        "type": "string",
+        "description": "Repository or working-tree the reading covers."
+      },
+      "boundary": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "The declared extent of the read: paths and artefacts inside it, and those deliberately outside it."
+      },
+      "entry_points": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Where control or data enters the region under change."
+      },
+      "relevant_files": {
         "type": "array",
         "description": "Each file the change plausibly touches, with the reason it is relevant and the locator the reading came from.",
         "items": {
           "type": "object",
           "properties": {
-            "path":    { "type": "string" },
-            "why":     { "type": "string" },
-            "locator": { "type": "string", "description": "Tool plus path or query that produced this finding." }
+            "path": {
+              "type": "string"
+            },
+            "why": {
+              "type": "string"
+            },
+            "locator": {
+              "type": "string",
+              "description": "Tool plus path or query that produced this finding."
+            }
           },
-          "required": ["path", "why"]
+          "required": [
+            "path",
+            "why"
+          ]
         }
       },
-      "existing_tests":      { "type": "array", "items": { "type": "string" }, "description": "Checks that already cover the region — the baseline a later verdict is measured against." },
-      "conventions_observed": { "type": "array", "items": { "type": "string" }, "description": "Prevailing patterns the change is expected to hold to." },
-      "unknowns":            { "type": "array", "items": { "type": "string" }, "description": "Questions the material does not answer and paths that could not be reached. Required: the honest bound of the read." }
+      "existing_tests": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Checks that already cover the region — the baseline a later verdict is measured against."
+      },
+      "conventions_observed": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Prevailing patterns the change is expected to hold to."
+      },
+      "unknowns": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Questions the material does not answer and paths that could not be reached. Required: the honest bound of the read."
+      },
+      "index_revision": {
+        "type": "string",
+        "description": "The source revision the MECHANICAL half of this reading was compiled against — the tree state src/repo_index.ts walked. Present when a compiler produced those fields, absent when a human or a model read the code directly. It is what makes the freshness gate possible (#424 I16): a change-context whose index_revision no longer matches the current source describes a tree that has moved, and is refused rather than used. Structure compiled from a stale tree is not merely old, it is WRONG in the specific way that is hardest to notice — the shape is right, the file:line locators are plausible, and every one of them points at the wrong place. OPTIONAL by construction: a change-context may come from any of four interchangeable producers (a reader, the compiler, a prior standard, a human) and only the compiler has a revision to report, so requiring it would make the type unsatisfiable for the three that read code directly — which is the producer-agnosticism I11 pins."
+      }
     }
   },
   "required_fields": [

package/domain_types/lineage-adoption-target.json

@@ -0,0 +1,22 @@
+{
+  "slug": "lineage-adoption-target",
+  "version": 1,
+  "extends": "Signal",
+  "domain": "lineage",
+  "status": "active",
+  "description": "WHICH INSTITUTION an approved lineage-record grounds. Both lineage-record and lineage-verdict promise an attachment neither carries: the record says that on approval it 'becomes first-class lineage attached to an institution, inherited by every agent seated there', and the verdict says a passing verdict 'promotes the record to first-class institutional lineage' — yet neither holds an institution_slug, so a sealed adoption named no target and the caller had to know it out of band. The attachment is not a property of the LINEAGE: the same record can ground two institutions and nothing about its ancestry changes when it does. It is not a property of the APPROVAL either: the approver judges whether the evidence is sound, which is a question about grounding rather than about attachment. It is a property of the ADOPTION ACT. One record, approved once, may be adopted into two institutions by two separate acts, each with its own approver and its own seal. Carrying it here rather than on either sealed type also means no shared type changes shape, and lineage-adopt-v0's chair is already an ENTRY chair, so the target arrives the same way the record does — in the dispatch payload.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "institution_slug": {
+        "type": "string",
+        "description": "The institution this adoption grounds. Must resolve against the loaded genome; an unresolved slug is a dead name and fails closed rather than adopting into nothing."
+      },
+      "note": {
+        "type": "string",
+        "description": "Optional. Why THIS institution, when a record could ground more than one. Recorded beside the act rather than inferred from it later."
+      }
+    }
+  },
+  "required_fields": ["source", "institution_slug"]
+}

package/domain_types/lineage-map.json

@@ -21,9 +21,14 @@
               "enum": ["descends-from", "aligns-with", "diverges-from", "supersedes", "informed-by"]
             },
             "grounding_internal": { "type": "string" },
-            "grounding_external": { "type": "string" }
+            "grounding_external": { "type": "string" },
+            "strength": {
+              "type": "string",
+              "enum": ["dereferenceable-both-sides", "structural-correspondence", "conceptual-analogy"],
+              "$comment": "The weaver DRAWS the grounding strength; the scribe carries it through unchanged into the lineage-record. Ordinal, closed vocabulary — see domain_types/lineage-record.json for the orthogonality note against CitationSchema.evidence_grade (src/genome_schema.ts:293-309)."
+            }
           },
-          "required": ["internal_ref", "external_ref", "relation", "grounding_internal", "grounding_external"]
+          "required": ["internal_ref", "external_ref", "relation", "grounding_internal", "grounding_external", "strength"]
         }
       }
     }