@pikku/cli 0.12.93 → 0.12.99

package/dist/src/functions/commands/scenario-ladder.js

@@ -49,7 +49,7 @@ export const collectScenarioStepProse = (workflowMeta, functionsMeta) => {
     for (const step of walkScenarioSteps(workflowMeta?.steps)) {
         const stepMeta = functionsMeta[step.stepFunc];
         const parts = {
-            phase: step.phase ?? 'step',
+            phase: step.phase,
             description: step.options?.description ?? stepMeta?.description ?? step.stepName,
             // A call-site description is an explicit override, so it wins over the
             // step's template the same way it wins over its description.
@@ -76,16 +76,65 @@ const sameProse = (a, b) => a.phase === b.phase &&
     a.description === b.description &&
     a.template === b.template &&
     a.actor === b.actor;
-/** The step functions in this scenario that declare `browser: true`. */
+/** The step functions in this scenario that declare a `browser` binding. */
 export const scenarioBrowserSteps = (workflowMeta, functionsMeta) => {
     const names = new Set();
     for (const step of walkScenarioSteps(workflowMeta?.steps)) {
-        if (functionsMeta[step.stepFunc]?.scenarioStepBrowser === true) {
+        if (functionsMeta[step.stepFunc]?.scenarioStepSurfaces?.includes('browser')) {
             names.add(step.stepFunc);
         }
     }
     return [...names];
 };
+/**
+ * Steps this scenario cannot run on `surface` at all — they declare neither a
+ * binding for it nor a `default` to fall back to.
+ *
+ * Every phase counts. An action with nothing to run is a broken ladder; an
+ * assertion with nothing to run would report a pass having checked nothing,
+ * which the engine now refuses outright. Both are better caught here, so the
+ * flow is held back with a reason than failed halfway through.
+ *
+ * A step that *can* run, just not on the run surface, is the different case — a
+ * coverage gap, counted by {@link scenarioSurfaceCoverage} rather than a reason
+ * to skip.
+ */
+export const scenarioStepsWithoutBinding = (workflowMeta, functionsMeta, surface) => {
+    const names = new Set();
+    for (const step of walkScenarioSteps(workflowMeta?.steps)) {
+        const surfaces = functionsMeta[step.stepFunc]?.scenarioStepSurfaces ?? [
+            'default',
+        ];
+        if (!surfaces.includes(surface) && !surfaces.includes('default')) {
+            names.add(step.stepFunc);
+        }
+    }
+    return [...names];
+};
+export const scenarioSurfaceCoverage = (workflowMeta, functionsMeta, runSurface) => {
+    let onSurface = 0;
+    let total = 0;
+    const unwitnessed = new Set();
+    for (const step of walkScenarioSteps(workflowMeta?.steps)) {
+        const surfaces = functionsMeta[step.stepFunc]?.scenarioStepSurfaces ?? [
+            'default',
+        ];
+        // A step with no binding this run can execute never runs, so it is not a
+        // statistic about this run — `scenarioStepsWithoutBinding` holds the flow
+        // back for it. Counting it here would score a run on work it refuses to do.
+        if (!surfaces.includes(runSurface) && !surfaces.includes('default')) {
+            continue;
+        }
+        total += 1;
+        if (runSurface === 'default' || surfaces.includes(runSurface)) {
+            onSurface += 1;
+        }
+        else if (step.phase === 'then') {
+            unwitnessed.add(step.stepFunc);
+        }
+    }
+    return { onSurface, total, unwitnessed: [...unwitnessed] };
+};
 /**
  * Render one step's gherkin sentence.
  *

package/dist/src/functions/commands/scenario.d.ts

@@ -1,3 +1,4 @@
+import type { ScenarioSurface } from '@pikku/core/workflow';
 export declare const scenarioList: import("#pikku").PikkuFunctionConfig<{}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
 export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     environment: string;
@@ -7,6 +8,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     excludeTags?: string;
     coverage?: boolean;
     browser?: boolean;
+    run?: ScenarioSurface;
+    strict?: boolean;
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
@@ -20,6 +23,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     excludeTags?: string;
     coverage?: boolean;
     browser?: boolean;
+    run?: ScenarioSurface;
+    strict?: boolean;
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;
@@ -33,6 +38,8 @@ export declare const scenarioRun: import("#pikku").PikkuFunctionConfig<{
     excludeTags?: string;
     coverage?: boolean;
     browser?: boolean;
+    run?: ScenarioSurface;
+    strict?: boolean;
     spawn?: boolean;
     keepAlive?: boolean;
     trace?: boolean;

package/dist/src/functions/commands/scenario.js

@@ -1,18 +1,21 @@
 import { resolve, join } from 'node:path';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { pikkuSessionlessFunc } from '#pikku';
-import { InMemoryWorkflowService, createHttpScenarioActors, } from '@pikku/core/services';
+import { InMemoryWorkflowService } from '@pikku/core/services';
+import { createHttpPersonas } from '@pikku/core/persona';
 import { PikkuScenarioService } from '@pikku/core/scenario';
 import { pikkuState, getAllPackageStates } from '@pikku/core/internal';
 import { resolveFeatureScenarios } from '@pikku/core/workflow';
 import { loadScenarioBootstrap } from './load-user-project.js';
-import { collectScenarioStepProse, scenarioBrowserSteps, scenarioFailureFromSteps, scenarioStepRows, } from './scenario-ladder.js';
+import { collectScenarioStepProse, scenarioBrowserSteps, scenarioFailureFromSteps, scenarioStepRows, scenarioStepsWithoutBinding, scenarioSurfaceCoverage, } from './scenario-ladder.js';
+import { SCENARIO_SURFACES } from '@pikku/core/workflow';
 import { formatScenarioReport } from './scenario-formatter.js';
 import { resolveScenarioBrowserProvider, scenarioBrowserLifecycle, } from './scenario-browser.js';
-import { resolveScenarioActors } from '../../utils/resolve-scenario-actors.js';
+import { resolvePersonas } from '../../utils/resolve-personas.js';
 import { spawnDevServer } from '../../server/spawn-dev-server.js';
 import { buildScenarioPlan } from './scenario-plan.js';
-import { resolveScenarioEnvironment } from './scenario-environment.js';
+import { resolveEnvironment } from './environment.js';
+import { createDevAIAgentRunner } from './dev-ai-runner.js';
 const isScenario = (wf) => wf?.scenario === true;
 const listScenarios = (state) => Object.entries(state.workflows?.meta ?? {})
     .filter(([, wf]) => isScenario(wf))
@@ -84,14 +87,17 @@ export const scenarioList = pikkuSessionlessFunc({
     },
 });
 export const scenarioRun = pikkuSessionlessFunc({
-    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, spawn = false, keepAlive = false, trace = false, apiUrl, appUrl, }) => {
+    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, run: runSurface = 'default', strict = false, spawn = false, keepAlive = false, trace = false, apiUrl, appUrl, }) => {
+        if (!SCENARIO_SURFACES.includes(runSurface)) {
+            throw new Error(`Unknown --run surface '${runSurface}'. Expected one of: ${SCENARIO_SURFACES.join(', ')}.`);
+        }
         const state = await getInspectorState(true, false, false, true);
         // Resolved once, so actors, step env, the browser driver and any spawned
         // server all target the same place — including when the target only exists
         // at run time and arrives through --api-url/--app-url.
-        const env = resolveScenarioEnvironment({
+        const env = resolveEnvironment({
             environment,
-            environments: config.scenarios?.environments ?? {},
+            environments: config.environments ?? {},
             apiUrl,
             appUrl,
             spawn,
@@ -164,16 +170,17 @@ export const scenarioRun = pikkuSessionlessFunc({
             throw new Error('SCENARIO_ACTOR_SECRET is not set — scenario actors cannot sign in. ' +
                 'Export it in the environment running this command (never put it in pikku.config.json).');
         }
-        // Declared actors plus one per persona nobody declared a body for. Resolved
-        // once: the HTTP actors and the Playwright provider below must see the same
-        // registry, and codegen resolved the same way to type `ScenarioActorName`.
-        const scenarioActors = resolveScenarioActors(config.scenarios);
-        const actors = createHttpScenarioActors({
+        // Every declared persona, with its address filled in. Resolved once: the
+        // HTTP personas and the Playwright provider below must see the same
+        // registry, and codegen resolved the same way to type `PersonaName`.
+        const scenarioActors = resolvePersonas(state.personas?.definitions ?? [], config.scenarios?.emailDomain);
+        const actors = createHttpPersonas({
             apiUrl: env.apiUrl,
             secret,
-            actors: scenarioActors,
+            personas: scenarioActors,
             signInPath: env.signInPath,
             rpcPath: env.rpcPath,
+            model: config.scenarios?.model,
         });
         const functionsMeta = state.functions?.meta ?? {};
         const scenarioNames = new Set(groups.flatMap((group) => group.entries.map((e) => e.scenarioName)));
@@ -183,6 +190,15 @@ export const scenarioRun = pikkuSessionlessFunc({
             scenarioBrowserSteps(state.workflows?.meta?.[name], functionsMeta),
         ])
             .filter(([, steps]) => steps.length > 0));
+        // `--no-browser` is the blunt form of `--run default`: a machine with no
+        // browser takes the server-side path rather than skipping the scenario.
+        const effectiveSurface = browser === false && runSurface === 'browser' ? 'default' : runSurface;
+        const unrunnableStepsByFlow = new Map([...scenarioNames]
+            .map((name) => [
+            name,
+            scenarioStepsWithoutBinding(state.workflows?.meta?.[name], functionsMeta, effectiveSurface),
+        ])
+            .filter(([, steps]) => steps.length > 0));
         // Two reasons a scenario is held back, both reported as SKIP rather than
         // failed. `--no-browser` is the direct replacement for cucumber's `@console`
         // tag, so a standard run stays green on a machine with no browser; a `skip`
@@ -191,8 +207,9 @@ export const scenarioRun = pikkuSessionlessFunc({
         const skipReasonFor = (entry) => {
             if (entry.skip)
                 return entry.skip;
-            if (!browser && browserStepsByFlow.has(entry.scenarioName)) {
-                return 'browser steps, --no-browser';
+            const unrunnable = unrunnableStepsByFlow.get(entry.scenarioName);
+            if (unrunnable?.length) {
+                return `no ${effectiveSurface} or default binding: ${unrunnable.join(', ')}`;
             }
             return undefined;
         };
@@ -215,10 +232,27 @@ export const scenarioRun = pikkuSessionlessFunc({
             apiUrl: env.apiUrl,
             appUrl: env.appUrl,
         });
+        scenarioService.setRunSurface(effectiveSurface);
+        // Scenario steps run here, not on the target — everything they touch of the
+        // app goes over HTTP through an actor, which is what `guardRpc` below
+        // enforces. `actor.converse` is the exception, and the reason this is not
+        // just the three services above: the persona's own turns are LLM calls made
+        // in this process, and without a runner every conversing scenario fails
+        // before it says anything. Built the same way `pikku dev` builds its own,
+        // and only when the project declares agents, so a project with no agents
+        // does not have to have AI env set to run scenarios.
+        const aiAgentRunner = Object.keys(state.agents?.agentsMeta ?? {}).length > 0
+            ? await createDevAIAgentRunner({
+                logger,
+                projectRoot: config.rootDir,
+                variables,
+            })
+            : undefined;
         pikkuState(null, 'package', 'singletonServices', {
             logger,
             workflowService,
             workflowRunService: workflowService,
+            ...(aiAgentRunner ? { aiAgentRunner } : {}),
         });
         const guardRpc = {
             rpcWithWire: async (rpcName) => {
@@ -227,7 +261,11 @@ export const scenarioRun = pikkuSessionlessFunc({
                     `'${environment}' (${env.apiUrl}), not local services.`);
             },
         };
-        const needsBrowser = groups.some((group) => group.entries.some((entry) => browserStepsByFlow.has(entry.scenarioName)));
+        // Only a browser run launches one. Under `--run default` a step with a
+        // browser binding takes its default path instead, so there is nothing to
+        // drive and nothing to pay for.
+        const needsBrowser = effectiveSurface === 'browser' &&
+            groups.some((group) => group.entries.some((entry) => browserStepsByFlow.has(entry.scenarioName)));
         const failureDir = join(resolve(config.rootDir, config.outDir), 'scenario-failures');
         const browserLifecycle = scenarioBrowserLifecycle(needsBrowser
             ? await (async () => {
@@ -446,10 +484,36 @@ export const scenarioRun = pikkuSessionlessFunc({
             trace,
             projectRoot: config.rootDir,
         })) {
-            logger[level](text);
+            const write = logger[level].bind(logger);
+            write(text);
+        }
+        // How much of the run actually happened on the surface it targeted. Every
+        // step counts, so a step that fell back to the server lowers the ratio
+        // rather than needing a footnote. Assertions that fell back are named
+        // separately — those are sentences claiming an observation nobody made.
+        const surfaceCoverage = { onSurface: 0, total: 0 };
+        const unwitnessed = new Set();
+        for (const name of scenarioNames) {
+            const scenario = scenarioSurfaceCoverage(state.workflows?.meta?.[name], functionsMeta, effectiveSurface);
+            surfaceCoverage.onSurface += scenario.onSurface;
+            surfaceCoverage.total += scenario.total;
+            for (const step of scenario.unwitnessed)
+                unwitnessed.add(step);
+        }
+        if (effectiveSurface !== 'default' && surfaceCoverage.total > 0) {
+            const line = `${surfaceCoverage.onSurface}/${surfaceCoverage.total} steps ran on ${effectiveSurface}`;
+            if (unwitnessed.size === 0) {
+                logger.info(line);
+            }
+            else {
+                const write = logger[strict ? 'error' : 'warn'].bind(logger);
+                write(`${line} — asserted server-side only: ${[...unwitnessed].join(', ')}`);
+            }
         }
         const failed = results.filter((r) => r.status === 'failed');
-        if (failed.length > 0 || hookFailures.length > 0) {
+        if (failed.length > 0 ||
+            hookFailures.length > 0 ||
+            (strict && unwitnessed.size > 0)) {
             process.exitCode = 1;
         }
     },

package/dist/src/functions/commands/scopes-shared.d.ts

@@ -1,5 +1,7 @@
+import type { Kysely } from 'kysely';
 import type { FlatScope } from '@pikku/core/scope';
 import { KyselyScopeService } from '@pikku/kysely';
+import type { KyselyPikkuDB } from '@pikku/kysely';
 type Logger = {
     info: (msg: string) => void;
     warn: (msg: string) => void;
@@ -8,6 +10,12 @@ type Logger = {
 export declare const loadDeclaredScopes: (scopesMetaJsonFile: string, logger: Logger) => Promise<FlatScope[] | null>;
 export type OpenedScopeService = {
     service: KyselyScopeService;
+    /**
+     * The same connection the service holds, for the one thing it cannot answer:
+     * a user's id from their address. Grants are keyed by id, and the `user`
+     * table those ids come from is better-auth's, not the scope schema's.
+     */
+    db: Kysely<KyselyPikkuDB>;
     destroy: () => Promise<void>;
 };
 /**
@@ -25,6 +33,10 @@ export declare const openScopeService: ({ config, logger, }: {
         outDir: string;
         runtimeDir?: string;
         srcDirectories: string[];
+        db?: {
+            schema?: string;
+            defaultSchema?: string;
+        };
     };
     logger: Logger;
 }, declared: FlatScope[], command: string) => Promise<OpenedScopeService | null>;

package/dist/src/functions/commands/scopes-shared.js

@@ -52,7 +52,7 @@ export const openScopeService = async ({ config, logger, }, declared, command) =
     if (!userConfig) {
         return null;
     }
-    const resolved = resolveDb(userConfig, config.rootDir, config.outDir, config.runtimeDir);
+    const resolved = resolveDb(userConfig, config.rootDir, config.outDir, config.runtimeDir, config.db);
     if (!resolved) {
         logger.error(`${command}: no database configured — set sqliteDb or postgresUrl in your createConfig.`);
         throw new Error('no database configured');
@@ -62,7 +62,7 @@ export const openScopeService = async ({ config, logger, }, declared, command) =
         const service = new KyselyScopeService(db);
         await service.init();
         await service.syncScopes(declared);
-        return { service, destroy: () => db.destroy() };
+        return { service, db, destroy: () => db.destroy() };
     }
     catch (e) {
         await db.destroy();

package/dist/src/functions/commands/serve.js

@@ -12,6 +12,7 @@ import { loadUserBootstrap, loadUserModule } from './load-user-project.js';
 import { createDevAIAgentRunner } from './dev-ai-runner.js';
 import { resolveConsoleMount } from './serve-console.js';
 import { serverReadyLine } from '../../server/server-ready.js';
+import { createEphemeralContentSigningJWT } from '../../server/content-signing-jwt.js';
 export const serve = pikkuSessionlessFunc({
     remote: true,
     func: async ({ logger, config, getInspectorState, variables, devServerRunner }, { port, console: serveConsole }) => {
@@ -37,7 +38,7 @@ export const serve = pikkuSessionlessFunc({
         const effectiveDbConfig = envDatabaseUrl
             ? parseDatabaseUrl(envDatabaseUrl)
             : userConfig;
-        const resolvedDb = resolveDb(effectiveDbConfig, config.rootDir, config.outDir, config.runtimeDir);
+        const resolvedDb = resolveDb(effectiveDbConfig, config.rootDir, config.outDir, config.runtimeDir, config.db);
         const resolvedLocalDb = resolvedDb ?? undefined;
         const kysely = resolvedLocalDb
             ? await createKysely(resolvedLocalDb)
@@ -54,8 +55,11 @@ export const serve = pikkuSessionlessFunc({
                 sizeLimit: userConfig.content.sizeLimit,
             }
             : undefined;
-        const localContent = localContentConfig
-            ? new LocalContent(localContentConfig, logger)
+        const contentSigningJWT = localContentConfig
+            ? createEphemeralContentSigningJWT()
+            : undefined;
+        const localContent = localContentConfig && contentSigningJWT
+            ? new LocalContent(localContentConfig, logger, contentSigningJWT)
             : undefined;
         const schedulerService = new InMemorySchedulerService();
         const aiStorage = kysely
@@ -128,7 +132,7 @@ export const serve = pikkuSessionlessFunc({
             port: resolvedPort,
             content: localContentConfig,
             ...(consoleMount ? { staticMounts: [consoleMount] } : {}),
-        }, logger);
+        }, logger, { contentSigningJWT });
         const lifecycle = await loadLifecycle();
         await pikkuServer.init();
         await lifecycle?.beforeStart?.(resolvedServices);

package/dist/src/functions/commands/versions-check.js

@@ -30,7 +30,7 @@ export const pikkuVersionsCheck = pikkuSessionlessFunc({
                     if (error.nextVersion !== undefined) {
                         logger.info(`  Set \`version: ${error.nextVersion}\` on the function, then run:`);
                     }
-                    logger.info(`  npx pikku versions-update`);
+                    logger.info(`  npx pikku versions update`);
                 }
                 else if (error.code === ErrorCode.FUNCTION_VERSION_MODIFIED &&
                     error.functionKey) {
@@ -54,7 +54,7 @@ export const pikkuVersionsCheck = pikkuSessionlessFunc({
                     logger.info(``);
                     logger.info(`  This usually means a merge conflict in versions.pikku.json.`);
                     logger.info(`  Resolve the conflict, then run:`);
-                    logger.info(`  npx pikku versions-update`);
+                    logger.info(`  npx pikku versions update`);
                 }
                 else if (error.code === ErrorCode.VERSION_GAP_NOT_ALLOWED &&
                     error.functionKey) {
@@ -85,7 +85,7 @@ export const pikkuVersionsCheck = pikkuSessionlessFunc({
                     }
                     logger.info(``);
                     logger.info(`  The manifest is corrupted. Run:`);
-                    logger.info(`  npx pikku versions-update`);
+                    logger.info(`  npx pikku versions update`);
                 }
                 else {
                     logger.info(`[${error.code}] ${error.message}`);

package/dist/src/functions/commands/virtual-user-formatter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The virtual user run report, and how it is rendered.
+ *
+ * A run is not a pass/fail: a virtual user pursuing plausible goals against a
+ * real stage produces a story — what it tried, what it gave up on, and what
+ * came back that should not have. The findings are the product; everything else
+ * is context for reading them.
+ *
+ * Kept a pure function over plain data for the same reason the scenario
+ * reporter is: a second formatter (JSON for fabric, JUnit for CI) is then one
+ * function rather than an unpicking of the runner.
+ */
+import type { VirtualUserRunResult } from '@pikku/core/virtual-user';
+export interface VirtualUserReportContext {
+    persona: string;
+    disposition: string;
+    environment: string;
+    apiUrl: string;
+    /** How much of the catalogue's read/write split had to be guessed at. */
+    catalogue: {
+        total: number;
+        annotated: number;
+        inferred: number;
+    };
+}
+export interface VirtualUserReportLine {
+    level: 'info' | 'error' | 'warn';
+    text: string;
+}
+export declare const formatVirtualUserReport: (result: VirtualUserRunResult, context: VirtualUserReportContext) => VirtualUserReportLine[];

package/dist/src/functions/commands/virtual-user-formatter.js

@@ -0,0 +1,65 @@
+const STATUS_MARK = {
+    completed: 'DONE',
+    abandoned: 'DROP',
+    stuck: 'STUCK',
+    suspended: 'OPEN',
+    open: 'OPEN',
+};
+/** Why a run ended, in words rather than an enum. */
+const STOPPED_BY = {
+    'no-intents': 'this persona had nothing to want — no scenario names them',
+    'budget-steps': 'ran out of steps',
+    'budget-mutations': 'ran out of mutations',
+    'budget-duration': 'ran out of time',
+    'stop-hook': 'the app called a halt',
+    exhausted: 'saw everything it came for through',
+};
+const findingLine = (finding) => `  ${finding.kind.padEnd(18)} ${finding.detail} (step ${finding.step})`;
+const plural = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
+export const formatVirtualUserReport = (result, context) => {
+    const lines = [];
+    const info = (text) => lines.push({ level: 'info', text });
+    const error = (text) => lines.push({ level: 'error', text });
+    const warn = (text) => lines.push({ level: 'warn', text });
+    info(`Virtual user '${context.persona}' (${context.disposition}) against '${context.environment}' — ${context.apiUrl}`);
+    info(`  seed ${result.seed} · ${plural(context.catalogue.total, 'endpoint')} offered` +
+        (context.catalogue.inferred
+            ? ` · read/write guessed for ${context.catalogue.inferred} of them`
+            : ''));
+    if (result.intents.length) {
+        info('');
+        info('What it tried');
+        for (const intent of result.intents) {
+            const mark = STATUS_MARK[intent.status] ?? intent.status.toUpperCase();
+            const interrupted = intent.suspensions
+                ? `, put down ${plural(intent.suspensions, 'time')}`
+                : '';
+            const summary = intent.summary ? ` — ${intent.summary}` : '';
+            info(`  ${mark.padEnd(5)} ${intent.title} (${plural(intent.steps.length, 'step')}${interrupted})${summary}`);
+        }
+    }
+    info('');
+    if (result.findings.length === 0) {
+        info('Nothing came back that should not have.');
+    }
+    else {
+        error(`${plural(result.findings.length, 'finding')}`);
+        for (const finding of result.findings) {
+            error(findingLine(finding));
+        }
+    }
+    const { tally } = result;
+    info('');
+    info(`${plural(tally.steps, 'step')} · ${plural(tally.calls, 'call')} · ` +
+        `${plural(tally.mutations, 'mutation')} · ${tally.tokensIn}/${tally.tokensOut} tokens ` +
+        `(${tally.model}) · ${Math.round(tally.elapsedMs / 1000)}s`);
+    info(`Stopped because it ${STOPPED_BY[result.stoppedBy]}.`);
+    if (result.stoppedBy === 'no-intents') {
+        warn(`Give it something to want: declare a scenario naming '${context.persona}', or pass --goals.`);
+    }
+    // A seed is only worth printing when there is something to reproduce.
+    if (result.findings.length) {
+        info(`Replay this exact run with --seed ${result.seed}.`);
+    }
+    return lines;
+};

package/dist/src/functions/db/annotation-parser.d.ts

@@ -2,6 +2,8 @@ import type { ColumnKind } from './coercion-plugin.js';
 import { type ZodFormat } from './zod-codegen.js';
 type Classification = 'public' | 'private' | 'pii' | 'secret';
 type AnonymizeStrategy = 'fake:email' | 'fake:name' | 'hash' | 'keep' | null;
+type ColumnForm = 'plain' | 'hashed' | 'wrapped' | 'sealed';
+export declare const COLUMN_FORMS: readonly ["plain", "hashed", "wrapped", "sealed"];
 export interface ColAnnotation {
     /** Column kind override: `date`, `bool`, `json`, or `uuid`. */
     kind?: ColumnKind;
@@ -15,6 +17,11 @@ export interface ColAnnotation {
     format?: ZodFormat;
     classification?: Classification;
     anonymize?: AnonymizeStrategy;
+    /**
+     * At-rest representation, independent of `classification`. Drives the
+     * insert/update brand on the generated column type. Absent means `plain`.
+     */
+    form?: ColumnForm;
 }
 /** Per-table, per-column annotation map sourced from `db/annotations.ts`. */
 export type AnnotationMap = Record<string, Record<string, ColAnnotation>>;
@@ -37,6 +44,13 @@ export declare function nameSuggestsKind(colName: string): ColumnKind | null;
  * where `security` is the privacy level and `classification` is the anonymize
  * strategy. Returns `{}` if the sidecar doesn't exist yet (first migrate run,
  * before it has been generated).
+ *
+ * `DbClassificationMap` nests under the schema name whenever the project has
+ * one (`{ app: { user: { email: … } } }`), so the sidecar is flattened back to
+ * bare table names here — the codegen looks columns up by `bareTableName`.
+ * Reading a schema-qualified map as though it were flat silently yields an
+ * annotation for every column of every table, which is how a project could
+ * classify a column `secret` and still generate it as `private`.
  */
 export declare function loadAnnotations(rootDir: string): AnnotationMap;
 export {};

package/dist/src/functions/db/annotation-parser.js

@@ -1,6 +1,12 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ZOD_FORMATS } from './zod-codegen.js';
+export const COLUMN_FORMS = [
+    'plain',
+    'hashed',
+    'wrapped',
+    'sealed',
+];
 /**
  * Warn-only naming heuristic. We no longer *infer* a column's kind from its
  * name (it produced wrong types — e.g. SQLite stores `*_at` as ISO TEXT, not a
@@ -23,6 +29,17 @@ function parseStrategy(s) {
         ? s
         : null;
 }
+/**
+ * A column entry's own values are all primitives; a table's are objects. That
+ * is the only structural difference between the two levels, and it is what
+ * tells a schema-qualified map (`{ app: { user: { … } } }`) from a bare one
+ * (`{ user: { … } }`) without having to be told which shape was authored.
+ */
+function isColumnEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    return Object.values(value).every((v) => typeof v !== 'object' || v === null);
+}
 /**
  * Load annotations from the `db/annotations.gen.json` sidecar, which is
  * compiled from the developer-authored `db/annotations.ts` (`DbClassificationMap`)
@@ -34,6 +51,13 @@ function parseStrategy(s) {
  * where `security` is the privacy level and `classification` is the anonymize
  * strategy. Returns `{}` if the sidecar doesn't exist yet (first migrate run,
  * before it has been generated).
+ *
+ * `DbClassificationMap` nests under the schema name whenever the project has
+ * one (`{ app: { user: { email: … } } }`), so the sidecar is flattened back to
+ * bare table names here — the codegen looks columns up by `bareTableName`.
+ * Reading a schema-qualified map as though it were flat silently yields an
+ * annotation for every column of every table, which is how a project could
+ * classify a column `secret` and still generate it as `private`.
  */
 export function loadAnnotations(rootDir) {
     const jsonPath = join(rootDir, 'db', 'annotations.gen.json');
@@ -41,8 +65,24 @@ export function loadAnnotations(rootDir) {
         return {};
     try {
         const raw = JSON.parse(readFileSync(jsonPath, 'utf8'));
+        const tables = [];
+        for (const [key, value] of Object.entries(raw)) {
+            if (!value || typeof value !== 'object')
+                continue;
+            const isTable = Object.values(value).every((v) => v === null || isColumnEntry(v));
+            if (isTable) {
+                tables.push([key, value]);
+                continue;
+            }
+            // `key` is a schema; its values are the tables.
+            for (const [table, cols] of Object.entries(value)) {
+                if (cols && typeof cols === 'object') {
+                    tables.push([table, cols]);
+                }
+            }
+        }
         const result = {};
-        for (const [table, cols] of Object.entries(raw)) {
+        for (const [table, cols] of tables) {
             result[table] = {};
             for (const [col, ann] of Object.entries(cols)) {
                 if (!ann)
@@ -57,7 +97,9 @@ export function loadAnnotations(rootDir) {
                     entry.tsType = ann.tsType;
                 if (ann.format && ann.format in ZOD_FORMATS)
                     entry.format = ann.format;
-                // `security` is the privacy level. `encrypted` brands as `secret`.
+                // `security` is the privacy level. The legacy `encrypted` value
+                // predates `form` and conflated the two axes; it still parses, as the
+                // pair it always meant.
                 switch (ann.security) {
                     case 'public':
                     case 'private':
@@ -67,8 +109,14 @@ export function loadAnnotations(rootDir) {
                         break;
                     case 'encrypted':
                         entry.classification = 'secret';
+                        entry.form = 'wrapped';
                         break;
                 }
+                // An explicit `form` wins over the one implied by legacy `encrypted`.
+                if (ann.form &&
+                    COLUMN_FORMS.includes(ann.form)) {
+                    entry.form = ann.form;
+                }
                 const strategy = parseStrategy(ann.classification);
                 if (strategy !== null)
                     entry.anonymize = strategy;

package/dist/src/functions/db/better-auth-schema.js

@@ -3,6 +3,7 @@ import { pathToFileURL } from 'node:url';
 import { readdirSync, statSync, readFileSync, existsSync } from 'node:fs';
 import { join, extname, dirname } from 'node:path';
 import { PIKKU_BETTER_AUTH } from '@pikku/better-auth';
+import { createSecretValue } from '@pikku/core';
 import { LocalVariablesService } from '@pikku/core/services';
 import { loadUserModule } from '../commands/load-user-project.js';
 let cachedGetMigrations = null;
@@ -95,7 +96,7 @@ async function loadAuthFactory(sourceFile) {
 function fakeSecretService() {
     const placeholder = 'schema-introspection-only';
     return {
-        getSecret: async () => placeholder,
+        getSecret: async () => createSecretValue(placeholder),
         hasSecret: async () => true,
         setSecret: async () => { },
     };