@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/features/contracts/knowledgePolicy.ts

@@ -0,0 +1,249 @@
+import { z } from 'zod'
+import type { FieldDecl, ZoneDecl } from '../../elements'
+import type { SiteManifest } from '../../site/types'
+import { KnowledgeTitleSchema } from './knowledge'
+
+export type TextSingleProjection = { kind: 'text' }
+export type FieldProjection =
+  | { kind: 'text'; tokens?: Record<string, TextSingleProjection> }
+  | { kind: 'group'; fields: Record<string, FieldProjection> }
+  | { kind: 'list'; item: FieldProjection }
+  | { kind: 'zone'; blocks: ZoneProjection }
+  | { kind: 'single'; key: string; value: FieldProjection }
+  | { kind: 'entries'; collection: string; fields: Record<string, FieldProjection> }
+export type ZoneProjection = Record<
+  string,
+  { fields: Record<string, FieldProjection>; entryFields?: Record<string, FieldProjection> }
+>
+export type PageProjection = {
+  title: { from: 'pageTitle' } | { from: 'literal'; value: string }
+  blocks: ZoneProjection
+  layouts?: Record<string, ZoneProjection>
+}
+export type EntryProjection = {
+  title: { from: 'field'; field: string } | { from: 'literal'; value: string }
+  blocks: ZoneProjection
+  layouts?: Record<string, ZoneProjection>
+}
+export type KnowledgePolicyV1 = {
+  version: 1
+  pages: Record<string, PageProjection>
+  pageTypes: Record<string, PageProjection>
+  collections: Record<string, EntryProjection>
+}
+export const KNOWLEDGE_POLICY_LIMITS = {
+  bytes: 256 * 1024,
+  depth: 12,
+  selectors: 2000,
+  hops: 3,
+  references: 100,
+} as const
+const name = z
+  .string()
+  .regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/)
+  .refine((v) => !['__proto__', 'constructor', 'prototype'].includes(v))
+const fields = (): z.ZodType<Record<string, FieldProjection>> => z.record(name, field)
+const field: z.ZodType<FieldProjection> = z.lazy(() =>
+  z.discriminatedUnion('kind', [
+    z.strictObject({
+      kind: z.literal('text'),
+      tokens: z.record(name, z.strictObject({ kind: z.literal('text') })).optional(),
+    }),
+    z.strictObject({ kind: z.literal('group'), fields: fields() }),
+    z.strictObject({ kind: z.literal('list'), item: field }),
+    z.strictObject({ kind: z.literal('zone'), blocks: zone }),
+    z.strictObject({ kind: z.literal('single'), key: name, value: field }),
+    z.strictObject({ kind: z.literal('entries'), collection: name, fields: fields() }),
+  ]),
+)
+const zone: z.ZodType<ZoneProjection> = z.record(
+  name,
+  z.strictObject({ fields: fields(), entryFields: fields().optional() }),
+)
+const literal = z.strictObject({ from: z.literal('literal'), value: KnowledgeTitleSchema })
+const page = z.strictObject({
+  title: z.union([z.strictObject({ from: z.literal('pageTitle') }), literal]),
+  blocks: zone,
+  layouts: z.record(name, zone).optional(),
+})
+const entry = z.strictObject({
+  title: z.union([z.strictObject({ from: z.literal('field'), field: name }), literal]),
+  blocks: zone,
+  layouts: z.record(name, zone).optional(),
+})
+// Bound traversal before recursive Zod parsing, including cyclic non-JSON callers.
+const bounded = (v: unknown): boolean => {
+  let selectors = 0
+  const seen = new Set<object>()
+  const walk = (x: unknown, depth: number): boolean => {
+    if (depth > 12) return false
+    if (!x || typeof x !== 'object') return true
+    if (seen.has(x)) return false
+    seen.add(x)
+    if ('kind' in x && ++selectors > 2000) return false
+    const ok = Object.values(x).every((y) => walk(y, depth + 1))
+    seen.delete(x)
+    return ok
+  }
+  try {
+    return (
+      walk(v, 0) &&
+      new TextEncoder().encode(JSON.stringify(v)).byteLength <= KNOWLEDGE_POLICY_LIMITS.bytes
+    )
+  } catch {
+    return false
+  }
+}
+export const KnowledgePolicySchema: z.ZodType<KnowledgePolicyV1> = z
+  .unknown()
+  .refine(bounded, 'Knowledge policy exceeds its bounds.')
+  .pipe(
+    z.strictObject({
+      version: z.literal(1),
+      pages: z.record(name, page),
+      pageTypes: z.record(name, page),
+      collections: z.record(name, entry),
+    }),
+  )
+const textLike = (d: FieldDecl | undefined) =>
+  !!d &&
+  'element' in d &&
+  (d.element === 'u90/rich-text' || (d.element === 'u90/text' && d.options?.format !== 'code'))
+/** Independent manifest validation. Pairing itself deliberately does not invoke this gate. */
+export function validateKnowledgePolicy(
+  manifest: SiteManifest,
+  input: unknown = manifest.knowledge,
+): { ready: true; policy: KnowledgePolicyV1 } | { ready: false; reason: string } {
+  const parsed = KnowledgePolicySchema.safeParse(input)
+  if (!parsed.success)
+    return {
+      ready: false,
+      reason: input === undefined ? 'Knowledge policy missing.' : 'Invalid knowledge policy.',
+    }
+  const m = manifest
+  function assert(ok: unknown, reason: string): asserts ok {
+    if (!ok) throw new Error(reason)
+  }
+  const own = <T>(record: Record<string, T>, key: string): T | undefined =>
+    Object.hasOwn(record, key) ? record[key] : undefined
+  const selectFields = (
+    selectors: Record<string, FieldProjection>,
+    declarations: Record<string, FieldDecl>,
+    collection?: string,
+    hops = 0,
+    budget = 3,
+  ) => {
+    for (const [key, selector] of Object.entries(selectors))
+      select(selector, own(declarations, key), collection, hops, budget)
+  }
+  const select = (
+    p: FieldProjection,
+    d: FieldDecl | undefined,
+    collection?: string,
+    hops = 0,
+    budget = 3,
+  ): void => {
+    assert(d, 'Unknown selected field.')
+    assert(hops <= 3, 'Reference hop ceiling exceeded.')
+    if (p.kind === 'text') {
+      assert(textLike(d), 'Selected field is not non-code text.')
+      for (const key of Object.keys(p.tokens ?? {}))
+        assert(textLike(own(m.schema.singles, key)?.field), 'Token must name a text Single.')
+    } else if (p.kind === 'group') {
+      assert('container' in d && d.container === 'u90/group', 'Expected group.')
+      selectFields(p.fields, d.fields, collection, hops, budget)
+    } else if (p.kind === 'list') {
+      assert('container' in d && d.container === 'u90/list', 'Expected list.')
+      select(p.item, d.item, collection, hops, budget)
+    } else if (p.kind === 'zone') {
+      assert('container' in d && d.container === 'u90/zone', 'Expected zone.')
+      selectZone(p.blocks, d, collection, hops, budget)
+    } else if (p.kind === 'single') {
+      assert(
+        'element' in d && d.element === 'u90/single' && d.options?.key === p.key,
+        'Single target mismatch.',
+      )
+      select(p.value, own(m.schema.singles, p.key)?.field, collection, hops + 1, 3)
+    } else {
+      assert(
+        'element' in d &&
+          ['u90/relation', 'u90/selection', 'u90/query'].includes(d.element) &&
+          d.options?.to === p.collection,
+        'Entry target mismatch.',
+      )
+      const target = own(m.schema.collections, p.collection)
+      assert(target, 'Unknown collection.')
+      const renderedDepth = Math.min(
+        budget,
+        d.element === 'u90/query' || d.options?.inverseOf ? 1 : Number(d.options?.depth ?? 1),
+      )
+      assert(renderedDepth > 0, 'Selected entry fields exceed public render depth.')
+      selectFields(p.fields, target.fields, p.collection, hops + 1, renderedDepth - 1)
+    }
+  }
+  const selectZone = (
+    p: ZoneProjection,
+    d: ZoneDecl,
+    collection?: string,
+    hops = 0,
+    budget = 3,
+  ): void => {
+    for (const [key, b] of Object.entries(p)) {
+      const block = own(m.schema.blocks, key)
+      assert(block && d.allow.includes(key), 'Block is not allowed at this placement.')
+      selectFields(b.fields, block.fields, collection, hops, budget)
+      if (b.entryFields) {
+        assert(collection && block.entry === collection, 'Invalid entryFields placement.')
+        selectFields(
+          b.entryFields,
+          m.schema.collections[collection].fields,
+          collection,
+          hops,
+          budget,
+        )
+      }
+    }
+  }
+  const layouts = (p: PageProjection | EntryProjection, start: string | undefined) => {
+    const chain = new Set<string>()
+    let key = start ?? Object.keys(m.layouts).find((k) => m.layouts[k].default)
+    while (key && !chain.has(key)) {
+      chain.add(key)
+      key = m.layouts[key]?.parent
+    }
+    for (const [layout, selected] of Object.entries(p.layouts ?? {})) {
+      assert(chain.has(layout), 'Layout is not attached.')
+      selectZone(selected, {
+        container: 'u90/zone',
+        allow: m.layouts[layout].blocks.filter((b) => b !== 'SLOT'),
+      })
+    }
+  }
+  try {
+    for (const category of ['pages', 'pageTypes'] as const)
+      for (const [key, p] of Object.entries(parsed.data[category])) {
+        const root = own(m[category], key)
+        assert(root, 'Unknown page root.')
+        selectZone(p.blocks, root.blocks)
+        layouts(p, root.layout)
+      }
+    for (const [key, p] of Object.entries(parsed.data.collections)) {
+      const root = own(m.collections, key)
+      const declaration = own(m.schema.collections, key)
+      assert(root?.route && declaration, 'Collection root must be routable.')
+      if (p.title.from === 'field')
+        assert(
+          textLike(own(declaration.fields, p.title.field)),
+          'Title field must be non-code text.',
+        )
+      selectZone(p.blocks, declaration.template ?? { container: 'u90/zone', allow: [] }, key)
+      layouts(p, root.layout)
+    }
+    return { ready: true, policy: parsed.data }
+  } catch (error) {
+    return {
+      ready: false,
+      reason: error instanceof Error ? error.message : 'Invalid policy binding.',
+    }
+  }
+}

