@intentius/chant 0.124.46 → 0.124.49

package/src/workspace/work-evidence-ops.ts

@@ -0,0 +1,189 @@
+/**
+ * Evidence that cites an ops result (#3171): a run on the Op run ledger, a
+ * deploy on an environment's release ledger, a gate answer on a gate ledger,
+ * or a release plan in `_plans/`. `attachWorkEvidence` resolves the citation
+ * here before it writes anything, so a criterion is only ticked by a record
+ * the `chant/lifecycle` branch really holds.
+ *
+ * The citation names the record the way `chant workspace graph --intent`'s
+ * `trace` names its links (#4023): `ref` is the ledger file on the branch,
+ * `field` and `value` are what picks the record out of it, and `sha256` is
+ * the hash of the record as stored, a ledger line or a plan file. A citation
+ * that comes with a `sha256` is refused when the record no longer hashes to
+ * it.
+ *
+ * A run says what it showed: an `ok` run is passing evidence and a `fail`
+ * run failing evidence, and the result given must agree. A run that is
+ * still gated or waiting has no outcome yet and is refused. A deploy, a gate
+ * answer and a plan show what they record; whether that meets the criterion
+ * is the citer's `result`.
+ *
+ * Everything is read from the local `chant/lifecycle` branch. Nothing is
+ * fetched, the stance `graph --intent` takes.
+ */
+
+import { createHash } from "node:crypto";
+import { ledgerDir, readBlobFromPath } from "../lifecycle/git";
+import type { EvidenceResult } from "./work";
+
+/** The ledgers evidence can cite. */
+export const OPS_EVIDENCE_LEDGERS = ["run", "deploy", "gate", "plan"] as const;
+export type OpsEvidenceLedger = (typeof OPS_EVIDENCE_LEDGERS)[number];
+
+/** What a caller cites: which record, in which ledger, and optionally the hash it expects. */
+export type OpsCitation = {
+  /** The workspace member whose ledger holds the record, when it is not the flat layout. */
+  member?: string;
+  /** The hash of the record as stored, when the caller already has it. */
+  sha256?: string;
+} & (
+  | { ledger: "run"; env: string; op: string; id: string }
+  | { ledger: "deploy"; env: string; runId: string; component?: string }
+  | { ledger: "gate"; op: string; gate: string; at: string }
+  | { ledger: "plan"; digest: string }
+);
+
+/** The citation as the evidence entry stores it, once it resolved. */
+export interface OpsEvidence {
+  ledger: OpsEvidenceLedger;
+  /** The ledger file, as `chant/lifecycle:<path>`. */
+  ref: string;
+  /** The field of the record that picked it out, and its value. */
+  field: string;
+  value: string;
+  /** Hex SHA-256 of the record as stored. */
+  sha256: string;
+  /** The environment, for a run or a deploy. */
+  env?: string;
+  /** The run's status, for a run. */
+  outcome?: string;
+}
+
+export type OpsCitationError = { code: "write-input-invalid" | "work-evidence-ops-missing" | "work-evidence-ops-mismatch" | "work-evidence-ops-unfinished"; message: string };
+
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+
+const sha256 = (s: string): string => createHash("sha256").update(s).digest("hex");
+
+function lines(text: string): { line: string; rec: Record<string, unknown> }[] {
+  const out: { line: string; rec: Record<string, unknown> }[] = [];
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line === "") continue;
+    try {
+      const rec: unknown = JSON.parse(line);
+      if (rec !== null && typeof rec === "object" && !Array.isArray(rec)) out.push({ line, rec: rec as Record<string, unknown> });
+    } catch {
+      // A malformed line is skipped, as every ledger reader skips it.
+    }
+  }
+  return out;
+}
+
+/** Check a citation's shape, before anything is read. Returns the message for a bad one. */
+export function opsCitationProblem(cite: unknown): string | null {
+  if (cite === null || typeof cite !== "object" || Array.isArray(cite)) return "ops is an object naming a ledger";
+  const c = cite as Record<string, unknown>;
+  const str = (k: string) => typeof c[k] === "string" && (c[k] as string) !== "";
+  const name = (k: string) => typeof c[k] === "string" && NAME.test(c[k] as string);
+  if (!(OPS_EVIDENCE_LEDGERS as readonly string[]).includes(c.ledger as string)) return `ops.ledger is one of ${OPS_EVIDENCE_LEDGERS.join(", ")}, not ${JSON.stringify(c.ledger)}`;
+  if (c.member !== undefined && !name("member")) return "ops.member is a member name";
+  if (c.sha256 !== undefined && !(typeof c.sha256 === "string" && HEX64.test(c.sha256))) return "ops.sha256 is a hex SHA-256";
+  const allowed: Record<OpsEvidenceLedger, { names: string[]; strings: string[]; optional: string[] }> = {
+    run: { names: ["env", "op"], strings: ["id"], optional: [] },
+    deploy: { names: ["env"], strings: ["runId"], optional: ["component"] },
+    gate: { names: ["op"], strings: ["gate", "at"], optional: [] },
+    plan: { names: [], strings: ["digest"], optional: [] },
+  };
+  const spec = allowed[c.ledger as OpsEvidenceLedger];
+  for (const k of spec.names) if (!name(k)) return `a ${c.ledger} citation names ops.${k}`;
+  for (const k of spec.strings) if (!str(k)) return `a ${c.ledger} citation names ops.${k}`;
+  for (const k of spec.optional) if (c[k] !== undefined && !str(k)) return `ops.${k} is a string`;
+  const known = new Set(["ledger", "member", "sha256", ...spec.names, ...spec.strings, ...spec.optional]);
+  const extra = Object.keys(c).filter((k) => !known.has(k));
+  if (extra.length > 0) return `a ${c.ledger} citation takes ${[...known].join(", ")}, not ${extra.join(", ")}`;
+  if (c.ledger === "plan" && /[/\\]/.test(c.digest as string)) return "ops.digest is a plan digest, not a path";
+  return null;
+}
+
+/**
+ * Find the cited record on the local `chant/lifecycle` branch and check it
+ * against the citation and the result given. Never throws for a refusal.
+ */
+export async function resolveOpsCitation(cite: OpsCitation, result: EvidenceResult, cwd: string): Promise<{ ops: OpsEvidence } | { error: OpsCitationError }> {
+  const problem = opsCitationProblem(cite);
+  if (problem) return { error: { code: "write-input-invalid", message: problem } };
+  const loc = { cwd, ...(cite.member !== undefined ? { member: cite.member } : {}) };
+  const missing = (what: string): { error: OpsCitationError } => ({ error: { code: "work-evidence-ops-missing", message: `the local chant/lifecycle branch has no ${what}` } });
+
+  let found: { dir: string; file: string; text: string; field: string; value: string; env?: string; outcome?: string };
+  switch (cite.ledger) {
+    case "run": {
+      const file = `runs__${cite.op}.jsonl`;
+      const content = await readBlobFromPath(cite.env, file, loc);
+      const hit = content === null ? undefined : lines(content).find((l) => l.rec.id === cite.id);
+      if (!hit) return missing(`run ${cite.id} of ${cite.op} in ${cite.env}`);
+      const status = String(hit.rec.status);
+      if (status !== "ok" && status !== "fail") {
+        return { error: { code: "work-evidence-ops-unfinished", message: `run ${cite.id} of ${cite.op} is ${status}: it has no outcome yet to cite` } };
+      }
+      const shows: EvidenceResult = status === "ok" ? "pass" : "fail";
+      if (shows !== result) {
+        return { error: { code: "work-evidence-ops-mismatch", message: `run ${cite.id} of ${cite.op} in ${cite.env} ended ${status}, so it is ${shows} evidence, not ${result}` } };
+      }
+      found = { dir: cite.env, file, text: hit.line, field: "id", value: cite.id, env: cite.env, outcome: status };
+      break;
+    }
+    case "deploy": {
+      const file = "releases.jsonl";
+      const content = await readBlobFromPath(cite.env, file, loc);
+      const hits = content === null ? [] : lines(content).filter((l) => l.rec.runId === cite.runId && (cite.component === undefined || l.rec.component === cite.component));
+      if (hits.length === 0) return missing(`deploy by run ${cite.runId}${cite.component ? ` of ${cite.component}` : ""} in ${cite.env}`);
+      if (hits.length > 1) {
+        return { error: { code: "write-input-invalid", message: `run ${cite.runId} deployed ${hits.length} components in ${cite.env}: name the one cited in ops.component` } };
+      }
+      found = { dir: cite.env, file, text: hits[0].line, field: "runId", value: cite.runId, env: cite.env };
+      break;
+    }
+    case "gate": {
+      const file = `${cite.op}.jsonl`;
+      const content = await readBlobFromPath("_gates", file, loc);
+      const hit = content === null ? undefined : lines(content).find((l) => (l.rec.kind ?? "resolution") === "resolution" && l.rec.gate === cite.gate && l.rec.timestamp === cite.at);
+      if (!hit) return missing(`answer to gate ${cite.gate} of ${cite.op} at ${cite.at}`);
+      found = { dir: "_gates", file, text: hit.line, field: "timestamp", value: cite.at };
+      break;
+    }
+    case "plan": {
+      const file = `${cite.digest.replace(/:/g, "_")}.json`;
+      const content = await readBlobFromPath("_plans", file, loc);
+      if (content === null) return missing(`release plan ${cite.digest}`);
+      let digest: unknown;
+      try {
+        digest = (JSON.parse(content) as { digest?: unknown }).digest;
+      } catch {
+        digest = undefined;
+      }
+      if (digest !== cite.digest) return { error: { code: "work-evidence-ops-mismatch", message: `the plan stored for ${cite.digest} names another digest` } };
+      found = { dir: "_plans", file, text: content, field: "digest", value: cite.digest };
+      break;
+    }
+  }
+
+  const hash = sha256(found.text);
+  if (cite.sha256 !== undefined && cite.sha256 !== hash) {
+    return { error: { code: "work-evidence-ops-mismatch", message: `the ${cite.ledger} record cited hashes to ${hash}, not the ${cite.sha256} given: it is another record` } };
+  }
+  const ref = `chant/lifecycle:${await ledgerDir(found.dir, loc)}/${found.file}`;
+  return {
+    ops: {
+      ledger: cite.ledger,
+      ref,
+      field: found.field,
+      value: found.value,
+      sha256: hash,
+      ...(found.env !== undefined ? { env: found.env } : {}),
+      ...(found.outcome !== undefined ? { outcome: found.outcome } : {}),
+    },
+  };
+}

