letopis 0.18.1 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 Формат: [Keep a Changelog](https://keepachangelog.com/), версии — semver.
 
+## [0.19.0] — 2026-07-14
+
+### Added — физический purge (hard-erase) + живой подхват правок схемы
+
+- **`.purge({ confirm })`** — необратимый физический снос уже логически удалённой (tombstone)
+  сущности + всего поддерева по `links` (все версии). Двухфазно: живую не трогает (сначала
+  `.delete()`); без `confirm` — dry-превью замыкания. Внутри — серверная `purge()`:
+  `SET LOCAL letopis.purge='on'` отключает append-only-триггер через `WHEN`-условие → плоский
+  `DELETE` (детерминированно, без `TM_SelfModified`).
+- **`.withDeleted()`** — включить удалённые (tombstone) в выдачу последнего шага; снимает ТОЛЬКО
+  фильтр `deleted`, изоляция арендатора (`enforceAccount`) и ACL (`enforceAcl`) действуют.
+- **`db.accounts.purge(id)`** — полный офбординг тенанта: физ. снос всех Entity (`account|owner`)
+  + сам Account (Credential — FK-каскад). Гарды: только Owner/System, не последний Owner, не свой аккаунт.
+- **`db.reloadSchema()` / `db.schema.define(def)`** — правка определений классов простым SQL в
+  таблице `Schema` подхватывается без реконнекта (пересборка registry + ACL-резолвера).
+
+### Changed — DDL (требует наката `ddl.sql` на существующие схемы)
+
+- `entity_delete` получил `WHEN (current_setting('letopis.purge', true) IS DISTINCT FROM 'on')` —
+  обычный путь (tombstone + каскад) неизменен; под флагом триггер пропускается для физ-сноса.
+- Новые серверные функции: `purge_closure(partition,class,ids[])`,
+  `purge(partition,class,id[,dry]) RETURNS SETOF Entity`, `purge_account(id)`.
+
+### Notes
+
+- Голый повторный `DELETE` надгробия БЕЗ флага остаётся no-op (safety-инвариант жив).
+- Тесты: новый `test/wave5.test.ts` (13 кейсов P1/P2) — весь набор 181/181 зелёный.
+
 ## [0.18.1] — 2026-07-13
 
 ### Fixed — упаковка: CLI-скрипты в npm-пакете

package/README.md

@@ -781,6 +781,29 @@ await db.Мастер(m).окно().delete({ confirm: true }).rows()  // кон
 (+advisory-lock). История неприкосновенна; повторный delete → `[]`; `create()` с тем же
 id — воскрешение.
 
+### `.purge({ confirm })` — ФИЗИЧЕСКИЙ hard-erase (необратимо)
+
+```ts
+await db.Клиент(cid).delete({ confirm: true }).rows()  // 1) мягко: tombstone (обратимо)
+await db.Клиент(cid).purge().rows()                    // превью замыкания (что сотрётся), БД цела
+await db.Клиент(cid).purge({ confirm: true }).rows()   // 2) физически: tombstone + всё поддерево (все версии)
+```
+
+**Двухфазно:** `.purge()` работает ТОЛЬКО по уже логически удалённому (tombstone) — живую сущность
+не трогает (сначала `.delete()`). Историю, в отличие от `.delete()`, НЕ сохраняет. Внутри — серверная
+`purge(partition,class,id)`: `SET LOCAL letopis.purge='on'` отключает append-only-триггер (через `WHEN`)
+→ плоский физический `DELETE` замыкания (детерминированно, без вложенного DML). Голый SQL:
+`SELECT * FROM "v1.notify".purge('entity','Клиент','…')` (или `…,true)` — dry-превью).
+
+### `.withDeleted()` — включить удалённые (tombstone) в выдачу
+
+```ts
+await db.Клиент(cid).rows()                 // только живые
+await db.Клиент(cid).withDeleted().rows()   // + tombstone (последний шаг)
+```
+
+Снимает **только** фильтр `deleted IS NULL`; изоляция арендатора (`enforceAccount`) и ACL (`enforceAcl`) действуют.
+
 ### Откат плана
 
 ```ts
@@ -1144,9 +1167,11 @@ await db.Клиент(id).anonymize(['name', 'phone']).rows()
 // новая версия: string-поля = '[erased]', тег 'anonymized'; остальные поля целы
 ```
 
-Физического стирания НЕТ — история священна: старые версии хранят PII до retention-политики
-(§ 10.8). Полное «право на забвение» = `anonymize()` сейчас + настроенный retention потом.
-Не-string поле в списке — ошибка (типы сверяются по Schema).
+Физического стирания `anonymize()` НЕ делает — история священна: старые версии хранят PII до
+retention-политики (§ 10.8). Три уровня «права на забвение»: `anonymize()` (затереть PII, запись
+живёт) → retention (снос по времени) → **`.purge({ confirm })`** — немедленный физический hard-erase
+удалённого (tombstone) + всего поддерева, а `db.accounts.purge(id)` — целого тенанта (см. § 11).
+Не-string поле в списке `anonymize` — ошибка (типы сверяются по Schema).
 
 ### 10.8 Политики хранения: `db/policies.mjs`
 
@@ -2542,7 +2567,41 @@ await db.accounts.delete(SYS)      // [6.0 ms]
 ```
 
 **Кейс:** чистка мусорной регистрации — удалять можно только то, что не оставило следов;
-след есть → `enabled: false` вместо удаления.
+след есть → `enabled: false` вместо удаления, либо `db.accounts.purge(id)` — полный офбординг ниже.
+
+#### `db.accounts.purge(id): Promise<boolean>`
+
+Полный физический **офбординг тенанта** (необратимо): все `Entity` с `account = id` ИЛИ `owner = id`
++ сам `Account` (`Credential` — FK-каскад). Освобождает `entity_account_fk`/`entity_owner_fk` (RESTRICT),
+которые блокируют обычный `delete`. Внутри — серверная `purge_account()` (флаг отключает append-only-триггер).
+Предохранители (до сноса): вызывать может лишь **Owner/System**; нельзя снести **последний enabled Owner**
+(лок-аут тенанта) и **свой** аккаунт сессии.
+
+```ts
+const dbSys = await connect({ dsn, schema: 'v1.notify', account: SYS })
+await dbSys.accounts.purge(tenantId)   // → true: Entity + Account + Credential снесены, место освобождено
+```
+
+#### `db.schema.define(def)` / `db.reloadSchema()` — живой подхват правок схемы
+
+Определения классов живут в таблице `Schema`. Меняешь их **простым SQL** (или `db.schema.define(...)`)
+→ `db.reloadSchema()` пересобирает реестр (и ACL-резолвер) **без реконнекта**.
+
+```ts
+// правка простым SQL + перечитывание (напр. новое значение enum)
+await db.sql.unsafe(`UPDATE "v1.notify"."Schema"
+  SET attributes = jsonb_set(attributes, '{status,values}', '["queued","sent","paused"]')
+  WHERE id = 'Delivery'`)
+await db.reloadSchema()               // запись со status:'paused' теперь проходит валидацию
+
+// или спец-метод (сам перечитывает)
+await db.schema.define({ id: 'Coupon', alias: 'Купон', category: 'HUB',
+  attributes: { id: { type: 'uuid', generate: 7 }, code: { type: 'string' } } })
+```
+
+`up()` при существующей схеме seed **не** перезаливает → правка в `Schema` переживает рестарт (клоббер только
+при явном re-run старого seed через `db/apply.mjs`/`fresh`). Бамп версии (`vN.*`) — **новый пустой** namespace
+с переливом данных, НЕ инструмент для аддитивной правки определения (новое значение enum/поле/класс).
 
 #### `db.credentials.find(f?): Promise<Credential[]>`
 

package/dist/chain.d.ts

@@ -33,6 +33,11 @@ export interface ChainCore {
     asOf(t: string | Date): Chain;
     /** Keyset-пагинация: строго после курсора (см. cursorOf). Требует .sort(). */
     after(cursor: import('./types.js').Cursor): Chain;
+    /**
+     * Включить в выдачу последнего шага удалённые (tombstone). Снимает ТОЛЬКО фильтр deleted —
+     * изоляция арендатора (enforceAccount) и ACL (enforceAcl) остаются в силе.
+     */
+    withDeleted(): Chain;
     /** ВСЕ версии сущностей последнего шага (включая tombstone → $deleted), по возрастанию updated. */
     versions(): Promise<Row[]>;
     /** Рекурсивный self-обход: дети любой глубины (тот же класс), $depth в Row. */
@@ -89,6 +94,15 @@ export interface ChainCore {
     delete(opts?: {
         confirm?: boolean;
     }): Chain;
+    /**
+     * ФИЗИЧЕСКИЙ hard-erase (необратимо): сносит УЖЕ логически удалённые (tombstone) цели + всё
+     * поддерево по links (все версии). Живую сущность не трогает — сначала .delete(). { confirm: true }
+     * — стирает; без confirm — превью замыкания (что сотрётся), БД не тронута. Историю НЕ сохраняет
+     * (в отличие от .delete()). Реализуется серверной purge() (SET LOCAL letopis.purge отключает триггер).
+     */
+    purge(opts?: {
+        confirm?: boolean;
+    }): Chain;
 }
 /**
  * Свойство-класс на цепочке:
@@ -126,6 +140,11 @@ export interface DbCore {
     watch(cb: (e: WatchEvent) => void, opts?: WatchOpts): Promise<() => void>;
     watch(cls: string, cb: (e: WatchEvent) => void, opts?: WatchOpts): Promise<() => void>;
     close(): Promise<void>;
+    /**
+     * Перечитать определения классов из таблицы Schema (после правки её простым SQL / db.schema.define):
+     * пересобирает registry и, при enforceAcl, ACL-резолвер — без реконнекта. Подхват «сразу».
+     */
+    reloadSchema(): Promise<void>;
     registry: Registry;
     /** Голый postgres-клиент (тесты, EXPLAIN). */
     sql: Ctx['sql'];
@@ -134,6 +153,8 @@ export interface DbCore {
     credentials: Tables['credentials'];
     resources: Tables['resources'];
     rules: Tables['rules'];
+    /** Определения классов: db.schema.define(def) — upsert в таблицу Schema + reloadSchema(). */
+    schema: Tables['schema'];
     /** Вход по кредам (пароль/api-key/key-secret/внешние identity) + сессии в Redis. */
     auth: AuthApi;
     /** ACL по Resource/Rule: check(эндпоинт) / checkData(класс, READ|WRITE|DELETE) / reload. */

package/dist/chain.js

@@ -354,6 +354,8 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                     return (field, dir) => withMods({ order: field, desc: dir === true || dir === 'desc' });
                 case 'asOf':
                     return (t) => withMods({ asOf: t instanceof Date ? t.toISOString() : t });
+                case 'withDeleted':
+                    return () => withMods({ withDeleted: true });
                 case 'deep':
                     return (max = 32) => withLast({ deepMax: max });
                 // END_BLOCK_READ_MODIFIERS
@@ -434,6 +436,8 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                     return (opts) => withOp({ kind: 'delete', confirm: opts?.confirm === true, mods });
                 case 'anonymize':
                     return (fields) => withOp({ kind: 'anonymize', fields, mods });
+                case 'purge':
+                    return (opts) => withOp({ kind: 'purge', confirm: opts?.confirm === true, mods });
                 // END_BLOCK_WRITE_TERMINALS
                 // START_BLOCK_COLUMN_MODS
                 case 'alias':
@@ -512,7 +516,7 @@ export function makeDb(ctx, root) {
             if (typeof prop === 'symbol' || prop === 'then')
                 return undefined;
             // START_BLOCK_TABLES_AUTH_ACL
-            if (prop === 'accounts' || prop === 'credentials' || prop === 'resources' || prop === 'rules') {
+            if (prop === 'accounts' || prop === 'credentials' || prop === 'resources' || prop === 'rules' || prop === 'schema') {
                 tables ??= makeTables(ctx);
                 return tables[prop];
             }
@@ -607,6 +611,11 @@ export function makeDb(ctx, root) {
                 // START_BLOCK_CLOSE_META
                 case 'close':
                     return () => ctx.sql.end();
+                case 'reloadSchema':
+                    return async () => {
+                        await ctx.reload?.();
+                        acl = undefined; // db.acl-фасад перестроится на свежем registry при следующем доступе
+                    };
                 case 'registry':
                     return ctx.registry;
                 case 'sql':

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { uuidv5, uuidv7, LETOPIS_NS } from './uuid.js';
 export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, } from './ops.js';
 export type { Row, Path, Filter, ChainMods, Cursor, ConnectOpts, QueryEvent, Account, Credential, Resource, Rule, AclOp, AclDecision, } from './types.js';
 export type { EntityDb, EntityTx, Chain, Batch, WatchEvent, WatchOpts } from './chain.js';
-export type { Tables, AccountsApi, CredentialsApi, ResourcesApi, RulesApi } from './tables.js';
+export type { Tables, AccountsApi, CredentialsApi, ResourcesApi, RulesApi, SchemaApi } from './tables.js';
 export { totpCode } from './auth.js';
 export type { AuthApi, AuthResult } from './auth.js';
 export type { AclApi } from './acl.js';

package/dist/index.js

@@ -60,8 +60,10 @@ export async function connect(opts) {
         slowMs: opts.slowMs,
     };
     // START_BLOCK_ENFORCE_ACL
-    // enforceAcl: правила и категории субъекта фиксируются на connect (перечитка — новый connect)
-    if (opts.enforceAcl) {
+    // enforceAcl: правила и категории субъекта компилятся в резолвер (перечитываются reloadSchema/reload)
+    const compileAcl = async () => {
+        if (!opts.enforceAcl)
+            return;
         if (!opts.account)
             throw new Error('letopis: enforceAcl requires connect({ account })');
         const tables = makeTables(ctx);
@@ -72,8 +74,14 @@ export async function connect(opts) {
         ]);
         if (!account)
             throw new Error(`letopis: enforceAcl — account "${opts.account}" not found`);
-        ctx.aclDecide = compileEnforcer({ resources, rules }, account.id, account.categories, registry);
-    }
+        ctx.aclDecide = compileEnforcer({ resources, rules }, account.id, account.categories, ctx.registry);
+    };
+    await compileAcl();
+    // db.reloadSchema(): перечитать определения классов из таблицы Schema (registry + enforcer) без реконнекта
+    ctx.reload = async () => {
+        ctx.registry = await loadRegistry(sql, opts.schema, partition);
+        await compileAcl();
+    };
     // END_BLOCK_ENFORCE_ACL
     return makeDb(ctx);
 }

package/dist/sql.d.ts

@@ -41,6 +41,8 @@ export interface Ctx {
     onQuery?: (e: QueryEvent) => void;
     /** Порог «медленного» запроса, мс (без onQuery — console.warn). */
     slowMs?: number;
+    /** Перечитать определения классов из таблицы Schema: пересобрать registry (+ enforcer при enforceAcl). Ставит connect(). */
+    reload?: () => Promise<void>;
 }
 /** Транзиентные ошибки PG — гонка, снимаемая повтором: deadlock / serialization failure. */
 export declare function isTransient(e: unknown): boolean;
@@ -131,4 +133,10 @@ export declare function deleteSql(pgSchema: string, n: number): string;
  * Рекурсивный CTE; каждый узел — актуальная живая версия. $1 partition, $2 class, $3+ — ids.
  */
 export declare function closureSql(pgSchema: string, n: number): string;
+/**
+ * Вызов серверной purge(): $4 dry → превью (актуальные версии замыкания, БД цела), иначе двухфазный
+ * физический снос корня+поддерева. RETURNS SETOF Entity (по строке на сущность). Вся логика
+ * (замыкание, двухфазность, отключение триггера через SET LOCAL) — в БД. $1 partition, $2 class, $3 id, $4 dry.
+ */
+export declare function purgeCallSql(pgSchema: string): string;
 export {};

package/dist/sql.js

@@ -517,8 +517,10 @@ export function buildRead(ctx, steps, mods, mode) {
         const innerWhere = [`e.partition = ${pPart}`, `e.class = ${pCls}`];
         if (mods.asOf !== undefined)
             innerWhere.push(`e.updated <= ${p.push(mods.asOf)}::timestamptz`); // «как было на T»
-        // versions: последний шаг включает и удалённые сущности (история существует после delete)
-        const outerWhere = [mode === 'versions' && i === steps.length - 1 ? 'TRUE' : 't.deleted IS NULL'];
+        // versions/.withDeleted(): последний шаг включает и удалённые (история/tombstone видны после delete).
+        // Снимается ТОЛЬКО фильтр deleted — enforceAccount/enforceAcl/контекст-фраги ниже действуют (изоляция цела).
+        const keepDeleted = i === steps.length - 1 && (mode === 'versions' || mods.withDeleted === true);
+        const outerWhere = [keepDeleted ? 'TRUE' : 't.deleted IS NULL'];
         const candWhere = f.candFrags.map((fr) => fr('c'));
         for (const c of f.idConds)
             innerWhere.push(c('e'));
@@ -726,3 +728,18 @@ export function closureSql(pgSchema, n) {
      )
      SELECT DISTINCT ON (class, id) * FROM node ORDER BY class, id, updated DESC`);
 }