package/src/features/contracts/search.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+import { KnowledgeKeySchema, KnowledgePathSchema, KnowledgeTitleSchema } from './knowledge'
+export const SearchHitSchema = z.strictObject({
+  id: KnowledgeKeySchema,
+  title: KnowledgeTitleSchema,
+  path: KnowledgePathSchema,
+  excerpt: z.string().max(1000),
+  kind: z.enum(['page', 'entry', 'faq']),
+})
+export type SearchHit = z.infer<typeof SearchHitSchema>
+
+export const SearchQuerySchema = z.strictObject({ q: z.string().trim().min(2).max(200) })
+export const SearchResponseSchema = z.strictObject({
+  version: z.literal(1),
+  results: z.array(SearchHitSchema).max(8),
+})
+// Eight hits: ASCII key128 + canonical ASCII path2048 + worst-case JSON title/excerpt
+// escaping (200+1000)*6 + bounded field syntax < 76 KiB. Reserve 128 KiB for this response only.
+export const SEARCH_RESPONSE_BYTES = 128 * 1024
+export function parseSearchQuery(params: URLSearchParams) {
+  if (params.size !== 1 || !params.has('q')) return null
+  const parsed = SearchQuerySchema.safeParse({ q: params.get('q') })
+  return parsed.success ? parsed.data : null
+}

