@pikku/core 0.12.74 → 0.12.77

package/dist/wirings/workflow/scenario-step.types.d.ts

@@ -3,14 +3,20 @@ import type { ScenarioPersona } from '../../services/personas-service.js';
  * Scenario steps: named, typed units of scenario behaviour.
  *
  * A step's body is an ordinary pikku function, so it may drive a browser, call
- * an RPC as its actor, or run a workflow. `given`/`when`/`then` are sugar over
- * `step` — they only change the prose the reporter renders.
+ * an RPC as its actor, or run a workflow. `given` and `when` differ only in the
+ * prose the reporter renders; `then` also changes what runs, because its
+ * bindings are witnesses — every declared surface is observed and the
+ * observations must agree. See {@link ScenarioSurfaceResolution}.
  */
 /**
- * Which Gherkin-style keyword the reporter prefixes this step with. `step`
- * renders no prefix at all.
+ * Which Gherkin-style keyword the reporter prefixes this step with.
+ *
+ * Every step takes one. A scenario is read by people deciding whether it
+ * describes the behaviour they wanted, and a step that says only what it does
+ * without saying whether it is setup, action or claim is the one nobody can
+ * check — which is also why PKU680 can tell a scenario that never asserts.
  */
-export type ScenarioStepPhase = 'step' | 'given' | 'when' | 'then';
+export type ScenarioStepPhase = 'given' | 'when' | 'then';
 /**
  * Who acts in a step.
  *
@@ -41,7 +47,7 @@ export declare const SCENARIO_SURFACES: readonly ScenarioSurface[];
 /**
  * How a step's declared surfaces resolve for one run.
  *
- * `given`/`when`/`step` bindings are **alternatives** — clicking Buy and calling
+ * `given`/`when` bindings are **alternatives** — clicking Buy and calling
  * `createOrder` are two ways to cause one effect, so exactly one runs.
  *
  * `then` bindings are **witnesses** — "the order row says paid" and "the
@@ -73,7 +79,7 @@ export type ScenarioSurfaceResolution = {
     unwitnessed: boolean;
 };
 /**
- * Options accepted by `scenario.step/given/when/then`.
+ * Options accepted by `scenario.given/when/then`.
  *
  * Note the retry default differs from an ordinary workflow step: retrying a
  * failed assertion is the wrong behaviour for a test primitive, so steps

package/dist/wirings/workflow/workflow.types.d.ts

@@ -188,6 +188,13 @@ export type WorkflowsMeta = Record<string, CommonWireMeta & {
     dsl?: boolean;
     expose?: boolean;
     scenario?: boolean;
+    /**
+     * The flow asserts through an expectation helper — `expectService`,
+     * `expectError`, `expectEventually` — rather than a `then` step. Those are
+     * inline steps and carry no phase, so without this PKU680 reads a scenario
+     * whose only witness is a recorded service call as asserting nothing.
+     */
+    asserts?: boolean;
     skip?: string;
     actors?: string[];
 }>;

package/knowledge/decisions/internals/a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md

