@voltro/cli 0.33.0 → 0.34.0

package/templates/apps/api-versioning/mutations/documents.update.mutation.ts

@@ -8,6 +8,18 @@ import { Schema } from 'effect'
 export const updateDocument = defineMutation({
   name: 'documents.update',
   target: { table: 'documents', op: 'update' },
+  // Open: `tenant()` scopes the update, so a caller-supplied `id` from another
+  // tenant matches no row. Nothing is destroyed either — the versioning plugin
+  // snapshots the previous value, so every edit is recoverable through
+  // `documents.history` / `documents.asOf`.
+  //
+  // History is an audit trail, not an access control: it tells you WHAT
+  // changed, never whether the change was allowed. No auth strategy or rbac
+  // ships here, so a `guards: [{ scope }]` would deny every caller.
+  openAccess:
+    'edits a document of the request\'s tenant (an id outside it matches no row); the previous '
+    + 'value is snapshotted, so nothing is destroyed. Version history records changes — it '
+    + 'does not authorize them.',
   input: Schema.Struct({
     id: Schema.String,
     content: Schema.String,

package/templates/apps/api-versioning/package.json

@@ -13,18 +13,19 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/plugin-versioning": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-multitenancy": "0.34.0",
+    "@voltro/plugin-versioning": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-webhooks/mutations/orders.fulfill.mutation.ts

@@ -4,6 +4,22 @@ import { Schema } from 'effect'
 export const fulfillOrder = defineMutation({
   name:   'orders.fulfill',
   target: { table: 'orders', op: 'insert' },
+  // Open — and unlike a plain insert, this one FANS OUT: on commit it emits
+  // `order.completed` to every subscribed target, so an unguarded call makes
+  // this server POST to third parties. Two things bound that today and both are
+  // checkable: the emit is post-commit (a rollback ships nothing), and the
+  // target list is empty until someone calls `ctx.webhooks.subscribe`, which is
+  // not reachable from this procedure.
+  //
+  // No auth strategy and no rbac ship in this template, so a
+  // `guards: [{ scope: 'orders:write' }]` would deny every caller instead of
+  // the wrong ones. Add an identity, then that guard — before real subscribers
+  // exist. (The INCOMING `orders` webhook is a different door with its own
+  // control: an HMAC signature over `<unix>.<rawBody>`, not this decision.)
+  openAccess:
+    'inserts an order from caller-supplied fields into the request\'s tenant, then emits '
+    + '`order.completed` post-commit. The emit reaches only targets someone registered via '
+    + '`ctx.webhooks.subscribe` — none by default — so guard this before subscribers exist.',
   input:  Schema.Struct({ sku: Schema.NonEmptyString, totalCents: Schema.Number }),
   output: Schema.Struct({
     id:         Schema.String,

package/templates/apps/api-webhooks/package.json

@@ -13,19 +13,20 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/plugin-webhooks": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
-    "@voltro/sql-postgres": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-multitenancy": "0.34.0",
+    "@voltro/plugin-webhooks": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
+    "@voltro/sql-postgres": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-webhooks/queries/orders.list.query.ts

@@ -4,6 +4,16 @@ import { Schema } from 'effect'
 export const listOrders = defineQuery({
   name:   'orders.list',
   source: 'orders',
+  // Open: `tenant()` confines every delivery to the tenantId on the request, so
+  // one tenant's orders never reach another's subscription, and the rows carry
+  // only sku / amount / status — no customer identity. With no auth strategy
+  // configured that tenantId is the caller's own `x-tenant` header, and a
+  // `guards: [{ scope }]` would be unsatisfiable: an anonymous Subject holds no
+  // scopes, so the guard would deny 100% of traffic.
+  openAccess:
+    'lists the request tenant\'s own orders (sku, amount, status — no customer identity); '
+    + '`tenant()` scopes every delivery. No auth strategy ships here, so the tenant comes from '
+    + 'the caller\'s `x-tenant` header — add a strategy, then a `guards:`.',
   input:  Schema.Struct({}),
   output: Schema.Array(Schema.Struct({
     id:         Schema.String,

package/templates/apps/changelog/package.json

@@ -12,12 +12,12 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/changelog": "0.33.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/client": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/i18n": "0.33.0",
-    "@voltro/web": "0.33.0",
+    "@voltro/changelog": "0.34.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/client": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/i18n": "0.34.0",
+    "@voltro/web": "0.34.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
@@ -25,7 +25,9 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "tsx": "^4.22.4",
+    "jsdom": "^30.0.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/edge-functions/package.json

@@ -12,8 +12,8 @@
   },
   "dependencies": {
     "@effect/platform": "^0.97.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/serverless": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/serverless": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {

package/templates/apps/frontend-admin/package.json

@@ -12,21 +12,23 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.33.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/client": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/i18n": "0.33.0",
-    "@voltro/ui-shadcn": "0.33.0",
-    "@voltro/web": "0.33.0",
+    "@{{projectName}}/api": "0.34.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/client": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/i18n": "0.34.0",
+    "@voltro/ui-shadcn": "0.34.0",
+    "@voltro/web": "0.34.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.33.0",
+    "@voltro/devtools": "0.34.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "jsdom": "^30.0.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/frontend-admin/src/lib/admin.ts

@@ -1,16 +1,27 @@
-// The scopes the admin gates its write actions on (via useCan). The admin
-// derives a CONVENTIONAL scope per entity action — `<table>:create`,
-// `<table>:write`, `<table>:delete` (see deriveEntityAdmins) — and hides any
-// action the current subject's scopes don't satisfy.
+// The scopes the admin judges its write affordances against.
 //
-// DEMO: we feed `admin:full` (the blanket-bypass scope) so the demo shows every
-// action. In a real app, REPLACE this with the current subject's scopes from
-// your session — e.g. a reactive query:
+// READ THIS BEFORE SWAPPING IT OUT — the shape changed, and the old shape had a
+// trap. The admin no longer invents a scope per entity (`<table>:create` and
+// friends). It reads each procedure's OWN declared access off the capability
+// map (`spec.create.guards` — the descriptor's `guards:` / `openAccess:`) and
+// decides with `useAccessDecision`. So these scopes are matched against what
+// your api really declares; a name that appears in neither place gates nothing.
+//
+// That is the whole fix. A UI gating on an invented convention hides every write
+// from every caller of every app that named its scopes differently — a total
+// outage of the affordance that reads like a working permission check, and that
+// a demo seeding `admin:full` can never surface.
+//
+// DEMO: we feed `admin:full` (the blanket-bypass scope) so the scaffold shows
+// every action on first boot. In a real app, REPLACE this with the current
+// subject's scopes from your session — e.g. a reactive query:
 //
 //   const { data } = useSubscription<{ scopes: string[] }>('app', 'auth.session')
 //   <PermissionProvider scopes={data?.scopes ?? []}>…</PermissionProvider>
 //
-// useCan reads these reactively, so the admin's affordances update the instant
+// useAccessDecision reads these reactively, so affordances update the instant
 // the subject's roles change. (This is UX gating, not enforcement — the api's
-// own permission() guards remain the real authorization boundary.)
+// own guards remain the real authorization boundary. A control shown while the
+// decision is `unknown` is deliberate: a per-row guard is the server's to
+// answer, and it answers with a typed ScopeError.)
 export const DEMO_SCOPES: ReadonlyArray<string> = ['admin:full']

package/templates/apps/frontend-admin/src/locales/de.ts

@@ -18,7 +18,7 @@ export default defineLocale<typeof en>()({
   'lang.label': 'Sprache',
 
   'landing.heading': 'Das Backoffice, für dich erledigt.',
-  'landing.body':    'Dieser Admin liest zur Laufzeit die <strong>Capability-Map</strong> deiner API und rendert eine live, reaktive <code>DataTable</code> + <code>AutoForm</code> für jede Entität, die sie freigibt — rechtegeprüft mit <code>useCan</code>, mit einer Herkunfts-Lade pro Zeile und universellem Undo/Redo. Richte ihn auf eine beliebige Voltro-API und er passt sich an; der Seiten-Code unter <code>src/pages/admin/</code> gehört dir zum Bearbeiten.',
+  'landing.body':    'Dieser Admin liest zur Laufzeit die <strong>Capability-Map</strong> deiner API und rendert eine live, reaktive <code>DataTable</code> + <code>AutoForm</code> für jede Entität, die sie freigibt — gegated auf den Zugriff, den jede Prozedur selbst deklariert, mit einer Herkunfts-Lade pro Zeile und universellem Undo/Redo. Richte ihn auf eine beliebige Voltro-API und er passt sich an; der Seiten-Code unter <code>src/pages/admin/</code> gehört dir zum Bearbeiten.',
   'landing.cta':     'Beim Admin anmelden →',
 
   'login.heading': 'Anmelden',
@@ -38,6 +38,7 @@ export default defineLocale<typeof en>()({
   'overview.reactiveSuffix': ' · reaktiv',
   'overview.readonly':       'schreibgeschützt',
   'overview.empty':          'Diese API stellt keine Benutzer-Entitäten bereit.',
+  'overview.serverOnly':     '{count, plural, one {# reine Server-Spalte, ausgeblendet} other {# reine Server-Spalten, ausgeblendet}}',
 
   'entity.create':  'Erstellen',
   'entity.addLabel': '{table} hinzufügen',
@@ -48,6 +49,15 @@ export default defineLocale<typeof en>()({
   'entity.delete':  'Löschen',
   'entity.unknown': 'Keine Entität <code>{entity}</code> in der Capability-Map dieser API.',
 
+  'entity.requires':          'erfordert {scopes}',
+  'entity.openAccess':        'offener Zugriff — {reason}',
+  'entity.accessUndeclared':  'keine Zugriffsentscheidung deklariert',
+  'entity.accessUnknown':     'Diese API prüft die Berechtigung pro Zeile, das kann nur sie beantworten. Das Bedienelement wird angezeigt; die API entscheidet beim Absenden.',
+
+  'entity.serverOnly':   '{count, plural, one {# reine Server-Spalte verlässt} other {# reine Server-Spalten verlassen}} die API nie und {count, plural, one {kann} other {können}} nicht übermittelt werden: {names}',
+  'entity.sensitive':    'Personenbezogene Daten — in Exporten maskiert: {names}',
+  'entity.notEditable':  'Kein einzelner Primärschlüssel, daher lassen sich Zeilen nicht zum Bearbeiten oder Löschen adressieren. Nur Liste.',
+
   'prov.title':       'Herkunft · <code>{table}</code> #{id}',
   'prov.close':       'schließen',
   'prov.loading':     'lädt…',

package/templates/apps/frontend-admin/src/locales/en.ts

@@ -24,7 +24,7 @@ export default defineCatalog({
 
   // ---- Public landing ((marketing)/index.tsx) ----
   'landing.heading': 'The back-office, done for you.',
-  'landing.body':    'This admin reads your api’s <strong>capability map</strong> at runtime and renders a live, reactive <code>DataTable</code> + <code>AutoForm</code> for every entity it exposes — permission-gated with <code>useCan</code>, with a per-row provenance drawer and universal undo/redo. Point it at any Voltro api and it adapts; the page code under <code>src/pages/admin/</code> is yours to edit.',
+  'landing.body':    'This admin reads your api’s <strong>capability map</strong> at runtime and renders a live, reactive <code>DataTable</code> + <code>AutoForm</code> for every entity it exposes — gated on the access each procedure itself declares, with a per-row provenance drawer and universal undo/redo. Point it at any Voltro api and it adapts; the page code under <code>src/pages/admin/</code> is yours to edit.',
   'landing.cta':     'Sign in to the admin →',
 
   // ---- Public sign-in ((marketing)/login.tsx) ----
@@ -47,6 +47,7 @@ export default defineCatalog({
   'overview.reactiveSuffix': ' · reactive',
   'overview.readonly':       'read-only',
   'overview.empty':          'No user entities exposed by this api.',
+  'overview.serverOnly':     '{count, plural, one {# server-only column, hidden} other {# server-only columns, hidden}}',
 
   // ---- Per-entity CRUD (admin/[entity].tsx) ----
   'entity.create':  'Create',
@@ -58,6 +59,17 @@ export default defineCatalog({
   'entity.delete':  'Delete',
   'entity.unknown': 'No entity <code>{entity}</code> in this api’s capability map.',
 
+  // ---- Declared access, shown rather than guessed (admin/[entity].tsx) ----
+  'entity.requires':          'requires {scopes}',
+  'entity.openAccess':        'open access — {reason}',
+  'entity.accessUndeclared':  'no access decision declared',
+  'entity.accessUnknown':     'This api checks permission per row, so only it can answer. The control is shown; the api decides when you submit.',
+
+  // ---- Exposure axes, straight from the schema (admin/[entity].tsx) ----
+  'entity.serverOnly':   '{count, plural, one {# server-only column} other {# server-only columns}} never leave the api and cannot be submitted: {names}',
+  'entity.sensitive':    'Personal data — masked in exports: {names}',
+  'entity.notEditable':  'No single primary key, so rows can’t be addressed for edit or delete. List only.',
+
   // ---- Provenance drawer (admin/[entity].tsx) ----
   'prov.title':       'Provenance · <code>{table}</code> #{id}',
   'prov.close':       'close',

package/templates/apps/frontend-admin/src/pages/admin/[entity]/page.tsx

@@ -1,22 +1,36 @@
 // Per-entity CRUD — URL `/admin/<entity>`. Everything here is DISCOVERED:
 // useCapabilityManifest → deriveEntityAdmins gives this entity's list query +
-// create/update/delete mutation tags + the columns. We bind the shipped
-// schema-driven components to those tags:
-//   - <DataTable api="app" query={listTag}/>  — live, reactive rows
-//   - <AutoForm  api="app" mutation={createTag}/> — fields from the input schema
-// Writes are gated by useCan on the conventional `<table>:create|delete` scopes;
-// each row has a provenance ("why is this here?") drawer (08) + delete; the
-// layout's undo bar reverts the last change (00/09). Edit this file freely — it's
-// your template code, not a sealed runtime feature.
+// create/update/delete actions + the columns. We bind the shipped schema-driven
+// components to those tags:
+//   - <DataTable api="app" query={spec.list.tag}/>      — live, reactive rows
+//   - <AutoForm  api="app" mutation={spec.create.tag}/> — fields from the input schema
+//
+// WRITES ARE GATED ON THE ACCESS THE API DECLARES, not on a scope string this
+// page invented. `spec.create.guards` is the procedure's own `guards:` /
+// `openAccess:`, straight off the capability map, so this gate and the server's
+// check read the same data and cannot drift.
+//
+// The decision is THREE-valued, and `unknown` is SHOWN, not hidden: a guard with
+// a `resource` extractor is answered per ROW by the server, and a browser
+// holding only global scopes cannot pre-compute it. Hiding those would empty the
+// admin for exactly the multi-tenant apps whose subjects carry no global scopes.
+// The server stays the authorization boundary and answers a typed ScopeError.
+//
+// Each row has a provenance ("why is this here?") drawer (08) + delete; the
+// layout's undo bar reverts the last change (00/09). Edit this file freely —
+// it's your template code, not a sealed runtime feature.
 import { useState, type ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
 import { useParams, AutoForm, DataTable } from '@voltro/web'
 import {
   useCapabilityManifest,
   deriveEntityAdmins,
-  useCan,
+  useAccessDecision,
+  requiredScopes,
+  openAccessReason,
   useMutation,
   useProvenance,
+  type EntityAction,
   type EntityAdminSpec,
 } from '@voltro/client'
 import { T, useTFn } from '@voltro/i18n'
@@ -55,23 +69,36 @@ const ProvenanceDrawer = ({ table, id, onClose }: { readonly table: string; read
   )
 }
 
+// What the api requires for this action, in words — so an operator who hits a
+// ScopeError can read the scope they are missing instead of guessing at it.
+const AccessNote = ({ action }: { readonly action: EntityAction }): ReactNode => {
+  const reason = openAccessReason(action.guards)
+  const scopes = requiredScopes(action.guards)
+  if (reason !== undefined) return <span className="meta"><T id="entity.openAccess" values={{ reason }} /></span>
+  if (scopes.length > 0) return <span className="meta"><T id="entity.requires" values={{ scopes: scopes.join(', ') }} /></span>
+  return <span className="meta"><T id="entity.accessUndeclared" /></span>
+}
+
 // The bound CRUD surface for one entity. A child component so its hooks
-// (useCan/useMutation) get the real spec, never undefined.
+// (useAccessDecision/useMutation) get the real spec, never undefined.
 const EntityAdmin = ({ spec }: { readonly spec: EntityAdminSpec }): ReactNode => {
   const [sel, setSel] = useState<string | null>(null)
   const t = useTFn()
-  const canCreate = useCan(spec.createScope)
-  const canDelete = useCan(spec.deleteScope)
-  // Always-called; the tag is only used when deleteTag exists (gated below).
-  const del = useMutation<{ id: string }>('app', spec.deleteTag ?? '__voltro.noop')
+  const create = useAccessDecision(spec.create.guards)
+  const remove = useAccessDecision(spec.delete.guards)
+  // Always-called; the tag is only used when spec.delete.tag exists (gated below).
+  const del = useMutation<Record<string, string>>('app', spec.delete.tag ?? '__voltro.noop')
+  // The column the api keys rows on — NOT a hard-coded `id`. A table keyed on
+  // anything else would otherwise get an empty id sent on every delete.
+  const pk = spec.pkColumn ?? 'id'
 
   const rowActions = (row: Row): ReactNode => {
-    const id = String(row['id'] ?? '')
+    const id = String(row[pk] ?? '')
     return (
       <span className="row-actions">
         <button type="button" className="btn ghost" onClick={() => setSel(id)}><T id="entity.why" /></button>
-        {spec.deleteTag && canDelete && id ? (
-          <button type="button" className="btn danger" onClick={() => void del.mutate({ id })}><T id="entity.delete" /></button>
+        {spec.delete.tag && spec.editable && remove !== 'denied' && id ? (
+          <button type="button" className="btn danger" onClick={() => void del.mutate({ [pk]: id })}><T id="entity.delete" /></button>
         ) : null}
       </span>
     )
@@ -81,17 +108,33 @@ const EntityAdmin = ({ spec }: { readonly spec: EntityAdminSpec }): ReactNode =>
     <section>
       <h1>{spec.table}</h1>
 
-      {spec.createTag && canCreate ? (
+      {/* `.serverOnly()` columns are absent from `spec.columns` by construction —
+          they never cross the wire, and the runtime REFUSES a mutation input that
+          sets one. Saying so beats a silently shorter column list. */}
+      {spec.serverOnlyColumns.length > 0 ? (
+        <p className="meta">
+          <T id="entity.serverOnly" values={{ count: spec.serverOnlyColumns.length, names: spec.serverOnlyColumns.join(', ') }} />
+        </p>
+      ) : null}
+      {spec.sensitiveColumns.length > 0 ? (
+        <p className="meta">
+          <T id="entity.sensitive" values={{ names: spec.sensitiveColumns.join(', ') }} />
+        </p>
+      ) : null}
+      {!spec.editable ? <p className="meta"><T id="entity.notEditable" /></p> : null}
+
+      {spec.create.tag && create !== 'denied' ? (
         <div className="section">
-          <h2><T id="entity.create" /></h2>
-          <AutoForm api="app" mutation={spec.createTag} submitLabel={t('entity.addLabel', { table: spec.table })} />
+          <h2><T id="entity.create" /> <AccessNote action={spec.create} /></h2>
+          {create === 'unknown' ? <p className="muted"><T id="entity.accessUnknown" /></p> : null}
+          <AutoForm api="app" mutation={spec.create.tag} submitLabel={t('entity.addLabel', { table: spec.table })} />
         </div>
       ) : null}
 
       <div className="section">
         <h2><T id="entity.rows" /></h2>
-        {spec.listTag ? (
-          <DataTable api="app" query={spec.listTag} rowActions={rowActions} emptyText={t('entity.empty', { table: spec.table })} />
+        {spec.list.tag ? (
+          <DataTable api="app" query={spec.list.tag} rowActions={rowActions} emptyText={t('entity.empty', { table: spec.table })} />
         ) : (
           <p className="muted"><T id="entity.noList" /></p>
         )}

package/templates/apps/frontend-admin/src/pages/admin/entity.test.tsx

@@ -5,7 +5,13 @@
 // renders one of three observable states: a loading skeleton, an "unknown
 // entity" banner, or the bound CRUD surface (heading + AutoForm + DataTable).
 // We mock @voltro/web (useParams + the AutoForm/DataTable components) and
-// @voltro/client (the discovery + gating hooks).
+// @voltro/client (the discovery + access hooks).
+//
+// The access cases below are the point of this file. The page must gate on the
+// DECLARED access the manifest carries, never on a scope string it invented,
+// and it must SHOW an `unknown` decision instead of hiding it — a per-row guard
+// is the server's to answer, and hiding it empties the admin for every
+// multi-tenant app whose subjects hold no global scopes.
 
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
 import { act, createElement, type ReactNode } from 'react'
@@ -19,20 +25,25 @@ vi.mock('@voltro/web', () => ({
   useParams: () => params(),
   AutoForm: ({ mutation }: { mutation: string }) =>
     createElement('div', { 'data-testid': 'auto-form' }, mutation),
-  DataTable: ({ query }: { query: string }) =>
-    createElement('div', { 'data-testid': 'data-table' }, query),
+  DataTable: ({ query, rowActions }: { query: string; rowActions?: (r: Record<string, unknown>) => ReactNode }) =>
+    createElement('div', { 'data-testid': 'data-table' }, query, rowActions?.({ id: 'r1', entryNo: 'e1' })),
 }))
 
 interface ManifestState { manifest: unknown; loading: boolean }
 const capabilityManifest = vi.fn<() => ManifestState>()
 const entityAdmins = vi.fn<() => Array<Record<string, unknown>>>()
-const can = vi.fn<() => boolean>()
+const accessDecision = vi.fn<() => 'allowed' | 'denied' | 'unknown'>()
+const mutate = vi.fn()
 
 vi.mock('@voltro/client', () => ({
   useCapabilityManifest: () => capabilityManifest(),
   deriveEntityAdmins: () => entityAdmins(),
-  useCan: () => can(),
-  useMutation: () => ({ mutate: vi.fn() }),
+  useAccessDecision: () => accessDecision(),
+  requiredScopes: (guards?: ReadonlyArray<{ kind: string; scope?: ReadonlyArray<string> }>) =>
+    (guards ?? []).flatMap((g) => (g.kind === 'scope' ? [...(g.scope ?? [])] : [])),
+  openAccessReason: (guards?: ReadonlyArray<{ kind: string; reason?: string }>) =>
+    (guards ?? []).find((g) => g.kind === 'open')?.reason,
+  useMutation: () => ({ mutate }),
   useProvenance: () => ({ data: undefined, loading: false, error: undefined }),
 }))
 
@@ -58,12 +69,36 @@ const render = (node: ReactNode): void => {
 const cell = (id: string): string | null =>
   container.querySelector(`[data-testid="${id}"]`)?.textContent ?? null
 
+/** A derived spec in its current shape. */
+const spec = (over: Record<string, unknown> = {}): Record<string, unknown> => ({
+  table: 'todos',
+  columns: [{ name: 'id' }, { name: 'title' }],
+  serverOnlyColumns: [],
+  sensitiveColumns: [],
+  reactive: true,
+  pkColumn: 'id',
+  editable: true,
+  list: { tag: 'todos.list' },
+  create: { tag: 'todos.create', guards: [{ kind: 'scope', scope: ['todos:manage'], mode: 'all', resourceScoped: false }] },
+  update: {},
+  delete: { tag: 'todos.delete' },
+  ...over,
+})
+
+const showEntity = (over: Record<string, unknown> = {}): void => {
+  params.mockReturnValue({ entity: (over['table'] as string) ?? 'todos' })
+  capabilityManifest.mockReturnValue({ manifest: {}, loading: false })
+  entityAdmins.mockReturnValue([spec(over)])
+  render(createElement(EntityPage))
+}
+
 beforeEach(() => {
   params.mockReset()
   capabilityManifest.mockReset()
   entityAdmins.mockReset()
-  can.mockReset()
-  can.mockReturnValue(true)
+  accessDecision.mockReset()
+  mutate.mockReset()
+  accessDecision.mockReturnValue('allowed')
 })
 
 afterEach(() => {
@@ -98,22 +133,94 @@ describe('entity page — render states', () => {
   })
 
   test('renders the bound CRUD surface (heading + AutoForm + DataTable) for a known entity', () => {
-    params.mockReturnValue({ entity: 'todos' })
-    capabilityManifest.mockReturnValue({ manifest: {}, loading: false })
-    entityAdmins.mockReturnValue([
-      {
-        table: 'todos',
-        columns: ['id', 'title'],
-        listTag: 'todos.list',
-        createTag: 'todos.create',
-        createScope: 'todos:create',
-        deleteScope: 'todos:delete',
-        deleteTag: 'todos.delete',
-      },
-    ])
-    render(createElement(EntityPage))
+    showEntity()
     expect(container.querySelector('h1')!.textContent).toBe('todos')
     expect(cell('auto-form')).toBe('todos.create')
-    expect(cell('data-table')).toBe('todos.list')
+    expect(cell('data-table')).toContain('todos.list')
+  })
+})
+
+describe('entity page — gates on the DECLARED access', () => {
+  test('shows the create form when the api says the caller may create', () => {
+    accessDecision.mockReturnValue('allowed')
+    showEntity()
+    expect(cell('auto-form')).toBe('todos.create')
+  })
+
+  test('hides it on a DEFINITE denial', () => {
+    accessDecision.mockReturnValue('denied')
+    showEntity()
+    expect(container.querySelector('[data-testid="auto-form"]')).toBeNull()
+    // …and the list is still there. A denied write is not a denied read.
+    expect(cell('data-table')).toContain('todos.list')
+  })
+
+  test('SHOWS it on an indeterminate decision, and says why', () => {
+    // The false-deny trap: a per-row guard cannot be pre-computed in a browser.
+    // Hiding it would empty the admin for exactly the multi-tenant apps whose
+    // subjects carry no global scopes.
+    accessDecision.mockReturnValue('unknown')
+    showEntity()
+    expect(cell('auto-form')).toBe('todos.create')
+    expect(container.textContent).toContain('checks permission per row')
+  })
+
+  test('names the scope the api ACTUALLY requires, so a refusal is readable', () => {
+    showEntity()
+    expect(container.textContent).toContain('requires todos:manage')
+  })
+
+  test('reports an openAccess decision with its reason', () => {
+    showEntity({ create: { tag: 'todos.create', guards: [{ kind: 'open', reason: 'demo seeding' }] } })
+    expect(container.textContent).toContain('open access — demo seeding')
+  })
+
+  test('says so when a procedure declared no access at all', () => {
+    showEntity({ create: { tag: 'todos.create' } })
+    expect(container.textContent).toContain('no access decision declared')
+  })
+
+  test('renders nothing to create when the api exposes no create mutation', () => {
+    showEntity({ create: {} })
+    expect(container.querySelector('[data-testid="auto-form"]')).toBeNull()
+  })
+})
+
+describe('entity page — the three exposure axes', () => {
+  test('names the .serverOnly() columns it withheld, and why', () => {
+    showEntity({ serverOnlyColumns: ['pwHash', 'internalNote'] })
+    expect(container.textContent).toContain('2 server-only columns')
+    expect(container.textContent).toContain('pwHash, internalNote')
+    expect(container.textContent).toContain('cannot be submitted')
+  })
+
+  test('flags .sensitive() columns as export-masked, NOT as hidden', () => {
+    // The category error to avoid: `.sensitive()` is the export axis. The value
+    // is real wire data the operator is meant to see.
+    showEntity({ sensitiveColumns: ['email'] })
+    expect(container.textContent).toContain('masked in exports: email')
+  })
+
+  test('says nothing when no column is marked', () => {
+    showEntity()
+    expect(container.textContent).not.toContain('server-only')
+    expect(container.textContent).not.toContain('masked in exports')
+  })
+})
+
+describe('entity page — row identity', () => {
+  test('keys the delete on the pk the api declares, not a hard-coded id', () => {
+    showEntity({ pkColumn: 'entryNo' })
+    const del = container.querySelector('button.danger')!
+    act(() => { del.dispatchEvent(new MouseEvent('click', { bubbles: true })) })
+    // A hard-coded `id` would have sent `{ id: 'r1' }` — or `{ id: '' }` for a
+    // table that has no `id` column at all.
+    expect(mutate).toHaveBeenCalledWith({ entryNo: 'e1' })
+  })
+
+  test('offers no delete for a table with no addressable row', () => {
+    showEntity({ editable: false, pkColumn: undefined })
+    expect(container.querySelector('button.danger')).toBeNull()
+    expect(container.textContent).toContain('No single primary key')
   })
 })