@quickback-dev/cli 0.56.11 → 0.57.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -361,7 +361,7 @@ The compiler automatically injects the four **[audit fields](#audit-fields)** (`
361
361
 
362
362
  ## Audit Fields
363
363
 
364
- Quickback adds four audit columns to **every table** (including child/junction tables without `defineTable`) — never declare them in your schemas:
364
+ Quickback maintains four audit columns on **every table** (including child/junction tables without `defineTable`):
365
365
 
366
366
  | Field | Type | Description |
367
367
  |-------|------|-------------|
@@ -374,6 +374,31 @@ Audit fields are a separate concept from soft-delete (`deletedAt`/`deletedBy`)
374
374
 
375
375
  Opt out of audit injection entirely with `compiler.features.auditFields: false` in `quickback.config.ts`. (You almost never want to.)
376
376
 
377
+ ### Declaring them visibly — `...q.audit()` / `...q.softDelete()`
378
+
379
+ Historically these columns were invisible: injected into the *generated* schema only, so the table object in your editor didn't have them. They are now declared **visibly** (required by default — see below) so `$infer`, your editor, and the emitted schema all agree:
380
+
381
+ ```ts
382
+ export default feature("candidates", {
383
+ columns: {
384
+ id: q.id(),
385
+ name: q.text({ maxLength: 200 }).required(),
386
+ organizationId: q.scope("organization"),
387
+ ...q.audit(), // createdAt / modifiedAt / createdBy / modifiedBy
388
+ ...q.softDelete(), // deletedAt / deletedBy — matches crud.delete.mode
389
+ },
390
+ })
391
+ ```
392
+
393
+ The spreads are **declarative, not definitional**: the compiler expands them to the exact canonical column lines it would otherwise inject, so emitted output is identical either way. Raw Drizzle tables declare the canonical column lines literally instead (under a `── quickback:audit (compiler-managed) ──` marker). Run **`quickback migrate visible-columns`** to add either form across an existing project in one shot.
394
+
395
+ Two rules keep this safe:
396
+
397
+ - **The compiler validates managed columns against canon — on by default.** A `createdAt` missing its default chain, a `.notNull()` `createdBy`, a defaulted `deletedAt`, a renamed SQL name — each breaks a security pillar (audit integrity, ownership predicates, the Firewall's soft-delete ridge, name-keyed guards/RLS), so divergence is a **compile error**, and every feature table must declare the audit quartet visibly (soft-delete pair iff the resource soft-deletes). Never silently normalized. `compiler.features.visibleAuditColumns: false` opts out — invisible injection returns and divergence downgrades to a warning.
398
+ - **Unknown spreads are a compile error.** The columns object is compiled from source, so `...someSharedCols` can't be resolved — it fails the build rather than silently dropping columns.
399
+
400
+ Note `$insert` types the audit keys as `never` — the wrapper hard-stamps them (below), so supplying one is a type error rather than a silently discarded value.
401
+
377
402
  ### How auto-injection works (two layers)
378
403
 
379
404
  "Auto-injection" covers two distinct steps. Conflating them is the most common source of confusion:
@@ -386,16 +411,15 @@ The runtime layer **hard-stamps** every audit field on every write. Caller-suppl
386
411
  ```ts
387
412
  // In a custom action handler — caller cannot fake audit attribution
388
413
  await db.insert(records).values({
389
- id: createId(),
390
414
  status: 'active',
391
415
  createdBy: 'admin', // ← ignored; wrapper writes ctx.userId
392
416
  modifiedAt: '1999-01-01', // ← ignored; wrapper writes "now"
393
417
  });
394
418
  ```
395
419
 
396
- What the caller is responsible for: `id` (the framework doesn't mint ids for you) and the domain fields.
420
+ What the caller is responsible for: the domain fields. (`id` auto-fills via the column's `$defaultFn` — `q.id()` and injected ids both carry one.)
397
421
 
398
- What the caller does *not* need to set: any of the four audit fields, ever.
422
+ What the caller does *not* need to set: `id`, the scope column, or any of the audit fields, ever.
399
423
 
400
424
  ### Actors: who shows up in `createdBy` / `modifiedBy`
401
425
 
@@ -93,6 +93,20 @@ Every sealed blob is `qbseal:<version>:<base64url(json)>`. Three payload shapes:
93
93
 
94
94
  The decoder rejects a non-`qbseal:` string, an unknown version, an envelope over 64 KiB, or a malformed body — all fail-closed.
95
95
 
96
+ ### The `SealedValue` type brand (server-side code)
97
+
98
+ A `.sealed()` / `q.vaultRef()` column is typed as an opaque **`SealedValue`**
99
+ brand in the generated Drizzle schema, not `string`. Any server-side code that
100
+ tries to *use* the value as a string — `JSON.parse(row.backgroundCheck)`,
101
+ `.length`, string interpolation — is a **TypeScript compile error**, on reads
102
+ and on `.returning()` alike. That's the type-level face of "the server is
103
+ structurally unable to read it": at rest the column only ever holds a
104
+ `{ __vaultRef }` marker, and the brand keeps action code from string-processing
105
+ or hand-forwarding that marker. Sealed values leave the system exclusively
106
+ through the `/seal/v1` reveal rails below. (Envelope `.encrypted()` columns are
107
+ deliberately *not* branded — they type as `string` because the server can
108
+ decrypt that tier; an action reading one gets `qbenc:` ciphertext.)
109
+
96
110
  ## The `/seal/v1` lifecycle
97
111
 
98
112
  All routes are `POST`, JSON in/out, mounted at `/seal/v1`, and require an authenticated session with an **active organization** (`requireOrg` → 401/403). Errors use the standard Quickback error envelope. Most write routes accept `"dryRun": true` to validate + preview without persisting.
@@ -82,18 +82,44 @@ export default defineQueue<ProcessMaterialMessage>({
82
82
  The `execute` function receives a context object:
83
83
 
84
84
  ```typescript
85
- execute: async ({ message, db, env, services, ack, retry }) => {
85
+ execute: async ({ message, db, env, services, ack, retry, withInternalContext }) => {
86
86
  // message - The message payload (typed via generic)
87
- // db - Drizzle database instance
87
+ // db - Drizzle database instance (raw — you own provenance on writes)
88
88
  // env - Cloudflare bindings (AI, queues, etc.)
89
89
  // services - Generated services (ai, etc.)
90
90
  // ack() - Acknowledge message (auto-called on success)
91
91
  // retry() - Retry message (auto-called on failure)
92
+ // withInternalContext - enter the INTERNAL trust zone (see below)
92
93
 
93
94
  return { success: true }; // or { success: false, error: 'reason' }
94
95
  }
95
96
  ```
96
97
 
98
+ ### `withInternalContext` — attributable internal writes
99
+
100
+ Queue runs are server-internal: no authenticated user, no request, no org
101
+ scope. The top-level `db` is the **raw** client — writes through it stamp no
102
+ audit actor, and provenance is your responsibility. When the handler needs to
103
+ touch `roles: ['INTERNAL']`-gated rows, or you want its writes attributed,
104
+ enter the internal trust zone:
105
+
106
+ ```typescript
107
+ execute: async ({ message, withInternalContext }) => {
108
+ await withInternalContext(async ({ ctx, db, services }) => {
109
+ // ctx.internal = true, ctx.userId = "system:queue-<name>"
110
+ // db is audit-wrapped: createdBy/modifiedBy stamp as system:queue-<name>
111
+ await db.update(pats).set({ lastUsedAt: new Date().toISOString() });
112
+ });
113
+ return { success: true };
114
+ }
115
+ ```
116
+
117
+ The handle it passes is **audit-wrapped** — `createdBy`/`modifiedBy` land as
118
+ `system:queue-<name>`, matching the cron schedules' `system:cron-<name>`
119
+ convention, so internal writes are attributable in the audit trail. There is
120
+ no `activeOrgId`: tenant scoping happens at the row level via the message
121
+ payload (e.g. `message.body.organizationId`).
122
+
97
123
  ## Constants and Imports
98
124
 
99
125
  The compiler extracts top-level constants and imports from your handler file and includes them in the generated queue consumer: