@vellumai/assistant 0.4.5 → 0.4.7

package/src/memory/job-handlers/backfill.ts

@@ -29,16 +29,9 @@ type ProvenanceTrustClass = 'guardian' | 'trusted_contact' | 'unknown';
 function parseProvenanceTrustClass(rawMetadata: string | null): ProvenanceTrustClass | undefined {
   if (!rawMetadata) return undefined;
   try {
-    const parsedJson: unknown = JSON.parse(rawMetadata);
-    const parsed = messageMetadataSchema.safeParse(parsedJson);
+    const parsed = messageMetadataSchema.safeParse(JSON.parse(rawMetadata));
     if (!parsed.success) return undefined;
-    if (parsed.data.provenanceTrustClass) return parsed.data.provenanceTrustClass;
-    // Legacy fallback for rows written before provenanceTrustClass existed.
-    const legacyRole = (parsedJson as { provenanceActorRole?: unknown }).provenanceActorRole;
-    if (legacyRole === 'guardian') return 'guardian';
-    if (legacyRole === 'non-guardian') return 'trusted_contact';
-    if (legacyRole === 'unverified_channel') return 'unknown';
-    return undefined;
+    return parsed.data.provenanceTrustClass;
   } catch {
     return undefined;
   }

package/src/memory/migrations/039-actor-refresh-token-records.ts

@@ -0,0 +1,51 @@
+import type { DrizzleDb } from '../db-connection.js';
+
+/**
+ * Create the actor_refresh_token_records table for hash-only refresh token persistence.
+ *
+ * Stores the SHA-256 hash of each refresh token with family tracking,
+ * device binding, and dual expiry (absolute + inactivity).
+ * The raw token plaintext is never stored.
+ */
+export function createActorRefreshTokenRecordsTable(database: DrizzleDb): void {
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS actor_refresh_token_records (
+      id TEXT PRIMARY KEY,
+      token_hash TEXT NOT NULL,
+      family_id TEXT NOT NULL,
+      assistant_id TEXT NOT NULL,
+      guardian_principal_id TEXT NOT NULL,
+      hashed_device_id TEXT NOT NULL,
+      platform TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'active',
+      issued_at INTEGER NOT NULL,
+      absolute_expires_at INTEGER NOT NULL,
+      inactivity_expires_at INTEGER NOT NULL,
+      last_used_at INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+
+  // Token hash lookup (any status — needed for replay detection)
+  database.run(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_refresh_tokens_hash
+      ON actor_refresh_token_records(token_hash)`,
+  );
+
+  // Unique active refresh token per device binding.
+  // DROP first so that databases that already created the older non-unique
+  // index with the same name get upgraded to UNIQUE.
+  database.run(/*sql*/ `DROP INDEX IF EXISTS idx_refresh_tokens_active_device`);
+  database.run(
+    /*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_refresh_tokens_active_device
+      ON actor_refresh_token_records(assistant_id, guardian_principal_id, hashed_device_id)
+      WHERE status = 'active'`,
+  );
+
+  // Family lookup for replay detection (revoke entire family)
+  database.run(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_refresh_tokens_family
+      ON actor_refresh_token_records(family_id)`,
+  );
+}

package/src/memory/migrations/125-guardian-principal-id-columns.ts

@@ -0,0 +1,19 @@
+import type { DrizzleDb } from '../db-connection.js';
+
+/**
+ * Add guardian_principal_id columns to channel_guardian_bindings and
+ * canonical_guardian_requests, plus decided_by_principal_id to
+ * canonical_guardian_requests.
+ *
+ * These nullable TEXT columns support the canonical identity binding
+ * cutover — linking guardian bindings and approval requests to a
+ * stable principal identity rather than relying solely on
+ * channel-specific external user IDs.
+ *
+ * Uses ALTER TABLE ADD COLUMN with try/catch for idempotency.
+ */
+export function migrateGuardianPrincipalIdColumns(database: DrizzleDb): void {
+  try { database.run(/*sql*/ `ALTER TABLE channel_guardian_bindings ADD COLUMN guardian_principal_id TEXT`); } catch { /* already exists */ }
+  try { database.run(/*sql*/ `ALTER TABLE canonical_guardian_requests ADD COLUMN guardian_principal_id TEXT`); } catch { /* already exists */ }
+  try { database.run(/*sql*/ `ALTER TABLE canonical_guardian_requests ADD COLUMN decided_by_principal_id TEXT`); } catch { /* already exists */ }
+}

package/src/memory/migrations/126-backfill-guardian-principal-id.ts

@@ -0,0 +1,210 @@
+import { type DrizzleDb, getSqliteFrom } from '../db-connection.js';
+import { withCrashRecovery } from './validate-migration-state.js';
+
+/**
+ * Backfill guardianPrincipalId for existing channel_guardian_bindings and
+ * canonical_guardian_requests rows.
+ *
+ * Strategy:
+ *
+ * 1. Derive the assistant's canonical principal from the active 'vellum'
+ *    binding's guardianExternalUserId. This is the stable identity used for
+ *    all guardian decisions from the desktop client.
+ *
+ * 2. Backfill channel_guardian_bindings:
+ *    a. For the vellum binding: set guardianPrincipalId = guardianExternalUserId
+ *       (the vellum external user ID IS the canonical principal).
+ *    b. For non-vellum bindings: set guardianPrincipalId to the vellum
+ *       binding's principal (unifying all channels onto one canonical
+ *       principal). Falls back to guardianExternalUserId if no vellum
+ *       binding exists.
+ *
+ * 3. Backfill canonical_guardian_requests (pending only):
+ *    a. If the request has a guardianExternalUserId that maps to an active
+ *       binding, use that binding's guardianPrincipalId (now backfilled).
+ *    b. For desktop-originated requests (sourceType = 'desktop' or
+ *       sourceChannel = 'vellum') that lack guardianExternalUserId,
+ *       use the assistant principal derived in step 1.
+ *    c. Pending requests that cannot be deterministically bound are expired
+ *       (including access_request rows, which are now principal-bound).
+ *
+ * 4. Idempotent: uses checkpoint key + only updates rows with NULL
+ *    guardianPrincipalId.
+ */
+export function migrateBackfillGuardianPrincipalId(database: DrizzleDb): void {
+  withCrashRecovery(database, 'migration_backfill_guardian_principal_id_v3', () => {
+    const raw = getSqliteFrom(database);
+
+    // Guard: tables must exist
+    const bindingsTableExists = raw.query(
+      `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'channel_guardian_bindings'`,
+    ).get();
+    if (!bindingsTableExists) return;
+
+    const requestsTableExists = raw.query(
+      `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'canonical_guardian_requests'`,
+    ).get();
+
+    // Guard: guardian_principal_id column must exist on bindings table
+    const bindingColExists = raw.query(
+      `SELECT 1 FROM pragma_table_info('channel_guardian_bindings') WHERE name = 'guardian_principal_id'`,
+    ).get();
+    if (!bindingColExists) return;
+
+    try {
+      raw.exec('BEGIN');
+
+      // ── Step 1a: Backfill vellum binding first ─────────────────────
+      // The vellum binding's external user ID IS the canonical principal.
+      raw.exec(/*sql*/ `
+        UPDATE channel_guardian_bindings
+        SET guardian_principal_id = guardian_external_user_id,
+            updated_at = ${Date.now()}
+        WHERE status = 'active'
+          AND channel = 'vellum'
+          AND guardian_external_user_id IS NOT NULL
+          AND guardian_principal_id IS NULL
+      `);
+
+      // ── Step 1b: Derive canonical principal from vellum binding ──
+      const vellumRow = raw.query(
+        `SELECT guardian_principal_id FROM channel_guardian_bindings
+         WHERE assistant_id = 'self' AND channel = 'vellum' AND status = 'active'
+         AND guardian_principal_id IS NOT NULL LIMIT 1`,
+      ).get() as { guardian_principal_id: string } | null;
+
+      if (vellumRow) {
+        // Unify non-vellum bindings onto the canonical principal
+        raw.query(
+          `UPDATE channel_guardian_bindings
+           SET guardian_principal_id = ?,
+               updated_at = ${Date.now()}
+           WHERE status = 'active'
+             AND channel != 'vellum'
+             AND guardian_external_user_id IS NOT NULL
+             AND guardian_principal_id IS NULL`,
+        ).run(vellumRow.guardian_principal_id);
+      } else {
+        // No vellum binding — fallback to channel-specific principal
+        raw.exec(/*sql*/ `
+          UPDATE channel_guardian_bindings
+          SET guardian_principal_id = guardian_external_user_id,
+              updated_at = ${Date.now()}
+          WHERE status = 'active'
+            AND guardian_external_user_id IS NOT NULL
+            AND guardian_principal_id IS NULL
+        `);
+      }
+
+      // ── Step 2: Derive assistant principal from vellum binding ─────
+      // The vellum binding's guardianExternalUserId is the canonical
+      // assistant principal used for desktop-originated requests.
+      const vellumBinding = raw.query(
+        `SELECT guardian_external_user_id, guardian_principal_id FROM channel_guardian_bindings WHERE assistant_id = 'self' AND channel = 'vellum' AND status = 'active' LIMIT 1`,
+      ).get() as { guardian_external_user_id: string; guardian_principal_id: string | null } | null;
+
+      // Use the (now-backfilled) principal from the vellum binding
+      const assistantPrincipal = vellumBinding?.guardian_principal_id ?? vellumBinding?.guardian_external_user_id ?? null;
+
+      // ── Step 3: Backfill canonical_guardian_requests ────────────────
+      if (requestsTableExists) {
+        const requestColExists = raw.query(
+          `SELECT 1 FROM pragma_table_info('canonical_guardian_requests') WHERE name = 'guardian_principal_id'`,
+        ).get();
+
+        if (requestColExists) {
+          const now = new Date().toISOString();
+
+          // 3a. Pending requests with a guardianExternalUserId that maps
+          // to an active binding — use the binding's principal.
+          // Includes all kinds; binding is always useful when available.
+          const pendingWithGuardian = raw.query(
+            `SELECT r.id, r.guardian_external_user_id, r.kind
+             FROM canonical_guardian_requests r
+             WHERE r.status = 'pending'
+               AND r.guardian_principal_id IS NULL
+               AND r.guardian_external_user_id IS NOT NULL`,
+          ).all() as Array<{ id: string; guardian_external_user_id: string; kind: string }>;
+
+          // Build a lookup of guardianExternalUserId -> principalId from
+          // active bindings (all already backfilled in step 1).
+          const activeBindings = raw.query(
+            `SELECT guardian_external_user_id, guardian_principal_id
+             FROM channel_guardian_bindings
+             WHERE assistant_id = 'self' AND status = 'active' AND guardian_principal_id IS NOT NULL`,
+          ).all() as Array<{ guardian_external_user_id: string; guardian_principal_id: string }>;
+
+          const externalToP = new Map<string, string>();
+          for (const b of activeBindings) {
+            externalToP.set(b.guardian_external_user_id, b.guardian_principal_id);
+          }
+
+          const updateStmt = raw.prepare(
+            `UPDATE canonical_guardian_requests SET guardian_principal_id = ?, updated_at = ? WHERE id = ?`,
+          );
+          const expireStmt = raw.prepare(
+            `UPDATE canonical_guardian_requests SET status = 'expired', updated_at = ? WHERE id = ?`,
+          );
+
+          const unboundRequestIds: string[] = [];
+
+          for (const req of pendingWithGuardian) {
+            const principal = externalToP.get(req.guardian_external_user_id);
+            if (principal) {
+              updateStmt.run(principal, now, req.id);
+            } else {
+              // Cannot deterministically map — will expire below.
+              unboundRequestIds.push(req.id);
+            }
+          }
+
+          // 3b. Desktop-originated pending requests missing guardian info
+          // entirely — bind to the assistant principal. Only applies to
+          // requests that also lack a guardian external user ID; requests
+          // that carry an external ID but failed step 3a mapping should be
+          // expired, not reassigned.
+          if (assistantPrincipal) {
+            raw.query(
+              `UPDATE canonical_guardian_requests
+               SET guardian_principal_id = ?, updated_at = ?
+               WHERE status = 'pending'
+                 AND guardian_principal_id IS NULL
+                 AND guardian_external_user_id IS NULL
+                 AND (source_type = 'desktop' OR source_channel = 'vellum')`,
+            ).run(assistantPrincipal, now);
+          }
+
+          // 3c. Expire remaining pending requests that still have no
+          // guardian_principal_id. These requests can never be approved
+          // in the principal-based system, so they must be expired
+          // proactively. This includes access_request rows which are
+          // now decisionable and principal-bound.
+          const stillUnbound = raw.query(
+            `SELECT id FROM canonical_guardian_requests
+             WHERE guardian_principal_id IS NULL
+               AND status = 'pending'`,
+          ).all() as Array<{ id: string }>;
+
+          for (const req of stillUnbound) {
+            expireStmt.run(now, req.id);
+          }
+
+          // Also expire requests identified in 3a that had no binding match.
+          for (const id of unboundRequestIds) {
+            const check = raw.query(
+              `SELECT guardian_principal_id FROM canonical_guardian_requests WHERE id = ? AND status = 'pending'`,
+            ).get(id) as { guardian_principal_id: string | null } | null;
+            if (check && !check.guardian_principal_id) {
+              expireStmt.run(now, id);
+            }
+          }
+        }
+      }
+
+      raw.exec('COMMIT');
+    } catch (e) {
+      try { raw.exec('ROLLBACK'); } catch { /* no active transaction */ }
+      throw e;
+    }
+  });
+}

package/src/memory/migrations/index.ts

@@ -40,6 +40,7 @@ export { migrateGuardianActionSupersession } from './035-guardian-action-superse
 export { migrateNormalizePhoneIdentities } from './036-normalize-phone-identities.js';
 export { migrateVoiceInviteColumns } from './037-voice-invite-columns.js';
 export { createActorTokenRecordsTable } from './038-actor-token-records.js';
+export { createActorRefreshTokenRecordsTable } from './039-actor-refresh-token-records.js';
 export { createCoreTables } from './100-core-tables.js';
 export { createWatchersAndLogsTables } from './101-watchers-and-logs.js';
 export { addCoreColumns } from './102-alter-table-columns.js';
@@ -65,6 +66,8 @@ export { createCanonicalGuardianTables } from './121-canonical-guardian-requests
 export { migrateCanonicalGuardianRequesterChatId } from './122-canonical-guardian-requester-chat-id.js';
 export { migrateCanonicalGuardianDeliveriesDestinationIndex } from './123-canonical-guardian-deliveries-destination-index.js';
 export { migrateVoiceInviteDisplayMetadata } from './124-voice-invite-display-metadata.js';
+export { migrateGuardianPrincipalIdColumns } from './125-guardian-principal-id-columns.js';
+export { migrateBackfillGuardianPrincipalId } from './126-backfill-guardian-principal-id.js';
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

package/src/memory/migrations/registry.ts

@@ -95,6 +95,11 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     version: 14,
     description: 'Normalize phone-like identity fields to E.164 format across guardian bindings, verification challenges, canonical requests, ingress members, and rate limits',
   },
+  {
+    key: 'migration_backfill_guardian_principal_id_v3',
+    version: 15,
+    description: 'Backfill guardianPrincipalId for existing channel_guardian_bindings and canonical_guardian_requests rows, expire unresolvable pending requests',
+  },
 ];
 
 export interface MigrationValidationResult {

package/src/memory/schema.ts

@@ -637,6 +637,7 @@ export const channelGuardianBindings = sqliteTable('channel_guardian_bindings',
   channel: text('channel').notNull(),
   guardianExternalUserId: text('guardian_external_user_id').notNull(),
   guardianDeliveryChatId: text('guardian_delivery_chat_id').notNull(),
+  guardianPrincipalId: text('guardian_principal_id'),
   status: text('status').notNull().default('active'),
   verifiedAt: integer('verified_at').notNull(),
   verifiedVia: text('verified_via').notNull().default('challenge'),
@@ -887,6 +888,7 @@ export const canonicalGuardianRequests = sqliteTable('canonical_guardian_request
   requesterExternalUserId: text('requester_external_user_id'),
   requesterChatId: text('requester_chat_id'),
   guardianExternalUserId: text('guardian_external_user_id'),
+  guardianPrincipalId: text('guardian_principal_id'),
   callSessionId: text('call_session_id'),
   pendingQuestionId: text('pending_question_id'),
   questionText: text('question_text'),
@@ -896,6 +898,7 @@ export const canonicalGuardianRequests = sqliteTable('canonical_guardian_request
   status: text('status').notNull().default('pending'),
   answerText: text('answer_text'),
   decidedByExternalUserId: text('decided_by_external_user_id'),
+  decidedByPrincipalId: text('decided_by_principal_id'),
   followupState: text('followup_state'),
   expiresAt: text('expires_at'),
   createdAt: text('created_at').notNull(),
@@ -1159,6 +1162,25 @@ export const actorTokenRecords = sqliteTable('actor_token_records', {
   updatedAt: integer('updated_at').notNull(),
 });
 
+// ── Actor Refresh Token Records ──────────────────────────────────────
+
+export const actorRefreshTokenRecords = sqliteTable('actor_refresh_token_records', {
+  id: text('id').primaryKey(),
+  tokenHash: text('token_hash').notNull(),
+  familyId: text('family_id').notNull(),
+  assistantId: text('assistant_id').notNull(),
+  guardianPrincipalId: text('guardian_principal_id').notNull(),
+  hashedDeviceId: text('hashed_device_id').notNull(),
+  platform: text('platform').notNull(),
+  status: text('status').notNull().default('active'),
+  issuedAt: integer('issued_at').notNull(),
+  absoluteExpiresAt: integer('absolute_expires_at').notNull(),
+  inactivityExpiresAt: integer('inactivity_expires_at').notNull(),
+  lastUsedAt: integer('last_used_at'),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});
+
 // ── Scoped Approval Grants ──────────────────────────────────────────
 
 export const scopedApprovalGrants = sqliteTable('scoped_approval_grants', {

package/src/notifications/README.md

@@ -51,7 +51,14 @@ When the LLM is unavailable or returns invalid output, a deterministic fallback
 
 ### 4. Deterministic Checks
 
-Hard invariants that the LLM cannot override (`deterministic-checks.ts`):
+Hard invariants that the LLM cannot override:
+
+**Post-generation enforcement** (`decision-engine.ts`):
+
+- **Guardian question request-code enforcement** — `enforceGuardianRequestCode()` ensures request-code instructions (approve/reject or free-text answer) appear in all `guardian.question` notification copy, even when the LLM omits them.
+- **Access-request instruction enforcement** — `enforceAccessRequestInstructions()` validates that `ingress.access_request` copy contains: (1) the request-code approve/reject directive, (2) the exact "open invite flow" phrase. If any required element is missing, the full deterministic contract text is appended. This prevents model-generated copy from dropping security-critical action directives.
+
+**Pre-send gate checks** (`deterministic-checks.ts`):
 
 - **Schema validity** -- fail-closed if the decision is malformed
 - **Source-active suppression** -- if the user is already viewing the source context, suppress

package/src/notifications/copy-composer.ts

@@ -29,6 +29,162 @@ export function nonEmpty(value: string | undefined): string | undefined {
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
+// ── Access-request copy contract ─────────────────────────────────────────────
+//
+// Deterministic helpers for building guardian-facing access-request copy.
+// These are used both by the fallback template and the decision-engine
+// post-generation enforcement to ensure required directives always appear.
+
+const IDENTITY_FIELD_MAX_LENGTH = 120;
+
+/**
+ * Sanitize an untrusted identity field for inclusion in notification copy.
+ *
+ * - Strips control characters (U+0000–U+001F, U+007F–U+009F) and newlines.
+ * - Clamps to IDENTITY_FIELD_MAX_LENGTH characters.
+ * - Wraps in quotes to neutralize instruction-like payload text.
+ */
+export function sanitizeIdentityField(value: string): string {
+  const stripped = value.replace(/[\x00-\x1f\x7f-\x9f\r\n]+/g, ' ').trim();
+  const clamped = stripped.length > IDENTITY_FIELD_MAX_LENGTH
+    ? stripped.slice(0, IDENTITY_FIELD_MAX_LENGTH) + '…'
+    : stripped;
+  return clamped;
+}
+
+export function buildAccessRequestIdentityLine(payload: Record<string, unknown>): string {
+  const requester = sanitizeIdentityField(str(payload.senderIdentifier, 'Someone'));
+  const sourceChannel = typeof payload.sourceChannel === 'string' ? payload.sourceChannel : undefined;
+  const callerName = nonEmpty(typeof payload.actorDisplayName === 'string' ? payload.actorDisplayName : undefined);
+  const actorUsername = nonEmpty(typeof payload.actorUsername === 'string' ? payload.actorUsername : undefined);
+  const actorExternalId = nonEmpty(typeof payload.actorExternalId === 'string' ? payload.actorExternalId : undefined);
+
+  if (sourceChannel === 'voice' && callerName) {
+    const safeName = sanitizeIdentityField(callerName);
+    const safeId = sanitizeIdentityField(str(payload.actorExternalId, requester));
+    return `${safeName} (${safeId}) is calling and requesting access to the assistant.`;
+  }
+
+  // For non-voice, include extra context when available.
+  // Sanitize before comparing to avoid deduplication failures when identity
+  // fields contain control characters that are stripped from `requester`.
+  const sanitizedUsername = actorUsername ? sanitizeIdentityField(actorUsername) : undefined;
+  const sanitizedExternalId = actorExternalId ? sanitizeIdentityField(actorExternalId) : undefined;
+  const parts = [requester];
+  if (sanitizedUsername && sanitizedUsername !== requester) {
+    parts.push(`@${sanitizedUsername}`);
+  }
+  if (sanitizedExternalId && sanitizedExternalId !== requester && sanitizedExternalId !== sanitizedUsername) {
+    parts.push(`[${sanitizedExternalId}]`);
+  }
+  if (sourceChannel) {
+    parts.push(`via ${sourceChannel}`);
+  }
+
+  return `${parts.join(' ')} is requesting access to the assistant.`;
+}
+
+export function buildAccessRequestDecisionDirective(requestCode: string): string {
+  const code = requestCode.toUpperCase();
+  return `Reply "${code} approve" to grant access or "${code} reject" to deny.`;
+}
+
+export function buildAccessRequestInviteDirective(): string {
+  return 'Reply "open invite flow" to start Trusted Contacts invite flow.';
+}
+
+export function buildAccessRequestRevokedNote(): string {
+  return 'Note: this user was previously revoked.';
+}
+
+/**
+ * Normalize text before running directive-matching regexes.
+ *
+ * - Replaces smart/curly apostrophes (\u2018, \u2019, \u201B) with ASCII `'`
+ *   so contractions like "Don\u2019t" are matched by the `n't` lookbehind.
+ * - Collapses runs of whitespace into a single space so "Do not   reply"
+ *   is matched by the single-space negative lookbehind.
+ * - Trims leading/trailing whitespace.
+ */
+export function normalizeForDirectiveMatching(text: string): string {
+  return text
+    .replace(/[\u2018\u2019\u201B]/g, "'")
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Check whether a text contains the required access-request instruction elements:
+ * 1. Approve directive: Reply "CODE approve"
+ * 2. Reject directive: Reply "CODE reject"
+ * 3. Invite directive: Reply "open invite flow"
+ *
+ * Each directive is matched independently using negative lookbehind to reject
+ * matches preceded by negation words ("not", "n't", "never"). This prevents
+ * contradictory copy like `Do not reply "CODE reject"` from satisfying the
+ * check even when a positive approve directive exists nearby.
+ *
+ * The text is normalized before matching to handle smart apostrophes and
+ * multiple whitespace characters that would otherwise bypass negation detection.
+ */
+export function hasAccessRequestInstructions(
+  text: string | undefined,
+  requestCode: string,
+): boolean {
+  if (typeof text !== 'string') return false;
+  const normalized = normalizeForDirectiveMatching(text);
+  const escapedCode = requestCode.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Each directive must follow "reply" without a preceding negation word.
+  // Negative lookbehinds reject "do not reply", "don't reply", "never reply".
+  const approveRe = new RegExp(
+    `(?<!not\\s)(?<!n't\\s)(?<!never\\s)reply\\b[^.!?\\n]*?"${escapedCode}\\s+approve"`,
+    'i',
+  );
+  const rejectRe = new RegExp(
+    `(?<!not\\s)(?<!n't\\s)(?<!never\\s)reply\\b[^.!?\\n]*?"${escapedCode}\\s+reject"`,
+    'i',
+  );
+  const inviteRe = /(?<!not\s)(?<!n't\s)(?<!never\s)reply\b[^.!?\n]*?"open invite flow"/i;
+
+  return approveRe.test(normalized) && rejectRe.test(normalized) && inviteRe.test(normalized);
+}
+
+/**
+ * Check whether text contains the invite-flow directive ("open invite flow")
+ * using the same normalized negative-lookbehind pattern as the full check.
+ * This is used for enforcement when requestCode is absent but the invite
+ * directive should still be present.
+ */
+export function hasInviteFlowDirective(text: string | undefined): boolean {
+  if (typeof text !== 'string') return false;
+  const normalized = normalizeForDirectiveMatching(text);
+  const inviteRe = /(?<!not\s)(?<!n't\s)(?<!never\s)reply\b[^.!?\n]*?"open invite flow"/i;
+  return inviteRe.test(normalized);
+}
+
+/**
+ * Build the deterministic access-request contract text from payload fields.
+ * This is the canonical baseline that enforcement can append when generated
+ * copy is missing required elements.
+ */
+export function buildAccessRequestContractText(payload: Record<string, unknown>): string {
+  const requestCode = nonEmpty(typeof payload.requestCode === 'string' ? payload.requestCode : undefined);
+  const previousMemberStatus = typeof payload.previousMemberStatus === 'string'
+    ? payload.previousMemberStatus
+    : undefined;
+
+  const lines: string[] = [];
+  lines.push(buildAccessRequestIdentityLine(payload));
+  if (previousMemberStatus === 'revoked') {
+    lines.push(buildAccessRequestRevokedNote());
+  }
+  if (requestCode) {
+    lines.push(buildAccessRequestDecisionDirective(requestCode));
+  }
+  lines.push(buildAccessRequestInviteDirective());
+  return lines.join('\n');
+}
+
 // Templates keyed by dot-separated sourceEventName strings matching producers.
 const TEMPLATES: Record<string, CopyTemplate> = {
   'reminder.fired': (payload) => ({
@@ -60,36 +216,10 @@ const TEMPLATES: Record<string, CopyTemplate> = {
     };
   },
 
-  'ingress.access_request': (payload) => {
-    const requester = str(payload.senderIdentifier, 'Someone');
-    const requestCode = nonEmpty(typeof payload.requestCode === 'string' ? payload.requestCode : undefined);
-    const sourceChannel = typeof payload.sourceChannel === 'string' ? payload.sourceChannel : undefined;
-    const callerName = nonEmpty(typeof payload.senderName === 'string' ? payload.senderName : undefined);
-    const previousMemberStatus = typeof payload.previousMemberStatus === 'string'
-      ? payload.previousMemberStatus
-      : undefined;
-    const lines: string[] = [];
-
-    // Voice-originated access requests include caller name context
-    if (sourceChannel === 'voice' && callerName) {
-      lines.push(`${callerName} (${str(payload.senderExternalUserId, requester)}) is calling and requesting access to the assistant.`);
-    } else {
-      lines.push(`${requester} is requesting access to the assistant.`);
-    }
-    if (previousMemberStatus === 'revoked') {
-      lines.push('Note: this user was previously revoked.');
-    }
-
-    if (requestCode) {
-      const code = requestCode.toUpperCase();
-      lines.push(`Reply "${code} approve" to grant access or "${code} reject" to deny.`);
-    }
-    lines.push('Reply "open invite flow" to start Trusted Contacts invite flow.');
-    return {
-      title: 'Access Request',
-      body: lines.join('\n'),
-    };
-  },
+  'ingress.access_request': (payload) => ({
+    title: 'Access Request',
+    body: buildAccessRequestContractText(payload),
+  }),
 
   'ingress.access_request.callback_handoff': (payload) => {
     const callerName = nonEmpty(typeof payload.callerName === 'string' ? payload.callerName : undefined);