+/**
+ * Вызов серверной purge(): $4 dry → превью (актуальные версии замыкания, БД цела), иначе двухфазный
+ * физический снос корня+поддерева. RETURNS SETOF Entity (по строке на сущность). Вся логика
+ * (замыкание, двухфазность, отключение триггера через SET LOCAL) — в БД. $1 partition, $2 class, $3 id, $4 dry.
+ */
+// START_CONTRACT: purgeCallSql
+//   PURPOSE: SQL-обёртка вызова серверной purge() (снос/превью) — вся логика в БД, JS лишь зовёт.
+//   INPUTS: { pgSchema: string }
+//   OUTPUTS: { string - SELECT * FROM "<schema>".purge($1,$2,$3,$4) }
+//   SIDE_EFFECTS: none
+//   LINKS: M-SQL, V-M-SQL, M-DDL, M-WRITE
+// END_CONTRACT: purgeCallSql
+export function purgeCallSql(pgSchema) {
+    return `SELECT * FROM ${escId(pgSchema)}.purge($1, $2, $3, $4)`;
+}

package/dist/tables.d.ts

@@ -17,6 +17,12 @@ export interface AccountsApi {
     set(a: Partial<Account>): Promise<Account>;
     /** Физический DELETE; Credential снесётся FK-каскадом. */
     delete(id: string): Promise<boolean>;
+    /**
+     * Полный физический офбординг тенанта (необратимо): все Entity (account|owner=id) + сам Account
+     * (Credential — FK-каскад), через серверную purge_account(). Предохранители: только Owner/System-вызов;
+     * нельзя снести последний enabled Owner (лок-аут) и свой аккаунт. → true если Account снесён.
+     */
+    purge(id: string): Promise<boolean>;
 }
 export interface CredentialsApi {
     /** deleted IS NULL по умолчанию; withDeleted: true — включая удалённые. */
@@ -72,10 +78,28 @@ export interface RulesApi {
     }): Promise<Rule>;
     delete(account: string, resource: string): Promise<boolean>;
 }