package/src/workspace/work-evidence.schema.json

@@ -45,7 +45,7 @@
         },
         "evidence": {
           "type": "object",
-          "description": "The entry appended: a title, a url or a path pinned by sha256, as_of, and the criterion, its verification, the result and by, the lease holder.",
+          "description": "The entry appended: a title, a url, a path pinned by sha256 or an ops result verified against its ledger (#3171), as_of, and the criterion, its verification, the result and by, the lease holder.",
           "required": [
             "title",
             "criterion",
@@ -91,6 +91,50 @@
             "by": {
               "type": "string",
               "description": "The lease holder that attached it."
+            },
+            "ops": {
+              "type": "object",
+              "description": "An ops result on the chant/lifecycle branch (#3171), named the way graph --intent's trace names a link: the ledger file in ref, the field and value that pick the record out of it, and the record's sha256 as stored. A run carries its env and outcome, a deploy its env.",
+              "required": [
+                "ledger",
+                "ref",
+                "field",
+                "value",
+                "sha256"
+              ],
+              "properties": {
+                "ledger": {
+                  "enum": [
+                    "run",
+                    "deploy",
+                    "gate",
+                    "plan"
+                  ]
+                },
+                "ref": {
+                  "type": "string",
+                  "pattern": "^chant/lifecycle:"
+                },
+                "field": {
+                  "type": "string"
+                },
+                "value": {
+                  "type": "string"
+                },
+                "sha256": {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{64}$"
+                },
+                "env": {
+                  "type": "string"
+                },
+                "outcome": {
+                  "enum": [
+                    "ok",
+                    "fail"
+                  ]
+                }
+              }
             }
           }
         },
@@ -207,7 +251,10 @@
                 "lease-held",
                 "lease-not-held",
                 "lease-token-mismatch",
-                "not-a-git-repository"
+                "not-a-git-repository",
+                "work-evidence-ops-missing",
+                "work-evidence-ops-mismatch",
+                "work-evidence-ops-unfinished"
               ]
             },
             "message": {

package/src/workspace/work-evidence.ts

@@ -17,6 +17,13 @@
  * one: the run holding the lease is the item's implementer, and a manual
  * verdict comes from someone else. A person records that verdict with
  * `records amend`, naming themselves in `by`.
+ *
+ * Evidence is a public link, a workspace file pinned by hash, or an ops
+ * result (#3171): a run, a deploy, a gate answer or a release plan on the
+ * `chant/lifecycle` branch, cited the way `graph --intent`'s trace cites it.
+ * The citation is resolved against the ledger it names before anything is
+ * written, and a run's outcome must agree with the result
+ * (`./work-evidence-ops.ts`).
  */
 
 import { relative, sep } from "node:path";
@@ -26,6 +33,7 @@ import { pinFile } from "./records-cli";
 import { AMEND_ERROR_CODES, amendRecord } from "./records-write";
 import { acceptanceCriteria, EVIDENCE_RESULTS, workAcceptance, type EvidenceResult, type VerificationType, type WorkAcceptance } from "./work";
 import { findWorkItem, WorkError } from "./work-cli";
+import { resolveOpsCitation, type OpsCitation } from "./work-evidence-ops";
 
 /** Why evidence was not attached. Closed. Nothing is written with any of them. */
 export const WORK_EVIDENCE_ERROR_CODES = [
@@ -40,6 +48,9 @@ export const WORK_EVIDENCE_ERROR_CODES = [
   "lease-not-held",
   "lease-token-mismatch",
   "not-a-git-repository",
+  "work-evidence-ops-missing",
+  "work-evidence-ops-mismatch",
+  "work-evidence-ops-unfinished",
 ] as const satisfies readonly ReasonCode[];
 export type WorkEvidenceErrorCode = (typeof WORK_EVIDENCE_ERROR_CODES)[number];
 
@@ -59,8 +70,10 @@ export interface AttachWorkEvidenceRequest {
   title: string;
   /** A public link, or */
   url?: string;
-  /** a workspace file, pinned by the hash of its bytes now. */
+  /** a workspace file, pinned by the hash of its bytes now, or */
   path?: string;
+  /** an ops result on the `chant/lifecycle` branch (#3171), verified against its ledger. */
+  ops?: OpsCitation;
   /** When the evidence was taken, as an ISO 8601 timestamp. Now by default. */
   asOf?: string;
 }
@@ -111,7 +124,9 @@ export async function attachWorkEvidence(req: AttachWorkEvidenceRequest): Promis
       throw new EvidenceError("write-usage-invalid", `result is pass or fail, not ${JSON.stringify(req.result)}`);
     }
     if (typeof req.title !== "string" || req.title.trim() === "") throw new EvidenceError("write-usage-invalid", "the evidence has no title");
-    if ((req.url === undefined) === (req.path === undefined)) throw new EvidenceError("write-usage-invalid", "the evidence is a url or a path, exactly one of them");
+    if ([req.url, req.path, req.ops].filter((v) => v !== undefined).length !== 1) {
+      throw new EvidenceError("write-usage-invalid", "the evidence is a url, a path or an ops result, exactly one of them");
+    }
     if (req.url !== undefined && !req.url.startsWith("https://")) throw new EvidenceError("write-input-invalid", `evidence links are https://, not ${JSON.stringify(req.url)}`);
 
     const found = await findWorkItem(req.item, req.cwd, req.kind);
@@ -139,7 +154,11 @@ export async function attachWorkEvidence(req: AttachWorkEvidenceRequest): Promis
     }
 
     let pin: Record<string, unknown>;
-    if (req.path !== undefined) {
+    if (req.ops !== undefined) {
+      const resolved = await resolveOpsCitation(req.ops, req.result, req.cwd);
+      if ("error" in resolved) throw new EvidenceError(resolved.error.code, resolved.error.message);
+      pin = { ops: resolved.ops };
+    } else if (req.path !== undefined) {
       const pinned = pinFile(req.path, req.cwd);
       if ("error" in pinned) throw new EvidenceError("write-input-invalid", pinned.error);
       pin = { path: pinned.path, sha256: pinned.sha256 };

package/src/workspace/workspace-gates.ts

@@ -0,0 +1,200 @@
+/**
+ * Workspace gates (#2554, #2524 D17, ws-039).
+ *
+ * A workspace gate is one approval for a change across members. A run of
+ * `chant workspace run --gate <name>` whose member runs stop at their own
+ * gates records a pending fact under `_members/_workspace/_gates/<name>.jsonl`
+ * that lists each stopped member gate and the plan it waits on (a cover),
+ * with the digest of that list. `chant workspace run approve <name>` records
+ * an approval of one such digest.
+ *
+ * The rule (ws-039): a workspace gate never satisfies a member gate, unless
+ * both hold:
+ *
+ * 1. its approval's digest covers the member's plan: the approval lists the
+ *    member, the Op, the gate and the plan digest the member run reached it
+ *    with, and the list still hashes to the approval's digest;
+ * 2. the member opts in at base: its entry in `chant.workspace.json`, read
+ *    from the base revision as other policy is, sets
+ *    `acceptWorkspaceGates: true`. A declaration read only from the working
+ *    tree never opts a member in.
+ *
+ * A member run started under the gate (`CHANT_WORKSPACE_GATE`) asks this
+ * module through `GateCheckInput.workspace` after its own approvals have
+ * not passed the gate. Nothing is written to the member's gate ledger: the
+ * run's step record says `via: "workspace"` and names the workspace gate.
+ */
+
+import { samePlanDigest } from "../lifecycle/plan-digest";
+import { resolveMemberLedger } from "../lifecycle/member-ledger";
+import type { WorkspaceGateStood } from "../op/gate";
+import { appendWorkspaceLine, canonicalDigest, readWorkspaceLines, WORKSPACE_GATES_DIR } from "./workspace-ledger";
+
+/** One member gate a workspace gate covers. */
+export interface WorkspaceGateCover {
+  member: string;
+  op: string;
+  gate: string;
+  planDigest: string;
+  /** The member gate's environment, when it is bound to one. */
+  environment?: string;
+}
+
+export interface WorkspaceGatePending {
+  version: 1;
+  kind: "pending";
+  gate: string;
+  /** The workspace run that recorded it. */
+  run: string;
+  timestamp: string;
+  digest: string;
+  covers: WorkspaceGateCover[];
+}
+
+export interface WorkspaceGateApproval {
+  version: 1;
+  kind: "approval";
+  gate: string;
+  digest: string;
+  covers: WorkspaceGateCover[];
+  approvedBy: string;
+  timestamp: string;
+  note?: string;
+}
+
+export type WorkspaceGateLine = WorkspaceGatePending | WorkspaceGateApproval;
+
+/** Covers in one order, so the same set always has the same digest. */
+export function sortCovers(covers: readonly WorkspaceGateCover[]): WorkspaceGateCover[] {
+  const key = (c: WorkspaceGateCover) => `${c.member}\u0000${c.op}\u0000${c.gate}\u0000${c.environment ?? ""}\u0000${c.planDigest}`;
+  return [...covers]
+    .map((c) => ({ member: c.member, op: c.op, gate: c.gate, planDigest: c.planDigest, ...(c.environment !== undefined ? { environment: c.environment } : {}) }))
+    .sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+}
+
+/** The digest a workspace gate's pending fact and approval carry: the member plans it covers. */
+export function workspaceGateDigest(covers: readonly WorkspaceGateCover[]): string {
+  return canonicalDigest(sortCovers(covers));
+}
+
+/** What a member gate asks about. */
+export interface MemberGateQuery {
+  op: string;
+  gate: string;
+  planDigest: string;
+  environment?: string;
+}
+
+/**
+ * The rule of ws-039, pure: the newest approval that stands in for the
+ * member gate `q`, or null. Null whenever the member has not opted in.
+ */
+export function workspaceGateStandsIn(
+  q: MemberGateQuery,
+  ctx: { member: string; optedIn: boolean; approvals: readonly WorkspaceGateApproval[] },
+): WorkspaceGateApproval | null {
+  if (!ctx.optedIn) return null;
+  const covering = ctx.approvals.filter(
+    (a) =>
+      // The covers must still hash to the digest that was approved.
+      workspaceGateDigest(a.covers) === a.digest &&
+      a.covers.some(
+        (c) =>
+          c.member === ctx.member && c.op === q.op && c.gate === q.gate &&
+          samePlanDigest(c.planDigest, q.planDigest) &&
+          (c.environment ?? null) === (q.environment ?? null),
+      ),
+  );
+  return covering.sort((a, b) => (a.timestamp < b.timestamp ? -1 : a.timestamp > b.timestamp ? 1 : 0)).at(-1) ?? null;
+}
+
+const fileFor = (gate: string) => `${gate}.jsonl`;
+
+function isCover(v: unknown): v is WorkspaceGateCover {
+  const c = v as WorkspaceGateCover;
+  return typeof c === "object" && c !== null && typeof c.member === "string" && typeof c.op === "string" && typeof c.gate === "string" && typeof c.planDigest === "string";
+}
+
+function isGateLine(v: unknown): v is WorkspaceGateLine {
+  const l = v as WorkspaceGateLine;
+  if (typeof l !== "object" || l === null || l.version !== 1 || typeof l.gate !== "string" || typeof l.digest !== "string" || typeof l.timestamp !== "string") return false;
+  if (!Array.isArray(l.covers) || !l.covers.every(isCover)) return false;
+  if (l.kind === "pending") return typeof l.run === "string";
+  if (l.kind === "approval") return typeof l.approvedBy === "string";
+  return false;
+}
+
+/** A workspace gate's ledger, oldest first. */
+export async function readWorkspaceGate(cwd: string, gate: string): Promise<{ pending: WorkspaceGatePending[]; approvals: WorkspaceGateApproval[]; malformed: number }> {
+  const { records, malformed } = await readWorkspaceLines(cwd, WORKSPACE_GATES_DIR, fileFor(gate), isGateLine);
+  return {
+    pending: records.filter((r): r is WorkspaceGatePending => r.kind === "pending"),
+    approvals: records.filter((r): r is WorkspaceGateApproval => r.kind === "approval"),
+    malformed,
+  };
+}
+
+export async function appendWorkspaceGatePending(cwd: string, input: Omit<WorkspaceGatePending, "version" | "kind" | "digest" | "covers"> & { covers: readonly WorkspaceGateCover[] }): Promise<WorkspaceGatePending> {
+  const covers = sortCovers(input.covers);
+  const record: WorkspaceGatePending = { version: 1, kind: "pending", gate: input.gate, run: input.run, timestamp: input.timestamp, digest: workspaceGateDigest(covers), covers };
+  await appendWorkspaceLine(cwd, WORKSPACE_GATES_DIR, fileFor(input.gate), record, `Workspace gate pending: ${input.gate}`);
+  return record;
+}
+
+/**
+ * Approve a workspace gate's pending fact: the newest one, or the one whose
+ * digest is `digest`. The approval copies its covers. Throws when there is no
+ * such fact.
+ */
+export async function approveWorkspaceGate(
+  cwd: string,
+  input: { gate: string; digest?: string; approvedBy: string; timestamp: string; note?: string },
+): Promise<WorkspaceGateApproval> {
+  const { pending } = await readWorkspaceGate(cwd, input.gate);
+  const candidates = input.digest === undefined ? pending : pending.filter((p) => p.digest === input.digest);
+  const fact = candidates.at(-1);
+  if (!fact) {
+    throw new Error(
+      input.digest === undefined
+        ? `workspace gate "${input.gate}" has no pending fact to approve; a chant workspace run --gate ${input.gate} whose members stop at their gates records one`
+        : `workspace gate "${input.gate}" has no pending fact with digest ${input.digest}`,
+    );
+  }
+  const record: WorkspaceGateApproval = {
+    version: 1,
+    kind: "approval",
+    gate: input.gate,
+    digest: fact.digest,
+    covers: fact.covers,
+    approvedBy: input.approvedBy,
+    timestamp: input.timestamp,
+    ...(input.note ? { note: input.note } : {}),
+  };
+  await appendWorkspaceLine(cwd, WORKSPACE_GATES_DIR, fileFor(input.gate), record, `Workspace gate approval: ${input.gate}`);
+  return record;
+}
+
+/**
+ * Whether the member holding `cwd` opts in to workspace gates at base, and
+ * its name. A member of a nested workspace, the root member and a directory
+ * no member owns never opt in.
+ */
+export async function memberAcceptsWorkspaceGates(cwd: string): Promise<{ member: string | null; accepts: boolean }> {
+  const ledger = await resolveMemberLedger(cwd);
+  if (ledger.members.length !== 1) return { member: ledger.members.join("/") || null, accepts: false };
+  const member = ledger.members[0]!;
+  const { scopeSource } = await import("./write-scope");
+  const source = scopeSource(cwd);
+  if (source.from !== "base" || !source.declaration) return { member, accepts: false };
+  const entry = source.declaration.members.find((m) => m.name === member);
+  return { member, accepts: entry?.acceptWorkspaceGates === true };
+}
+
+/** The stand-in a member run started under workspace gate `gate` asks (`GateCheckInput.workspace`). */
+export async function memberGateStandIn(cwd: string, gate: string, q: MemberGateQuery): Promise<WorkspaceGateStood | null> {
+  const { member, accepts } = await memberAcceptsWorkspaceGates(cwd);
+  if (!member || !accepts) return null;
+  const { approvals } = await readWorkspaceGate(cwd, gate);
+  const found = workspaceGateStandsIn(q, { member, optedIn: accepts, approvals });
+  return found ? { gate, digest: found.digest, approvedBy: found.approvedBy, timestamp: found.timestamp } : null;
+}