@everystack/model 0.4.16 → 0.4.17

package/README.md

@@ -110,6 +110,50 @@ defineModel('posts', {
 
 `privileges` takes only those three, and it is additive — it widens what a role holds and can never narrow it. DML stays in `can()`, where the grant and the row policy are decided together. `db:pull --abilities live` writes this key from the live grants, so an existing database that grants its admin role all three keeps them.
 
+## Soft delete
+
+A `deletedAt` column is a column. `softDelete` is the decision about what it MEANS, and it sits
+on the model beside `fields`:
+
+```typescript
+export const Upload = defineModel('uploads', {
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    accountId: field.uuid().notNull().references(() => Account),
+    s3Key: field.text().notNull(),
+    deletedAt: field.timestamptz(),
+  },
+  softDelete: true,
+  abilities: [can('read', { owner: 'accountId' }), can('delete', { owner: 'accountId' })],
+});
+```
+
+It changes two different things, and neither default is safe:
+
+- **Durability, on every model** — `true` makes a `DELETE` mark `deleted_at` instead of removing
+  the row, and hides marked rows from the data API's reads and updates. `false` makes `DELETE`
+  permanent.
+- **Visibility, only where there is a public read** — `true` AND-s `deleted_at IS NULL` into the
+  anon policy. On an owner-scoped or admin-only model the compiled SQL is identical either way,
+  so durability is the axis that matters there.
+
+**`defineModel` refuses to guess** when a model has `deletedAt` AND either a public read or a way
+to DELETE (`can('delete')`, `can('manage')`, or a `privileges` DELETE grant). Omit the line on
+such a model and it throws at import, naming which branch it tripped. Where nothing reads
+publicly and nothing deletes, the flag provably changes neither the SQL nor the handler, so
+nothing is required.
+
+Pick `true` if the row is meant to survive its own deletion — anything with a cleanup or purge
+job, an audit trail, or rows other tables reference. Pick `false` if `deleted_at` here is
+audit-only and a `DELETE` really should remove the row. It is not cosmetic: a table whose S3
+cleanup job finds work by `deleted_at IS NOT NULL` orphans every file it should have purged if
+the row is hard-deleted instead.
+
+A column named `deleted_at` is not a statement of intent — it is carried for audit, for
+app-layer filtering, for half-finished migrations. This used to be inferred from the field's
+presence, which made the compiler author a security rule nobody wrote. `db:pull` writes the
+flag explicitly for the same reason.
+
 ## Relations
 
 ```typescript
@@ -137,13 +181,18 @@ everystack db:pull     --stage dev   # reverse an existing database into model s
 
 ### Handler config
 
-`deriveHandlerConfig(models)` compiles the same Models into the authorization config `createHandler` consumes (exposed tables, hidden/protected columns, relations, row ownership) — so the HTTP handler and the database enforce the *same* declared rules, with no second source of truth.
+`deriveHandlerConfig(models)` compiles the same Models into the authorization config `createHandler` consumes (exposed tables, hidden/protected columns, relations, row ownership, **`softDelete.tables`**) — so the HTTP handler and the database enforce the *same* declared rules, with no second source of truth.
 
 ```typescript
 import { deriveHandlerConfig } from '@everystack/model';
 const handler = createHandler(db, schema, deriveHandlerConfig(models));
 ```
 
+Do not hand-write the per-table keys beside it. Each one is a view of the models, and a
+hand-kept copy drifts silently: `softDelete.tables` losing two entries is what let a table start
+hard-deleting rows whose S3 objects a purge job keyed on `deleted_at IS NOT NULL`. Handler-level
+options that are not per-table — `auth`, `pgSettings`, `rpc`, limits — stay explicit.
+
 ## Programmatic API (`@everystack/cli/model`)
 
 The same compiler the CLI uses is importable for your own CI and tests — point it at your live DB and assert the declaration and the database agree, or red-team the deployed authorization:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.16",
+  "version": "0.4.17",
   "description": "Declare a table's schema, validation, and authorization once — compiled to migrations, RLS, and handler config",
   "license": "AGPL-3.0-only",
   "publishConfig": {
@@ -12,10 +12,12 @@
   ],
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
     "./drizzle": {
+      "source": "./src/drizzle.ts",
       "types": "./src/drizzle.ts",
       "default": "./src/drizzle.ts"
     }

package/src/derived.ts

@@ -416,6 +416,15 @@ export interface FunctionDefinition {
    * PUBLIC-executable. Opinion lives in the linter, never in the parser.
    */
   privileges?: Record<string, string[]>;
+  /**
+   * Owner-only by design — no app role may ever EXECUTE this function.
+   *
+   * Parallel to `private` on views/matviews. An `internal` function is a helper called only
+   * by other SECURITY DEFINER functions running as the owner. The compiler still emits
+   * `REVOKE ALL … FROM PUBLIC`; `internal` tells the lint (`db:check`) the absence of callers
+   * is reviewed and permanent, not an oversight. Contradicts `abilities` and `privileges`.
+   */
+  internal?: boolean;
   comment?: string;
   body: RawSql;
 }
@@ -436,6 +445,7 @@ export interface FunctionDescriptor {
   abilities: Ability[];
   /** Recorded EXECUTE grants — see {@link FunctionDefinition.privileges}. */
   privileges: Record<string, string[]>;
+  internal: boolean;
   comment?: string;
   body: string;
 }
@@ -487,6 +497,12 @@ export function defineFunction(name: string, def: FunctionDefinition): FunctionD
     if (seen.has(a.name)) throw new Error(`function '${name}': duplicate argument '${a.name}'.`);
     seen.add(a.name);
   }
+  if (def.internal && (def.abilities?.length ?? 0) > 0) {
+    throw new Error(`function '${name}': internal: true declares it owner-only — it cannot also declare abilities. Drop one.`);
+  }
+  if (def.internal && Object.keys(def.privileges ?? {}).length > 0) {
+    throw new Error(`function '${name}': internal: true declares it owner-only — it cannot also declare privileges. Drop one.`);
+  }
   for (const a of def.abilities ?? []) {
     if (a.action !== 'execute') {
       throw new Error(`function '${name}': can('${a.action}') is not a function ability — functions carry can('execute', { role }) only.`);
@@ -526,6 +542,7 @@ export function defineFunction(name: string, def: FunctionDefinition): FunctionD
     dependsOn: def.dependsOn ?? [],
     abilities: def.abilities ?? [],
     privileges,
+    internal: def.internal ?? false,
     ...(def.comment ? { comment: def.comment } : {}),
     body: def.body.sql,
   };