@open-everywhere/core 0.1.0

package/dist/agent/operational/credential-grant-rows.js

@@ -0,0 +1,634 @@
+// The two durable credential-grant rows and the pure functions over them — no store, no eve, no config; the CAS statements live in the two backends and the policy in access/credential-grant.ts.
+// TODO(OPE-1060 S5): fold `resource` onto the ratified ARN resource list and `mode`/`expiresAt`/`purpose` into the Condition slot, once the OPE-1064 container grammar has landed.
+import { createHash } from "node:crypto";
+// 🔴 THE ONE `access/` IMPORT THIS MODULE MAKES, AND IT CLOSES NO CYCLE (OPE-1638).
+// `access/credential-grant-copy.ts` imports NOTHING — that is a stated property of the module, not a
+// coincidence — so the disclosure line can spend the same phrases every other grant message is built
+// from without the rows module and the access plane depending on each other.
+import { connectorDisplayName, grantActionIsReviewed, grantActionPhrase, grantOwnerPhrase, grantSpanPhrase } from "../access/credential-grant-copy.js";
+import { grantScopeKeyIsConversationStable } from "../access/credential-grant-key-shape.js";
+/** The reserved namespace S0 parses (`access/consequence.ts` RESERVED_TOOL_NAMESPACES). */
+const CREDENTIAL_GRANT_NAMESPACE = "grant";
+/**
+ * True iff `segment` may occupy a position in a `grant__<owner>_<connector>__<tool>_<target>`
+ * name — the owner slug, the connector id, the tool slug or the target slug.
+ *
+ * 🔴 A SEGMENT MAY NOT CONTAIN `__`. S0's parser requires a reserved name to hold EXACTLY three
+ * segments and reads the LAST one as the verb; a four-segment name yields no verb at all and
+ * classifies `destructive`. So a handle with a double underscore would not merely mis-name the
+ * tool — it would make every grant of that owner unusable. Reject it at mint, where it is one
+ * refusal, instead of at classify time, where it is a silent tier change.
+ */
+export function isGrantNameSegment(segment) {
+    return /^[a-z0-9]+(?:_[a-z0-9]+)*$/u.test(segment);
+}
+/**
+ * Slugify a display handle into a legal owner segment, or `undefined` when nothing legal survives.
+ *
+ * `undefined` is a REFUSAL, not a fallback to some generated id: the owner segment is what a room
+ * reads to know whose credential is being spent, so an unreadable slug is worse than no grant.
+ */
+export function grantOwnerSlug(handle) {
+    return grantNameSlug(handle);
+}
+/**
+ * Slugify a VENDOR MCP TOOL NAME into the head of a legal verb segment, or `undefined` when nothing
+ * legal survives (OPE-1136). `notion-fetch` → `notion_fetch`.
+ *
+ * 🔴 THE SLUG IS FOR THE NAME ONLY. The bytes the wire call and the fence use are `row.mcpTool`,
+ * never this — the same "the row is the authority" rule the tier already follows. A vendor is free
+ * to publish two tools whose slugs collide; the TARGET half of the verb segment
+ * ({@link grantBorrowVerbSegment}) is what keeps two grants of one tool apart, and each row still
+ * dials its own exact vendor name.
+ */
+export function grantToolSlug(mcpTool) {
+    return grantNameSlug(mcpTool);
+}
+/**
+ * Slugify the GRANTED TARGET'S HUMAN LABEL into the tail of a verb segment (OPE-1136, the
+ * 2026-08-25 mint ruling). `Quarterly report` → `quarterly_report`.
+ *
+ * `undefined` when nothing legal survives — a label of punctuation alone names no target. The
+ * caller then spells the verb segment from the tool slug alone, which is still a legal name; it is
+ * only less meaningful.
+ */
+export function grantTargetSlug(targetLabel) {
+    return grantNameSlug(targetLabel);
+}
+/** The one slugification {@link grantOwnerSlug}, {@link grantToolSlug} and {@link grantTargetSlug}
+ *  apply, so an owner segment and a verb segment can never drift into two spellings of "legal". */
+function grantNameSlug(raw) {
+    const slug = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "_")
+        .replace(/^_+|_+$/gu, "")
+        .replace(/_{2,}/gu, "_");
+    return slug.length > 0 && isGrantNameSegment(slug) ? slug : undefined;
+}
+/**
+ * Is `name` a name {@link grantBorrowToolName} could have MINTED — the exact structural inverse of
+ * the three-segment grammar?
+ *
+ * 🔴 STRUCTURE, NEVER A PREFIX TEST. `name.startsWith("grant__")` also admits `grant__owner` and
+ * `grant__a__b__c`, and those are the two shapes `access/consequence.ts` `parseQualifiedToolName`
+ * refuses to read: a reserved name holds EXACTLY three segments, or it yields no verb at all and
+ * classifies `destructive`. A caller that admitted such a name would admit a tool whose tier nobody
+ * can state. The segment rules are {@link isGrantNameSegment}'s, so a name this returns true for is
+ * a name the mount path can spell and the S0 parser can read.
+ *
+ * The answer is about the NAME's shape alone. It says nothing about whether a grant row exists, is
+ * active, or is spendable — `credentialGrantStateRefusal` and the broker own that, per call.
+ */
+export function isGrantToolName(name) {
+    const segments = name.split("__");
+    if (segments.length !== 3)
+        return false;
+    return segments[0] === CREDENTIAL_GRANT_NAMESPACE && isGrantNameSegment(segments[1] ?? "") && isGrantNameSegment(segments[2] ?? "");
+}
+/**
+ * 64 is the tightest model tool-name cap in wide use, and a grant name is assembled from four caller-supplied parts, two of them model-authored at ask time.
+ * Only the target half is truncated to fit; an over-long owner slug or tool slug refuses instead, because a truncated one names a different grant.
+ */
+export const GRANT_TOOL_NAME_MAX = 64;
+/** How many characters {@link grantBorrowRowSuffix} takes off a row id — enough that two rows in one
+ *  chat colliding on it is not a case anybody has to reason about, short enough to leave the target
+ *  label room in a 64-character name. */
+const GRANT_ROW_SUFFIX_LEN = 6;
+/**
+ * The target label rides in the verb segment so two grants of one vendor tool say what they differ about, instead of an ordinal that carries no meaning.
+ * Only the target half truncates: `mountedGrantName` re-derives this head from `row.mcpTool`, so a cut head would fail that check on every such name.
+ */
+export function grantBorrowVerbSegment(toolSlug, targetSlug, budget) {
+    if (!isGrantNameSegment(toolSlug) || toolSlug.length > budget)
+        return undefined;
+    if (targetSlug === undefined || !isGrantNameSegment(targetSlug))
+        return toolSlug;
+    // -1 for the `_` that joins the two halves. A target that leaves no room simply does not ride.
+    const room = budget - toolSlug.length - 1;
+    if (room < 1)
+        return toolSlug;
+    // A cut can land on the `_` between two words, so the trailing separator is stripped — a segment
+    // may not end in one. Re-slugified rather than trusted, so a cut can never emit an illegal name.
+    const cut = targetSlug.slice(0, room).replace(/_+$/u, "");
+    const tail = cut.length > 0 && isGrantNameSegment(cut) ? cut : undefined;
+    return tail === undefined ? toolSlug : `${toolSlug}_${tail}`;
+}
+/**
+ * The short row-id suffix a COLLIDING borrow name carries (OPE-1136, the 2026-08-25 mint ruling), or
+ * `undefined` when the id holds too little a name segment can spell.
+ *
+ * The ruling's disambiguator: two grants that would mount under one name are told apart by a
+ * fragment of the row's own id, and only then. A row id is a uuid, so the fragment is hex — already
+ * legal segment bytes — and it names exactly one row rather than a position in a list.
+ */
+export function grantBorrowRowSuffix(rowId) {
+    const usable = rowId.toLowerCase().replace(/[^a-z0-9]+/gu, "");
+    const suffix = usable.slice(0, GRANT_ROW_SUFFIX_LEN);
+    return suffix.length === GRANT_ROW_SUFFIX_LEN ? suffix : undefined;
+}
+/**
+ * The tool name one BORROW grant mounts under: `grant__<ownerSlug>_<connector>__<verbSegment>`
+ * (OPE-1136, resolving OPE-1135's naming question).
+ *
+ * 🔴 STILL EXACTLY THREE SEGMENTS, and that is the whole reason the vendor rides in the MIDDLE one.
+ * `parseQualifiedToolName` and {@link isGrantToolName} are unchanged by this grammar. For a reserved
+ * name the parser reads the last segment as the verb and yields NO connection path tokens, so the
+ * middle segment is tier-inert: a connector id that happened to spell a read verb can neither lower
+ * nor raise the tier from there. Putting the vendor in the VERB segment would break exactly that —
+ * S0's rule is that only the verb segment may lower a tier.
+ *
+ * 🔴 THE TARGET HALF OF THE VERB SEGMENT IS MODEL-AUTHORED, AND WHAT BOUNDS IT IS THE MINT, NOT THE
+ * CLASSIFIER. It adds tokens to the segment `classifyConnectorOpTier` scans, and that scan is NOT a
+ * monotone raise: an unrecognised verb segment carries `undefined` until the final fallback, so a
+ * read token in the tail can LOWER it from `destructive` to `read`. What makes that unreachable for
+ * a borrow is that `credentialGrantMintVerdict` refuses any vendor tool whose own classification is
+ * not `read` — so the tool slug at the HEAD always contributes a recognised read token, and from a
+ * `read` floor the tail can only raise (a label spelling `delete` gives `destructive`; one spelling
+ * `get` changes nothing). Over-gating in the safe direction is the accepted cost of a meaningful
+ * name. The GRANT's own tier is not read from the name at all — it is pinned on the row at mint from
+ * the vendor's own bytes. Restate this if a WRITE borrow is ever admitted.
+ *
+ * Throws on a segment the parser could not read back: an unreadable name is a silent tier change,
+ * so it must fail where it is composed.
+ */
+export function grantBorrowToolName(ownerSlug, connector, verbSegment) {
+    if (!isGrantNameSegment(ownerSlug))
+        throw new Error(`grantBorrowToolName: illegal owner segment "${ownerSlug}" (a segment may not contain "__")`);
+    if (!isGrantNameSegment(connector))
+        throw new Error(`grantBorrowToolName: illegal connector segment "${connector}" (a segment may not contain "__")`);
+    if (!isGrantNameSegment(verbSegment))
+        throw new Error(`grantBorrowToolName: illegal verb segment "${verbSegment}" (compose it with grantBorrowVerbSegment first)`);
+    const name = `${CREDENTIAL_GRANT_NAMESPACE}__${ownerSlug}_${connector}__${verbSegment}`;
+    // A TRIPWIRE, and it cannot fire under today's rules — three legal segments joined this way always
+    // read back as three. It is here for the day one of those rules widens: a composer that emitted a
+    // name `isGrantToolName` refuses would mount a tool nothing can classify, and this turns that into
+    // a throw at the composer instead of a silent `destructive` at the classifier.
+    if (!isGrantToolName(name))
+        throw new Error(`grantBorrowToolName: composed an unreadable name "${name}"`);
+    if (name.length > GRANT_TOOL_NAME_MAX)
+        throw new Error(`grantBorrowToolName: composed a ${String(name.length)}-character name, past the ${String(GRANT_TOOL_NAME_MAX)}-character bound`);
+    return name;
+}
+/**
+ * The borrow name to mount under, given the names ALREADY CLAIMED in this chat (OPE-1136), or
+ * `undefined` when this row can spell none.
+ *
+ * 🔴 THE ROW-ID SUFFIX RIDES ONLY ON A COLLISION, which is the ruling. `<toolSlug>_<targetSlug>` is
+ * offered first, and the fragment of `rowId` is appended only when that name is already claimed. Two
+ * grants of one tool on two different targets therefore both keep meaning-carrying names, and only a
+ * genuine same-tool-same-label pair pays for a fragment nobody can read.
+ *
+ * 🔴 `taken` IS EVERY GRANT ROW IN THE SCOPE, LIVE OR DEAD. Grant rows are never deleted and the
+ * mount projects EXISTENCE, refusing on state (design §7), so an expired grant still occupies its
+ * mounted name. Passing only the live rows would hand a fresh grant the name a dead one is already
+ * mounted under, and one of the two would be dropped at mount.
+ *
+ * It is not a lock. Two asks composed at the same instant can read the same `taken`, find the bare
+ * name free and both pin it; the mount-side dedupe is the backstop for that race, exactly as the
+ * design says. What the suffix removes is the ORDINAL's extra failure: two rows that each computed
+ * "I am the second" and landed on one `…_2`.
+ */
+export function nextGrantBorrowToolName(ownerSlug, connector, toolSlug, targetSlug, rowId, taken) {
+    // Everything the verb segment is NOT: `grant__`, the owner slug, `_`, the connector and `__`.
+    const fixed = CREDENTIAL_GRANT_NAMESPACE.length + 2 + ownerSlug.length + 1 + connector.length + 2;
+    const suffix = grantBorrowRowSuffix(rowId);
+    if (suffix === undefined)
+        return undefined;
+    // The budget reserves room for the suffix UP FRONT, so a name that fits without one still fits
+    // with one. Deciding the truncation after a collision would give one row two different verb
+    // segments depending on what else the chat holds.
+    const verb = grantBorrowVerbSegment(toolSlug, targetSlug, GRANT_TOOL_NAME_MAX - fixed - (suffix.length + 1));
+    if (verb === undefined)
+        return undefined;
+    const claimed = new Set(taken);
+    for (const candidate of [verb, `${verb}_${suffix}`]) {
+        const name = grantBorrowToolName(ownerSlug, connector, candidate);
+        if (!claimed.has(name))
+            return name;
+    }
+    // Both names are taken, which needs the SAME row id to have asked twice in one chat. Nothing in
+    // the ask path can do that — a row id is minted per ask — so this is the refusal for a caller that
+    // reused one, never a state a requester can reach.
+    return undefined;
+}
+/**
+ * Render a JSON-object row field as the text a store column holds, or `null` for an absent one.
+ *
+ * 🔴 IT CANONICALISES, AND IT REFUSES A NON-JSON VALUE. Two grants that froze the same arguments
+ * therefore hold the same bytes, whatever order the keys arrived in — which is what makes
+ * {@link grantFrozenArgsDigest} a stable key rather than an accident of insertion order. A value
+ * that is not a JSON value (a function, a symbol, `NaN`) throws HERE, at the write, rather than
+ * becoming an empty object that a fence would later enforce nothing against.
+ */
+export function grantJsonColumn(value) {
+    return value === undefined ? null : canonicalJson(value, "value");
+}
+/**
+ * Read a JSON-object column back, or `undefined` when the column holds nothing.
+ *
+ * 🔴 A MALFORMED VALUE THROWS; it never reads as `{}` or as absent. The two JSON columns carry the
+ * frozen arguments and the schema snapshot — the narrowings the owner approved. Reading a corrupt
+ * one as "nothing frozen" would turn a narrow grant into an open one, so the honest failure is a
+ * throw that takes the mount down loudly.
+ *
+ * `undefined` as well as `null` reads as absent: these are migration-added columns, so a deployment
+ * mid-rollout can answer a read from a row the ALTER has not reached yet.
+ */
+export function grantJsonFromColumn(text, column) {
+    if (text === null || text === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`credential grant row: column "${column}" does not hold JSON (${String(err)})`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`credential grant row: column "${column}" holds ${Array.isArray(parsed) ? "an array" : String(parsed === null ? "null" : typeof parsed)}, not a JSON object`);
+    }
+    return parsed;
+}
+/**
+ * `mcpTool`, `frozenArgs` and `toolName` are decided together at the ask and must be written together — the transport dials one, the fence pins one, the mount spells one, and a row carrying only some of them makes those three readers disagree silently.
+ * A row that names none of them lends nothing and must never be written; rows an older build persisted are still read, and they refuse `no_lent_tool` at the broker.
+ */
+export function grantBorrowColumnsProblem(row) {
+    // FIRST, so it stays reachable and so the caller reads the NARROWER sentence. A schema snapshot
+    // beside no vendor tool also fails the trio rule below, and the generic message would send an
+    // author looking for a missing ask-time column when what they wrote was an approve-time one.
+    if (row.inputSchema !== undefined && row.mcpTool === undefined)
+        return "a schema snapshot was written without the vendor tool it snapshots";
+    const present = [
+        ["mcpTool", row.mcpTool !== undefined],
+        ["frozenArgs", row.frozenArgs !== undefined],
+        ["toolName", row.toolName !== undefined],
+    ];
+    const missing = present.filter(([, has]) => !has).map(([name]) => name);
+    if (missing.length > 0) {
+        return `the row names ${missing.join(", ")} nowhere — a grant lends one vendor MCP tool, and mcpTool, frozenArgs and toolName are decided together at the ask and must be written together`;
+    }
+    return undefined;
+}
+/**
+ * The stable key for one FROZEN-ARGUMENT SET — half of the at-most-one rule's tuple (OPE-1136).
+ *
+ * The rule relaxed from (owner, verb, scope) to (owner, connector, mcpTool, THIS, scope): the same
+ * vendor tool frozen to two different resources is two decisions the owner made, so it is two
+ * grants, and the ordinal keeps their mounted names apart. Comparing the raw objects would make the
+ * answer depend on key order, so the comparison runs over this digest instead.
+ *
+ * Pass `{}` for a borrow that froze nothing. There is no digest of "absent" on purpose — a row with
+ * no frozen arguments at all names no borrow, and the borrow lookup never asks about one.
+ */
+export function grantFrozenArgsDigest(frozenArgs) {
+    return createHash("sha256").update(canonicalJson(frozenArgs, "frozenArgs")).digest("hex");
+}
+/**
+ * The deepest nesting a frozen-argument set or a schema snapshot may carry.
+ *
+ * A bound rather than a taste: without one, a cyclic object recurses until the stack dies, and the
+ * error a caller then sees names no boundary. Sixty-four is far past any vendor tool's arguments.
+ */
+const GRANT_JSON_MAX_DEPTH = 64;
+/** JSON with object keys in code-unit order, so one value has exactly one spelling. Throws on any
+ *  value JSON cannot hold — see {@link grantJsonColumn} for why that is the right direction. */
+function canonicalJson(value, path, depth = 0) {
+    if (depth > GRANT_JSON_MAX_DEPTH)
+        throw new Error(`credential grant row: ${path} nests deeper than ${String(GRANT_JSON_MAX_DEPTH)} levels (a cycle, or a value no vendor tool takes)`);
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error(`credential grant row: ${path} is ${String(value)}, which JSON cannot hold`);
+        return JSON.stringify(value);
+    }
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map((item, i) => canonicalJson(item, `${path}[${String(i)}]`, depth + 1)).join(",")}]`;
+    if (typeof value !== "object")
+        throw new Error(`credential grant row: ${path} is a ${typeof value}, which JSON cannot hold`);
+    // 🔴 A PLAIN OBJECT ONLY. `Object.entries` on a Date, a Map or a class instance returns NOTHING,
+    // so a non-plain object would canonicalise to `{}` — the empty value this whole module refuses to
+    // let a narrowing decay into. These values arrive from `JSON.parse`, so a non-plain one is a
+    // caller's mistake, and it is refused where it can still be fixed.
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        throw new Error(`credential grant row: ${path} is a ${value.constructor?.name ?? "non-plain"} object, not a JSON object`);
+    // 🔴 AN `undefined` PROPERTY IS REFUSED, NOT DROPPED — and this is the arm that matters most.
+    // `JSON.stringify` drops such a key silently, which is exactly how a frozen argument disappears:
+    // `{ page_id: resolved.id }` with an unresolved id would store `{}`, and `{}` freezes nothing. The
+    // array arm refuses the same value already (it recurses onto a bare `undefined`), so refusing here
+    // makes the two agree. Nothing legitimate is lost: these values arrive from `JSON.parse`.
+    const entries = Object.entries(value);
+    for (const [k, v] of entries) {
+        if (v === undefined)
+            throw new Error(`credential grant row: ${path}.${k} is undefined, which JSON cannot hold — a dropped key is a lost narrowing`);
+    }
+    entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v, `${path}.${k}`, depth + 1)}`).join(",")}}`;
+}
+/**
+ * The state half of the broker's per-call check: is this row still spendable at `nowIso`?
+ *
+ * 🔴 EXPIRY IS READ FROM THE ROW, not from the status column alone. A row can be `active` and past
+ * its `expiresAt` whenever no sweep has run yet — a store sweep is a tidy-up, never the control.
+ */
+export function credentialGrantStateRefusal(row, nowIso) {
+    if (row.status === "revoked")
+        return "revoked";
+    if (row.status === "used")
+        return "burned";
+    if (row.status === "expired")
+        return "expired";
+    if (row.expiresAt <= nowIso)
+        return "expired";
+    return undefined;
+}
+/**
+ * A REFUSAL RAISED BEFORE THE GRANTED ACTION WAS SENT (OPE-1198).
+ *
+ * 🔴 THE CLAIM IS ABOUT THE ACTION, AND IT IS DELIBERATELY NOT ABOUT THE VENDOR. What a thrower must
+ * be able to show is that the request the GRANT lends — the `tools/call`, or the composed REST call
+ * on the verb path — never left this process. It must NOT be read as "the vendor was untouched": the
+ * borrow path mints the owner's token and completes an MCP handshake first, so a fence trip on
+ * `tools/call` still leaves an authenticated session in the vendor's own log. That is the honest
+ * bound, and nothing on this plane may be written any wider.
+ *
+ * 🔴 IT IS A PROOF OBLIGATION ON WHOEVER THROWS IT, NOT A CONVENIENCE. The broker BURNS a once-mode
+ * grant before it sends, because a burn after the send would let a crashed call be re-spent — that
+ * ordering is load-bearing and does not change. What this class adds is the one case the ordering
+ * got wrong: a refusal that PROVABLY did not send the action. The broker refunds the burn on this
+ * error and on no other.
+ *
+ * 🔴 THIS CLASS IS NECESSARY FOR A REFUND, NOT SUFFICIENT (OPE-1240). The broker also caps how many
+ * refunds one grant row may collect in one turn; past the cap the row stays spent even though the
+ * error proved nothing was sent. Raising this class is still exactly the obligation described above —
+ * a thrower must never reason about the cap — but nothing may restate the sentence as "this error
+ * always refunds". See `access/credential-grant-broker.ts` step 7a.
+ *
+ * 🔴 A PLAIN `Error` IS THE FAIL-CLOSED ANSWER, AND IT MUST STAY THE DEFAULT. A timeout, a socket
+ * error or an SDK throw AFTER the request went out cannot tell a delivered call from a lost one, so
+ * it keeps the burn. Widening this class to "anything that threw" would refund a grant the vendor
+ * had already acted on, which is the double-spend the burn exists to prevent.
+ *
+ * Two producers raise it today: the MCP borrow fence
+ * ({@link import("../access/mcp-call-fence.js").McpCallFenceError}, which refuses before it calls
+ * the wrapped fetch) and the borrow transport's own pre-send resolution.
+ */
+export class GrantUndispatchedError extends Error {
+}
+/**
+ * THE REFUND CLAIM'S NON-ROLLABLE ORDINAL (OPE-1281) — the turn sequence inside an eve turn key, or
+ * `undefined` when the key does not carry one.
+ *
+ * 🔴 WHAT IT IS FOR. The per-turn refund cap lives on the grant row, and the row can hold only the
+ * turn it last counted. Until OPE-1281 any key that DIFFERED from the stored one rolled the count
+ * to 1, so two turn ids landing on one row alternately handed each other a fresh allowance — K
+ * refunds per alternation rather than K per turn. The ordinal makes the roll one-directional: only
+ * a turn STRICTLY LATER than the counted one rolls, so a turn arriving out of order counts against
+ * the allowance that is already there. See {@link
+ * import("./store.js").OperationalStore.claimCredentialGrantRefund}, which owns the rule.
+ *
+ * 🔴 WHY A SEQUENCE IS COMPARABLE HERE AT ALL, AND WHAT THAT DEPENDS ON. eve mints `turn.id` as
+ * `` `turn_${sequence}` `` (harness/emission.js), and the sequence counts up within ONE session's
+ * emission state — `emitTurnEpilogue` and `emitRecoverableFailedTurn` both return `sequence + 1`.
+ * It is NOT globally unique: every session's first turn is `turn_0` (identity/binding.ts, OPE-423).
+ * One grant row is read by one session — `scopeKey` IS the eve session id, and the broker refuses
+ * `out_of_scope` on a mismatch — so the keys reaching one row come from one counter and compare
+ * soundly. A reader that widened a row past one session would break that, and this is the sentence
+ * to read before doing it.
+ *
+ * 🔴 AN UNREADABLE KEY ANSWERS `undefined`, AND THE STORE THEN TREATS IT LIKE AN ABSENT ONE: it
+ * never rolls. That is the fail-closed direction — the allowance narrows to the row's lifetime
+ * instead of resetting — and it is the same direction the statement already took for a caller that
+ * could read no turn id at all. It is also what a change of eve's key shape would land on, so the
+ * shape is pinned by a test rather than trusted: `scripts/eve-turn-concurrency-test.ts` §5.
+ *
+ * Only a bare run of digits is read. A key with a sign, a decimal point, whitespace or any other
+ * suffix carries no ordinal, because guessing one from a shape eve does not mint is how a wrong
+ * comparison would enter silently.
+ */
+export function grantRefundTurnOrdinal(turnKey) {
+    if (turnKey === undefined)
+        return undefined;
+    const digits = /^turn_(\d{1,15})$/u.exec(turnKey);
+    if (digits === null)
+        return undefined;
+    return Number(digits[1]);
+}
+/**
+ * Re-raise `err` as a {@link GrantUndispatchedError}, keeping its message and its cause.
+ *
+ * For a caller that has ALREADY established that the granted action was not sent — a block that runs
+ * wholly before it — and only needs to mark what escapes. An error that already carries the marker is
+ * returned unchanged, so a fence refusal keeps its own class through a wrapping frame.
+ */
+export function asGrantUndispatched(err) {
+    if (err instanceof GrantUndispatchedError)
+        return err;
+    const marked = new GrantUndispatchedError(err instanceof Error ? err.message : String(err));
+    if (err !== undefined && err !== null)
+        marked.cause = err;
+    return marked;
+}
+/**
+ * The refusal names the boundary and tells the model not to retry, and the tool stays mounted through every one of these (design §7) because a tool that vanishes between steps is unexplainable.
+ * It spells no raw `verb` or `resource` column: the model relays these sentences, so every part comes off `credential-grant-copy.ts` and the string is in the leak-lint set like the rest of the plane.
+ */
+export function credentialGrantRefusalMessage(row, reason) {
+    const owner = grantOwnerPhrase(row.ownerSlug);
+    const target = grantResourceTargetLabel(row);
+    const on = target === undefined || target.length === 0 ? "" : ` — "${target}"`;
+    const what = `the grant to ${grantActionPhrase(row.connector, row.mcpTool)}${on} as ${owner}`;
+    switch (reason) {
+        case "revoked":
+            return `Refused: ${owner} revoked this grant. ${what} is no longer spendable. Do not retry — ask again if it is still needed.`;
+        case "expired":
+            return `Refused: this grant has expired. ${what} is no longer spendable. Do not retry — ask again if it is still needed.`;
+        case "burned":
+            return `Refused: this was a one-shot grant and it is already spent. ${what} admitted exactly one call. Do not retry — ask again if it is still needed.`;
+        case "out_of_scope":
+            return `Refused: this grant was approved for a different conversation. ${what} is spendable only where its owner approved it.`;
+        case "no_lent_tool":
+            // 🔴 IT IS NOT `expired` AND NOT `no_transport` (OPE-1334). The row names no vendor tool to
+            // lend, so there is nothing to send under anybody's credential — a permanent property of the
+            // row, not a clock and not a missing deployment part. Only a row an older build wrote for the
+            // deleted verb-registry path can carry this shape.
+            return `Refused: this grant names no vendor tool to run, so ${owner}'s grant can never be spent under any argument. Do not retry — ask again so a fresh grant is minted.`;
+        case "no_transport":
+            return `Refused: this deployment carries no transport for the granted connector, so the call cannot be sent. The grant itself is valid.`;
+        case "connector_delisted":
+            // The honest pair of facts, and they are separate: this deployment will not send the call, and
+            // the row is still the row its owner approved. Nothing here revokes anything — a connector
+            // returning to the reviewed list makes the same grant spendable again.
+            return (`Refused: this deployment no longer admits credential grants for that connector. ${what} cannot be spent, ` +
+                `even where a route to the vendor still exists. The grant itself stays as ${owner} approved it. Do not retry.`);
+        case "owner_unresolvable":
+            return `Refused: this grant does not name ${owner} in a form this deployment can resolve a credential for, so ${what} cannot be spent under anybody. Do not retry — ask again so a fresh grant is minted.`;
+        case "unverified_requester":
+            return `Refused: this turn names no single verified requester, so nobody can be recorded as having spent ${owner}'s credential. Do not retry.`;
+        case "halted":
+            return (`Refused: everything consequential is paused for this deployment right now — someone pulled the break-glass halt, ` +
+                `so no credential is spendable, ${owner}'s included. ${what} stays granted and works again once an admin ` +
+                `runs \`resume\`. Do not retry, and do not look for another route: the same halt covers them.`);
+        case "unattended_wake":
+            return (`Refused: the scheduler started this turn and nobody is in the room. A grant is spendable only where a person asked for it: ` +
+                `there is no requester to record against ${owner}'s credential, and nobody to read the "acting as ${owner}" notice. ` +
+                `${what} stays granted. Do not retry — it is spendable the next time a person addresses this conversation.`);
+    }
+}
+/**
+ * The host-authored disclosure line the room sees on any granted output (design §8.2). The model authors none of it and cannot suppress it, and the REQUESTER stays the actor.
+ * It names which target was touched, as quoted data, but carries no code-shaped column and no ISO instant, and it marks an unreviewed (connector, tool) pair; `scripts/credential-grant-copy-test.ts` lints it whole.
+ */
+export function credentialGrantDisclosureLine(
+// 🔴 `mode` AND `scopeKey` RIDE THE PICK (OPE-2160), because the span sentence below is read from
+// the row's own key and not from its expiry column alone. All three production callers hand this a
+// whole row, so nothing is asked to compose a fact it does not hold.
+row, nowMs) {
+    const owner = grantOwnerPhrase(row.ownerSlug);
+    const target = grantResourceTargetLabel(row);
+    const on = target === undefined || target.length === 0 ? "" : ` — "${target}"`;
+    const vague = grantActionIsReviewed(row.connector, row.mcpTool) ? "" : " (the exact vendor tool is not one this deployment has a reviewed description for)";
+    const reason = quotedPurpose(row.purpose);
+    const why = reason.length === 0 ? "" : ` The reason given was "${reason}".`;
+    return (`acting as ${owner} — used ${owner}'s ${connectorDisplayName(row.connector)} account to ` +
+        `${grantActionPhrase(row.connector, row.mcpTool)}${on}${vague}, ` +
+        `${grantSpanPhrase({ conversationStable: grantScopeKeyIsConversationStable(row.scopeKey), expiresAt: row.expiresAt, mode: row.mode, nowMs })}.${why}`);
+}
+/**
+ * THE HOST-COMPOSED DISPLAY LABEL a borrow row's `resource` column holds (OPE-1136).
+ *
+ * 🔴 IT IS A LABEL, NOT AN ADDRESS. A grant's REACH is the frozen arguments, which the fence pins
+ * byte-for-byte; this column exists so the owner's card, the disclosure line and the refusal copy can
+ * say WHAT was granted in one readable phrase.
+ *
+ * 🔴 TWO THINGS DO READ IT BACK, so its spelling is not free to change (OPE-1589):
+ *   · {@link grantResourceTargetLabel} recovers the TARGET LABEL out of it for the owner's card;
+ *   · `liveCredentialGrantAsk` (operational/store.ts) keys the ANTI-NAG rule on it, so a change to
+ *     the separator or to the call's spelling makes one pending ask stop matching the next and pages
+ *     the owner twice for one decision.
+ * Change either half of the composition and you must change both readers in the same diff.
+ *
+ * 🔴 EVERY PART OF IT IS MODEL-AUTHORED AT ASK TIME — the target label, the vendor tool name and the
+ * frozen values alike — so the whole string goes through {@link quotedPurpose}. It is rendered as
+ * quoted data everywhere it appears, and the single cap there is what keeps a long freeze from
+ * running away with a card.
+ *
+ * `Quarterly report — notion-fetch({id:12345})`.
+ */
+export function grantBorrowResourceLabel(targetLabel, mcpTool, frozenArgs) {
+    const call = `${mcpTool}(${JSON.stringify(frozenArgs)})`;
+    const label = targetLabel.trim();
+    return quotedPurpose(label.length === 0 ? call : `${label} — ${call}`);
+}
+/**
+ * THE TARGET LABEL BACK OUT OF THE `resource` COLUMN (OPE-1589) — `Quarterly report`, or `undefined`
+ * when the column holds no recoverable one.
+ *
+ * 🔴 WHY THIS EXISTS RATHER THAN A COLUMN. The card used to render `resource` whole, which put
+ * `Quarterly report — notion-fetch({"id":"…"})` in front of the owner: a vendor tool id and a
+ * code-shaped call, in the one message whose job is to be readable. The half a person recognises is
+ * the label they wrote; the other half is the machine's. A new column would be the direct answer and
+ * it would need a store migration for a display concern, so this recovers the label instead.
+ *
+ * 🔴 WHAT COMES BACK IS MODEL-AUTHORED, exactly like the purpose string. The requester wrote the
+ * label, so a requester who writes `Q3 — notion-fetch({id:x})` gets that back and the card shows it
+ * inside quotes as THEIR words. That is data on a card, not the host naming a vendor tool, and it is
+ * bounded by {@link quotedPurpose} like every other model-authored field here.
+ *
+ * 🔴 NO CALLER MAY READ `undefined` AS "NO REACH". The reach is the frozen arguments, always. This is
+ * display only: `undefined` means "this column holds no label I can show you", and the caller names
+ * the action alone.
+ */
+export function grantResourceTargetLabel(row) {
+    const tool = row.mcpTool === undefined ? "" : quotedPurpose(row.mcpTool);
+    if (tool.length === 0)
+        return undefined;
+    // 🔴 IT ANCHORS ON THE CALL'S OPENING, NOT ON THE WHOLE CALL. Recomposing the call and stripping it
+    // is the obvious shape and it is WRONG across the store: {@link grantBorrowResourceLabel} spells the
+    // arguments in INSERTION order, while `canonicalJson` writes the `frozen_args` column KEY-SORTED —
+    // so a two-key freeze written `{page_id,block_id}` comes back `{block_id,page_id}` and no
+    // recomposition from the stored row can reproduce the column's bytes. The live card recovered the
+    // label and every terminal card lost it (found in cold review, 2026-09-08). The opening marker is
+    // the one part of the composition that does not move.
+    const marker = ` — ${tool}(`;
+    const cut = row.resource.lastIndexOf(marker);
+    // `cut <= 0`: no marker at all (the requester gave no label, so the column IS the call), or the
+    // column opens with one, which the composition cannot produce.
+    if (cut <= 0)
+        return undefined;
+    // The call always ENDS the composed label. A column that does not close is one `quotedPurpose`
+    // capped, and a cut label is not one to show — name the action alone instead.
+    if (!row.resource.endsWith(")"))
+        return undefined;
+    const label = row.resource.slice(0, cut).trim();
+    return label.length === 0 ? undefined : label;
+}
+/**
+ * WHAT AN AUDIT ROW MAY SAY ABOUT A GRANT'S REACH — a KEYS-ONLY rendering (OPE-1136).
+ *
+ * 🔴 THE `resource` COLUMN HOLDS THE FROZEN VALUES, AND AN AUDIT ROW MAY NOT. The label is composed
+ * from the frozen ARGUMENTS, which are model-authored at ask time and can carry anything the
+ * requester wrote. Writing it into an audit row verbatim would move argument content into the log
+ * every reader treats as safe, against the `connector.op` contract ("ids and verbs only — never the
+ * op arguments or the tool output"). So the audit form names the vendor tool and the frozen KEYS,
+ * and stops there — the same shape `borrowScopeDigest` already uses for the call itself.
+ *
+ * A row that names NO vendor tool falls back to its `resource` column. Only a row an older build
+ * wrote for the deleted verb-registry path can carry that shape, and it held an ARN there — an id,
+ * which the contract admits.
+ *
+ * The card, the disclosure line and the refusal copy keep the full label: those are read by the two
+ * people who authored and approved it, in the moment they are deciding.
+ */
+export function grantAuditResource(row) {
+    if (row.mcpTool === undefined)
+        return row.resource;
+    // 🔴 THE KEYS RIDE THE SAME QUOTED-DATA DISCIPLINE AS THE TOOL NAME. They are model-authored at
+    // ask time and nothing validates them before the approve-time schema check, so a `grant.refused`
+    // row can be written for an ask that froze a thousand of them. `quotedPurpose` strips the quotes
+    // and newlines that would let the list escape its field, and caps the length.
+    const keys = quotedPurpose(Object.keys(row.frozenArgs ?? {}).sort().join(","));
+    return `${quotedPurpose(row.mcpTool)} keys:${keys}`;
+}
+/**
+ * Render a MODEL-AUTHORED purpose string as quoted data.
+ *
+ * Strips the quote characters and the newlines that would let the string escape its span, and caps
+ * the length. This is the same discipline a code-rendered approval card carries for a model-authored
+ * body: the string is recorded and shown, and it is never allowed to read as host copy.
+ */
+export function quotedPurpose(purpose) {
+    const flat = purpose.replace(/[\r\n]+/gu, " ").replace(/["'`]/gu, "").trim();
+    return flat.length > 200 ? `${flat.slice(0, 197)}...` : flat;
+}
+/**
+ * Render a DISPLAY NAME — a person's or a seat's, resolved from the identity plane — as ONE line.
+ *
+ * 🔴 A DISPLAY NAME IS NOT HOST COPY (OPE-1384). The grant card states what a grant reaches as a
+ * bullet list, and it interpolates display names into that list. A name carrying a newline can
+ * therefore forge a bullet — `"Ada\n• What a grant reaches: everything"` reads to the owner as a
+ * line the host wrote, in the one card whose whole job is to tell them what they are agreeing to.
+ * The person's own account name is not something this deployment controls, so it is DATA.
+ *
+ * ONE SANITISER FOR EVERY DISPLAY NAME THE CARD RENDERS, deliberately: the defect arrived because
+ * one interpolation was escaped and its neighbour was not, and a per-site fix would leave the next
+ * new bullet to make the same choice again.
+ *
+ * 🔴 IT FLATTENS, IT DOES NOT STRIP QUOTES — the one deliberate difference from
+ * {@link quotedPurpose}. That function drops `"`, `'` and `` ` `` because a model-authored purpose
+ * renders INSIDE a quoted span it could otherwise escape. A display name renders as plain text and
+ * as bold, in no span, so the quote characters are harmless there — and removing them would spell a
+ * real person's name wrong. "O'Brien" must not reach their own consent card as "OBrien". The
+ * newline is the whole attack surface here, because a forged bullet needs one.
+ */
+export function flatDisplayName(label) {
+    const flat = label.replace(/[\r\n]+/gu, " ").trim();
+    return flat.length > 200 ? `${flat.slice(0, 197)}...` : flat;
+}
+//# sourceMappingURL=credential-grant-rows.js.map