@fuzdev/fuz_app 0.33.0 → 0.35.0

package/dist/testing/admin_integration.js

@@ -10,6 +10,19 @@ import './assert_dev_env.js';
  * Consumers call it with their route factory, session config, role schema,
  * and RPC endpoint specs — all admin route tests come for free.
  *
+ * Scope: admin *semantics* — cross-admin isolation, permit grant/revoke
+ * flow, session/token revoke-all, audit writes. Output-schema conformance
+ * for admin methods is **not** the concern of this suite; it lives in:
+ *
+ * - `describe_rpc_round_trip_tests` — every RPC method (admin methods
+ *   included) is hit with a spec-generated valid body and the 2xx result
+ *   is validated against `spec.output`.
+ * - `describe_round_trip_validation` — every REST route is hit and
+ *   validated against its declared `output` / error schemas (SSE routes
+ *   skipped via `Content-Type: text/event-stream`).
+ * - `describe_sse_route_tests` — SSE frames validated against their
+ *   declared `EventSpec`.
+ *
  * @module
  */
 import { describe, test, assert, afterAll } from 'vitest';
@@ -17,10 +30,10 @@ import { ROLE_KEEPER, ROLE_ADMIN } from '../auth/role_schema.js';
 import { AUTH_MIGRATION_NS } from '../auth/migrations.js';
 import { create_test_app } from './app_server.js';
 import { create_pglite_factory, create_describe_db, AUTH_INTEGRATION_TRUNCATE_TABLES, } from './db.js';
-import { find_auth_route, assert_response_matches_spec } from './integration_helpers.js';
+import { find_auth_route } from './integration_helpers.js';
 import { run_migrations } from '../db/migrate.js';
 import { ErrorCoverageCollector, assert_error_coverage, DEFAULT_INTEGRATION_ERROR_COVERAGE, } from './error_coverage.js';
-import { rpc_call, rpc_call_non_browser, require_rpc_endpoint_path, resolve_rpc_endpoints_for_setup, } from './rpc_helpers.js';
+import { rpc_call_for_spec, require_rpc_endpoint_path, resolve_rpc_endpoints_for_setup, } from './rpc_helpers.js';
 import { permit_offer_create_action_spec, permit_revoke_action_spec, } from '../auth/permit_offer_action_specs.js';
 import { admin_account_list_action_spec, admin_session_list_action_spec, admin_session_revoke_all_action_spec, admin_token_revoke_all_action_spec, audit_log_list_action_spec, audit_log_permit_history_action_spec, } from '../auth/admin_action_specs.js';
 import { account_token_create_action_spec, account_verify_action_spec, } from '../auth/account_action_specs.js';
@@ -54,8 +67,10 @@ const build_admin_test_app_options = (options, db, roles) => ({
  * Standard admin integration test suite for fuz_app admin routes.
  *
  * Exercises account listing, permit grant/revoke (via RPC), session
- * management, token management, audit log routes, admin-to-admin isolation,
- * and response schema validation.
+ * management, token management, audit log reads, admin-to-admin
+ * isolation, and 401/403 error-coverage on the admin REST surface.
+ * Output-schema conformance is not in scope — see the module docstring
+ * for the suites that cover it.
  *
  * @param options - session config, route factory, role schema, RPC endpoints
  */
@@ -86,10 +101,30 @@ export const describe_standard_admin_integration_tests = (options) => {
                 // admin REST route remaining is the optional
                 // `GET /audit-log/stream` SSE, plus the shared RPC endpoint
                 // path itself (admin methods live behind spec-level role auth).
+                // The `/audit-log/stream` suffix tracks the hardcoded path in
+                // `auth/audit_log_routes.ts` — if consumers ever need to mount
+                // the audit SSE at a different suffix, promote this to an
+                // `audit_log_path_suffix` option on
+                // `StandardAdminIntegrationTestOptions`.
                 const admin_routes = captured_route_specs.filter((s) => s.path.endsWith('/audit-log/stream') &&
                     s.auth.type === 'role' &&
                     s.auth.role === 'admin');
-                assert_error_coverage(error_collector, admin_routes.length > 0 ? admin_routes : captured_route_specs, { min_coverage: DEFAULT_INTEGRATION_ERROR_COVERAGE });
+                // Adaptive threshold: when the scoped admin REST surface is
+                // effectively empty (0–1 routes, typical post-RPC-migration),
+                // the 20% baseline is meaningless — a single SSE route that
+                // can't be exercised against an error schema drops the ratio
+                // to 0.0%. Log an informational skip instead of asserting.
+                // The admin RPC surface is covered by
+                // `describe_rpc_round_trip_tests`, not this collector.
+                if (admin_routes.length <= 1) {
+                    console.log(`[error coverage] skipped admin REST coverage assertion — ` +
+                        `scoped surface has ${admin_routes.length} route(s); ` +
+                        `admin RPC surface is covered by describe_rpc_round_trip_tests`);
+                    return;
+                }
+                assert_error_coverage(error_collector, admin_routes, {
+                    min_coverage: DEFAULT_INTEGRATION_ERROR_COVERAGE,
+                });
             }
         });
         /** Make request headers for a given session cookie. */