+export interface SchemaApi {
+    /**
+     * Upsert определения класса в таблицу Schema (ON CONFLICT (partition,id) DO UPDATE) + reloadSchema().
+     * Правка «простым SQL», подхватывается сразу без реконнекта. attributes — DSL fastest-validator
+     * (валидирует либа при чтении реестра); ancestors/descendants считает триггер schema_lineage.
+     */
+    define(def: {
+        id: string;
+        alias: string;
+        category: 'HUB' | 'LINK';
+        ancestor?: string | null;
+        attributes?: Record<string, unknown>;
+        meta?: Record<string, unknown>;
+        links?: unknown[];
+        order?: number;
+    }): Promise<void>;
+}
 export interface Tables {
     accounts: AccountsApi;
     credentials: CredentialsApi;
     resources: ResourcesApi;
     rules: RulesApi;
+    schema: SchemaApi;
 }
 export declare function makeTables(ctx: Ctx): Tables;

package/dist/tables.js

@@ -85,6 +85,44 @@ export function makeTables(ctx) {
             const rows = await run(`DELETE FROM ${T(ctx, 'Account')} WHERE id = $1 RETURNING id`, [id]);
             return rows.length > 0;
         },
+        // START_CONTRACT: accounts.purge
+        //   PURPOSE: Физический офбординг тенанта через purge_account(); гарды Owner/System, последний Owner, не-себя — до сноса, в одной tx.
+        //   INPUTS: { id: string - целевой аккаунт }
+        //   OUTPUTS: { Promise<boolean> - true если Account физически снесён }
+        //   SIDE_EFFECTS: физ. DELETE всех Entity аккаунта + Account (Credential FK-каскад) через SQL purge_account()
+        //   ERRORS: нет caller/ACL; вызов не Owner/System; снос последнего Owner; снос своего аккаунта
+        //   LINKS: M-TABLES, V-M-TABLES, M-DDL
+        // END_CONTRACT: accounts.purge
+        async purge(id) {
+            if (!ctx.account) {
+                throw new Error('letopis: accounts.purge requires an authenticated caller — connect({ account })');
+            }
+            if (id === ctx.account) {
+                throw new Error('letopis: accounts.purge cannot purge the calling account itself');
+            }
+            const schema = `"${ctx.pgSchema.replace(/"/g, '""')}"`;
+            return ctx.sql.begin(async (tsql) => {
+                const q = (t, p) => tsql.unsafe(t, p);
+                // вызывающий обязан быть Owner/System
+                const caller = await q(`SELECT categories FROM ${T(ctx, 'Account')} WHERE id = $1`, [ctx.account]);
+                const cats = caller[0]?.categories ?? [];
+                if (!cats.includes('Owner') && !cats.includes('System')) {
+                    throw new Error('letopis: accounts.purge is restricted to Owner/System accounts');
+                }
+                const tgt = await q(`SELECT categories FROM ${T(ctx, 'Account')} WHERE id = $1`, [id]);
+                if (!tgt.length)
+                    return false;
+                // нельзя снести последний enabled Owner → тенант без владельца (лок-аут)
+                if ((tgt[0].categories ?? []).includes('Owner')) {
+                    const cnt = await q(`SELECT count(*)::text AS n FROM ${T(ctx, 'Account')} WHERE 'Owner' = ANY(categories) AND enabled`, []);
+                    if (Number(cnt[0]?.n ?? 0) <= 1) {
+                        throw new Error('letopis: refusing to purge the last enabled Owner (tenant lock-out)');
+                    }
+                }
+                const res = await q(`SELECT ${schema}.purge_account($1::uuid) AS id`, [id]);
+                return res[0]?.id != null;
+            });
+        },
     };
     // END_BLOCK_ACCOUNTS_API
     // START_BLOCK_CREDENTIALS_API