@@ -0,0 +1,48 @@
+---
+type: decision
+title: A virtual user run is not a workflow and not a queued job
+description: runVirtualUser writes its record, dispatches the run without awaiting it, and returns the id — because an exploratory run has nothing to replay and the record already carries what a queue would be holding
+tags: virtual-user, storage
+---
+
+# A virtual user run is not a workflow and not a queued job
+
+`runVirtualUser` — the RPC `scaffold.virtualUser` generates — does three things
+in order: writes a `VirtualUserRunStore` record, dispatches
+`executeVirtualUserRun` **without awaiting it**, and returns the `runId`. There
+is no workflow, no queue, and no worker.
+
+Both of the alternatives are the obvious ones, and both are wrong for this.
+
+**A workflow** is a replayable step graph: its value is that a run can be
+resumed at the step it died on, and that the same input reaches the same step.
+A virtual user is the opposite by construction — it is an LLM deciding what to
+try next, so no two attempts take the same steps, and there is no step to resume
+*to*. Recording a run as a workflow puts entries in the workflow store that can
+never be replayed, and gives every operator reading that store a row that lies
+about what it is. The seed makes a run *reproducible* — run it again and it
+explores the same way — which is a different property from resumable, and one
+the record already carries.
+
+**A queue** buys durability across a restart and a retry on failure. It costs a
+broker dependency in every application that turns the scaffold on, plus a worker
+whose progress cannot be read anyway: the run's state lives in the store, not in
+the queue entry. The queue would be holding a copy of what the record already
+has, on the way to the same place.
+
+So the record is the run's only trace, and that is what `VirtualUserRunStore`
+exists for. It is also why `fail()` is a method rather than an absence: a run
+that crashed and a run that found nothing are different answers, and a record
+left at `running` is neither.
+
+The cost is real and is stated on the type: **a restart mid-run strands a record
+at `running` with nothing left to finish it.** A run older than its budget
+window and still `running` is dead, not working — that is a read-side rule, and
+it is cheaper than the two dependencies avoided. Nothing retries; a stranded run
+is started again, with its seed if the caller wants the same exploration.
+
+**What this rules out:** dispatching the run through `startWorkflow`; a
+scaffolded queue worker; awaiting the engine inside the request (a run takes
+minutes and survives neither a rollout nor a proxy timeout); and inferring
+`status` from `finishedAt` being unset, which cannot separate a crash from a run
+still going.

package/knowledge/decisions/internals/core-column-form-is-an-axis-of-its-own.md

@@ -0,0 +1,84 @@
+---
+type: decision
+title: A column's at-rest form is an axis of its own
+description: How a value is stored is independent of how sensitive it is, so form carries a required nominal brand on writes while classification stays optional on reads
+tags: core
+---
+
+# A column's at-rest form is an axis of its own
+
+`ColumnForm` in `packages/core/src/data-classification.ts` is a second,
+independent annotation on a column: `plain | hashed | wrapped | sealed`. It
+answers "how are these bytes held?", where `Classification` answers "may this
+value leave the process?".
+
+The two axes were one field before this, with `security: 'encrypted'` sitting
+alongside `secret` as though they were alternatives. They are not, and the
+conflation made the field unanswerable: a token hash and a live bearer token are
+both `secret`, one must never be encrypted — the digest *is* the lookup key —
+and the other must always be. Nothing in a single enum could tell them apart, so
+nothing could check either.
+
+## Why `wrapped` and `sealed` rather than `encrypted`
+
+Sealed values *are* encrypted, so an `encrypted` member sitting beside `sealed`
+would be a supertype posing as a sibling, and every new column would be an
+even-odds guess. What actually separates them is who can read the value back:
+`wrapped` is symmetric and the application holds the key; `sealed` is asymmetric
+and the application holds only the public half. Writing one where the other
+belongs produces a row nobody can ever open, which is why the type system is
+made to know the difference.
+
+## Why these brands are required when `Secret<T>` is optional
+
+`WrappedValue`, `SealedValue` and `HashedValue` are `string & { readonly [sym]:
+true }` with a `unique symbol` — nominal, and **required**, which
+[the classification-brand decision](core-data-classification-brand-is-an-optional-property.md)
+explicitly rules out for `Private`/`Pii`/`Secret`. That decision still stands and
+this does not weaken it. It applies to a different side of a different set of
+columns:
+
+- `Secret<T>` brands **every** classified column's SELECT type. A required brand
+  there would break `where('email', '=', someString)` in every downstream
+  project.
+- A form brands **only** the INSERT/UPDATE type, and only on the columns that
+  opt in by declaring a form. There is nothing to break, because a column
+  without a form generates exactly what it generated before.
+
+The brands compose rather than compete: a wrapped secret column selects as
+`Secret<WrappedValue>`, so the inspector's PKU910 check still finds
+`__classification__`, while a row read back is already a `WrappedValue` and
+flows into a rewrap or re-seal without a cast.
+
+Each brand widens to `string`, so query operands, serialization and template
+literals are unaffected. The constraint is on **construction**: the only way to
+produce one is `envelopeEncrypt`/`envelopeRewrap`/`wrapDEK` (wrapped) or
+`hashToken` (hashed), or the deliberately-named `unsafeAs*` assertions in
+`column-form.ts` for the three cases a bare string legitimately arrives —
+backfill migrations, test fixtures, and values sealed by another service.
+
+## What is deliberately NOT enforced
+
+`envelopeDecrypt` and `unwrapDEK` take plain `string`, not the brand. Requiring
+it would buy nothing — feeding in the wrong string already fails at the AEAD tag
+— while forcing a cast into every path that reads ciphertext out of a row or off
+the wire, which is where casts are least reviewable.
+
+The brand proves *provenance*, not correctness. It cannot know a value was
+wrapped under the right key, and making it know would mean phantom-typing key
+ids per scope, which the multi-recipient path would fight constantly.
+
+## The plain-secret diagnostic
+
+A `secret` column with no declared form raises **PKU483** as a warning, not an
+error. Every project predating the axis has such columns, and failing their next
+`db migrate` would be a breaking change for a diagnosis they have not had a
+chance to act on. `pikku db --fail-on-warn` is how a project opts into the
+ratchet. An explicit `form: 'plain'` silences it — that is the acknowledgement
+that reading the row is *meant* to yield a usable credential.
+
+**What this rules out:** collapsing `wrapped` and `sealed` back into one
+`encrypted`; making the form brands optional (they would enforce nothing);
+re-declaring them in generated schema files, since a local `unique symbol` is a
+distinct nominal type and core's own ciphertext would not be assignable to the
+column it belongs in — `db-codegen` imports them from `@pikku/core` instead.

