@open-everywhere/core 0.1.0

package/dist/agent/access/principal-gate-manifest.js

@@ -0,0 +1,718 @@
+// THE PRINCIPAL-GATE INTENT CHECK (OPE-271) — the pure half of `npm run lint:principal-gate`.
+//
+// WHAT IT IS FOR. Two questions in this codebase read almost identically and mean opposite things:
+//
+//   WHO is this turn attributable to?      → access/request.ts `principalIdOf` / `binding.principalId`
+//   is a HUMAN here, acting, right now?    → access/request.ts `actingPrincipalIdOf` / `actingPrincipalId`
+//
+// Before OPE-269 they were the same value, so `if (!principalIdOf(ctx)) throw` was the idiomatic
+// spelling of BOTH. Since OPE-269 a triggered routine fire binds as its routine's ATTESTED CREATOR
+// (identity/binding.ts `principalAttested`) — a real person's id, never empty — so that spelling
+// answers the first question and is UNREACHABLE as an answer to the second. Every gate that meant
+// "a human must be present" silently stopped being a gate at all.
+//
+// It has cost three sweeps to find them (OPE-269, OPE-272, OPE-273) and each one found more,
+// because nothing about the wrong spelling looks wrong. It reads perfectly natural, it type-checks,
+// its test passes (against a live human, who satisfies both), and the failure is an ABSENCE — a
+// refusal that never fires. So the durable fix is not another sweep. It is to make the choice
+// impossible to leave implicit: a refusal gate over a principal identity must SAY which of the two
+// it means, in a marker this checker can read.
+//
+//   // principal-gate: accountability — <why nobody nameable is the disqualifier>
+//   // principal-gate: presence — <why an unattended turn must not reach this>
+//
+// THE RULES, and why each is the one that catches the mistake:
+//   1. MARKED. Every refusal gate over a principal read carries a marker. Writing the naive idiom
+//      with no marker is the exact act that produced all three defects, so that is the act that
+//      fails CI.
+//   2. MATCHED. `accountability` is legal only on a BOUND read; `presence` only on an ACTING read.
+//      This is the rule with teeth: an author who correctly writes down "presence" over
+//      `principalIdOf` is told, by name, that the accessor cannot deliver it. The annotation and the
+//      code have to agree, so neither can drift into a lie while the other stays right.
+//   3. REASONED. A marker with no prose after the dash is a rubber stamp. The reason is the part a
+//      future reader needs, and the part that makes an author stop and actually decide.
+//
+// DELIBERATELY NOT ASSERTED HERE:
+//   • WHICH intent is correct for a given tool. That is a judgment about what the tool does, and no
+//     checker can make it. This gate only forces it to be MADE, WRITTEN DOWN, and kept consistent
+//     with the accessor — the same posture as `lint:tool-roster` (every tool decided about, never
+//     "this decision was right").
+//   • Non-refusal reads. `requestedBy: principalIdOf(ctx)!` on an approval card is provenance, not a
+//     gate, and marking every one of them would bury the markers that matter in noise. The unit is
+//     the REFUSAL — the place where an identity turns into a permission.
+//   • Fail-SOFT fallbacks. `if (!principalId) return NO_ROLE` (access/roles.ts) narrows rather than
+//     refuses; it is already fail-closed by construction and has no message to get wrong.
+//
+// Line-based on purpose, like `lint:consequence` and `lint:window-gate`'s source half: it must run
+// over sources with no type information and no module graph, from a consumer app's own scripts.
+// That buys a real limitation — see {@link findPrincipalGates}'s note on what it cannot see — and
+// the limitation is safe in the right direction, because the two shapes it DOES see are the two
+// idiomatic ways anyone writes this gate, and a shape it misses is a shape a reviewer will notice.
+/** The two things a principal refusal gate can mean. The whole point of the check is that a gate
+ *  must pick one; there is deliberately no third value meaning "either" or "unsure". */
+export const PRINCIPAL_GATE_INTENTS = ["accountability", "presence"];
+/** The only receivers whose .principalId this checker classifies as a binding's; any other receiver is opaque. Aliasing the binding to a third name defeats it, which is accepted: this stops the natural spelling being written by accident, not someone who has decided to get round it. */
+export const BINDING_RECEIVERS = ["binding", "b"];
+/** The third way a principal identity reaches a gate: destructured out of an options bag, where the KEY is the classification because actingPrincipalId is a name only one accessor has. Renaming on the way out to a new receiver, and a pattern spanning more than one line, both defeat it. */
+export const DESTRUCTURED_PRINCIPAL_KEYS = {
+    actingPrincipalId: "acting",
+    principalId: "opaque",
+};
+/** The intent each accessor family can actually deliver — rule 2, as data. `opaque` is absent
+ *  deliberately: there is nothing to check, and an entry here would be a claim. */
+export const INTENT_FOR_ACCESSOR = {
+    bound: "accountability",
+    acting: "presence",
+};
+/** Blank out comment content so a read mentioned in prose is never mistaken for code. Returns an
+ *  array parallel to the source lines, with comment text replaced by spaces. Block-comment state is
+ *  tracked across lines; string literals are NOT parsed (a `//` inside one blanks the rest of the
+ *  line), which can only ever make this checker see LESS, never invent a gate. */
+function stripComments(lines) {
+    let inBlock = false;
+    return lines.map((raw) => {
+        let out = "";
+        let i = 0;
+        while (i < raw.length) {
+            if (inBlock) {
+                if (raw.startsWith("*/", i)) {
+                    inBlock = false;
+                    out += "  ";
+                    i += 2;
+                }
+                else {
+                    out += " ";
+                    i += 1;
+                }
+                continue;
+            }
+            if (raw.startsWith("/*", i)) {
+                inBlock = true;
+                out += "  ";
+                i += 2;
+                continue;
+            }
+            if (raw.startsWith("//", i)) {
+                out += " ".repeat(raw.length - i);
+                break;
+            }
+            out += raw[i];
+            i += 1;
+        }
+        return out;
+    });
+}
+const ACTING_RE = /\bactingPrincipalIdOf\s*\(|\bactingPrincipalId\s*\(/;
+const BOUND_CALL_RE = /\bprincipalIdOf\s*\(/;
+// A `.principalId` PROPERTY read with its receiver captured. `principalIdOf(` is excluded by the
+// `\b` + the absence of `Of`, and is matched by BOUND_CALL_RE above anyway.
+const PROP_RE = /([A-Za-z_$][\w$]*)\.principalId\b(?!Of)/;
+function accessorOn(code) {
+    if (ACTING_RE.test(code))
+        return { accessor: "acting", expr: code.match(ACTING_RE)[0].replace(/\s+/g, "") };
+    if (BOUND_CALL_RE.test(code))
+        return { accessor: "bound", expr: "principalIdOf(" };
+    const prop = PROP_RE.exec(code);
+    if (prop) {
+        const receiver = prop[1];
+        return { accessor: BINDING_RECEIVERS.includes(receiver) ? "bound" : "opaque", expr: `${receiver}.principalId` };
+    }
+    return undefined;
+}
+/** A single-line object-destructuring declaration, with the whole pattern captured. Greedy on
+ *  purpose so a nested default (`opts = {}`) inside the pattern doesn't truncate it at the wrong
+ *  brace — the `\}\s*=` anchor backtracks to the LAST closing brace that is actually the pattern's. */
+const DESTRUCTURE_DECL_RE = /^\s*(?:const|let)\s*\{(.*)\}\s*=/;
+/** The names a file destructures out of a classified key, mapped to the accessor family that key delivers. File-scoped with no scope analysis, and a name bound from two different keys collapses to opaque rather than to no gate. */
+function destructuredPrincipalBindings(code) {
+    const bound = new Map();
+    for (const line of code) {
+        const m = DESTRUCTURE_DECL_RE.exec(line);
+        if (!m)
+            continue;
+        for (const raw of (m[1] ?? "").split(",")) {
+            // Drop any default (`opts = {}`), then split a rename (`key: alias`). A rest element
+            // (`...rest`) carries no key we recognise and falls out here.
+            const lhs = (raw.split("=")[0] ?? "").trim();
+            const parts = lhs.split(":");
+            const key = (parts[0] ?? "").trim();
+            const name = (parts[1] ?? parts[0] ?? "").trim();
+            const accessor = DESTRUCTURED_PRINCIPAL_KEYS[key];
+            if (accessor === undefined || !/^[A-Za-z_$][\w$]*$/.test(name))
+                continue;
+            const prior = bound.get(name);
+            bound.set(name, prior !== undefined && prior !== accessor ? "opaque" : accessor);
+        }
+    }
+    return bound;
+}
+/** Lines a `throw` may appear on after the `if`, for the gate to count as a refusal. Four covers
+ *  `if (…) {` + a multi-line `throw new Error(` + its message; a refusal further away than that is
+ *  not the idiom this checker is about. */
+const THROW_WINDOW = 4;
+/** How far a `const x = <read>` may sit above its own `if (!x)`. Generous, because the intervening
+ *  lines are usually one more precondition; beyond this the two are not a single gate. */
+const BINDING_WINDOW = 20;
+const MARKER_RE = /principal-gate:\s*([A-Za-z-]+)\s*(?:—|-{1,2}|:)?\s*(.*)$/;
+/** Read the marker off the contiguous comment block immediately above `line` (1-based, exclusive).
+ *  Contiguous means: comment lines and blank lines only — a statement between the marker and the
+ *  gate detaches it, deliberately, so a marker can never be inherited by the gate below the one it
+ *  was written for. */
+function markerAbove(lines, line) {
+    for (let i = line - 2; i >= 0; i--) {
+        const t = (lines[i] ?? "").trim();
+        if (t === "")
+            continue;
+        const isComment = t.startsWith("//") || t.startsWith("*") || t.startsWith("/*");
+        if (!isComment)
+            return undefined;
+        const m = MARKER_RE.exec(t);
+        if (m)
+            return { intent: m[1].toLowerCase(), reason: (m[2] ?? "").trim() };
+    }
+    return undefined;
+}
+/** The three shapes a principal refusal gate is written in: shapes A and B are reported at the READ, where the accessor choice is made, and shape C at the REFUSAL. It cannot see an indirect refusal, and shape C does no scope analysis, which errs toward asking for a marker rather than missing a gate. */
+export function findPrincipalGates(file, source) {
+    const lines = source.split("\n");
+    const code = stripComments(lines);
+    const gates = [];
+    const destructured = destructuredPrincipalBindings(code);
+    const hasThrowWithin = (from) => {
+        for (let j = from; j < Math.min(from + 1 + THROW_WINDOW, code.length); j++) {
+            if (/\bthrow\b/.test(code[j] ?? ""))
+                return true;
+        }
+        return false;
+    };
+    for (let i = 0; i < code.length; i++) {
+        const c = code[i] ?? "";
+        const found = accessorOn(c);
+        if (!found) {
+            // Shape C — a falsy refusal over a name this file DESTRUCTURED a principal key into. Checked
+            // here, in the `accessorOn` miss branch, because a destructured identifier is by construction
+            // not a call and not a property read: the two matchers above can never see it, and running
+            // this only where they found nothing means shape C can never double-report a gate they did.
+            const refused = destructuredRefusalOn(c, destructured);
+            if (refused && hasThrowWithin(i)) {
+                gates.push({ file, line: i + 1, accessor: refused.accessor, expr: refused.name, ...markerFields(lines, i + 1) });
+            }
+            continue;
+        }
+        if (/\bif\s*\(\s*!/.test(c) && hasThrowWithin(i)) {
+            gates.push({ file, line: i + 1, ...found, ...markerFields(lines, i + 1) });
+            continue;
+        }
+        const decl = /^\s*(?:const|let)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(.*)$/.exec(c);
+        if (!decl || !accessorOn(decl[2] ?? ""))
+            continue;
+        const name = decl[1];
+        const falsy = new RegExp(`\\bif\\s*\\(\\s*(?:!${name}\\s*\\)|${name}\\s*===\\s*undefined\\s*\\))`);
+        for (let j = i + 1; j < Math.min(i + 1 + BINDING_WINDOW, code.length); j++) {
+            if (!falsy.test(code[j] ?? ""))
+                continue;
+            if (hasThrowWithin(j))
+                gates.push({ file, line: i + 1, ...found, ...markerFields(lines, i + 1) });
+            break;
+        }
+    }
+    return gates;
+}
+/** Shape C's refusal matcher: a falsy `if` over a name the file destructured a principal key into.
+ *  The two spellings are the same pair shape B accepts (`!name` / `name === undefined`), so the two
+ *  shapes agree about what "refused" means and neither can drift into accepting a check the other
+ *  would not. */
+function destructuredRefusalOn(code, destructured) {
+    if (destructured.size === 0 || !/\bif\s*\(/.test(code))
+        return undefined;
+    for (const [name, accessor] of destructured) {
+        const falsy = new RegExp(`\\bif\\s*\\(\\s*(?:!${name}\\s*\\)|${name}\\s*===\\s*undefined\\s*\\))`);
+        if (falsy.test(code))
+            return { name, accessor };
+    }
+    return undefined;
+}
+function markerFields(lines, line) {
+    const m = markerAbove(lines, line);
+    if (!m)
+        return {};
+    const known = PRINCIPAL_GATE_INTENTS.includes(m.intent);
+    return known ? { intent: m.intent, reason: m.reason } : { unknownIntent: m.intent, reason: m.reason };
+}
+const SERVICE_PRINCIPAL_RE = /\bprincipalType:\s*["']service["']/;
+const ATTRIBUTES_KEY_RE = /\battributes:\s/;
+const FIRE_AUTH_BUILDER_RE = /FireAttributes\s*\(/;
+/** How far below the `principalType:` line the auth literal's `attributes:` may sit. Generous —
+ *  the real sites carry a long provenance comment between the two (routines/ingress.ts spans 18). */
+const ATTRIBUTES_WINDOW = 40;
+/** Find every SERVICE-principal session-auth construction in one file (RULE 4). */
+export function findUnattendedDispatchSites(file, source) {
+    const code = stripComments(source.split("\n"));
+    const sites = [];
+    for (let i = 0; i < code.length; i++) {
+        if (!SERVICE_PRINCIPAL_RE.test(code[i] ?? ""))
+            continue;
+        let viaFireAuth = false;
+        for (let j = i; j < Math.min(i + 1 + ATTRIBUTES_WINDOW, code.length); j++) {
+            if (!ATTRIBUTES_KEY_RE.test(code[j] ?? ""))
+                continue;
+            viaFireAuth = FIRE_AUTH_BUILDER_RE.test(code[j] ?? "");
+            break;
+        }
+        sites.push({ file, line: i + 1, viaFireAuth });
+    }
+    return sites;
+}
+/** RULE 4's check: every service-principal dispatch builds its bag through fire-auth. */
+export function checkUnattendedDispatch(sites) {
+    return sites
+        .filter((s) => !s.viaFireAuth)
+        .map((s) => ({
+        file: s.file,
+        line: s.line,
+        rule: "unattended-inline-bag",
+        message: `a session auth naming a SERVICE principal whose attribute bag does not come from routines/fire-auth.ts. ` +
+            `An unattended origin MUST carry the FIRE_UNATTENDED_ATTR marker — without it, its non-empty service id answers ` +
+            `every presence gate in the tree as if a human were acting (OPE-278; the webhook fire shipped exactly this way). ` +
+            `Build the bag with routineFireAttributes / webhookFireAttributes (or a sibling builder in that module), never inline.`,
+    }));
+}
+/** The three rules, over already-found gates. Pure so the mirror test can drive it on synthetic
+ *  sources and the driver can drive it on the real tree. */
+export function checkPrincipalGates(gates) {
+    const defects = [];
+    for (const g of gates) {
+        if (g.unknownIntent !== undefined) {
+            defects.push({
+                file: g.file,
+                line: g.line,
+                rule: "unknown-intent",
+                message: `principal-gate marker says "${g.unknownIntent}" — the vocabulary is exactly ${PRINCIPAL_GATE_INTENTS.join(" | ")}.`,
+            });
+            continue;
+        }
+        if (g.intent === undefined) {
+            defects.push({
+                file: g.file,
+                line: g.line,
+                rule: "unmarked",
+                message: `a refusal gate over \`${g.expr}\` with no principal-gate marker. Say which question it asks:\n` +
+                    `      // principal-gate: accountability — somebody NAMEABLE must exist (a card needs an "asked by" line). A fire's attested creator satisfies this, correctly.\n` +
+                    `      // principal-gate: presence — a HUMAN must be here, acting. A fire must NOT satisfy this — read the ACTING principal (actingPrincipalIdOf / actingPrincipalId).`,
+            });
+            continue;
+        }
+        const deliverable = INTENT_FOR_ACCESSOR[g.accessor];
+        // `opaque` has no deliverable — the receiver's provenance is unknown, so rule 2 is skipped and
+        // the marker's own reason is what carries the claim. See PrincipalAccessor for why that case is
+        // real rather than a shrug (Role.principalId is already the ACTING principal).
+        if (deliverable !== undefined && g.intent !== deliverable) {
+            defects.push({
+                file: g.file,
+                line: g.line,
+                rule: "mismatched",
+                message: g.intent === "presence"
+                    ? `declares intent "presence" but reads \`${g.expr}\`, which is the BOUND principal — on a triggered routine fire that is the routine's attested creator, a real person's id, so this refusal can never fire. Read the ACTING principal instead (actingPrincipalIdOf(ctx) / actingPrincipalId(binding)).`
+                    : `declares intent "accountability" but reads the ACTING principal, which is \`undefined\` on every fire. If refusing a fire is the point, the intent is "presence"; if naming the requester is the point, read the bound principal (principalIdOf(ctx) / binding.principalId).`,
+            });
+            continue;
+        }
+        if ((g.reason ?? "").length < 12) {
+            defects.push({
+                file: g.file,
+                line: g.line,
+                rule: "no-reason",
+                message: `principal-gate marker declares "${g.intent}" with no reason after it. Write why — the word alone is a rubber stamp, and the reason is what a later reader needs to tell whether it still holds.`,
+            });
+        }
+    }
+    return defects;
+}
+// Rule 5: the unattended signal an approval site hands the chain must be derived by unattendedOf or unattendedFrom, and no propose site may omit it. Shape E, an eve ApprovalPolicy or Approval<T>, is checked at FILE grain and only when the policy is type-annotated, unless the site carries an approval-chain: exempt marker with a reason.
+/** The approved derivations — the ctx-taking form and its binding-taking twin. A value that does not
+ *  reach through one of these is a rule-5 defect. */
+export const ATTENDEDNESS_DERIVATION = "unattendedOf(ctx)";
+export const ATTENDEDNESS_DERIVATION_BINDING = "unattendedFrom(binding)";
+const DERIVATION_CALL_RE = /\b(?:unattendedOf|unattendedFrom)\s*\(/;
+const PROPOSE_CALL_RE = /\brequestApproval\s*\(/;
+/** A declaration that aliases requestApproval for dependency injection. A call through the alias is still a propose site: a checker matching only the bare name reported two real slash-command propose sites clean, and both shipped with no chain bag. */
+const PROPOSE_ALIAS_DECL_RE = /^\s*(?:const|let)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(.*)$/;
+/** One REFERENCE operand: an identifier or a dotted / optional-chained member path, and nothing
+ *  else — `requestApproval`, `deps.requestApproval`, `deps?.approvals.requestApproval`. No call, no
+ *  index, no literal, no operator. */
+const REFERENCE_OPERAND = String.raw `[A-Za-z_$][\w$]*(?:\s*\??\.\s*[A-Za-z_$][\w$]*)*`;
+/** A whole right-hand side that is ONLY reference operands joined by a `??` / `||` fallback chain,
+ *  with an optional trailing `;`. This is what an injected-dependency alias looks like, and the
+ *  only shape `deps.requestApproval ?? requestApproval` needs. */
+const PROPOSE_ALIAS_RHS_RE = new RegExp(String.raw `^${REFERENCE_OPERAND}(?:\s*(?:\?\?|\|\|)\s*${REFERENCE_OPERAND})*\s*;?\s*$`);
+/** Where a `/` opens a REGEX rather than dividing: at the start of the expression, or after an
+ *  operator or opening bracket. A regex cannot follow a value, and division cannot follow these. */
+const REGEX_MAY_OPEN_AFTER = new Set(["", "=", "(", ",", ":", "[", "{", ";", "!", "&", "|", "?", "+", "-", "*", "%", "<", ">", "~", "^"]);
+/**
+ * Blank the CONTENT of every string, template and regex literal, leaving the delimiters and the
+ * text's length.
+ *
+ * A function name inside a message or a pattern is TEXT, not a reference to the function, and
+ * reading it as one is how this checker blamed a `console.warn` seventy lines from any propose site
+ * (OPE-1892). Regex literals matter as much as quotes here: `const DECLARATION_RE =
+ * /\bfunction\s+(?:requestApproval|…)/` sits in this very file and names the propose function
+ * inside a pattern.
+ *
+ * Unterminated on the line — a template literal spanning lines — blanks to end of line. That can
+ * only make the checker see LESS of a mention, never invent one.
+ */
+function stripLiterals(text) {
+    let out = "";
+    let i = 0;
+    let prev = ""; // last non-space character emitted — what tells a regex from a division
+    const blankUntil = (close, isRegex) => {
+        let inClass = false;
+        while (i < text.length) {
+            const c = text[i];
+            if (c === "\\") {
+                out += "  ".slice(0, Math.min(2, text.length - i));
+                i += 2;
+                continue;
+            }
+            if (isRegex && c === "[")
+                inClass = true;
+            else if (isRegex && c === "]")
+                inClass = false;
+            else if (c === close && !inClass)
+                break;
+            out += " ";
+            i += 1;
+        }
+        if (i < text.length) {
+            out += close;
+            i += 1;
+        }
+        prev = close;
+    };
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '"' || ch === "'" || ch === "`") {
+            out += ch;
+            i += 1;
+            blankUntil(ch, false);
+            continue;
+        }
+        if (ch === "/" && REGEX_MAY_OPEN_AFTER.has(prev)) {
+            out += ch;
+            i += 1;
+            blankUntil("/", true);
+            continue;
+        }
+        out += ch;
+        if (ch.trim() !== "")
+            prev = ch;
+        i += 1;
+    }
+    return out;
+}
+/**
+ * The alias NAME this line declares, or undefined. The RHS must REFERENCE `requestApproval` and
+ * must not CALL it — `const posted = await requestApproval(` is a propose site in its own right,
+ * and reading it as an alias declaration would make the checker skip every real one.
+ *
+ * 🔴 A MENTION IS NOT A DECLARATION (OPE-1892). The RHS is read with string and template literals
+ * BLANKED, then required to be a {@link PROPOSE_ALIAS_RHS_RE} reference expression. Before that, a
+ * plain `const failed = new Error(\`requestApproval: …\`)` bound the alias name `failed`, every
+ * later `failed(` in the file read as a propose site with no chain bag, and the checker cited an
+ * unrelated `console.warn`. A reader following that citation found no propose site at all.
+ *
+ * 🔴 AND NARROWING A SECURITY DETECTOR MAY NOT GO QUIET. A false positive costs a gate cycle; a
+ * false NEGATIVE ships an ungated propose site, which is the direction that matters. So a RHS that
+ * still names `requestApproval` once the literals are blanked but is NOT a reference expression — a
+ * ternary, a wrapper call, a shape nobody has written yet — is neither accepted as an alias nor
+ * silently dropped. It reads as `unclassified` and {@link findProposeAliasShapeProblems} reports
+ * it as a hard error naming the line, so the author either writes the ordinary shape or the rule
+ * learns the new one, under review. The only class this change makes INVISIBLE is the one the
+ * checker was never entitled to read: a name inside a STRING.
+ */
+function proposeAliasOn(line) {
+    const m = PROPOSE_ALIAS_DECL_RE.exec(line);
+    if (!m)
+        return undefined;
+    const rhs = stripLiterals(m[2] ?? "");
+    if (!/\brequestApproval\b/.test(rhs) || PROPOSE_CALL_RE.test(rhs))
+        return undefined;
+    if (!PROPOSE_ALIAS_RHS_RE.test(rhs.trim()))
+        return { kind: "unclassified" };
+    return m[1] === "requestApproval" ? undefined : { kind: "alias", name: m[1] };
+}
+/**
+ * Declarations that NAME the propose function on their right-hand side in a shape this rule does
+ * not classify (OPE-1892). The rule tracks a call through an alias, so a binding it cannot read is
+ * a propose site it would stop following — the silent failure a narrowed detector invites. It is
+ * reported instead, and the tree holds none today: the one real alias,
+ * `const requestApprovalFn = deps.requestApproval ?? requestApproval`, is an ordinary reference
+ * expression.
+ */
+export function findProposeAliasShapeProblems(file, source) {
+    const lines = source.split("\n");
+    const code = stripComments(lines);
+    const problems = [];
+    for (let i = 0; i < code.length; i++) {
+        if (proposeAliasOn(code[i] ?? "")?.kind === "unclassified")
+            problems.push({ file, line: i + 1, text: (lines[i] ?? "").trim().slice(0, 160) });
+    }
+    return problems;
+}
+const CHAIN_LITERAL_RE = /\bresolveApproverChain\s*\(\s*\{|:\s*ApprovalChainRequest\s*=\s*\{/;
+/** SHAPE E, half one: a policy bound to a name — `const approvalPolicy: Approval<Input> = (ctx) => {`.
+ *  The `[^=]*` cannot cross the assignment, so a generic argument list is covered and the arrow's own
+ *  `=>` is not. */
+const EVE_APPROVAL_DECL_RE = /^\s*(?:export\s+)?(?:const|let)\s+[A-Za-z_$][\w$]*\s*:\s*(?:Approval|ApprovalPolicy)\b[^=]*=/;
+/** SHAPE E, half two: a function that RETURNS a policy — `): ApprovalPolicy {`. The trailing `{` is
+ *  load-bearing: it is what separates an implementation from an OVERLOAD SIGNATURE (which ends `;`
+ *  and decides nothing), and the `)` before the colon is what separates a return type from a
+ *  PARAMETER annotation (`policy: ApprovalPolicy,` — a wrapper's input, not a policy it authors). */
+const EVE_APPROVAL_RETURN_RE = /\)\s*:\s*(?:Approval|ApprovalPolicy)\b[^{;]*\{\s*$/;
+/** Skip the DECLARATIONS of the two functions above — a signature is not a call site. */
+const DECLARATION_RE = /\bfunction\s+(?:requestApproval|resolveApproverChain)\b/;
+/** `unattended: <expr>` or the shorthand `unattended,` (tools/aws.ts binds it to a local first). */
+const UNATTENDED_KEY_RE = /\bunattended\s*:\s*(.+)$/;
+const UNATTENDED_SHORTHAND_RE = /^\s*unattended\s*,\s*$/;
+/** Hard ceiling on how far below the opening line the value may sit. The real propose blocks run
+ *  ~25 lines (declare_webhook.ts is the longest); the scan also stops at the call's own closer. */
+const ATTENDEDNESS_WINDOW = 60;
+const EXEMPT_MARKER_RE = /approval-chain:\s*exempt\s*(?:—|-{1,2}|:)?\s*(.*)$/;
+const AUTHORITY_EXEMPT_RE = /approval-authority:\s*headless\s*(?:—|-{1,2}|:)?\s*(.*)$/;
+/** Read the `approval-chain: exempt` marker off the contiguous comment block above `line`
+ *  (1-based, exclusive) — same contiguity rule as {@link markerAbove}, so a marker can never be
+ *  inherited by a site below the one it was written for. */
+function exemptMarkerAbove(lines, line) {
+    for (let i = line - 2; i >= 0; i--) {
+        const t = (lines[i] ?? "").trim();
+        if (t === "")
+            continue;
+        if (!(t.startsWith("//") || t.startsWith("*") || t.startsWith("/*")))
+            return undefined;
+        const m = EXEMPT_MARKER_RE.exec(t);
+        if (m)
+            return { reason: (m[1] ?? "").trim() };
+    }
+    return undefined;
+}
+/** Read the independent proposal-authority exemption off the same contiguous comment block. */
+function authorityExemptAbove(lines, line) {
+    for (let i = line - 2; i >= 0; i--) {
+        const t = (lines[i] ?? "").trim();
+        if (t === "")
+            continue;
+        if (!(t.startsWith("//") || t.startsWith("*") || t.startsWith("/*")))
+            return undefined;
+        const m = AUTHORITY_EXEMPT_RE.exec(t);
+        if (m)
+            return { reason: (m[1] ?? "").trim() };
+    }
+    return undefined;
+}
+/** The line a declaration OPENS on — `export function foo(` / `const foo: T =` — for a shape-E site
+ *  whose match landed on the return-type line of a multi-line signature. */
+const DECL_OPENER_RE = /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\b|(?:const|let)\s)/;
+/** How far above a shape-E match a declaration opener may sit. A signature longer than this is not a
+ *  signature anyone reads. */
+const DECL_OPENER_WINDOW = 12;
+/** A shape-E match lands on the return-type line, so the marker is looked for above the declaration's opener as well as directly above the match. The walk steps up only over deeper-indented signature lines and then examines exactly one line, so a site can never inherit another declaration's exemption. */
+function eveApprovalExemptMarker(lines, line) {
+    const direct = exemptMarkerAbove(lines, line);
+    if (direct !== undefined)
+        return direct;
+    const indentOf = (t) => (t.match(/^\s*/) ?? [""])[0].length;
+    const matchIndent = indentOf(lines[line - 1] ?? "");
+    for (let i = line - 2; i >= 0 && i >= line - 2 - DECL_OPENER_WINDOW; i--) {
+        const t = lines[i] ?? "";
+        if (t.trim() !== "" && indentOf(t) > matchIndent)
+            continue; // still inside the signature
+        return DECL_OPENER_RE.test(t) ? exemptMarkerAbove(lines, i + 1) : undefined;
+    }
+    return undefined;
+}
+/** Names this file binds from the approved derivation (`const unattended = unattendedOf(ctx);`), so
+ *  a site that passes the local rather than the call still reads as derived. File-scoped with no
+ *  scope analysis, exactly like {@link destructuredPrincipalBindings} and for the same reason: the
+ *  binding's PROVENANCE is what the rule is about, and that does not depend on where it sits. */
+function derivedNames(code) {
+    const names = new Set();
+    for (const line of code) {
+        const m = /^\s*(?:const|let)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(.*)$/.exec(line);
+        if (m && DERIVATION_CALL_RE.test(m[2] ?? ""))
+            names.add(m[1]);
+    }
+    return names;
+}
+/** Names this file binds to `requestApproval` itself, so a call through the alias is still a propose
+ *  site. File-scoped and provenance-based, exactly like {@link derivedNames}. */
+function proposeAliases(code) {
+    const names = [];
+    for (const line of code) {
+        const read = proposeAliasOn(line);
+        // An unclassified binding names no alias to follow; findProposeAliasShapeProblems reports it as
+        // its own hard error, so it never passes silently (OPE-1892).
+        if (read?.kind === "alias")
+            names.push(read.name);
+    }
+    return names.length === 0 ? undefined : new RegExp(`\\b(?:${names.join("|")})\\s*\\(`);
+}
+/** Find every approval site that hands the chain an attendedness signal, in one file (RULE 5). */
+export function findAttendednessSites(file, source) {
+    const lines = source.split("\n");
+    const code = stripComments(lines);
+    const aliasCall = proposeAliases(code);
+    const sites = [];
+    const fileDerives = code.some((l) => DERIVATION_CALL_RE.test(l));
+    for (let i = 0; i < code.length; i++) {
+        const c = code[i] ?? "";
+        if (DECLARATION_RE.test(c) || proposeAliasOn(c) !== undefined)
+            continue;
+        if (EVE_APPROVAL_DECL_RE.test(c) || EVE_APPROVAL_RETURN_RE.test(c)) {
+            const eveMarker = eveApprovalExemptMarker(lines, i + 1);
+            sites.push({
+                file,
+                line: i + 1,
+                shape: "eve-approval",
+                derivedInFile: fileDerives,
+                ...(eveMarker !== undefined ? { exemptReason: eveMarker.reason } : {}),
+                exempt: eveMarker !== undefined,
+                authorityExempt: false,
+            });
+            continue;
+        }
+        const isPropose = PROPOSE_CALL_RE.test(c) || (aliasCall !== undefined && aliasCall.test(c));
+        if (!isPropose && !CHAIN_LITERAL_RE.test(c))
+            continue;
+        const indent = (c.match(/^\s*/) ?? [""])[0].length;
+        let expr;
+        let authorityContext;
+        for (let j = i; j < Math.min(i + 1 + ATTENDEDNESS_WINDOW, code.length); j++) {
+            const line = code[j] ?? "";
+            // Stop at the call's own closer — `);` / `};` at or left of the opening indent. Without this
+            // a site with no value would borrow the NEXT call's, and report clean.
+            if (j > i && /^\s*[)}]/.test(line) && (line.match(/^\s*/) ?? [""])[0].length <= indent)
+                break;
+            if (UNATTENDED_SHORTHAND_RE.test(line)) {
+                expr = "unattended";
+            }
+            const m = UNATTENDED_KEY_RE.exec(line);
+            if (m) {
+                expr = (m[1] ?? "").trim().replace(/[,}]+\s*$/, "").trim();
+            }
+            const postDeps = /\bapprovalPostDeps\s*\(\s*[^,)]*(?:,\s*([A-Za-z_$][\w$]*))?\s*\)/.exec(line);
+            if (postDeps?.[1])
+                authorityContext = postDeps[1];
+            const explicit = /\bauthorityContext\s*:\s*([A-Za-z_$][\w$]*)/.exec(line);
+            if (explicit?.[1])
+                authorityContext = explicit[1];
+            if (/^\s*authorityContext\s*,\s*$/.test(line))
+                authorityContext = "authorityContext";
+        }
+        const marker = exemptMarkerAbove(lines, i + 1);
+        const authorityMarker = isPropose ? authorityExemptAbove(lines, i + 1) : undefined;
+        sites.push({
+            file,
+            line: i + 1,
+            shape: isPropose ? "propose" : "chain-literal",
+            ...(expr !== undefined ? { expr } : {}),
+            ...(marker !== undefined ? { exemptReason: marker.reason } : {}),
+            exempt: marker !== undefined,
+            ...(authorityContext !== undefined ? { authorityContext } : {}),
+            authorityExempt: authorityMarker !== undefined,
+            ...(authorityMarker !== undefined ? { authorityExemptReason: authorityMarker.reason } : {}),
+        });
+    }
+    const derived = derivedNames(code);
+    // Resolve a local (`unattended,` / `unattended: flag`) back to its provenance, so the check below
+    // compares derivations rather than identifiers.
+    return sites.map((s) => s.expr !== undefined && derived.has(s.expr) ? { ...s, expr: `${s.expr} = ${ATTENDEDNESS_DERIVATION}` } : s);
+}
+/** RULE 5's check: every approval site derives its attendedness signal through `unattendedOf`. */
+export function checkAttendednessSites(sites) {
+    const defects = [];
+    for (const s of sites) {
+        if (s.exempt) {
+            if ((s.exemptReason ?? "").length < 12) {
+                defects.push({
+                    file: s.file,
+                    line: s.line,
+                    rule: "attendedness-exempt-no-reason",
+                    message: `an \`approval-chain: exempt\` marker with no reason after it. Write why this site cannot derive attendedness ` +
+                        `from a turn — the word alone is a rubber stamp, and this marker is the one way to opt OUT of a security control.`,
+                });
+            }
+            continue;
+        }
+        if (s.shape === "eve-approval") {
+            if (s.derivedInFile === true)
+                continue;
+            defects.push({
+                file: s.file,
+                line: s.line,
+                rule: "attendedness-eve-approval-underived",
+                message: `an eve \`ApprovalPolicy\` / \`Approval<T>\` site in a file that never derives attendedness.\n` +
+                    `      eve's approval plane is the SECOND approval front door in this tree. A \`"user-approval"\` answer becomes a\n` +
+                    `      \`tool-approval\` input request that SUSPENDS the run with \`status:"input_required"\` and no timeout arm, so on an\n` +
+                    `      unattended fire it raises a card nobody can click and the fire never settles (OPE-1241). Derive the signal with\n` +
+                    `      \`${ATTENDEDNESS_DERIVATION}\` (access/request.ts) or \`${ATTENDEDNESS_DERIVATION_BINDING}\` (identity/binding.ts)\n` +
+                    `      and REFUSE an unattended run instead of parking it — connections/connector-auth.ts\n` +
+                    `      \`withUnattendedConnectorFence\` is the worked example. If this policy authors no verdict of its own (a\n` +
+                    `      pass-through wrapper, whose wrapped policy owns the question):\n` +
+                    `      // approval-chain: exempt — <why this site decides nothing>`,
+            });
+            continue;
+        }
+        if (s.expr === undefined) {
+            if (s.shape !== "propose")
+                continue; // a literal cannot omit a required field; tsc says so.
+            defects.push({
+                file: s.file,
+                line: s.line,
+                rule: "attendedness-missing",
+                message: `a propose site with no \`chain:\` bag. Pass \`chain: { unattended: ${ATTENDEDNESS_DERIVATION} },\`.\n` +
+                    `      The approver chain turns \`ask\` into \`deny\` on this signal, so a site that omits it lets an autonomous\n` +
+                    `      fire card into an empty room (OPE-440). If this kind never routes through the chain (a NON_TOOL_ACTION_KIND):\n` +
+                    `      // approval-chain: exempt — <why the chain never sees this kind>`,
+            });
+            continue;
+        }
+        if (!DERIVATION_CALL_RE.test(s.expr)) {
+            defects.push({
+                file: s.file,
+                line: s.line,
+                rule: "attendedness-hand-rolled",
+                message: `derives attendedness as \`${s.expr}\` instead of \`${ATTENDEDNESS_DERIVATION}\` (access/request.ts) or ` +
+                    `\`${ATTENDEDNESS_DERIVATION_BINDING}\` (identity/binding.ts).\n` +
+                    `      One function, one place to test it. A hand-rolled spelling is how the wrong accessor gets in: read the BOUND\n` +
+                    `      principal here and every fire answers "a human is present", because a fire binds as its attested creator.`,
+            });
+        }
+    }
+    return defects;
+}
+// Rule 6: every PROPOSAL site either passes the live context into requestApproval's dependencies or
+// states why it is truly headless. It deliberately consumes rule 5's total requestApproval/alias
+// inventory: checking helper calls instead would miss a proposal that passed `{}` directly.
+export function checkApprovalAuthoritySites(sites) {
+    const defects = [];
+    for (const site of sites) {
+        if (site.shape !== "propose")
+            continue;
+        if (site.authorityExempt) {
+            if ((site.authorityExemptReason ?? "").length < 12) {
+                defects.push({ file: site.file, line: site.line, rule: "approval-authority-exempt-no-reason", message: "an `approval-authority: headless` marker needs a reason naming why this caller has no live model turn" });
+            }
+            continue;
+        }
+        if (site.authorityContext !== "ctx") {
+            defects.push({
+                file: site.file,
+                line: site.line,
+                rule: "approval-authority-context-missing",
+                message: "requestApproval must receive dependencies carrying the live tool context (`approvalPostDeps(platform, ctx)` or `authorityContext: ctx`) so a decision wake restores the exact proposing wake; use `approval-authority: headless — <reason>` only for a real control-plane caller",
+            });
+        }
+    }
+    return defects;
+}
+//# sourceMappingURL=principal-gate-manifest.js.map