@@ -181,5 +219,22 @@ export function makeTables(ctx) {
         },
     };
     // END_BLOCK_RULES_API
-    return { accounts, credentials, resources, rules };
+    // START_BLOCK_SCHEMA_API
+    const schema = {
+        async define(def) {
+            // jsonb-значения через sql.json() — postgres.js кладёт как jsonb (не PG-массив/строку)
+            const j = (v) => ctx.sql.json(v);
+            await run(`INSERT INTO ${T(ctx, 'Schema')} (partition, id, alias, category, ancestor, attributes, meta, links, "order")
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+         ON CONFLICT (partition, id) DO UPDATE SET
+           alias = EXCLUDED.alias, category = EXCLUDED.category, ancestor = EXCLUDED.ancestor,
+           attributes = EXCLUDED.attributes, meta = EXCLUDED.meta, links = EXCLUDED.links, "order" = EXCLUDED."order"`, [
+                ctx.partition, def.id, def.alias, def.category, def.ancestor ?? null,
+                j(def.attributes ?? {}), j(def.meta ?? {}), j(def.links ?? []), def.order ?? 0,
+            ]);
+            await ctx.reload?.(); // подхватить новое определение сразу (registry + enforcer)
+        },
+    };
+    // END_BLOCK_SCHEMA_API
+    return { accounts, credentials, resources, rules, schema };
 }

package/dist/types.d.ts

@@ -125,12 +125,12 @@ export interface Cursor {
  * Терминал исполняет план (все операции + финальное чтение) одной транзакцией.
  */
 export interface PlanOp {
-    kind: 'create' | 'update' | 'delete' | 'anonymize';
+    kind: 'create' | 'update' | 'delete' | 'anonymize' | 'purge';
     /** create/update: данные новой версии (deep-merge листьев). */
     data?: Record<string, unknown>;
     /** anonymize: string-поля под '[erased]'. */
     fields?: string[];
-    /** delete: true — удалить; без confirm — превью (вернуть кандидатов, БД не трогать). */
+    /** delete/purge: true — выполнить; без confirm — превью (вернуть кандидатов/замыкание, БД не трогать). */
     confirm?: boolean;
     /** Снапшот модификаторов на момент вызова операции (limit/sort для поиска целей). */
     mods: ChainMods;
@@ -149,6 +149,8 @@ export interface ChainMods {
     /** Внутреннее: агрегация терминалов .sum/.avg/.min/.max/.countBy. */
     aggFn?: 'sum' | 'avg' | 'min' | 'max' | 'countBy';
     aggField?: string;
+    /** .withDeleted(): последний шаг включает удалённые (tombstone). Снимает ТОЛЬКО фильтр deleted; enforceAccount/enforceAcl действуют. */
+    withDeleted?: boolean;
 }
 export interface Account {
     id: string;

package/dist/write.d.ts

@@ -56,6 +56,15 @@ export declare function anonymizeOp(ctx: Ctx, steps: Step[], mods: ChainMods, fi
  * Без confirm — ПРЕВЬЮ: то же замыкание (цели + каскад), но БД не трогается.
  */
 export declare function delOp(ctx: Ctx, steps: Step[], mods: ChainMods, confirm: boolean): Promise<Row[]>;
+/**
+ * .purge({confirm}): ФИЗИЧЕСКИЙ hard-erase — сносит логически удалённые цели + всё поддерево (все версии).
+ * Вся логика — в серверной purge() (двухфазность: живую цель не трогает; замыкание по links; SET LOCAL
+ * отключает entity_delete → плоский снос без TM_SelfModified). JS лишь резолвит цели и зовёт функцию.
+ * confirm: false → dry-превью (что сотрётся, БД цела); true → снос, возвращает снесённое ($deleted).
+ * gate: DELETE-право на класс цели (aclWrite) — поддерево уже было DELETE-авторизовано при мягком удалении.
+ * В отличие от .delete() (tombstone, обратимо) — необратимо, историю НЕ сохраняет.
+ */
+export declare function purgeOp(ctx: Ctx, steps: Step[], mods: ChainMods, confirm: boolean): Promise<Row[]>;
 export type PlanMode = 'rows' | 'ids' | 'count' | 'paths' | 'versions' | 'agg';
 /**
  * Исполнить план целиком: все операции + финальное чтение — одна транзакция

package/dist/write.js

@@ -40,7 +40,7 @@
 // END_CHANGE_SUMMARY
 import { randomUUID } from 'node:crypto';
 import { uuidv5, uuidv7 } from './uuid.js';
-import { buildRead, runQuery, insertSql, multiInsertSql, deleteSql, closureSql, isTransient, retryDelay, RETRIES, } from './sql.js';
+import { buildRead, runQuery, insertSql, multiInsertSql, deleteSql, closureSql, purgeCallSql, isTransient, retryDelay, RETRIES, } from './sql.js';
 import { aclDenied } from './acl.js';
 // START_CONTRACT: ValidationError
 //   PURPOSE: Ошибка валидации класса, несущая список проблемных полей (issues).
@@ -581,6 +581,40 @@ export async function delOp(ctx, steps, mods, confirm) {
     });
     // END_BLOCK_DELETE_CASCADE
 }
+/**
+ * .purge({confirm}): ФИЗИЧЕСКИЙ hard-erase — сносит логически удалённые цели + всё поддерево (все версии).
+ * Вся логика — в серверной purge() (двухфазность: живую цель не трогает; замыкание по links; SET LOCAL
+ * отключает entity_delete → плоский снос без TM_SelfModified). JS лишь резолвит цели и зовёт функцию.
+ * confirm: false → dry-превью (что сотрётся, БД цела); true → снос, возвращает снесённое ($deleted).
+ * gate: DELETE-право на класс цели (aclWrite) — поддерево уже было DELETE-авторизовано при мягком удалении.
+ * В отличие от .delete() (tombstone, обратимо) — необратимо, историю НЕ сохраняет.
+ */
+// START_CONTRACT: purgeOp
+//   PURPOSE: .purge({confirm}) — резолв целей (вкл. tombstone) + вызов серверной purge() (снос при confirm, иначе dry-превью).
+//   INPUTS: { ctx: Ctx; steps: Step[]; mods: ChainMods; confirm: boolean }
+//   OUTPUTS: { Promise<Row[]> - снесённое с $deleted, либо dry-превью; [] если цели не tombstone/не найдены }
+//   SIDE_EFFECTS: физический DELETE в Entity через purge() (SET LOCAL letopis.purge отключает триггер)
+//   ERRORS: acl denies DELETE (класс цели)
+//   LINKS: M-WRITE, V-M-WRITE, M-ACL, M-DDL, M-SQL
+// END_CONTRACT: purgeOp
+export async function purgeOp(ctx, steps, mods, confirm) {
+    const target = steps[steps.length - 1];
+    aclWrite(ctx, target, 'DELETE');
+    // цели ищем ВКЛЮЧАЯ tombstone — .purge() работает по уже логически удалённым (двухфазность в purge())
+    const targets = await readRows(ctx, steps, { ...mods, withDeleted: true });
+    if (!targets.length)
+        return [];
+    return inTransaction(ctx, async (c) => {
+        const out = [];
+        // вся логика (двухфазность, замыкание, отключение триггера) — в серверной purge(); dry = !confirm
+        for (const t of targets) {
+            const rows = await runQuery(c, purgeCallSql(c.pgSchema), [c.partition, target.cls.id, t.id, !confirm], 'delete', [target.cls.id]);
+            for (const r of rows)
+                out.push(confirm ? { ...toRow(r), $deleted: true } : toRow(r));
+        }
+        return out;
+    });
+}
 /** Разрезать план: сегменты (…шаги + op-шаг) и читающий хвост после последней операции. */
 function splitPlan(steps) {
     const segments = [];
@@ -604,6 +638,8 @@ function opCall(c, steps, op) {
             return anonymizeOp(c, steps, op.mods, op.fields ?? []);
         case 'delete':
             return delOp(c, steps, op.mods, op.confirm === true);
+        case 'purge':
+            return purgeOp(c, steps, op.mods, op.confirm === true);
     }
 }
 /** Виртуальный старт-шаг «от этих строк»: контекст/чтение следующего сегмента. */
@@ -651,7 +687,8 @@ export async function runPlan(ctx, steps, mods, mode) {
                     last.push(...await opCall(c, rowSteps, seg.op));
                 }
             }
-            start = seg.op.kind === 'delete' ? last.filter((r) => r.class === targetCls.id) : last;
+            start = (seg.op.kind === 'delete' || seg.op.kind === 'purge')
+                ? last.filter((r) => r.class === targetCls.id) : last;
         }
         // END_BLOCK_RUNPLAN_SEGMENTS
         const opStep = segments[segments.length - 1].steps.at(-1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letopis",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Letopis (летопись): append-only versioned entity store on TimescaleDB with dot-notation chains — every change is a new row, history is first-class (asOf, versions, watch, cascade tombstones)",
   "keywords": [
     "timescaledb",

package/sql/ddl.sql

@@ -321,7 +321,8 @@ CREATE TRIGGER entity_update
 --   * бьёт только актуальную ЖИВУЮ строку (история и tombstone неприкосновенны);
 --   * advisory-lock сериализует параллельные удаления сущности;
 --   * каскад: DELETE живых зависимых (links ⊃ {класс: id}) → рекурсия этого же триггера;
---   * физического удаления не происходит никогда (очистка истории — retention-политики).
+--   * физического удаления не происходит никогда — КРОМЕ явного purge (см. ниже):
+--     при SET LOCAL letopis.purge='on' триггер целиком пропускается (WHEN) → физический DELETE.
 -- Работает и для голого SQL: DELETE FROM "<SCHEMA-NAME>"."Entity" WHERE partition=… AND class=… AND id=…
 -- -----------------------------------------------------------------------------
 -- START_CONTRACT: entity_delete
@@ -363,7 +364,94 @@ END $$;
 DROP TRIGGER IF EXISTS entity_delete ON "<SCHEMA-NAME>"."Entity";
 CREATE TRIGGER entity_delete
     BEFORE DELETE ON "<SCHEMA-NAME>"."Entity"
-    FOR EACH ROW EXECUTE FUNCTION "<SCHEMA-NAME>".entity_delete();
+    FOR EACH ROW
+    -- purge-режим: при SET LOCAL letopis.purge='on' триггер НЕ срабатывает → физический DELETE.
+    -- Обычный путь (флаг не выставлен) видит NULL → IS DISTINCT FROM 'on' = true → триггер работает (tombstone).
+    WHEN (current_setting('letopis.purge', true) IS DISTINCT FROM 'on')
+    EXECUTE FUNCTION "<SCHEMA-NAME>".entity_delete();
+
+-- -----------------------------------------------------------------------------
+-- Физический hard-erase (purge). Вся логика — в БД (две функции); либа лишь зовёт purge():
+--   * purge_closure(partition,class,ids[]) — (class,id) всего поддерева по links (вкл. tombstone);
+--     единый источник замыкания (UNION отсекает циклы/диаманты).
+--   * purge(partition,class,id[,dry]) RETURNS SETOF Entity — двухфазный снос корня + поддерева:
+--       - ДВУХФАЗНОСТЬ: только если сущность уже логически удалена (актуальная версия — tombstone);
+--         живую не трогает (0 строк);
+--       - dry=true  → превью (актуальные версии замыкания), БД не трогается;
+--       - dry=false → SET LOCAL letopis.purge='on' отключает entity_delete (см. WHEN выше) → плоский DELETE
+--         замыкания без вложенного DML (без TM_SelfModified, детерминированно), возвращает снесённое;
+--       - флаг транзакционный (is_local) + явный сброс → дальше в той же tx снова tombstone; привилегий не требует.
+-- Голый SQL:  SELECT * FROM "<SCHEMA-NAME>".purge('entity','Order','X');          -- снос
+--             SELECT * FROM "<SCHEMA-NAME>".purge('entity','Order','X', true);    -- превью
+-- -----------------------------------------------------------------------------
+-- START_CONTRACT: purge_closure
+--   PURPOSE: (class,id)-замыкание поддерева по links (вкл. tombstone) — что снесёт purge(); переиспользуется самой purge() (снос и dry-превью).
+--   INPUTS: { p_partition text; p_class text; p_ids text[] }
+--   OUTPUTS: { SETOF (class text, id text) - узлы замыкания }
+--   SIDE_EFFECTS: none (STABLE)
+--   LINKS: M-DDL, V-M-DDL, M-WRITE, M-SQL
+-- END_CONTRACT: purge_closure
+CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".purge_closure(p_partition text, p_class text, p_ids text[])
+RETURNS TABLE(class text, id text) LANGUAGE sql STABLE AS $$
+    WITH RECURSIVE closure(cls, cid) AS (
+        SELECT p_class, x FROM unnest(p_ids) AS x
+        UNION                                          -- не ALL → отсекает циклы/диаманты links
+        SELECT e.class, e.id
+          FROM "<SCHEMA-NAME>"."Entity" e
+          JOIN closure c ON e.links @> jsonb_build_object(c.cls, c.cid)
+         WHERE e.partition = p_partition
+    )
+    SELECT cls, cid FROM closure;
+$$;
+
+-- START_CONTRACT: purge
+--   PURPOSE: Двухфазно физически стереть логически удалённый корень и всё поддерево (по links, все версии); dry=превью.
+--   INPUTS: { p_partition text; p_class text; p_id text; p_dry boolean = false }
+--   OUTPUTS: { SETOF Entity - снесённые (по одному на сущность, latest) либо превью (dry); пусто если не tombstone }
+--   SIDE_EFFECTS: при dry=false — SET LOCAL letopis.purge (отключает entity_delete на tx) + физический DELETE; advisory-lock
+--   LINKS: M-DDL, V-M-DDL, M-WRITE, M-TABLES
+-- END_CONTRACT: purge
+CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".purge(
+    p_partition text, p_class text, p_id text, p_dry boolean DEFAULT false)
+RETURNS SETOF "<SCHEMA-NAME>"."Entity" LANGUAGE plpgsql AS $$
+BEGIN
+    PERFORM pg_advisory_xact_lock(
+        hashtextextended(p_partition || '|' || p_class || '|' || p_id, 0));
+
+    -- двухфазность: hard-purge только ПОСЛЕ логического удаления — актуальная версия обязана быть tombstone.
+    -- Живую (не удалённую) сущность purge НЕ трогает (возвращает 0 строк).
+    IF NOT EXISTS (
+        SELECT 1 FROM "<SCHEMA-NAME>"."Entity" e
+         WHERE e.partition = p_partition AND e.class = p_class AND e.id = p_id AND e.deleted IS NOT NULL
+           AND e.updated = (SELECT max(updated) FROM "<SCHEMA-NAME>"."Entity"
+                             WHERE partition = p_partition AND class = p_class AND id = p_id)
+    ) THEN
+        RETURN;
+    END IF;
+
+    IF p_dry THEN
+        -- превью: актуальная версия каждого члена замыкания, БД не трогаем
+        RETURN QUERY
+          SELECT DISTINCT ON (e.class, e.id) e.* FROM "<SCHEMA-NAME>"."Entity" e
+            JOIN "<SCHEMA-NAME>".purge_closure(p_partition, p_class, ARRAY[p_id]) c
+              ON e.class = c.class AND e.id = c.id
+           WHERE e.partition = p_partition
+           ORDER BY e.class, e.id, e.updated DESC;
+        RETURN;
+    END IF;
+
+    PERFORM set_config('letopis.purge', 'on', true);   -- SET LOCAL: entity_delete отключён на эту tx
+    RETURN QUERY
+      WITH del AS (
+        DELETE FROM "<SCHEMA-NAME>"."Entity" e
+         USING "<SCHEMA-NAME>".purge_closure(p_partition, p_class, ARRAY[p_id]) c
+         WHERE e.partition = p_partition AND e.class = c.class AND e.id = c.id  -- триггер пропущен (WHEN)
+        RETURNING e.*
+      )
+      SELECT DISTINCT ON (class, id) * FROM del ORDER BY class, id, updated DESC;
+    PERFORM set_config('letopis.purge', '', true);     -- сброс: дальше в той же tx снова tombstone
+    RETURN;
+END $$;
 
 -- =============================================================================
 -- Служебные таблицы (auth/ACL) — перенесены из legacy-дампа 1:1.
@@ -431,6 +519,30 @@ CREATE TABLE IF NOT EXISTS "<SCHEMA-NAME>"."Rule" (
 );
 -- END_BLOCK_AUTH_TABLES
 
+-- -----------------------------------------------------------------------------
+-- purge_account(): полный физический офбординг тенанта — все Entity (account|owner) + сам Account.
+--   Credential уходит FK-каскадом (ON DELETE CASCADE). Флаг letopis.purge отключает entity_delete на
+--   снос Entity (см. WHEN). Права/предохранители (Owner-only, последний Owner, не-себя) — в либе
+--   (accounts.purge, им нужен ctx/ACL). Возвращает id снесённого Account либо NULL.
+-- -----------------------------------------------------------------------------
+-- START_CONTRACT: purge_account
+--   PURPOSE: Физически стереть тенанта: все Entity с account|owner = id + сам Account (Credential — FK-каскад).
+--   INPUTS: { p_id uuid }
+--   OUTPUTS: { uuid - id снесённого Account, либо NULL если не найден }
+--   SIDE_EFFECTS: SET LOCAL letopis.purge (отключает entity_delete); физический DELETE Entity + Account
+--   LINKS: M-DDL, V-M-DDL, M-TABLES
+-- END_CONTRACT: purge_account
+CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".purge_account(p_id uuid)
+RETURNS uuid LANGUAGE plpgsql AS $$
+DECLARE gone uuid;
+BEGIN
+    PERFORM set_config('letopis.purge', 'on', true);   -- SET LOCAL: entity_delete отключён (см. WHEN)
+    DELETE FROM "<SCHEMA-NAME>"."Entity" WHERE account = p_id OR owner = p_id;  -- обе оси (иначе entity_owner_fk RESTRICT)
+    PERFORM set_config('letopis.purge', '', true);
+    DELETE FROM "<SCHEMA-NAME>"."Account" WHERE id = p_id RETURNING id INTO gone;  -- Credential — FK-каскад
+    RETURN gone;
+END $$;
+
 -- -----------------------------------------------------------------------------
 -- Триггер 4: realtime — факт каждой новой версии в pg_notify (канал = имя схемы).
 -- Payload лёгкий (без data): подписчик дочитывает нужное сам. Потребитель: db.watch().