package/knowledge/decisions/internals/core-data-classification-brand-is-an-optional-property.md

@@ -22,10 +22,17 @@ goes into one.
 
 The consumer is `@pikku/inspector`, whose `findPiiPaths` reads the level union
 directly and whose PKU910 output check detects the brand on a function's return
-type. The brands are populated from `-- @private` / `-- @secret` / `-- @public`
-SQL comment annotations via `pikku db migrate`, which regenerates
+type. The brands are populated from the hand-authored `db/annotations.ts`
+(`DbClassificationMap`) via `pikku db migrate`, which regenerates
 `outDir/db/schema.d.ts` and `outDir/db/classification.gen.ts`.
 
+A column's **at-rest form** is a separate axis making the opposite trade — see
+[form is an axis of its own](core-column-form-is-an-axis-of-its-own.md). Its
+brands are nominal and required, which is safe precisely because they land on
+the INSERT/UPDATE side of the columns that opt in, rather than on the SELECT
+side of every classified column. That is not an exception to the rule below; it
+is a different rule about a different side.
+
 **What this rules out:** making `__classification__` required to get stronger
 guarantees, or replacing the optional property with a unique symbol / nominal
 brand that behaves like a required one. Either change compiles here and then

package/knowledge/decisions/internals/index.md

@@ -38,6 +38,7 @@ caller is entitled to assume.
 - [CLI parse errors are routed by message prefix](cli-parse-errors-are-routed-by-message-prefix.md) — The CLI runners decide between printing help and printing errors by string-matching the prefixes the parser writes, so those message strings are an interface
 - [CLI stdout is reserved for machine-readable output](cli-stdout-is-reserved-for-machine-readable-output.md) — The default renderer emits single-line NDJSON, diagnostics go to stderr, and --json only hijacks rendering for commands that declared a renderer
 - [CLI unknown long options warn instead of failing](cli-unknown-long-options-warn-instead-of-failing.md) — Unrecognised --long options are accepted, warned about and dropped so older binaries tolerate newer invocations, while unknown short flags stay hard errors