package/src/features/contracts/verification.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod'
+import { FeedbackInputSchema } from './feedback'
+export * from './verificationConfig'
+export type VerificationAction = 'form_submit' | 'feedback_submit' | 'ask_ai_session'
+export const ProofSchema = z
+  .string()
+  .min(1)
+  .refine((v) => new TextEncoder().encode(v).length <= 4096 && !/[\s\x00-\x1f\x7f]/.test(v))
+/** null requests the saved no-provider policy; only the platform can authorize it. */
+export const ActionProofSchema = ProofSchema.nullable()
+export const GrantSchema = z
+  .string()
+  .min(1)
+  .max(4096)
+  .regex(/^[A-Za-z0-9_.-]+$/)
+export const FeedbackVerificationSchema = z.strictObject({
+  body: FeedbackInputSchema,
+  proof: ActionProofSchema,
+})
+export const FeedbackSubmissionSchema = z.strictObject({
+  body: FeedbackInputSchema,
+  grant: GrantSchema,
+})
+export const FormVerificationSchema = z.strictObject({
+  requestId: z.uuid(),
+  mode: z.enum(['verify', 'submit']),
+  proof: ActionProofSchema.optional(),
+  grant: GrantSchema.optional(),
+})
+export const FormEnvelopeSchema = z.strictObject({
+  values: z.record(z.string(), z.unknown()),
+  verification: FormVerificationSchema,
+})
+
+// Both approved providers belong in the site's initial CSP, so a saved provider switch needs no code change.
+export const VERIFICATION_CSP = {
+  scriptSrc: [
+    'https://www.google.com',
+    'https://www.gstatic.com',
+    'https://challenges.cloudflare.com',
+  ],
+  connectSrc: [
+    'https://www.google.com',
+    'https://www.gstatic.com',
+    'https://challenges.cloudflare.com',
+  ],
+  frameSrc: [
+    'https://www.google.com',
+    'https://recaptcha.google.com',
+    'https://challenges.cloudflare.com',
+  ],
+} as const