@@ -107,15 +142,15 @@ export const describe_standard_admin_integration_tests = (options) => {
          * `describe_rpc_round_trip_tests` + fuz_app's own action suite.
          */
         const offer_and_accept = async (args) => {
-            const res = await rpc_call({
+            const res = await rpc_call_for_spec({
                 app: args.app,
                 path: rpc_path,
-                method: permit_offer_create_action_spec.method,
+                spec: permit_offer_create_action_spec,
                 params: { to_account_id: args.to_account_id, role: args.role },
                 headers: args.admin_headers,
             });
             assert.ok(res.ok, `permit_offer_create failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-            const offer = res.result.offer;
+            const { offer } = res.result;
             const accept_result = await get_db().transaction(async (tx) => query_accept_offer({ db: tx }, { offer_id: offer.id, to_account_id: args.to_account_id, ip: null }));
             return { offer_id: offer.id, permit_id: accept_result.permit.id };
         };
@@ -124,28 +159,29 @@ export const describe_standard_admin_integration_tests = (options) => {
             test('admin can list all accounts', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
                 const user_two = await test_app.create_account({ username: 'user_two' });
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: admin_account_list_action_spec.method,
+                    spec: admin_account_list_action_spec,
+                    params: null,
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(res.ok, `admin_account_list failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const result = res.result;
-                assert.ok(Array.isArray(result.accounts), 'Expected accounts array');
-                assert.ok(result.accounts.length >= 2, 'Expected at least 2 accounts');
-                assert.ok(Array.isArray(result.grantable_roles), 'Expected grantable_roles array');
+                assert.ok(Array.isArray(res.result.accounts), 'Expected accounts array');
+                assert.ok(res.result.accounts.length >= 2, 'Expected at least 2 accounts');
+                assert.ok(Array.isArray(res.result.grantable_roles), 'Expected grantable_roles array');
                 // Verify user_two appears in the listing
-                const found = result.accounts.find((e) => e.account.id === user_two.account.id);
+                const found = res.result.accounts.find((e) => e.account.id === user_two.account.id);
                 assert.ok(found, 'Expected user_two in accounts listing');
             });
             test('non-admin cannot list accounts', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db(), [ROLE_KEEPER]));
                 captured_route_specs ??= test_app.route_specs;
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: admin_account_list_action_spec.method,
+                    spec: admin_account_list_action_spec,
+                    params: null,
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(!res.ok, 'Expected admin_account_list to fail for non-admin');
@@ -165,45 +201,46 @@ export const describe_standard_admin_integration_tests = (options) => {
             test('admin can list all active sessions', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
                 await test_app.create_account({ username: 'user_two' });
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: admin_session_list_action_spec.method,
+                    spec: admin_session_list_action_spec,
+                    params: null,
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(res.ok, `admin_session_list failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const body = res.result;
-                assert.ok(Array.isArray(body.sessions), 'Expected sessions array');
-                assert.ok(body.sessions.length >= 2, 'Expected sessions from multiple accounts');
+                assert.ok(Array.isArray(res.result.sessions), 'Expected sessions array');
+                assert.ok(res.result.sessions.length >= 2, 'Expected sessions from multiple accounts');
             });
             test('admin can revoke all sessions for another account', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
                 const user_two = await test_app.create_account({ username: 'user_two' });
                 // Verify user_two's session works via `account_verify` RPC
-                const before = await rpc_call({
+                const before = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: account_verify_action_spec.method,
+                    spec: account_verify_action_spec,
+                    params: null,
                     headers: create_headers(user_two.session_cookie),
                 });
                 assert.strictEqual(before.status, 200);
                 // Admin revokes all sessions for user_two via RPC
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: admin_session_revoke_all_action_spec.method,
+                    spec: admin_session_revoke_all_action_spec,
                     params: { account_id: user_two.account.id },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(res.ok, `admin_session_revoke_all failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const result = res.result;
-                assert.strictEqual(result.ok, true);
-                assert.ok(result.count >= 1, 'Expected at least 1 revoked session');
+                assert.strictEqual(res.result.ok, true);
+                assert.ok(res.result.count >= 1, 'Expected at least 1 revoked session');
                 // Verify user_two's session no longer works
-                const after = await rpc_call({
+                const after = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: account_verify_action_spec.method,
+                    spec: account_verify_action_spec,
+                    params: null,
                     headers: create_headers(user_two.session_cookie),
                 });
                 assert.strictEqual(after.status, 401);
@@ -211,22 +248,22 @@ export const describe_standard_admin_integration_tests = (options) => {
             test('admin revoking own sessions invalidates own session', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
                 // Admin revokes own sessions via RPC
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: admin_session_revoke_all_action_spec.method,
+                    spec: admin_session_revoke_all_action_spec,
                     params: { account_id: test_app.backend.account.id },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(res.ok, `admin_session_revoke_all failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const result = res.result;
-                assert.strictEqual(result.ok, true);
-                assert.ok(result.count >= 1, 'Expected at least 1 revoked session');
+                assert.strictEqual(res.result.ok, true);
+                assert.ok(res.result.count >= 1, 'Expected at least 1 revoked session');
                 // Admin's own session should no longer work
-                const after = await rpc_call({
+                const after = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: account_verify_action_spec.method,
+                    spec: account_verify_action_spec,
+                    params: null,
                     headers: test_app.create_session_headers(),
                 });
                 assert.strictEqual(after.status, 401);
@@ -238,31 +275,34 @@ export const describe_standard_admin_integration_tests = (options) => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
                 const user_two = await test_app.create_account({ username: 'user_two' });
                 // Verify user_two's bearer token works via `account_verify` RPC
-                const before = await rpc_call_non_browser({
+                const before = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: account_verify_action_spec.method,
+                    spec: account_verify_action_spec,
+                    params: null,
                     headers: { authorization: `Bearer ${user_two.api_token}` },
+                    suppress_default_origin: true,
                 });
                 assert.strictEqual(before.status, 200);
                 // Admin revokes all tokens for user_two via RPC
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: admin_token_revoke_all_action_spec.method,
+                    spec: admin_token_revoke_all_action_spec,
                     params: { account_id: user_two.account.id },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(res.ok, `admin_token_revoke_all failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const result = res.result;
-                assert.strictEqual(result.ok, true);
-                assert.ok(result.count >= 1, 'Expected at least 1 revoked token');
+                assert.strictEqual(res.result.ok, true);
+                assert.ok(res.result.count >= 1, 'Expected at least 1 revoked token');
                 // Verify user_two's bearer token no longer works
-                const after = await rpc_call_non_browser({
+                const after = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: account_verify_action_spec.method,
+                    spec: account_verify_action_spec,
+                    params: null,
                     headers: { authorization: `Bearer ${user_two.api_token}` },
+                    suppress_default_origin: true,
                 });
                 assert.strictEqual(after.status, 401);
             });
@@ -271,40 +311,39 @@ export const describe_standard_admin_integration_tests = (options) => {
         describe('audit log RPC reads', () => {
             test('admin can list audit log events', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: audit_log_list_action_spec.method,
+                    spec: audit_log_list_action_spec,
+                    params: {},
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(res.ok, `audit_log_list failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const body = res.result;
-                assert.ok(Array.isArray(body.events), 'Expected events array');
+                assert.ok(Array.isArray(res.result.events), 'Expected events array');
             });
             test('audit log supports event_type filter', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
                 // Admin offer emits `permit_offer_create`. The downstream
                 // `permit_grant` only fires on accept — out of scope for this test.
                 const user_two = await test_app.create_account({ username: 'user_two' });
-                const offer_res = await rpc_call({
+                const offer_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: permit_offer_create_action_spec.method,
+                    spec: permit_offer_create_action_spec,
                     params: { to_account_id: user_two.account.id, role: grantable_role },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(offer_res.ok, 'permit_offer_create should succeed');
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: audit_log_list_action_spec.method,
+                    spec: audit_log_list_action_spec,
                     params: { event_type: 'permit_offer_create' },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(res.ok, `audit_log_list failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const body = res.result;
-                assert.ok(body.events.length >= 1, 'Expected at least 1 permit_offer_create event');
-                for (const event of body.events) {
+                assert.ok(res.result.events.length >= 1, 'Expected at least 1 permit_offer_create event');
+                for (const event of res.result.events) {
                     assert.strictEqual(event.event_type, 'permit_offer_create');
                 }
             });
@@ -319,15 +358,15 @@ export const describe_standard_admin_integration_tests = (options) => {
                     to_account_id: user_two.account.id,
                     role: grantable_role,
                 });
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: audit_log_permit_history_action_spec.method,
+                    spec: audit_log_permit_history_action_spec,
+                    params: {},
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(res.ok, `audit_log_permit_history failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const body = res.result;
-                assert.ok(body.events.length >= 1, 'Expected at least 1 permit history event');
+                assert.ok(res.result.events.length >= 1, 'Expected at least 1 permit history event');
             });
         });
         // --- 6. Admin audit trail ---
@@ -343,86 +382,83 @@ export const describe_standard_admin_integration_tests = (options) => {
                     granted_by: test_app.backend.actor.id,
                 });
                 // Revoke via RPC
-                const revoke_res = await rpc_call({
+                const revoke_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: permit_revoke_action_spec.method,
+                    spec: permit_revoke_action_spec,
                     params: { actor_id: target_actor.id, permit_id: permit.id },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(revoke_res.ok, `permit_revoke failed: ${revoke_res.ok ? '' : JSON.stringify(revoke_res.error)}`);
                 // Check audit log for permit_revoke event
-                const audit_res = await rpc_call({
+                const audit_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: audit_log_list_action_spec.method,
+                    spec: audit_log_list_action_spec,
                     params: { event_type: 'permit_revoke' },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(audit_res.ok, `audit_log_list failed: ${audit_res.ok ? '' : JSON.stringify(audit_res.error)}`);
-                const audit_body = audit_res.result;
-                assert.ok(audit_body.events.length >= 1, 'Expected permit_revoke audit event');
-                assert.strictEqual(audit_body.events[0].event_type, 'permit_revoke');
+                assert.ok(audit_res.result.events.length >= 1, 'Expected permit_revoke audit event');
+                assert.strictEqual(audit_res.result.events[0].event_type, 'permit_revoke');
             });
             test('admin session revoke-all creates audit event', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
                 const user_two = await test_app.create_account({ username: 'user_two' });
                 // Revoke all sessions for user_two via RPC
-                const revoke_res = await rpc_call({
+                const revoke_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: admin_session_revoke_all_action_spec.method,
+                    spec: admin_session_revoke_all_action_spec,
                     params: { account_id: user_two.account.id },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(revoke_res.ok, `admin_session_revoke_all failed: ${revoke_res.ok ? '' : JSON.stringify(revoke_res.error)}`);
                 // Check audit log
-                const audit_res = await rpc_call({
+                const audit_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: audit_log_list_action_spec.method,
+                    spec: audit_log_list_action_spec,
                     params: { event_type: 'session_revoke_all' },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(audit_res.ok, 'audit_log_list should succeed');
-                const audit_body = audit_res.result;
-                assert.ok(audit_body.events.length >= 1, 'Expected session_revoke_all audit event');
-                assert.strictEqual(audit_body.events[0].event_type, 'session_revoke_all');
+                assert.ok(audit_res.result.events.length >= 1, 'Expected session_revoke_all audit event');
+                assert.strictEqual(audit_res.result.events[0].event_type, 'session_revoke_all');
             });
             test('admin token revoke-all creates audit event', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
                 const user_two = await test_app.create_account({ username: 'user_two' });
                 // Revoke all tokens for user_two via RPC
-                const revoke_res = await rpc_call({
+                const revoke_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: admin_token_revoke_all_action_spec.method,
+                    spec: admin_token_revoke_all_action_spec,
                     params: { account_id: user_two.account.id },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(revoke_res.ok, `admin_token_revoke_all failed: ${revoke_res.ok ? '' : JSON.stringify(revoke_res.error)}`);
                 // Check audit log
-                const audit_res = await rpc_call({
+                const audit_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: audit_log_list_action_spec.method,
+                    spec: audit_log_list_action_spec,
                     params: { event_type: 'token_revoke_all' },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(audit_res.ok, 'audit_log_list should succeed');
-                const audit_body = audit_res.result;
-                assert.ok(audit_body.events.length >= 1, 'Expected token_revoke_all audit event');
-                assert.strictEqual(audit_body.events[0].event_type, 'token_revoke_all');
+                assert.ok(audit_res.result.events.length >= 1, 'Expected token_revoke_all audit event');
+                assert.strictEqual(audit_res.result.events[0].event_type, 'token_revoke_all');
             });
             test('admin session revoke-all 404 emits failure audit', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
                 // `Uuid = z.uuid()` is v4-strict; use a valid v4 shape so we hit the
                 // handler's account lookup rather than failing at param validation.
                 const missing_id = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaa01';
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: admin_session_revoke_all_action_spec.method,
+                    spec: admin_session_revoke_all_action_spec,
                     params: { account_id: missing_id },
                     headers: test_app.create_session_headers(),
                 });
@@ -432,48 +468,48 @@ export const describe_standard_admin_integration_tests = (options) => {
                 // Failure audit row should be visible on the audit-log feed.
                 // `target_account_id` is null (FK prevents referencing a missing id)
                 // — the probed id is preserved under `metadata.attempted_account_id`.
-                const audit_res = await rpc_call({
+                const audit_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: audit_log_list_action_spec.method,
+                    spec: audit_log_list_action_spec,
                     params: { event_type: 'session_revoke_all' },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(audit_res.ok, 'audit_log_list should succeed');
-                const audit_body = audit_res.result;
-                const failure = audit_body.events.find((e) => e.outcome === 'failure');
+                const failure = audit_res.result.events.find((e) => e.outcome === 'failure');
                 assert.ok(failure, 'Expected a failure-outcome session_revoke_all audit event');
                 assert.strictEqual(failure.target_account_id, null);
-                assert.strictEqual(failure.metadata.reason, 'account_not_found');
-                assert.strictEqual(failure.metadata.attempted_account_id, missing_id);
+                const failure_meta = failure.metadata;
+                assert.strictEqual(failure_meta.reason, 'account_not_found');
+                assert.strictEqual(failure_meta.attempted_account_id, missing_id);
             });
             test('admin token revoke-all 404 emits failure audit', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
                 const missing_id = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaa02';
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: admin_token_revoke_all_action_spec.method,
+                    spec: admin_token_revoke_all_action_spec,
                     params: { account_id: missing_id },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(!res.ok, 'Expected 404 for missing account');
                 assert.strictEqual(res.status, 404);
                 assert.strictEqual(res.error.data.reason, 'account_not_found');
-                const audit_res = await rpc_call({
+                const audit_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: audit_log_list_action_spec.method,
+                    spec: audit_log_list_action_spec,
                     params: { event_type: 'token_revoke_all' },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(audit_res.ok, 'audit_log_list should succeed');
-                const audit_body = audit_res.result;
-                const failure = audit_body.events.find((e) => e.outcome === 'failure');
+                const failure = audit_res.result.events.find((e) => e.outcome === 'failure');
                 assert.ok(failure, 'Expected a failure-outcome token_revoke_all audit event');
                 assert.strictEqual(failure.target_account_id, null);
-                assert.strictEqual(failure.metadata.reason, 'account_not_found');
-                assert.strictEqual(failure.metadata.attempted_account_id, missing_id);
+                const failure_meta = failure.metadata;
+                assert.strictEqual(failure_meta.reason, 'account_not_found');
+                assert.strictEqual(failure_meta.attempted_account_id, missing_id);
             });
         });
         // --- 7. Audit log completeness ---
@@ -527,19 +563,19 @@ export const describe_standard_admin_integration_tests = (options) => {
                 // 4. revoke permit (RPC)
                 const target_actor = await query_actor_by_account({ db: get_db() }, user_two.account.id);
                 assert.ok(target_actor);
-                const revoke_res = await rpc_call({
+                const revoke_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: permit_revoke_action_spec.method,
+                    spec: permit_revoke_action_spec,
                     params: { actor_id: target_actor.id, permit_id },
                     headers: test_app.create_session_headers(),
                 });
                 assert.ok(revoke_res.ok, `permit_revoke failed: ${revoke_res.ok ? '' : JSON.stringify(revoke_res.error)}`);
                 // 5. create token (RPC)
-                const token_res = await rpc_call({
+                const token_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: account_token_create_action_spec.method,
+                    spec: account_token_create_action_spec,
                     params: { name: 'audit-test-token' },
                     headers: test_app.create_session_headers(),
                 });
@@ -578,15 +614,15 @@ export const describe_standard_admin_integration_tests = (options) => {
                     origin: 'http://localhost:5173',
                     cookie: `${cookie_name}=${relogin_match[1]}`,
                 };
-                const audit_res = await rpc_call({
+                const audit_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: audit_log_list_action_spec.method,
+                    spec: audit_log_list_action_spec,
+                    params: {},
                     headers: relogin_headers,
                 });
                 assert.ok(audit_res.ok, `audit_log_list failed: ${audit_res.ok ? '' : JSON.stringify(audit_res.error)}`);
-                const audit_body = audit_res.result;
-                const events = audit_body.events;
+                const events = audit_res.result.events;
                 // check that each operation produced at least one event.
                 // `permit_offer_create` fires on the admin RPC; `permit_grant`
                 // fires when the recipient accepts (driven by offer_and_accept).
@@ -625,16 +661,15 @@ export const describe_standard_admin_integration_tests = (options) => {
                     granted_by: test_app.backend.actor.id,
                 });
                 // Admin B revokes their own permit via RPC — should succeed
-                const revoke_res = await rpc_call({
+                const revoke_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: permit_revoke_action_spec.method,
+                    spec: permit_revoke_action_spec,
                     params: { actor_id: admin_b.actor.id, permit_id: permit.id },
                     headers: create_headers(admin_b.session_cookie),
                 });
                 assert.ok(revoke_res.ok, `permit_revoke failed: ${revoke_res.ok ? '' : JSON.stringify(revoke_res.error)}`);
-                const result = revoke_res.result;
-                assert.strictEqual(result.revoked, true);
+                assert.strictEqual(revoke_res.result.revoked, true);
             });
             test('admin revoke-all sessions for another admin works', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
@@ -643,17 +678,16 @@ export const describe_standard_admin_integration_tests = (options) => {
                     roles: ['admin'],
                 });
                 // Admin A revokes all of admin B's sessions via RPC
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: admin_session_revoke_all_action_spec.method,
+                    spec: admin_session_revoke_all_action_spec,
                     params: { account_id: admin_b.account.id },
                     headers: create_headers(test_app.backend.session_cookie),
                 });
                 assert.ok(res.ok, `admin_session_revoke_all failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const result = res.result;
-                assert.ok(typeof result.count === 'number', 'Expected count field in response');
-                assert.ok(result.count >= 1, 'Expected at least 1 session revoked');
+                assert.ok(typeof res.result.count === 'number', 'Expected count field in response');
+                assert.ok(res.result.count >= 1, 'Expected at least 1 session revoked');
             });
             test('admin revoke-all tokens for another admin works', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
@@ -662,36 +696,36 @@ export const describe_standard_admin_integration_tests = (options) => {
                     roles: ['admin'],
                 });
                 // Admin B creates an API token via RPC
-                const token_res = await rpc_call({
+                const token_res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: account_token_create_action_spec.method,
+                    spec: account_token_create_action_spec,
                     params: { name: 'admin-b-token' },
                     headers: create_headers(admin_b.session_cookie),
                 });
                 assert.ok(token_res.ok, `account_token_create failed: ${token_res.ok ? '' : JSON.stringify(token_res.error)}`);
                 // Admin A revokes all of admin B's tokens via RPC
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: admin_token_revoke_all_action_spec.method,
+                    spec: admin_token_revoke_all_action_spec,
                     params: { account_id: admin_b.account.id },
                     headers: create_headers(test_app.backend.session_cookie),
                 });
                 assert.ok(res.ok, `admin_token_revoke_all failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const result = res.result;
-                assert.ok(typeof result.count === 'number', 'Expected count field in response');
+                assert.ok(typeof res.result.count === 'number', 'Expected count field in response');
                 // Token was created above, so revoke should evict at least one.
-                assert.ok(result.count >= 1, 'Expected at least 1 token revoked');
+                assert.ok(res.result.count >= 1, 'Expected at least 1 token revoked');
             });
             test('non-admin cannot access admin routes for another account', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
                 const regular_user = await test_app.create_account({ username: 'regular_user_iso' });
                 // Regular user tries to list accounts via the admin RPC — should 403
-                const res = await rpc_call({
+                const res = await rpc_call_for_spec({
                     app: test_app.app,
                     path: rpc_path,
-                    method: admin_account_list_action_spec.method,
+                    spec: admin_account_list_action_spec,
+                    params: null,
                     headers: create_headers(regular_user.session_cookie),
                 });
                 assert.ok(!res.ok, 'Expected admin_account_list to fail for non-admin');
@@ -703,10 +737,16 @@ export const describe_standard_admin_integration_tests = (options) => {
             test('exercises 401/403 on admin routes for error coverage', async () => {
                 const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
                 captured_route_specs ??= test_app.route_specs;
+                // Post-RPC migration, `/api/admin` is nearly empty — admin reads
+                // and mutations live on the RPC endpoint behind spec-level role
+                // auth. The path-prefix carve is still the right scope here
+                // because error coverage is tracked against REST `RouteSpec`s,
+                // not RPC method specs (`describe_rpc_round_trip_tests` covers
+                // the admin RPC surface separately).
                 const prefix = options.admin_prefix ?? '/api/admin';
                 const admin_routes = test_app.route_specs.filter((s) => s.path.startsWith(prefix) && s.auth.type === 'role' && s.auth.role === 'admin');
-                // Hit admin routes without auth to exercise 401 error schemas
-                for (const route of admin_routes.slice(0, 5)) {
+                // Hit admin routes without auth to exercise 401 error schemas.
+                for (const route of admin_routes) {
                     const res = await test_app.app.request(route.path, {
                         method: route.method,
                         headers: { host: 'localhost' },
@@ -717,24 +757,5 @@ export const describe_standard_admin_integration_tests = (options) => {
                 }
             });
         });
-        // --- 8. Admin response schema validation ---
-        describe('admin response schema validation', () => {
-            test('admin route 200 responses match declared output schemas', async () => {
-                const test_app = await create_test_app(build_admin_test_app_options(options, get_db()));
-                const prefix = options.admin_prefix ?? '/api/admin';
-                const admin_get_routes = test_app.route_specs.filter((s) => s.method === 'GET' &&
-                    s.path.startsWith(prefix) &&
-                    s.auth.type === 'role' &&
-                    s.auth.role === 'admin');
-                assert.ok(admin_get_routes.length > 0, 'Expected at least one admin GET route — ensure create_route_specs includes admin routes');
-                for (const route of admin_get_routes) {
-                    const res = await test_app.app.request(route.path, {
-                        headers: test_app.create_session_headers(),
-                    });
-                    assert.strictEqual(res.status, 200, `${route.method} ${route.path} should return 200`);
-                    await assert_response_matches_spec(test_app.route_specs, route.method, route.path, res);
-                }
-            });
-        });
     });
 };