+- [A column's at-rest form is an axis of its own](core-column-form-is-an-axis-of-its-own.md) — How a value is stored is independent of how sensitive it is, so form carries a required nominal brand on writes while classification stays optional on reads
 - [The data-classification brand is an optional property](core-data-classification-brand-is-an-optional-property.md) — Making __classification__ required would break ordinary Kysely operands, so the brand only constrains values flowing out
 - [The function runner restores the wire fields it overwrites](core-function-runner-restores-the-wire-fields-it-overwrites.md) — One wire object is reused across nested calls, so functionId, audit, addonNamespace and rpc are saved and put back in a finally
 - [Hot reload merges generated meta and never replaces it](core-hot-reload-merges-generated-meta-never-replaces-it.md) — Reloading codegen output must preserve runtime-registered meta, which no generated JSON contains
@@ -77,8 +78,11 @@ caller is entitled to assume.
 - [The in-memory workflow service is inline-only and single-process](the-in-memory-workflow-service-is-inline-only-and-single-process.md) — InMemoryWorkflowService wires no queues and implements withRunLock/withStepLock as pass-throughs, because inline execution has no second holder to exclude
 - [The KEK salt is scoped to the key version, not the secret](the-kek-salt-is-scoped-to-the-key-version.md) — One stored salt per key version means N secrets cost one derivation, which is the point of envelope encryption
 - [The schema service is never stubbed, or tests validate nothing](the-schema-service-is-never-stubbed.md) — createStubProxy returns undefined for the schema property so the real schema service is built — a stubbed one turns validation into a silent no-op
+- [One project-shape check, called by both validators](one-project-shape-check-two-validators.md) — workspace validate and fabric validate were separate walks over the same project that duplicated sixteen findings verbatim; the shared half now lives in shared-checks.ts
+- [Scenarios, steps and personas live in files named for them](scenarios-live-in-files-named-for-them.md) — pikkuScenario/pikkuScenarioStep must be in *.scenario.ts/*.steps.ts and definePersonas in *.virtual-user.ts, an error because the mixing is only cheap to undo while it is one file
 - [Trigger declaration is split from trigger source](trigger-declaration-is-split-from-trigger-source.md) — Triggers are declared everywhere but subscribed only in the trigger worker, so app processes never open the underlying subscription
 - [TypedSecretService caches for the process lifetime](typed-secret-service-caches-for-the-process-lifetime.md) — Resolved secrets are cached with no TTL, so a secret rotated out of band is not picked up until restart — tracked as pikkujs/pikku#964
+- [Both validators check personas through one shared module, and a persona counts from either the meta or the source](validate-checks-personas-through-a-shared-module.md) — workspace validate and fabric validate are separate implementations, so the persona/actor/knowledge checks live in persona-checks.ts and are called by both
 - [Webhook delivery history records every attempt, best effort](webhook-delivery-history-records-every-attempt-best-effort.md) — The webhook worker persists each attempt before it throws, and a failure to persist is logged rather than allowed to mask the delivery result
 - [Webhook service collaborators are constructor args, not locator lookups](webhook-service-collaborators-are-constructor-args-not-locator-lookups.md) — QueueWebhookService takes its queue as a constructor parameter so a project wiring webhooks without a queue fails to compile instead of at first send
 - [Whether a run is inline is read from the run record](whether-a-run-is-inline-is-read-from-the-run-record.md) — The runContexts map is a read-through cache over WorkflowRun.inline and a lifetime for replay ordinals, never the answer to what a run is

package/knowledge/decisions/internals/one-project-shape-check-two-validators.md

@@ -0,0 +1,53 @@
+---
+type: decision
+title: One project-shape check, called by both validators
+description: workspace validate and fabric validate were separate walks over the same project that duplicated sixteen findings verbatim; the shared half now lives in shared-checks.ts and fabric validate is that plus the deploy-shaped checks
+tags: cli, validate, fabric
+---
+
+# One project-shape check, called by both validators
+
+`pikku workspace validate` and `pikku fabric validate` read like one command
+with a flag. They were two implementations — 495 lines and 2026 — that walked
+the same project and emitted sixteen identical findings. `functions-dir-missing`
+existed character for character in both files. All sixteen already agreed on
+severity, which is the only reason the duplication was invisible.
+
+What the duplication cost was not the lines. It was that each validator carried
+checks the other lacked for no reason anyone could name, and nobody noticed
+because nobody read them side by side:
+
+- fabric validate never checked that `packages/functions` declares zod v4, or
+  that it has a `package.json` at all — while it did check that six other
+  dependencies are present.
+- workspace validate never checked the four scaffold flags beyond `console`,
+  though the console it requires is useless without `rpc`.
+- fabric validate swallowed a JSON parse error and reported
+  `pikku-config-missing` for a file sitting right there.
+
+Two of workspace validate's own checks were not merely absent from fabric — they
+had never run anywhere:
+
+- the auth checks were gated on a middleware instance with `definitionId ===
+  'betterAuthSession'`, but the CLI wires `betterAuthStatelessSession` whenever
+  `session.cookieCache` is on, which is the configuration Fabric asks for. So
+  they skipped precisely the apps most likely to have auth.
+- they looked for migrations in `packages/functions/db/`, and for tables named
+  `app_user` and `auth_verification_token`. `pikku db migrate` reads migrations
+  from `<root>/db/<engine>/`, and those two table names appear nowhere else in
+  pikku or in any template. Had the gate ever opened, the check would have been
+  wrong for every project it fired on.
+
+`shared-checks.ts` is now the half that is true of any pikku project regardless
+of where it deploys. Workspace validate is exactly that module; fabric validate
+is that module plus the deploy-shaped checks — themes, frontends, the
+Cloudflare adapter, the `.gitignore` contract, the frontend type-check.
+
+Fabric's fix hints won where the two differed: they are multi-line and show the
+config block to paste, and there was no reason workspace users were getting the
+one-line version.
+
+**What this rules out:** adding a check to one validator and not the other;
+`pikku fabric validate` reporting a corrupt config as a missing one; asserting
+auth table names no scaffold generates; and reading migrations from anywhere
+other than where `pikku db migrate` reads them.

package/knowledge/decisions/internals/scenarios-live-in-files-named-for-them.md

@@ -0,0 +1,48 @@
+---
+type: decision
+title: Scenarios, steps and personas live in files named for them, and validate errors when they do not
+description: pikkuScenario/pikkuFeature/pikkuScenarioStep must be in *.scenario.ts, *.scenarios.ts or *.steps.ts, and definePersonas/runVirtualUser in *.virtual-user.ts or *.vu.ts — an error, because the mixing is only cheap to undo while it is one file
+tags: cli, validate, scenarios, personas
+---
+
+# Scenarios, steps and personas live in files named for them, and validate errors when they do not
+
+A `pikkuScenario` declared beside the functions it exercises reads as more of
+the same file. The wiring, the function, and the test of the function arrive in
+one scroll, and the scenario is the part that gets lost — you cannot tell from
+a directory listing which files ship and which files test.
+
+So `validate` requires the declaration to be in a file named for what it is:
+
+| declaration | file |
+| --- | --- |
+| `pikkuScenario`, `pikkuFeature` | `*.scenario.ts`, `*.scenarios.ts` |
+| `pikkuScenarioStep` and its platform/addon variants | `*.steps.ts` (or the above) |
+| `definePersonas`, `runVirtualUser` | `*.virtual-user.ts`, `*.vu.ts` |
+
+Three suffixes for scenarios rather than one, because the split that matters is
+scenarios apart from application code, not a particular spelling — `.steps.ts`
+holds the steps, `.scenarios.ts` holds the scenarios that call them, and a
+project that already made that split does not have to rename anything.
+
+**Error, not warning.** The mixing is cheap to undo while it is one file and
+expensive once it is thirty, and a warning is exactly the signal a project
+learns to scroll past. This is the one place where the scenario checks are
+strict: everything else `validate` says about scenarios (no personas declared,
+no actor sign-in, no environments) is a warning, because those describe an
+under-tested project rather than an unreadable one.
+
+**Personas are the virtual-user file** because there is no `defineVirtualUsers`
+to look for. That name was retired in favour of `definePersonas`: a virtual user
+is derived rather than authored — the function meta becomes its catalogue, the
+scenario meta becomes its intents, the declared personas become its identities.
+The persona list is the only part a project writes, so it is the part that has
+to be findable by filename.
+
+Matching is on the call (`\bpikkuScenario\s*\(`), not the import, so an aliased
+import cannot slip past and a mention in a comment or a string does not trip it.
+Generated files are exempt — codegen puts things where it likes.
+
+**What this rules out:** a scenario in a function file; a step in a wiring file;
+personas in a general-purpose `personas.ts`; and reporting any of these as a
+warning that a project can carry indefinitely.

package/knowledge/decisions/internals/validate-checks-personas-through-a-shared-module.md

@@ -0,0 +1,43 @@
+---
+type: decision
+title: Both validators check personas through one shared module, and a persona counts from either the meta or the source
+description: workspace validate and fabric validate are separate implementations, so the persona/actor/knowledge checks live in persona-checks.ts and are called by both — and a persona is counted from the generated meta or a definePersonas() source scan, whichever answers first
+tags: cli, validate, scenarios, personas
+---
+
+# Both validators check personas through one shared module, and a persona counts from either the meta or the source
+
+`pikku workspace validate` and `pikku fabric validate` read like one command
+with a flag. They are not. They are two implementations that walk the same
+project and duplicate about eighteen findings between them verbatim —
+`functions-dir-missing` exists twice, character for character, in two files.
+Fabric adds the deploy-shaped checks (themes, frontends, the Cloudflare
+adapter, the `.gitignore` contract); workspace adds the local-development ones
+(`dev.db`, the auth migrations).
+
+So a check written into either one is a check half the projects never run. An
+app that never deploys through fabric only ever sees workspace validate; an app
+that does sees fabric validate in CI. The persona checks are the kind that only
+pay off when nobody remembers to ask for them, which means they had to be in
+both. Rather than duplicate them a nineteenth time, they live in
+`persona-checks.ts` and both validators call `runPersonaChecks`. Merging the
+two validators outright is the better fix and a much larger one; this does not
+block it.
+
+**A persona counts from either source, and either alone is wrong at a
+predictable moment.** The generated `pikku-personas-meta.gen.json` is empty on
+a fresh clone where codegen has not run, so trusting only it means a warning
+that fires on every new checkout — and a validator that cries wolf gets muted,
+after which it never says anything worth hearing. A source scan for
+`definePersonas(` cannot see personas an addon contributed. Declared by either
+counts as declared.
+
+**Everything here is `warn`, never `error`.** A project with no personas is
+under-tested, not broken, and `validate` gating a deploy on it would make the
+first thing anyone does with the check be to remove it. `knowledge-empty` stays
+at the `info` the shared `@pikku/knowledge` package already assigned it rather
+than being raised to match — the severity belongs to that package.
+
+**What this rules out:** duplicating the checks into both validators;
+adding them to only one; deriving the persona count from the generated meta
+alone; failing a build over a missing persona.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.74",
+  "version": "0.12.77",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -8,7 +8,7 @@
   "main": "dist/index.js",
   "type": "module",
   "scripts": {
-    "tsc": "tsc",
+    "tsc": "tsc && tsc -p tsconfig.type-tests.json",
     "build": "tsc -b",
     "ncu": "npx npm-check-updates",
     "release": "npm run build && npm test",
@@ -57,6 +57,7 @@
     "./services/v8-coverage": "./dist/services/v8-coverage-service.js",
     "./services/istanbul-coverage": "./dist/services/istanbul-coverage-service.js",
     "./services/local-content": "./dist/services/local-content.js",
+    "./services/local-content-request-handler": "./dist/services/local-content-request-handler.js",
     "./services/temporary-file-service": "./dist/services/temporary-file-service.js",
     "./crypto-utils": "./dist/crypto-utils.js",
     "./hmac": "./dist/utils/hmac.js",

package/src/column-form.test.ts

@@ -0,0 +1,97 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  hashToken,
+  unsafeAsHashed,
+  unsafeAsSealed,
+  unsafeAsWrapped,
+} from './column-form.js'
+import type {
+  HashedValue,
+  SealedValue,
+  WrappedValue,
+} from './data-classification.js'
+import { deriveKEK, envelopeEncrypt, envelopeRewrap } from './crypto-utils.js'
+
+const KEY_MATERIAL = 'x'.repeat(32)
+
+describe('hashToken', () => {
+  test('is the sha256 of the input, lowercase hex', async () => {
+    // Known vector, so a refactor of the hex encoding cannot quietly change
+    // what every stored hash in every downstream database means.
+    assert.equal(
+      await hashToken('abc'),
+      'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'
+    )
+  })
+
+  test('is stable across calls', async () => {
+    assert.equal(await hashToken('token'), await hashToken('token'))
+  })
+
+  test('separates different inputs', async () => {
+    assert.notEqual(await hashToken('a'), await hashToken('b'))
+  })
+})
+
+describe('the form brands', () => {
+  test('a plain string is not assignable to any of them', () => {
+    // @ts-expect-error plaintext cannot be written to a wrapped column
+    const wrapped: WrappedValue = 'not-ciphertext'
+    // @ts-expect-error plaintext cannot be written to a sealed column
+    const sealed: SealedValue = 'not-ciphertext'
+    // @ts-expect-error a raw token cannot be written where its hash belongs
+    const hashed: HashedValue = 'raw-token'
+    assert.ok(wrapped && sealed && hashed)
+  })
+
+  test('the three do not substitute for one another', () => {
+    const wrapped = unsafeAsWrapped('ct')
+    // @ts-expect-error a value fabric cannot read is not one it can
+    const asWrapped: WrappedValue = unsafeAsSealed('ct')
+    // @ts-expect-error a digest is not ciphertext
+    const asHashed: HashedValue = wrapped
+    assert.ok(asWrapped && asHashed)
+  })
+
+  test('but each still widens to string, so reads and query operands are unaffected', () => {
+    const asString: string = unsafeAsWrapped('ct')
+    assert.equal(asString, 'ct')
+    assert.equal(`${unsafeAsHashed('abc')}`, 'abc')
+  })
+})
+
+describe('the envelope primitives produce the brand', () => {
+  test('envelopeEncrypt returns ciphertext that is writable to a wrapped column', async () => {
+    const kek = await deriveKEK(KEY_MATERIAL, 'c2FsdA')
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, 'value')
+    // No cast: this is the whole mechanism — the only way to satisfy the
+    // column type is to have actually encrypted something.
+    const forColumn: WrappedValue = ciphertext
+    const dekForColumn: WrappedValue = wrappedDEK
+    assert.ok(forColumn.length > 0 && dekForColumn.length > 0)
+  })
+
+  test('a rewrapped DEK is still writable, so rotation needs no escape hatch', async () => {
+    const oldKek = await deriveKEK(KEY_MATERIAL, 'c2FsdA')
+    const newKek = await deriveKEK('y'.repeat(32), 'c2FsdA')
+    const { wrappedDEK } = await envelopeEncrypt(oldKek, 'value')
+    const rewrapped: WrappedValue = await envelopeRewrap(
+      oldKek,
+      newKek,
+      wrappedDEK
+    )
+    assert.notEqual(rewrapped, wrappedDEK)
+  })
+
+  test('decrypting accepts a bare string, so reading a row back needs no cast', async () => {
+    const kek = await deriveKEK(KEY_MATERIAL, 'c2FsdA')
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, 'value')
+    const { envelopeDecrypt } = await import('./crypto-utils.js')
+    const fromRow: string = ciphertext
+    assert.equal(
+      await envelopeDecrypt<string>(kek, fromRow, wrappedDEK),
+      'value'
+    )
+  })
+})

package/src/column-form.ts

@@ -0,0 +1,58 @@
+// knowledge: decisions/internals/core-column-form-is-an-axis-of-its-own.md
+import type {
+  HashedValue,
+  SealedValue,
+  WrappedValue,
+} from './data-classification.js'
+
+/**
+ * SHA-256 of a credential, lowercase hex — the sole producer of `HashedValue`.
+ *
+ * Deliberately unpeppered. These are high-entropy random bearer tokens, not
+ * passwords: there is no candidate set to search, so a pepper would add a key
+ * to manage and a rotation story to own while buying nothing. A column holding
+ * a *low*-entropy secret is not a `hashed` column — it wants a password KDF and
+ * a different type entirely.
+ *
+ * Async because it runs on WebCrypto rather than `node:crypto`, so the same
+ * code path works in a Worker. Callers that hash a bearer token on every
+ * request are already async.
+ */
+export const hashToken = async (raw: string): Promise<HashedValue> => {
+  const subtle = globalThis.crypto?.subtle
+  if (!subtle) {
+    throw new Error('WebCrypto not available')
+  }
+  const digest = await subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(raw)
+  )
+  let hex = ''
+  for (const byte of new Uint8Array(digest)) {
+    hex += byte.toString(16).padStart(2, '0')
+  }
+  return hex as HashedValue
+}
+
+/**
+ * Assert that a string already in storage is ciphertext of the given form.
+ *
+ * The brands exist so that new writes must come from a real encrypt/hash call,
+ * but three paths legitimately hold such a value as a bare `string`: a
+ * migration backfilling rows written before the column declared its form, a
+ * test fixture, and a value arriving over the wire from a service that sealed
+ * it elsewhere. Each of those is a promise the caller is making, not something
+ * the type system can check — which is why these are named to be greppable and
+ * why there is no non-`unsafe` spelling. If one of these appears in ordinary
+ * request-handling code, that is the bug.
+ */
+export const unsafeAsWrapped = (stored: string): WrappedValue =>
+  stored as WrappedValue
+
+/** See `unsafeAsWrapped`. */
+export const unsafeAsSealed = (stored: string): SealedValue =>
+  stored as SealedValue
+
+/** See `unsafeAsWrapped`. */
+export const unsafeAsHashed = (stored: string): HashedValue =>
+  stored as HashedValue