package/src/features/contracts/verificationConfig.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod'
+export const VerificationConfigSchema = z.strictObject({
+  mode: z.enum(['managed', 'byo', 'disabled']),
+  provider: z.enum(['google-cloud', 'google-v3', 'turnstile']),
+  siteKey: z.string().nullable(),
+  readiness: z.enum(['configured', 'setup_required', 'unavailable']),
+  revision: z.int().nonnegative(),
+})
+export type VerificationConfig = z.infer<typeof VerificationConfigSchema>

package/src/features/server/ConsentDefaults.tsx

@@ -0,0 +1,15 @@
+import Script from 'next/script'
+import { CONSENT_DEFAULTS_ID, CONSENT_DEFAULTS_SCRIPT } from '../consent/defaults'
+/** Mount once in the consuming server root layout, before SiteFeatures. */
+export function ConsentDefaults() {
+  return (
+    // App Router consumers mount this wrapper in their root layout. This rule
+    // uses the Pages Router _document filename heuristic for reusable packages.
+    // eslint-disable-next-line @next/next/no-before-interactive-script-outside-document
+    <Script
+      id={CONSENT_DEFAULTS_ID}
+      strategy="beforeInteractive"
+      dangerouslySetInnerHTML={{ __html: CONSENT_DEFAULTS_SCRIPT }}
+    />
+  )
+}

package/src/features/server/README.md

