@open-everywhere/core 0.1.0

package/agent/operational/credential-grant-rows.ts

@@ -0,0 +1,944 @@
+// 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";
+
+/**
+ * How long a grant lives, and how many calls it admits.
+ *
+ * `once` BURNS on the first call. The burn is a compare-and-set in the store statement, never a
+ * read-then-write at a caller: a retried turn, a replayed step and two parallel tool calls in one
+ * step all race, and `ctx.callId` is not replay-stable, so nothing else can make the call
+ * single-use. `session` and `standing` differ only in the expiry a caller computes for them — the
+ * row treats both as "active until `expiresAt`".
+ */
+export type CredentialGrantMode = "once" | "session" | "standing";
+
+/** The grant lifecycle. Every non-`active` state is TERMINAL and refuses at the broker. */
+export type CredentialGrantState = "active" | "used" | "revoked" | "expired";
+
+/** The ask lifecycle. `approved` is the only state that has ever minted a grant. */
+export type CredentialGrantAskState = "pending" | "approved" | "declined" | "expired";
+
+/**
+ * A JSON OBJECT a grant row carries — the shape of `frozenArgs` and of `inputSchema` (OPE-1136).
+ *
+ * `unknown` values, never `string`. A frozen argument is whatever JSON value the vendor tool takes,
+ * so a nested object or an array is a legal value and a string-typed map would silently flatten it.
+ */
+export type GrantJsonObject = Readonly<Record<string, unknown>>;
+
+/** One pending request for a credential grant — the row the owner's DM card is rendered from. */
+export interface CredentialGrantAskRow {
+  readonly id: string;
+  /** The verified human who asked, as a principal key. */
+  readonly requesterPrincipalId: string;
+  /** The person whose credential would be spent, as a principal key. */
+  readonly ownerPrincipalId: string;
+  /**
+   * The owner's segment of the eventual mounted tool name, SLUGIFIED AND PINNED HERE.
+   *
+   * 🔴 It is pinned on the ASK, not re-derived at approve time. The card the owner reads and the
+   * tool name the chat later mounts must agree, and a handle can be renamed between the two. A
+   * re-derivation also has nothing honest to work from: the row carries a principal key, not a
+   * display handle, so re-deriving would spell the tool name out of an id.
+   */
+  readonly ownerSlug: string;
+  /** Which platform the owner's DM card goes to. */
+  readonly ownerPlatform: string;
+  /** The owner's bare platform id on `ownerPlatform` — what {@link DirectMessageRequest} needs. */
+  readonly ownerNativeId: string;
+  /** The vendor plane the credential belongs to (`notion`, `linear`, …). */
+  readonly connector: string;
+  /**
+   * WHAT THIS ROW LENDS, AS A NAME SEGMENT — {@link grantToolSlug} of the vendor tool
+   * ({@link mcpTool}), which is the head of the mounted name's verb segment.
+   *
+   * 🔴 IT IS READ ONLY AS A LABEL. The wire call reads `mcpTool` in the vendor's own bytes, and the
+   * tier is pinned on the grant row. Nothing derives either from this column.
+   */
+  readonly verb: string;
+  /**
+   * WHAT THIS ROW REACHES, FOR A HUMAN TO READ — the host-composed display label
+   * {@link grantBorrowResourceLabel} builds.
+   *
+   * 🔴 NOTHING PARSES IT. A grant's reach is its frozen arguments, and this column exists so the
+   * card, the disclosure line and the refusal copy can name what was granted in one readable phrase.
+   */
+  readonly resource: string;
+  /**
+   * THE VENDOR MCP TOOL this ask would lend, in the vendor's own exact bytes (OPE-1136).
+   *
+   * 🔴 THE ROW IS THE AUTHORITY ON THE WIRE NAME, never the mounted tool name. The mounted name
+   * carries a SLUG of this string ({@link grantToolSlug}), because a name segment may hold only
+   * `[a-z0-9_]` while a vendor tool name may hold anything. A caller that re-derived the wire name
+   * from the mounted one would dial `notion_fetch` where the vendor published `notion-fetch`.
+   *
+   * Absent ONLY on a row an older build wrote for the deleted verb-registry path (OPE-1334). The
+   * mint writes no such row and the stores refuse one; a persisted one refuses `no_lent_tool` at the
+   * broker and mounts nothing.
+   */
+  readonly mcpTool?: string;
+  /**
+   * THE ARGUMENTS THE OWNER FROZE — the keys the requester's chat may not choose (OPE-1136).
+   *
+   * `{}` means "nothing frozen"; ABSENT means "this row lends no tool at all" and is legal only on a
+   * row an older build wrote (OPE-1334). The two must never collapse into one spelling: the fence
+   * pins what this object holds, so reading a lost value as `{}` would widen a narrow grant into an
+   * open one.
+   */
+  readonly frozenArgs?: GrantJsonObject;
+  /**
+   * THE FULL MOUNTED TOOL NAME, PINNED HERE at ask time (OPE-1136), for the reason `ownerSlug` is:
+   * the card the owner reads and the tool the chat later mounts must name the same thing, and the
+   * ordinal that disambiguates two grants of one tool is decided against the rows that exist NOW.
+   *
+   * Absent ONLY on a row an older build wrote for the deleted verb-registry path (OPE-1334), which
+   * composed its name at mount instead. Such a row now mounts nothing.
+   */
+  readonly toolName?: string;
+  /** The CHAT this grant would serve — the session id. The grantee is the chat, not a person. */
+  readonly scopeKey: string;
+  /**
+   * THE ROOM'S CONVERSATION-STABLE SCOPE KEY (OPE-1950, narrowed by OPE-1972, extended by OPE-2012),
+   * read from the domain an operator explicitly declared this room into
+   * (`access/credential-grant-scope.ts` `grantDomainScopeKey`). A `standing`
+   * grant minted from this ask binds to THIS key instead of {@link scopeKey}, so it survives the seat
+   * rotation that retires the session `scopeKey` names.
+   *
+   * 🔴 IT HAS TWO SHAPES AND THE SEAT'S GRAIN DECIDES WHICH — `oe-grant-domain::<domain name>` from
+   * the domain's STANDING seat, and `oe-grant-room::<domain name>::<room key>` from a room's own
+   * `native` seat, which is what every room has while `window.topology` is unarmed. The room shape is
+   * strictly narrower. Read the width back with `grantScopeReachOf` rather than by matching a prefix
+   * at a call site; everything else treats the value as OPAQUE and compares it for equality.
+   *
+   * 🔴 IT IS NOT THE SEAT'S `channel_session` REGISTRY KEY, which is what an earlier revision of this
+   * sentence claimed and what `credential-grant-scope.ts` explicitly refuses: that key exists only
+   * where the window-topology capability is armed, so the 30-day promise would have held on one
+   * deployment and nowhere else.
+   *
+   * 🔴 BOTH KEYS ARE RECORDED, and the reason is that the owner's card offers more than one button.
+   * The mode the grant is minted under is the one the owner TAPPED, not the one the model requested,
+   * so the mint cannot know at ask time which key the row will carry — `grantScopeKeyForMode` picks
+   * it at approve time from the pair.
+   *
+   * 🔴 THIS FIELD DECIDES WHETHER THE 30-DAY ARM EXISTS AT ALL (OPE-2160). An ask carrying no key is
+   * rendered a card with NO standing button, and a `standing` mode that reaches the mint anyway is
+   * REFUSED — `grantScopeKeyForMode` answers `undefined` and nothing is bound. The old behaviour
+   * bound such a tap to {@link scopeKey} under a 30-day clock, and the next seat rotation ended it
+   * silently.
+   *
+   * 🔴 ABSENT FOR SIX REASONS, NOT ONE. It is recorded only when the ask was raised on an ATTENDED
+   * turn at a seat that IS the room's own conversation. So it is absent in a DM or group DM, on a
+   * conversation no platform mapper classified, in a room no operator declared into a domain, on an
+   * UNATTENDED delivery, on a seat that is neither a SEATED room's standing one nor an UNSEATED room's
+   * native one — a `thread` or `task` seat, which the ask verb still admits, and a `native` wake in a
+   * room that IS seated — and on a room whose domain name carries the `::` the room key packs its pair
+   * with. It is also absent on a row an older build wrote. In every one of those cases the seat keeps
+   * the exact-session rule for what it may READ, which is the pre-OPE-1950 behaviour — and, since
+   * OPE-2160, no standing grant may be MINTED from such an ask at all. So a reader must never assume
+   * that a standing row raised in a domain-declared room carries a conversation key: a row minted
+   * before OPE-2160 may carry a session id instead.
+   *
+   * 🔴 THE ROOM SHAPE DOES NOT EXCLUDE THREADS. An unseated deployment stamps no grain, so a thread
+   * reply there classifies `native` like every other wake and `domainKeyOf` collapses it onto the
+   * parent room. The `thread`-seat exclusion above is a fact about a SEATED deployment's domain key,
+   * never about the room key.
+   */
+  readonly domainScopeKey?: string;
+  /** MODEL-AUTHORED and therefore untrusted. Rendered as escaped, quoted data, never as copy. */
+  readonly purpose: string;
+  /**
+   * WHERE THE OWNER'S ANSWER IS REPORTED BACK — a JSON `ReplyTarget`, pinned when the ask is raised
+   * (OPE-1060 S3). Absent when the requester's surface hosts no mid-turn post arm.
+   *
+   * 🔴 IT IS PINNED, NOT RE-RESOLVED. The owner answers minutes later, from their own DM, in a
+   * request that carries no trace of the requesting room. Nothing at that moment can name the
+   * conversation the ask came from except a value the ask itself carried. The design's §6.4 promise —
+   * "the resolution arrives as a trigger back into the requester's conversation" — is exactly this
+   * column, and without it the requester learns the answer only by trying the tool.
+   *
+   * 🔴 IT IS RESOLVED FROM THE SESSION BINDING, NEVER FROM MODEL INPUT (`channels/reply-post.ts`
+   * `resolveReplyTarget`). A model-supplied target would let one turn address the owner's answer
+   * into a room the requester was never in.
+   */
+  readonly requesterTarget?: string;
+  readonly requestedMode: CredentialGrantMode;
+  /**
+   * WHERE THE OWNER'S CARD LANDED — the DM surface id and the message id the delivery named
+   * (OPE-1112). Stamped AFTER the row is inserted, because the card is delivered after the insert.
+   *
+   * 🔴 THEY EXIST SO A LAPSE CAN REWRITE THE CARD. An ask that ages out has no click behind it, so
+   * the sweep is the only thing that can tell the owner their card is dead — and it runs minutes
+   * later, in a process that holds nothing from the requester's turn. Nothing at that moment can
+   * name the message except a value the row itself carried.
+   *
+   * Absent means "no card locus was recorded": a pre-migration row, or a delivery whose arm named
+   * no message. Both read as "cannot rewrite the card", never as a guessed address.
+   */
+  readonly cardSurfaceId?: string;
+  readonly cardMessageId?: string;
+  readonly status: CredentialGrantAskState;
+  readonly createdAt: string;
+  /** The ASK's own TTL — short, and NOT the grant's. A late click must lose a CAS, not a UI check. */
+  readonly expiresAt: string;
+  readonly decidedAt?: string;
+  /** Set by the approve CAS, so an approved ask names the grant it minted. */
+  readonly grantId?: string;
+}
+
+/** One live (or spent) credential grant — what the mount projects and the broker enforces. */
+export interface CredentialGrantRow {
+  readonly id: string;
+  readonly askId: string;
+  readonly requesterPrincipalId: string;
+  readonly ownerPrincipalId: string;
+  /**
+   * The owner's segment of the mounted tool name, SLUGIFIED AND PINNED AT MINT.
+   *
+   * 🔴 It is pinned rather than derived per mount because a handle is not stable: handles change,
+   * carry punctuation and are not unique. A live grant whose name re-derived from a renamed handle
+   * would mount under a different tool name than the transcript already shows.
+   */
+  readonly ownerSlug: string;
+  readonly connector: string;
+  readonly verb: string;
+  readonly resource: string;
+  /** The vendor MCP tool this grant lends, in the vendor's exact bytes. See the ask row's field. */
+  readonly mcpTool?: string;
+  /** The arguments the owner froze. `{}` is "nothing frozen"; absent is "no borrow". Ask row's field. */
+  readonly frozenArgs?: GrantJsonObject;
+  /** The full mounted tool name, copied from the ask that minted this grant. Ask row's field. */
+  readonly toolName?: string;
+  /**
+   * THE INPUT SCHEMA THE MODEL IS OFFERED — the vendor tool's own schema with the frozen keys
+   * already subtracted, snapshotted at APPROVE time (OPE-1136).
+   *
+   * 🔴 A SNAPSHOT, because the catalogue is read from the live connection and a vendor may reshape a
+   * tool after the owner approved it. The snapshot is what the owner's decision was made against, so
+   * it is what the mount offers; a schema re-read per mount would let the vendor widen a grant the
+   * owner already answered.
+   *
+   * Absent on a row that carries no honest snapshot of its own — a row an older build wrote for the
+   * deleted verb-registry path (OPE-1334), which read its schema from a registered verb definition.
+   * Such a row mounts nothing rather than offering a guessed schema.
+   */
+  readonly inputSchema?: GrantJsonObject;
+  /**
+   * WHAT THIS GRANT IS BOUND TO. For `once` and `session` it is the asking eve session's id, and the
+   * grant dies with that session. For `standing` it is the ask's {@link CredentialGrantAskRow.domainScopeKey}
+   * (OPE-1950), which names either a domain or ONE room of one (OPE-2012), so a 30-day tap outlives
+   * the seat rotations inside those 30 days. Which of the two the mint wrote is decided by the
+   * APPROVED mode — see `access/credential-grant-scope.ts` `grantScopeKeyForMode`, and read it back
+   * through `grantScopeAdmits` rather than comparing this column by hand.
+   *
+   * 🔴 A `standing` ROW CANNOT BE MINTED WITHOUT THAT KEY (OPE-2160), so one is never written here
+   * with a session id today. A row minted BEFORE that rule can still carry one: the mint used to fall
+   * back to the asking session while the clock stamped the full 30 days, and the row went unreachable
+   * at the next seat rotation. Nothing rewrites such a row — it lapses on its own expiry — so a
+   * reader must test the SHAPE with `grantScopeKeyIsConversationStable` rather than assume the mode
+   * implies it. That is what keeps the lent tool from repeating a 30-day promise the key cannot keep.
+   */
+  readonly scopeKey: string;
+  readonly mode: CredentialGrantMode;
+  /**
+   * The granted call's consequence tier, decided ONCE at mint and never re-derived afterwards.
+   *
+   * 🔴 NEVER re-derived from the mounted name. A `grant__…` name puts a person's handle where a
+   * classifier looks for a verb (OPE-1060 S0 closed the false-open arm that let it LOWER a tier).
+   * The row is the authority.
+   *
+   * The mint pins the tier `classifyConnectorOpTier` gives `<connector>__<mcpTool>` — the
+   * byte-identical classification the owner's own DM makes for the same vendor op.
+   */
+  readonly tier: "read" | "write" | "destructive";
+  readonly status: CredentialGrantState;
+  readonly purpose: string;
+  readonly createdAt: string;
+  readonly expiresAt: string;
+  readonly usedAt?: string;
+  readonly revokedAt?: string;
+}
+
+/** 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: string): boolean {
+  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: string): string | undefined {
+  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: string): string | undefined {
+  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: string): string | undefined {
+  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: string): string | undefined {
+  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: string): boolean {
+  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: string, targetSlug: string | undefined, budget: number): string | undefined {
+  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: string): string | undefined {
+  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: string, connector: string, verbSegment: string): string {
+  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: string,
+  connector: string,
+  toolSlug: string,
+  targetSlug: string | undefined,
+  rowId: string,
+  taken: readonly string[],
+): string | undefined {
+  // 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: GrantJsonObject | undefined): string | null {
+  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: string | null | undefined, column: string): GrantJsonObject | undefined {
+  if (text === null || text === undefined) return undefined;
+  let parsed: unknown;
+  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 as GrantJsonObject;
+}
+
+/**
+ * `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: {
+  readonly mcpTool?: string;
+  readonly frozenArgs?: GrantJsonObject;
+  readonly toolName?: string;
+  readonly inputSchema?: GrantJsonObject;
+}): string | undefined {
+  // 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],
+  ] as const;
+  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: GrantJsonObject): string {
+  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: unknown, path: string, depth = 0): string {
+  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) as unknown;
+  if (proto !== Object.prototype && proto !== null) throw new Error(`credential grant row: ${path} is a ${(value as object).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 as Record<string, unknown>);
+  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(",")}}`;
+}
+
+/**
+ * Why the broker refused a call. Each name is a BOUNDARY the refusal copy states out loud.
+ *
+ * 🔴 `unattended_wake` MEANS "NOBODY IS IN THE ROOM" HERE (design §8.1, OPE-1094). The wake is an
+ * unattended scheduled fire, so no member of the conversation drove it. Do not read it as
+ * `access/member-plane.ts`'s `member_plane_nonmember_wake`, which is a different question on a
+ * different plane: that one means "this conversation carries a message from somebody the workspace
+ * could not vouch for". The two names come from two vocabularies and never mix — the member plane's
+ * value always carries its `member_plane_` prefix, and this one is only ever a grant refusal.
+ */
+export type CredentialGrantRefusal =
+  | "revoked"
+  | "expired"
+  | "burned"
+  | "out_of_scope"
+  | "no_lent_tool"
+  | "no_transport"
+  | "owner_unresolvable"
+  | "unverified_requester"
+  | "unattended_wake"
+  /** OPE-1602: a BREAK-GLASS HALT covers this call. Not a property of the grant row at all — the
+   *  grant stays exactly as live as it was, and the same call works again after `resume`. */
+  | "halted"
+  /**
+   * OPE-1457: this deployment admits no credential grant for the row's connector — the reviewed list
+   * `CREDENTIAL_GRANT_ROLES` (access/credential-grant.ts) does not name it.
+   *
+   * 🔴 IT IS NOT `no_transport`, AND THE DIFFERENCE IS THE WHOLE POINT. `no_transport` means this
+   * deployment carries no way to send the call; this means it carries no PERMISSION to. A connector
+   * removed from the reviewed list can still have a transport registered for it — the registry takes
+   * a bundle's registration for any connector core did not claim first — so the two questions have
+   * different answers exactly where it matters.
+   */
+  | "connector_delisted";
+
+/**
+ * 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: CredentialGrantRow, nowIso: string): CredentialGrantRefusal | undefined {
+  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: string | undefined): number | undefined {
+  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: unknown): GrantUndispatchedError {
+  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: Pick<CredentialGrantRow, "ownerSlug" | "resource" | "connector" | "mcpTool">,
+  reason: CredentialGrantRefusal,
+): string {
+  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: Pick<CredentialGrantRow, "ownerSlug" | "connector" | "mcpTool" | "resource" | "frozenArgs" | "expiresAt" | "purpose" | "mode" | "scopeKey">,
+  nowMs: number,
+): string {
+  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: string, mcpTool: string, frozenArgs: GrantJsonObject): string {
+  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: { readonly resource: string; readonly mcpTool?: string; readonly frozenArgs?: GrantJsonObject }): string | undefined {
+  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: { readonly resource: string; readonly mcpTool?: string; readonly frozenArgs?: GrantJsonObject }): string {
+  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: string): string {
+  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: string): string {
+  const flat = label.replace(/[\r\n]+/gu, " ").trim();
+  return flat.length > 200 ? `${flat.slice(0, 197)}...` : flat;
+}