letopis 0.13.0 → 0.18.0

package/dist/acl.js

@@ -1,5 +1,12 @@
 export const ACL_OPS = ['READ', 'WRITE', 'DELETE'];
 // --- матчеры -----------------------------------------------------------------
+// START_CONTRACT: matchCategories
+//   PURPOSE: Проверить шаблон pattern.categories ("{A,B}" | "!{A,B}" | NULL) против категорий аккаунта.
+//   INPUTS: { pattern: object|null - шаблон ресурса ACCOUNT; cats: string[] - категории аккаунта }
+//   OUTPUTS: { boolean - подходит ли субъект }
+//   SIDE_EFFECTS: none
+//   LINKS: M-ACL, V-M-ACL
+// END_CONTRACT: matchCategories
 /** pattern.categories: "{A,B}" | "!{A,B}" | отсутствие/NULL (матч всех). */
 export function matchCategories(pattern, cats) {
     const spec = pattern?.categories;
@@ -16,8 +23,16 @@ export function matchCategories(pattern, cats) {
     const hit = list.some((c) => cats.includes(c));
     return neg ? !hit : hit;
 }
+// START_CONTRACT: maskBody
+//   PURPOSE: Скомпилировать тело маски в regex-фрагмент: '{a,b}' → альтернативы (рекурсивно), '*' → хвост из 1+ сегментов.
+//   INPUTS: { mask: string - маска с '.'-сегментами }
+//   OUTPUTS: { string - regex-исходник без якорей }
+//   SIDE_EFFECTS: none
+//   LINKS: M-ACL, V-M-ACL
+// END_CONTRACT: maskBody
 /** Маска → regex: '{a,b}' — альтернативы (рекурсивно), '*' — хвост из 1+ сегментов. */
 function maskBody(mask) {
+    // START_BLOCK_MASK_COMPILE
     let out = '';
     for (let i = 0; i < mask.length; i++) {
         const ch = mask[i];
@@ -58,9 +73,17 @@ function maskBody(mask) {
             out += ch;
         }
     }
+    // END_BLOCK_MASK_COMPILE
     return out;
 }
 const regexCache = new Map();
+// START_CONTRACT: matchMask
+//   PURPOSE: Сопоставить значение с маской, кэшируя скомпилированный RegExp.
+//   INPUTS: { mask: string; value: string }
+//   OUTPUTS: { boolean }
+//   SIDE_EFFECTS: заполняет regexCache
+//   LINKS: M-ACL, V-M-ACL
+// END_CONTRACT: matchMask
 export function matchMask(mask, value) {
     let re = regexCache.get(mask);
     if (!re) {
@@ -123,8 +146,16 @@ function rowFilter(r, account) {
         return undefined;
     return Object.fromEntries(rest.map(([k, v]) => [k, substitute(v, account)]));
 }
+// START_CONTRACT: decide
+//   PURPOSE: Выбрать РОВНО ОДНО победившее правило: max weight; при равенстве deny бьёт allow, равные allow — по alias ресурса.
+//   INPUTS: { rules: Rule[]; subjects: Set<string> - alias'ы субъекта; objects: Map<string,Resource> - применимые ресурсы }
+//   OUTPUTS: { { winner?: Rule } }
+//   SIDE_EFFECTS: none
+//   LINKS: M-ACL, V-M-ACL
+// END_CONTRACT: decide
 /** Победитель: max weight; равный вес — deny бьёт allow, равные allow — по alias объекта. */
 function decide(rules, subjects, objects) {
+    // START_BLOCK_DECIDE_WINNER
     let winner;
     for (const rule of rules) {
         if (!rule.enabled || !subjects.has(rule.account) || !objects.has(rule.resource))
@@ -141,8 +172,16 @@ function decide(rules, subjects, objects) {
             winner = rule;
         }
     }
+    // END_BLOCK_DECIDE_WINNER
     return { winner };
 }
+// START_CONTRACT: toDecision
+//   PURPOSE: Превратить победителя в AclDecision (allow + остаточный row-фильтр | deny + code/message | deny-by-default).
+//   INPUTS: { winner?: Rule; objects: Map<string,Resource>; account: string }
+//   OUTPUTS: { AclDecision }
+//   SIDE_EFFECTS: none
+//   LINKS: M-ACL, V-M-ACL, type-AclDecision
+// END_CONTRACT: toDecision
 function toDecision(winner, objects, account) {
     if (!winner)
         return { allow: false, message: 'no matching rule (deny by default)' };
@@ -158,6 +197,13 @@ function toDecision(winner, objects, account) {
 const subjectAliases = (resources, cats) => new Set(resources.filter((r) => r.category === 'ACCOUNT' && matchCategories(r.pattern, cats)).map((r) => r.alias));
 const toMap = (rs) => new Map(rs.map((r) => [r.alias, r]));
 const accId = (a) => (typeof a === 'object' ? a.id : a);
+// START_CONTRACT: makeAcl
+//   PURPOSE: Построить рантайм-фасад AclApi (check по эндпоинту / checkData по классу+op / reload) с кэшом Resource/Rule.
+//   INPUTS: { tables: Tables; registry: Registry }
+//   OUTPUTS: { AclApi }
+//   SIDE_EFFECTS: лениво читает resources/rules через tables (кэш до reload())
+//   LINKS: M-ACL, V-M-ACL
+// END_CONTRACT: makeAcl
 export function makeAcl(tables, registry) {
     let cache = null;
     const load = () => (cache ??= (async () => ({
@@ -185,8 +231,16 @@ export function makeAcl(tables, registry) {
     };
 }
 // --- enforce-компилятор (connect({enforceAcl: true})) ----------------------------
+// START_CONTRACT: compileEnforcer
+//   PURPOSE: Скомпилировать синхронный энфорсер (ClassDef, op) → AclDecision с мемоизацией — субъект и правила зафиксированы на connect.
+//   INPUTS: { src: AclSource; account: string; cats: string[]; registry: Registry }
+//   OUTPUTS: { (cls: ClassDef, op: AclOp) => AclDecision }
+//   SIDE_EFFECTS: none (мемо-кэш решений)
+//   LINKS: M-ACL, V-M-ACL, M-SQL, M-WRITE
+// END_CONTRACT: compileEnforcer
 /** Синхронный резолвер для цепочек: категории субъекта и правила зафиксированы на connect. */
 export function compileEnforcer(src, account, cats, registry) {
+    // START_BLOCK_ENFORCER_MEMO
     const subjects = subjectAliases(src.resources, cats);
     const memo = new Map();
     return (cls, op) => {
@@ -202,6 +256,14 @@ export function compileEnforcer(src, account, cats, registry) {
         return d;
     };
 }
+// END_BLOCK_ENFORCER_MEMO
+// START_CONTRACT: aclDenied
+//   PURPOSE: Собрать читаемую Error отказа ACL для цепочек (её бросают вызывающие sql/write).
+//   INPUTS: { op: AclOp; clsId: string; d: AclDecision }
+//   OUTPUTS: { Error }
+//   SIDE_EFFECTS: none (возвращает Error, не бросает)
+//   LINKS: M-ACL, V-M-ACL
+// END_CONTRACT: aclDenied
 /** Читаемая ошибка отказа для цепочек. */
 export function aclDenied(op, clsId, d) {
     return new Error(`letopis: acl denies ${op} on ${clsId}${d.message ? ` — ${d.message}` : ''}`);

package/dist/auth.d.ts

@@ -1,3 +1,10 @@
+/**
+ * db.auth: вход по таблице Credential — на аккаунт много способов:
+ * пароль (логин/почта), api-ключ, ключ-секрет, внешние identity (oauth/sso/telegram).
+ * Пароли — scrypt (node:crypto, без зависимостей); ключи/секреты — в БД только sha256.
+ * Однозначность входа даёт credential_identity_udx: один живой кред на (category, identifier).
+ * OAuth-танец, rate-limit, lockout — на приложении: здесь хранение и проверка.
+ */
 import type { Account, Credential } from './types.js';
 import type { Tables } from './tables.js';
 import { type SessionStore, type Sessions } from './sessions.js';

package/dist/auth.js

@@ -5,6 +5,27 @@
  * Однозначность входа даёт credential_identity_udx: один живой кред на (category, identifier).
  * OAuth-танец, rate-limit, lockout — на приложении: здесь хранение и проверка.
  */
+// FILE: lib/src/auth.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Жизненный цикл и проверка кредов аккаунта — пароли (scrypt), api-ключи, ключ+секрет, TOTP, OTP, внешние identity — плюс выдача сессий.
+//   SCOPE: makeAuth (AuthApi) + totpCode + локальные крипто-хелперы (hashPassword/verifyHash/base32Encode/base32Decode/hotp)
+//   DEPENDS: M-TYPES, M-TABLES, M-SESSIONS
+//   LINKS: M-AUTH, V-M-AUTH
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   totpCode - TOTP-код authenticator-а для base32-секрета на момент времени (хелпер для тестов/сервисов)
+//   AuthResult - успешный вход: аккаунт + конкретный кред
+//   AuthApi - контракт всех способов входа (пароль/api-ключ/ключ-секрет/TOTP/OTP/identity) + выдача сессий
+//   makeAuth - фабрика AuthApi поверх Tables
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
 import { createHash, createHmac, randomBytes, randomInt, scrypt, timingSafeEqual } from 'node:crypto';
 import { promisify } from 'node:util';
 import { makeSessions } from './sessions.js';
@@ -13,11 +34,26 @@ const scryptAsync = promisify(scrypt);
 const SCRYPT = { N: 32768, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
 const KEYLEN = 32;
 const sha256 = (s) => createHash('sha256').update(s).digest('hex');
+// START_BLOCK_SCRYPT_HASH
+// START_CONTRACT: hashPassword
+//   PURPOSE: Захэшировать пароль scrypt-ом со случайной солью в самодостаточную строку.
+//   INPUTS: { password: string - открытый пароль }
+//   OUTPUTS: { Promise<string> - строка `scrypt$N$r$p$saltB64$hashB64` }
+//   SIDE_EFFECTS: none (CSPRNG-соль, scrypt-KDF)
+//   LINKS: M-AUTH, V-M-AUTH
+// END_CONTRACT: hashPassword
 async function hashPassword(password) {
     const salt = randomBytes(16);
     const hash = await scryptAsync(password, salt, KEYLEN, SCRYPT);
     return `scrypt$${SCRYPT.N}$${SCRYPT.r}$${SCRYPT.p}$${salt.toString('base64')}$${hash.toString('base64')}`;
 }
+// START_CONTRACT: verifyHash
+//   PURPOSE: Проверить пароль против сохранённого scrypt-хэша в постоянное время.
+//   INPUTS: { password: string - открытый пароль; stored: string - строка формата scrypt$… }
+//   OUTPUTS: { Promise<boolean> - true при совпадении; false для не-scrypt (legacy) форматов }
+//   SIDE_EFFECTS: none (timingSafeEqual — сравнение в постоянное время)
+//   LINKS: M-AUTH, V-M-AUTH
+// END_CONTRACT: verifyHash
 async function verifyHash(password, stored) {
     const [algo, N, r, p, saltB64, hashB64] = stored.split('$');
     if (algo !== 'scrypt')
@@ -30,6 +66,7 @@ async function verifyHash(password, stored) {
 }
 /** Выравнивание времени ответа: «identifier не существует» не быстрее «пароль неверен». */
 const dummyVerify = (password) => scryptAsync(password, Buffer.alloc(16), KEYLEN, SCRYPT).then(() => false);
+// END_BLOCK_SCRYPT_HASH
 const eqHex = (a, b) => {
     const ba = Buffer.from(a, 'hex');
     const bb = Buffer.from(b, 'hex');
@@ -41,6 +78,7 @@ const eqStr = (a, b) => {
     return ba.length === bb.length && timingSafeEqual(ba, bb);
 };
 // --- TOTP (RFC 6238 / HOTP RFC 4226) ---------------------------------------
+// START_BLOCK_TOTP
 const B32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
 function base32Encode(buf) {
     let bits = 0;
@@ -58,6 +96,13 @@ function base32Encode(buf) {
         out += B32[(value << (5 - bits)) & 31];
     return out;
 }
+// START_CONTRACT: base32Decode
+//   PURPOSE: Декодировать base32 (RFC 4648, алфавит A-Z2-7) в байты.
+//   INPUTS: { s: string - base32-строка (хвостовой padding и регистр допустимы) }
+//   OUTPUTS: { Buffer - декодированные байты }
+//   SIDE_EFFECTS: бросает Error 'letopis: invalid base32 TOTP secret' на недопустимый символ
+//   LINKS: M-AUTH, V-M-AUTH
+// END_CONTRACT: base32Decode
 function base32Decode(s) {
     let bits = 0;
     let value = 0;
@@ -77,6 +122,13 @@ function base32Decode(s) {
 }
 const TOTP_PERIOD = 30; // секунд на шаг (стандарт authenticator-приложений)
 const TOTP_DIGITS = 6;
+// START_CONTRACT: hotp
+//   PURPOSE: HOTP (RFC 4226) — HMAC-SHA1 счётчика + dynamic truncation в цифровой код.
+//   INPUTS: { secret: Buffer - общий секрет; counter: number - шаг/счётчик }
+//   OUTPUTS: { string - код из TOTP_DIGITS (6) цифр с ведущими нулями }
+//   SIDE_EFFECTS: none
+//   LINKS: M-AUTH, V-M-AUTH
+// END_CONTRACT: hotp
 function hotp(secret, counter) {
     const buf = Buffer.alloc(8);
     buf.writeBigUInt64BE(BigInt(counter));
@@ -87,11 +139,25 @@ function hotp(secret, counter) {
 }
 const totpStep = (atMs) => Math.floor(atMs / 1000 / TOTP_PERIOD);
 /** Код authenticator-а для секрета на момент времени (хелпер для тестов/сервисов). */
+// START_CONTRACT: totpCode
+//   PURPOSE: TOTP-код authenticator-а для base32-секрета на заданный момент времени.
+//   INPUTS: { secretBase32: string - секрет в base32; atMs?: number - момент в мс (default Date.now()) }
+//   OUTPUTS: { string - 6-значный код текущего 30-секундного шага }
+//   SIDE_EFFECTS: none (при отсутствии atMs читает Date.now())
+//   LINKS: M-AUTH, V-M-AUTH
+// END_CONTRACT: totpCode
 export function totpCode(secretBase32, atMs = Date.now()) {
     return hotp(base32Decode(secretBase32), totpStep(atMs));
 }
 // ---------------------------------------------------------------------------
 const accId = (a) => (typeof a === 'object' ? a.id : a);
+// START_CONTRACT: makeAuth
+//   PURPOSE: Собрать AuthApi поверх Tables — все способы входа + выдача сессий.
+//   INPUTS: { tables: Tables - доступ к таблицам Credential/Account }
+//   OUTPUTS: { AuthApi - методы setPassword/verify*/issue*/enrollTotp/link/lookup/sessions }
+//   SIDE_EFFECTS: none при сборке; методы читают/пишут строки Credential и читают Account через Tables
+//   LINKS: M-AUTH, V-M-AUTH, M-TABLES, M-SESSIONS
+// END_CONTRACT: makeAuth
 export function makeAuth(tables) {
     /** Живой кред по глобально-уникальной паре (category, identifier). */
     const findLive = async (category, identifier) => (await tables.credentials.find({ category, identifier }))[0] ?? null;
@@ -105,6 +171,13 @@ export function makeAuth(tables) {
         return { account, credential: cred };
     }
     return {
+        // START_CONTRACT: setPassword
+        //   PURPOSE: Upsert пароля (scrypt) для (account, category, identifier).
+        //   INPUTS: { a: { account: string|{id}, identifier: string, password: string, category?='PASSWORD', confirmed?: boolean } }
+        //   OUTPUTS: { Promise<Credential> - записанный кред }
+        //   SIDE_EFFECTS: пишет строку Credential (meta.password = scrypt-хэш) через Tables
+        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
+        // END_CONTRACT: setPassword
         async setPassword(a) {
             return tables.credentials.set({
                 account: accId(a.account),
@@ -114,6 +187,13 @@ export function makeAuth(tables) {
                 confirmed: a.confirmed,
             });
         },
+        // START_CONTRACT: verifyPassword
+        //   PURPOSE: Проверить identifier+пароль; на miss — dummy-verify для выравнивания времени ответа.
+        //   INPUTS: { a: { identifier: string, password: string, category?='PASSWORD', requireConfirmed?: boolean } }
+        //   OUTPUTS: { Promise<AuthResult|null> - аккаунт+кред при успехе, иначе null }
+        //   SIDE_EFFECTS: читает Credential/Account; при отсутствии креда выполняет dummyVerify (scrypt) для timing-выравнивания
+        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
+        // END_CONTRACT: verifyPassword
         async verifyPassword(a) {
             const cred = await findLive(a.category ?? 'PASSWORD', a.identifier);
             const stored = cred?.meta.password;
@@ -125,6 +205,14 @@ export function makeAuth(tables) {
                 return null;
             return finalize(cred, a);
         },
+        // START_BLOCK_APIKEY
+        // START_CONTRACT: issueApiKey
+        //   PURPOSE: Выдать api-ключ `lts_<48hex>` (в БД — только sha256 + префикс).
+        //   INPUTS: { a: { account: string|{id}, name?: string } }
+        //   OUTPUTS: { Promise<{ key: string, credential: Credential }> - ключ отдаётся ОДИН раз }
+        //   SIDE_EFFECTS: пишет Credential (category='APIKEY', identifier=sha256(key), meta.prefix)
+        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
+        // END_CONTRACT: issueApiKey
         async issueApiKey(a) {
             const key = `lts_${randomBytes(24).toString('hex')}`;
             const credential = await tables.credentials.set({
@@ -135,6 +223,13 @@ export function makeAuth(tables) {
             });
             return { key, credential };
         },
+        // START_CONTRACT: verifyApiKey
+        //   PURPOSE: Проверить api-ключ по sha256(key).
+        //   INPUTS: { key: string - api-ключ; opts?: { requireConfirmed?: boolean } }
+        //   OUTPUTS: { Promise<AuthResult|null> }
+        //   SIDE_EFFECTS: читает Credential/Account
+        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
+        // END_CONTRACT: verifyApiKey
         async verifyApiKey(key, opts = {}) {
             const cred = await findLive('APIKEY', sha256(key));
             return cred ? finalize(cred, opts) : null;
@@ -157,6 +252,14 @@ export function makeAuth(tables) {
                 return null;
             return finalize(cred, opts);
         },
+        // END_BLOCK_APIKEY
+        // START_CONTRACT: enrollTotp
+        //   PURPOSE: Завести TOTP-фактор: случайный секрет + otpauth-URI для QR (неподтверждён до первой проверки).
+        //   INPUTS: { a: { account: string|{id}, issuer?: string, label?: string } }
+        //   OUTPUTS: { Promise<{ secret: string, uri: string, credential: Credential }> }
+        //   SIDE_EFFECTS: пишет/перезаписывает Credential (category='TOTP', identifier=id, confirmed=false, meta.secret/lastStep)
+        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
+        // END_CONTRACT: enrollTotp
         async enrollTotp(a) {
             const id = accId(a.account);
             const secret = base32Encode(randomBytes(20));
@@ -174,6 +277,13 @@ export function makeAuth(tables) {
             });
             return { secret, uri, credential };
         },
+        // START_CONTRACT: verifyTotp
+        //   PURPOSE: Проверить 6-значный код в окне ±window; replay использованного шага отбит; первая удача активирует фактор.
+        //   INPUTS: { a: { account: string|{id}, code: string, window?: number=1 } }
+        //   OUTPUTS: { Promise<boolean> - true при валидном коде }
+        //   SIDE_EFFECTS: при успехе пишет Credential (meta.lastStep=s, confirmed=true)
+        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
+        // END_CONTRACT: verifyTotp
         async verifyTotp(a) {
             const id = accId(a.account);
             const cred = (await tables.credentials.find({ account: id, category: 'TOTP' }))[0];
@@ -204,6 +314,14 @@ export function makeAuth(tables) {
             const cred = (await tables.credentials.find({ account: accId(account), category: 'TOTP' }))[0];
             return cred?.confirmed === true;
         },
+        // START_BLOCK_OTP
+        // START_CONTRACT: issueOtp
+        //   PURPOSE: Выдать одноразовый код (в БД sha256 + TTL + счётчик попыток); доставка — на приложении.
+        //   INPUTS: { a: { account: string|{id}, identifier: string, category?='OTP', ttlSec?=600, digits?=6 } }
+        //   OUTPUTS: { Promise<{ code: string, credential: Credential }> - код отдаётся один раз }
+        //   SIDE_EFFECTS: пишет/перезаписывает Credential (meta.code=sha256, expires, attempts=0)
+        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
+        // END_CONTRACT: issueOtp
         async issueOtp(a) {
             const digits = a.digits ?? 6;
             const code = String(randomInt(0, 10 ** digits)).padStart(digits, '0');
@@ -220,6 +338,13 @@ export function makeAuth(tables) {
             });
             return { code, credential };
         },
+        // START_CONTRACT: verifyOtp
+        //   PURPOSE: Проверить одноразовый код; успех и перебор попыток (maxAttempts) сжигают код.
+        //   INPUTS: { a: { identifier: string, code: string, category?='OTP', maxAttempts?=5 } }
+        //   OUTPUTS: { Promise<AuthResult|null> }
+        //   SIDE_EFFECTS: читает Credential; удаляет кред при успехе/просрочке/переборе, иначе инкрементит meta.attempts
+        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
+        // END_CONTRACT: verifyOtp
         async verifyOtp(a) {
             const cred = await findLive(a.category ?? 'OTP', a.identifier);
             if (!cred)
@@ -245,6 +370,7 @@ export function makeAuth(tables) {
             await tables.credentials.delete(cred.id); // одноразовость: успех сжигает код
             return finalize(cred, {});
         },
+        // END_BLOCK_OTP
         async link(a) {
             return tables.credentials.set({
                 account: accId(a.account),

package/dist/chain.d.ts

@@ -4,8 +4,9 @@
  *
  * Выборка настраивается модификаторами: .limit(n) .offset(n) .sort(field, dir?)
  * Колонки — модификаторами: .tags(…) .account(…) .owner(…); ключ путей — .alias(…).
- * Запись: .set(data) / .delete({confirm}) / .anonymize(fields) — ЗВЕНЬЯ (возвращают
- * цепочку, продолжение — от результата); исполняет ТЕРМИНАЛ, весь план одной транзакцией.
+ * Запись: .create(data) / .update(data) / .delete({confirm}) / .anonymize(fields) — ЗВЕНЬЯ
+ * (возвращают цепочку, продолжение — от результата); исполняет ТЕРМИНАЛ, весь план
+ * одной транзакцией.
  */
 import type { Row, Path, Filter } from './types.js';
 import { type Ctx } from './sql.js';
@@ -49,31 +50,37 @@ export interface ChainCore {
     anonymize(fields: string[]): Chain;
     /** Переименовать ключ ТЕКУЩЕГО шага в выводе путей. */
     alias(name: string): Chain;
-    /** Колонка tags: строка | string[] (все) | has/hasAny/hasAll. В set() — значение тегов. */
+    /** Колонка tags: строка | string[] (все) | has/hasAny/hasAll. В записи — значение тегов. */
     tags(v: string | string[] | object): Chain;
-    /** Колонка account (uuid или Row/Account). В set()-insert — значение. */
+    /** Колонка account (uuid или Row/Account). В create() — значение. */
     account(v: string | {
         id: string;
     }): Chain;
-    /** Колонка owner (uuid или Row/Account). В set()-insert — значение. */
+    /** Колонка owner (uuid или Row/Account). В create() — значение. */
     owner(v: string | {
         id: string;
     }): Chain;
     /**
-     * Значение связи для записи БЕЗ участия в фильтре целей (в отличие от контекст-шага):
-     *   tr.Запись(b).позиция({}).link('Сотрудник', новый).set({}).rows()  // перевесить исполнителя
+     * Вставить узел в путь: x — ленивая цепочка-паттерн (стык проверяется правилами
+     * переходов) либо Row (шаг его класса по id). ТА ЖЕ переменная-цепочка повторно
+     * в одном пути — возврат к её узлу (ветвление); разные переменные — разные узлы.
      */
-    link(className: string, target: string | {
-        id: string;
-    }): Chain;
+    entity(x: Chain | Row): Chain;
     /**
-     * Записать в шаг, к которому приклеен точкой (ЗВЕНО — вернёт цепочку, исполняет терминал):
-     *   await db.Организация(org).Сотрудник().set({ name: 'Вася' }).rows()
-     * Связи — контекст-шагами до set(). Пустой фильтр без data.id → INSERT;
-     * id (фильтр или data.id) → UPSERT; фильтр-объект → версия каждого найденного.
+     * Создать сущность (ЗВЕНО — вернёт цепочку, исполняет терминал):
+     *   await db.Организация(org).Сотрудник().create({ name: 'Вася' }).rows()
+     * Связи — контекст-шагами до create() + слотами .Класс.set(…) после. id — по Schema
+     * (attributes.id: v4 | v7 | v5-вычисляемый); известный id (Класс(id) / data.id / v5)
+     * уже существует → новая версия (идемпотентно). Фильтр-объект — ошибка: это update().
+     */
+    create(data?: Record<string, unknown>): Chain;
+    /**
+     * Новая версия КАЖДОГО найденного путём (deep-merge листьев data):
+     *   await db.Запись(з).позиция({ qty: 1 }).update({ qty: 2 }).rows()
+     * Класс() ≡ Класс({}) — все в границах контекста. Не найдено → [] (НИКОГДА не создаёт).
      * Продолжение цепочки — от записанных строк (fan-out при множестве).
      */
-    set(data?: Record<string, unknown>): Chain;
+    update(data?: Record<string, unknown>): Chain;
     /**
      * Удаление-звено. { confirm: true } — серверный tombstone + каскад (продолжение — от
      * затомбстоуненных, $deleted: true); БЕЗ confirm — превью: терминал вернёт кандидатов
@@ -83,8 +90,25 @@ export interface ChainCore {
         confirm?: boolean;
     }): Chain;
 }
+/**
+ * Свойство-класс на цепочке:
+ *   ВЫЗОВ  `Класс(фильтр?)` — шаг-навигация; повтор LINK-класса в пути = возврат
+ *          к его узлу (pivot: ветвление к другому концу, дофильтровка AND);
+ *   СЛОТ   `Класс` без скобок — конец links записываемой версии:
+ *     .set(target) — установить конец (id | Row | вложенная цепочка: та же транзакция,
+ *                    ровно одна сущность класса конца); союз-конец замещается целиком;
+ *     .unset()     — снять optional-конец.
+ * Слот валиден только для конца из Schema.links владельца и ТОЛЬКО после операции
+ * записи: …create(…).Класс.set(x) / …update(…).Класс.unset() — та же версия строки.
+ */
+export type StepProp = ((filter?: Filter) => Chain) & {
+    set(target: string | {
+        id: string;
+    } | Chain): Chain;
+    unset(): Chain;
+};
 export type Chain = ChainCore & {
-    [className: string]: (filter?: Filter) => Chain;
+    [className: string]: StepProp;
 };
 export interface DbCore {
     /** Открыть транзакцию: tr — тот же API + commit/rollback/lock. */
@@ -114,6 +138,8 @@ export interface DbCore {
     auth: AuthApi;
     /** ACL по Resource/Rule: check(эндпоинт) / checkData(класс, READ|WRITE|DELETE) / reload. */
     acl: AclApi;
+    /** Начать путь с готового узла/паттерна: db.entity(pos).… (pos — ленивая цепочка или Row). */
+    entity(x: Chain | Row): Chain;
 }
 export type EntityDb = DbCore & {
     [className: string]: (filter?: Filter) => Chain;
@@ -147,5 +173,7 @@ export type Batch = {
 interface RootState {
     batches: Map<string, BatchPlan[]>;
 }
+/** Внутренний канал: план чужой ленивой цепочки (слот-значения, entity()). */
+export declare const PLAN: unique symbol;
 export declare function makeDb(ctx: Ctx, root?: RootState): EntityDb;
 export {};