@@ -0,0 +1,185 @@
+# Site Features server integration (contract 1)
+
+```ts
+// app/api/u90/features/v1/[...feature]/route.ts
+import { createSiteFeatures, createRecaptchaVerifier } from '@unitninety/site-kit/features/server'
+
+export const { GET, POST } = createSiteFeatures({
+  env: {
+    PLATFORM_URL: process.env.PLATFORM_URL!,
+    PAYLOAD_API_KEY: process.env.PAYLOAD_API_KEY!,
+    SITE_URL: process.env.SITE_URL!,
+  },
+  verifyVisitor: createRecaptchaVerifier({
+    secret: process.env.RECAPTCHA_SECRET!,
+    hostname: new URL(process.env.SITE_URL!).hostname,
+    action: 'site_session',
+    minimumScore: 0.5,
+  }),
+  // Optional deployment-specific resolver; see identity policy below.
+  // resolveClientIdentity: async (request) => trustedConnectionIdentity(request),
+})
+```
+
+GET `config`, POST `session`, and POST `feedback` are implemented. Unknown paths, query parameters,
+methods and future operations fail closed. Native `createU90(site, { features: {
+verifyVisitor, resolveClientIdentity }, env, fetch })` composes this exact gateway. Existing
+sites may omit feature environment values; their legacy handlers continue working.
+
+`SITE_URL` and the authenticated tenant's saved `siteUrl` must have the same exact origin.
+Local tests must save the owned local origin on their disposable tenant. Request Host,
+Origin and forwarding headers cannot add preview domains to the audience. `PLATFORM_URL`
+and the service key stay on the site server. The platform alone stores
+`SITE_FEATURE_TOKEN_KEY` (at least 32 random characters; generate 32 random bytes). Rotation
+invalidates existing sessions. No site receives that signing key.
+
+## Verification and identity policy
+
+The platform's saved connection chooses Default, Custom Google reCAPTCHA, Custom Cloudflare
+Turnstile, or Disabled. Default is used when no connection is saved; missing credentials and
+provider failures remain closed. Only a manager-saved Disabled connection skips the external
+assessment. Tenant authentication, the exact website audience, signed visitor identity and
+transactional action grants remain mandatory in every mode. AI spending/token budgets and
+Default monthly funded verification allowances remain active.
+
+`VerifyVisitor(request)` is an optional supplemental server check. It returns `{ ok: true }`
+or `{ ok: false, retryable: boolean }` and receives only a bounded `{ proof }` string. The
+platform still assesses the proof centrally; a successful callback cannot authorize an action
+or bypass a central refusal. All custom adapters have a ten-second deadline. Omitting the
+callback does not opt out of the saved provider. An explicit `proof: null` skips supplemental
+callbacks and is forwarded to the platform, which accepts it only for saved Disabled mode.
+
+A valid signed session reuses its verification authority for 15 minutes. The session owner
+survives renewal, while connection changes invalidate outstanding verification authority.
+Search is cookieless and does not request a provider check. A CAPTCHA result never creates
+an authenticated identity from arbitrary browser claims or forwarding headers.
+
+`resolveClientIdentity?: (request: Request) => Promise<string | undefined>` is separate from
+verification. It must use identity established by the deployment's authenticated connection
+metadata. Never return a browser-generated UUID, visitor session ID, proof, arbitrary
+`x-forwarded-for`, `x-real-ip`, or another browser-supplied header. The optional value is bounded
+to 512 UTF-8 bytes and sent only over the private authenticated exchange. Request and identity
+rate caps are no longer enforced by Protection.
+
+## Task 4 browser session protocol
+
+The only public body is strict JSON `{ requestId: UUID, proof?: string | null }`, capped at 16 KiB.
+A string `proof` must be nonempty and at most 4 KiB UTF-8. Explicit `null` requests saved
+Disabled mode; an omitted proof only probes existing session authority. The gateway consumes a private platform token and returns only `{ version: 1,
+ok: true }`; browser JavaScript never sees the credential.
+
+1. Coalesce concurrent `ensureSession` calls at the feature root. On a user action, generate
+   one logical-attempt UUID and POST `{requestId}` with same-origin credentials and an abort
+   signal. Do not acquire a proof on config load, hidden/disabled widget mount or Search.
+2. The site forwards only its named cookie in a private resume request. The platform verifies
+   signature, tenant, stored audience and expiry. Success preserves the same visitor ID and
+   returns acknowledgment without another provider assessment.
+3. If current session authority is missing, the site returns 403 `verification_required`.
+   Refresh public verification configuration. Acquire proof once for the saved provider, or
+   use `null` for saved Disabled mode, and POST the same UUID with that value. Rejected/empty proof, cancellation, missing client adapter,
+   verification refusal or outage becomes a visible retry state. No automatic challenge loop.
+4. On issue success the site sets `u90_feature_session`, host-only, HttpOnly, SameSite=Lax,
+   Path `/api/u90/features/v1`, Secure on HTTPS. It is a browser-session cookie without
+   Max-Age/Expires; the signed identity expires after 24 hours and verification authority after 15 minutes.
+5. On an uncertain network outcome, probe again without proof using the same UUID and cookie.
+   A received cookie resumes normally. If no cookie arrived, an already-claimed UUID cannot
+   recover its credential: the platform returns 409 `conflict` after an authorized issuance
+   attempt. Never replay a private token by request ID. An explicit user retry may begin one
+   fresh UUID attempt and obtain fresh single-use proof; do not spin or automatically repeat
+   paid work. In particular, don't automatically resend a consumed reCAPTCHA proof.
+6. A later feature authorization failure may run `ensureSession` once. That is distinct from
+   retrying the underlying operation and never authorizes automatic retry of uncertain paid
+   work. Session acknowledgment is not permission to call disabled features.
+
+Private exchange fields (`mode`, audience/session/client/verification headers) are constructed
+by the gateway. Browser versions of those headers and body fields are discarded or rejected.
+The platform authenticates the site service credential and independently enforces the saved connection.
+Never call the private platform exchange directly from browser code.
+
+## Platform storage extension contract
+
+`createFeatureRequestStore({ payload, req?, now? })` exposes:
+
+- `beginFeatureRequest({ tenantId, operation, requestId, payloadHash, ownerId, audience })`:
+  `{ status: 'new', attemptId }`, `{ status: 'running' }`,
+  `{ status: 'conflict' }`, or `{ status: 'replay', result }`.
+- `completeFeatureRequest({ tenantId, operation, requestId, payloadHash, ownerId, audience,
+attemptId, result })`: a boolean indicating whether the matching live pending attempt
+  completed. Always retain the returned attempt ID; late completions cannot overwrite a
+  replacement claim. Results are JSON object receipts/status capped at 16 KiB, never raw
+  provider streams or credentials.
+
+Derive owner/tenant/audience from authenticated claims; hash schema-normalized payload with
+`featurePayloadHash({ ownerId, audience, payload })`. Session issuance uses a fresh owner,
+so an uncredentialed repeated UUID conflicts even if its body is identical. Proof is excluded
+from hashes. Search can generate a server request ID for its one-shot durable reservation;
+no visitor cookie is needed. The supported operation list is currently session/feedback/search;
+AI must add its tighter metering and uncertain-charge reconciliation before enabling its route.
+
+Claims, tenant+client/session counters, and uniqueness run under the same tenant lock in an
+actual Payload transaction. Supplied `req` joins the caller's transaction: the caller owns
+commit/rollback and must roll back on failure. Never do provider/network/stream work inside
+these locks. Pending claims expire after 24 hours, completed receipts seven days after
+completion. Expired IDs can be reused with a new fenced attempt. Expiry never implies an
+uncertain paid provider operation is safe to retry; the AI plan must add settlement rules.
+
+The authenticated daily job-retention cron (04:30 UTC) drains expired runtime data through
+short transactions of up to 1,000 requests and 1,000 counters per batch, using a fixed expiry
+cutoff. Each cleanup statement has a five-second database deadline, and no new batch starts
+unless its worst-case time fits within the 40-second run budget (including Payload loading).
+The separately registered minutely `feature-retention` cron continues from expired rows still
+in PostgreSQL after a budget exit, interruption or locked-row skip; no in-memory continuation
+or unconsumed queue is required. Each run reports deleted counts and whether expired rows
+remain (conservatively true if no batch fit). Expiry indexes bound each pass. Tenant purge and
+copied-DB sanitization explicitly remove both runtime collections.
+
+## Feedback submission
+
+POST `feedback` carries canonical `FeedbackInput` alongside its verification envelope. It requires an exact site Origin,
+enabled Feedback, and a central action verification grant. The
+platform returns the public `{ submissionId, receivedAt }` receipt with 201 for a new row
+or 200 for an identical retry. A changed body or different grant owner reusing an ID returns 409.
+Verification metadata is separate from canonical answers; Feedback does not need an Ask AI session.
+
+The platform saves grant consumption, request claim, immutable canonical field snapshot, answers and receipt
+in one transaction. Notification claims happen after commit and permit one automatic attempt;
+a timeout is terminal even if delivery may have succeeded. A retry returns the committed receipt.
+Explicit KAW adoption replaces an empty provisioned canonical form while retaining the exact
+`pageFeedback` form ID, historical answers/snapshots, handling settings and read flags. Existing
+canonical history requires an explicit merge; this service never moves submitted history.
+
+## Generic forms and central grants
+
+`client.submitForm` and `client.submitEnquiry` require a verification envelope in their server-side
+options. Older two-argument integrations fail closed. The browser calls
+`acquireVerificationProof(config, 'form_submit')` or `useFormVerification(config)` at submit time.
+It returns a fresh provider proof or `null` when Disabled is explicitly saved. Forward that result
+to the server helper separately from form values:
+
+```ts
+await client.submitForm('contact', answers, {
+  protection: {
+    honeypot: honeypotValue,
+    verification: {
+      requestId,
+      proof: visitorProof, // string, or null only for saved Disabled mode
+      onGrant: (grant, requestId) => retainForIdenticalRetry(grant, requestId),
+    },
+  },
+})
+```
+
+The SDK exchanges the envelope for a central signed action grant, then submits normalized
+answers with that grant. The platform binds authority to the tenant, website, operation,
+request ID and payload, and consumes it inside the mutation transaction. Retain the returned
+grant/request ID for an unchanged uncertain retry; committed receipt recovery does not perform
+a second mutation. A supplied `verifyVisitor` callback is supplemental only and is skipped for
+`proof: null`. The platform still decides whether null is permitted by its saved mode.
+
+The optional honeypot must be empty and at most 256 bytes. The deprecated `clientIdentity` option
+remains bounded to 256 UTF-8 bytes without control characters; it does not establish a signed
+visitor identity or grant authorization. Oversized or malformed proofs fail before submission.
+Keep API keys and server verifiers private, and never put proof or grants in answer fields.
+
+Request, identity, notification and concurrency allowances have been removed from Protection.
+AI spending/token budgets and Default monthly funded verification allowances remain in force.