package/src/crypto-utils.ts

@@ -1,3 +1,4 @@
+import type { WrappedValue } from './data-classification.js'
 import { WeakKeyMaterialError } from './errors/errors.js'
 
 const encoder = new TextEncoder()
@@ -373,11 +374,19 @@ export const deriveKEK = async (
   return deriveKey(passphrase, fromBase64Url(salt))
 }
 
+/**
+ * The one place a `WrappedValue` is minted. Every branded return below routes
+ * through here, so the assertion "these bytes really are ciphertext" is made
+ * once and audited once instead of at each call site.
+ */
+const asWrapped = (ciphertext: string): WrappedValue =>
+  ciphertext as WrappedValue
+
 export const wrapDEK = async (
   kek: CryptoKey,
   plaintextDEK: string
-): Promise<string> => {
-  return encryptWithCryptoKey(kek, plaintextDEK)
+): Promise<WrappedValue> => {
+  return asWrapped(await encryptWithCryptoKey(kek, plaintextDEK))
 }
 
 export const unwrapDEK = async (
@@ -408,8 +417,8 @@ const decryptWithDEK = async <T>(
 }
 
 export interface EnvelopeEncryptResult {
-  ciphertext: string
-  wrappedDEK: string
+  ciphertext: WrappedValue
+  wrappedDEK: WrappedValue
 }
 
 export const envelopeEncrypt = async (
@@ -417,11 +426,21 @@ export const envelopeEncrypt = async (
   value: unknown
 ): Promise<EnvelopeEncryptResult> => {
   const dek = await generateDEK()
-  const ciphertext = await encryptWithDEK(dek, value)
+  const ciphertext = asWrapped(await encryptWithDEK(dek, value))
   const wrappedDEK = await wrapDEK(kek, dek)
   return { ciphertext, wrappedDEK }
 }
 
+/**
+ * Note the inputs are plain `string`, not `WrappedValue`.
+ *
+ * The brand exists to stop plaintext being *written* to a wrapped column, and
+ * a `WrappedValue` is assignable to `string`, so a branded caller still passes
+ * without a cast. Demanding the brand here would buy nothing — feeding the
+ * wrong string in already fails at the AEAD tag — while forcing a cast into
+ * every path that reads ciphertext back out of a row, a parsed envelope, or the
+ * wire, which is exactly where casts are least reviewable.
+ */
 export const envelopeDecrypt = async <T>(
   kek: CryptoKey,
   ciphertext: string,
@@ -435,7 +454,7 @@ export const envelopeRewrap = async (
   oldKEK: CryptoKey,
   newKEK: CryptoKey,
   wrappedDEK: string
-): Promise<string> => {
+): Promise<WrappedValue> => {
   const dek = await unwrapDEK(oldKEK, wrappedDEK)
   return wrapDEK(newKEK, dek)
 }