@astram/engine 0.1.0

package/dist/pipe/stages/write.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Stage: write. Persists the validated columns to the real physical table via the
+ * bound transactional query fn (parameterized — never string-built). Handles the
+ * create (INSERT with a pre-allocated uuid PK), update (UPDATE by id), and delete
+ * (DELETE by id). This is the ONLY stage that writes the base row; extension-field
+ * sidecar writes attach here too when the table is extensible.
+ *
+ * uuid generation uses node:crypto (guard/engine own node built-ins; core does not).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeStage = writeStage;
+const node_crypto_1 = require("node:crypto");
+const errors_js_1 = require("../../errors.js");
+const registry_js_1 = require("../../registry.js");
+function qualified(ctx) {
+    const schema = ctx.registration.schema;
+    const t = ctx.registration.table;
+    return schema ? `\`${schema}\`.\`${t}\`` : `\`${t}\``;
+}
+/** The physical column of a `tenantId`-trusted field, if the table has one. */
+function tenantColumn(ctx) {
+    const f = ctx.registration.fields.find((x) => x.trusted === 'tenantId');
+    return f ? (0, registry_js_1.columnOf)(f) : null;
+}
+/**
+ * Build a WHERE clause + params for a record id (uuid or composite). CRITICAL
+ * cross-tenant safety: when the table is tenant-owned (has a `tenantId`-trusted
+ * column), the WHERE is ALSO constrained to the ACTOR's tenant — so an update/
+ * delete can NEVER touch another tenant's row even if the id is known and the gate
+ * (which sees the actor's own tenant on a record-scoped resource) would allow it.
+ * This is the write-path twin of the read-path scoping (defense-in-depth).
+ */
+function whereById(ctx, id) {
+    const pk = ctx.registration.primaryKey;
+    let sql;
+    let params;
+    if (pk.kind === 'uuid') {
+        if (typeof id !== 'string') {
+            throw new errors_js_1.RegistrationError(`uuid PK table '${ctx.registration.typeKey}' needs a string id`);
+        }
+        sql = `\`${pk.column}\` = ?`;
+        params = [id];
+    }
+    else {
+        if (typeof id === 'string') {
+            throw new errors_js_1.RegistrationError(`composite PK table '${ctx.registration.typeKey}' needs a key map, not a string id`);
+        }
+        sql = pk.columns.map((c) => `\`${c}\` = ?`).join(' AND ');
+        params = pk.columns.map((c) => id[c]);
+    }
+    const tenantCol = tenantColumn(ctx);
+    if (tenantCol) {
+        sql += ` AND \`${tenantCol}\` = ?`;
+        params = [...params, ctx.actor.tenantId];
+    }
+    return { sql, params };
+}
+function writeStage() {
+    return {
+        name: 'write',
+        async run(ctx) {
+            const table = qualified(ctx);
+            if (ctx.op === 'create') {
+                const pk = ctx.registration.primaryKey;
+                // Pre-allocate the uuid PK (composite-PK tables set their key columns via fields).
+                if (pk.kind === 'uuid') {
+                    const pkCol = (0, registry_js_1.uuidPkColumn)(pk);
+                    if (ctx.columns[pkCol] === undefined)
+                        ctx.columns[pkCol] = (0, node_crypto_1.randomUUID)();
+                    ctx.resultId = ctx.columns[pkCol];
+                }
+                else {
+                    const key = {};
+                    for (const c of pk.columns)
+                        key[c] = String(ctx.columns[c]);
+                    ctx.resultId = key;
+                }
+                const cols = Object.keys(ctx.columns);
+                if (cols.length === 0) {
+                    throw new errors_js_1.RegistrationError(`create '${ctx.registration.typeKey}': no columns to insert`);
+                }
+                const placeholders = cols.map(() => '?').join(', ');
+                const sql = `INSERT INTO ${table} (${cols.map((c) => `\`${c}\``).join(', ')}) VALUES (${placeholders})`;
+                await ctx.query(sql, cols.map((c) => ctx.columns[c]));
+                return;
+            }
+            if (ctx.op === 'update') {
+                if (ctx.id === undefined)
+                    throw new errors_js_1.RegistrationError('update requires an id');
+                const cols = Object.keys(ctx.columns);
+                if (cols.length === 0)
+                    return; // nothing to patch
+                const setSql = cols.map((c) => `\`${c}\` = ?`).join(', ');
+                const where = whereById(ctx, ctx.id);
+                const sql = `UPDATE ${table} SET ${setSql} WHERE ${where.sql}`;
+                await ctx.query(sql, [...cols.map((c) => ctx.columns[c]), ...where.params]);
+                ctx.resultId = ctx.id;
+                return;
+            }
+            // delete
+            if (ctx.id === undefined)
+                throw new errors_js_1.RegistrationError('delete requires an id');
+            const where = whereById(ctx, ctx.id);
+            await ctx.query(`DELETE FROM ${table} WHERE ${where.sql}`, where.params);
+            ctx.resultId = ctx.id;
+        },
+    };
+}

package/dist/pipe/stages/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../../src/pipe/stages/write.ts"],"names":[],"mappings":"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"}

package/dist/ports.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The ports the engine depends on — injected adapters, so the engine's pipe logic
+ * is pure over its collaborators (ADR-0003 port/adapter grain). Concrete adapters
+ * (the sealed mariadb pool, the decision-authority binding, the audit sink) are
+ * wired in the engine's Nest module.
+ *
+ * Core types are TYPE-ONLY imports (erased at build — no runtime require of the
+ * ESM-only core).
+ */
+import type { Principal, Action, Resource, DecisionContext, Decision, AuditEvent } from '@astram/core';
+/** Raw parameterized query — the ONE DB primitive the pipe uses (sealed pool). */
+export type QueryFn = (sql: string, params?: readonly unknown[]) => Promise<unknown>;
+/** Opens a transaction and runs `body` with a bound {@link QueryFn}; commit/rollback. */
+export interface UnitOfWork {
+    run<T>(body: (query: QueryFn) => Promise<T>): Promise<T>;
+}
+/**
+ * The authorization port — the permission-gate stage calls this. Bound to the
+ * framework's single {@link import('@astram/core').DecisionAuthority} (guard's
+ * `SHIELD_DECISION_AUTHORITY`). The engine NEVER makes its own allow/deny logic;
+ * it asks `decide()` and obeys.
+ */
+export interface DecisionPort {
+    decide(principal: Principal, action: Action, resource: Resource, context: DecisionContext): Promise<Decision>;
+}
+/**
+ * The audit port — the audit stage calls `record()` (append-only). It receives the
+ * pipe's bound {@link QueryFn} so the audit row commits IN THE SAME TRANSACTION as
+ * the data write: there is never data without its audit row, and never an audit row
+ * for a rolled-back write. (This differs from core's connection-less `AuditSink`
+ * seam by design — atomicity with the record write is a paved-road invariant.)
+ */
+export interface AuditPort {
+    record(event: AuditEvent, query: QueryFn): Promise<void>;
+}
+export type { Principal, Action, Resource, DecisionContext, Decision, AuditEvent };
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,MAAM,EACN,QAAQ,EACR,eAAe,EACf,QAAQ,EACR,UAAU,EACX,MAAM,cAAc,CAAC;AAEtB,kFAAkF;AAClF,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAErF,yFAAyF;AACzF,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC1D;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CACJ,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,QAAQ,CAAC,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC"}

package/dist/ports.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * The ports the engine depends on — injected adapters, so the engine's pipe logic
+ * is pure over its collaborators (ADR-0003 port/adapter grain). Concrete adapters
+ * (the sealed mariadb pool, the decision-authority binding, the audit sink) are
+ * wired in the engine's Nest module.
+ *
+ * Core types are TYPE-ONLY imports (erased at build — no runtime require of the
+ * ESM-only core).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG"}

package/dist/registry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The table registry — the in-memory source of truth for every registered table's
+ * shape (the "SchemaOverview" of the Directus pattern). Features register a
+ * {@link ObjectType} at boot (code-registered) — the engine resolves by
+ * `typeKey` on every operation. One code path serves all tables because the schema
+ * is data.
+ *
+ * Runtime-registered (no-code) tables will register through the SAME registry later
+ * (the no-code phase); the pipe does not distinguish how a registration arrived.
+ */
+import type { FieldSpec, PkStrategy, ObjectType } from './types.js';
+export declare class TableRegistry {
+    private readonly byType;
+    /** Register a table. Throws on a duplicate typeKey or an invalid registration. */
+    register(reg: ObjectType): void;
+    /** Resolve a registration, or throw a RegistrationError if unknown. */
+    require(typeKey: string): ObjectType;
+    has(typeKey: string): boolean;
+    all(): readonly ObjectType[];
+}
+/** The physical column name for a field (explicit `column` or the field key). */
+export declare function columnOf(field: FieldSpec): string;
+/** The single uuid PK column name, or throw for a composite PK. */
+export declare function uuidPkColumn(pk: PkStrategy): string;
+/**
+ * Whether the type declares person-ownership (`access.owned === true`). An owned type
+ * has exactly one `trusted:'actorId'` field (enforced by chokepoint 1) — its column is
+ * the owner column. Only owned types pre-fetch their owner before the gate.
+ */
+export declare function isOwned(reg: ObjectType): boolean;
+/**
+ * The physical column of the `trusted:'actorId'` (owner) field, or `null` if the type
+ * has none. For an owned type chokepoint 1 guarantees exactly one exists.
+ */
+export declare function ownerColumn(reg: ObjectType): string | null;
+/** The physical column of the `trusted:'tenantId'` field, or `null` if the type has none. */
+export declare function tenantColumnOf(reg: ObjectType): string | null;
+/** The physical column of the field bearing `role`, or null if unclaimed. */
+export declare function columnForRole(reg: ObjectType, role: FieldSpec['role']): string | null;
+/** Boot-enforce that exactly-one field claims `role`; throw if none. */
+export declare function requireRole(reg: ObjectType, role: NonNullable<FieldSpec['role']>): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEpE,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IAExD,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAQ/B,uEAAuE;IACvE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAWpC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B,GAAG,IAAI,SAAS,UAAU,EAAE;CAG7B;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAEjD;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,CAKnD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAEhD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAG1D;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAG7D;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAGrF;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAMvF"}

package/dist/registry.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * The table registry — the in-memory source of truth for every registered table's
+ * shape (the "SchemaOverview" of the Directus pattern). Features register a
+ * {@link ObjectType} at boot (code-registered) — the engine resolves by
+ * `typeKey` on every operation. One code path serves all tables because the schema
+ * is data.
+ *
+ * Runtime-registered (no-code) tables will register through the SAME registry later
+ * (the no-code phase); the pipe does not distinguish how a registration arrived.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TableRegistry = void 0;
+exports.columnOf = columnOf;
+exports.uuidPkColumn = uuidPkColumn;
+exports.isOwned = isOwned;
+exports.ownerColumn = ownerColumn;
+exports.tenantColumnOf = tenantColumnOf;
+exports.columnForRole = columnForRole;
+exports.requireRole = requireRole;
+const errors_js_1 = require("./errors.js");
+class TableRegistry {
+    byType = new Map();
+    /** Register a table. Throws on a duplicate typeKey or an invalid registration. */
+    register(reg) {
+        validate(reg);
+        if (this.byType.has(reg.typeKey)) {
+            throw new errors_js_1.RegistrationError(`duplicate table registration for typeKey '${reg.typeKey}'`);
+        }
+        this.byType.set(reg.typeKey, reg);
+    }
+    /** Resolve a registration, or throw a RegistrationError if unknown. */
+    require(typeKey) {
+        const reg = this.byType.get(typeKey);
+        if (!reg) {
+            throw new errors_js_1.RegistrationError(`no table registered for typeKey '${typeKey}' — a feature must register it ` +
+                `before the engine can operate on it.`);
+        }
+        return reg;
+    }
+    has(typeKey) {
+        return this.byType.has(typeKey);
+    }
+    all() {
+        return [...this.byType.values()];
+    }
+}
+exports.TableRegistry = TableRegistry;
+/** The physical column name for a field (explicit `column` or the field key). */
+function columnOf(field) {
+    return field.column ?? field.key;
+}
+/** The single uuid PK column name, or throw for a composite PK. */
+function uuidPkColumn(pk) {
+    if (pk.kind !== 'uuid') {
+        throw new errors_js_1.RegistrationError('expected a uuid primary key');
+    }
+    return pk.column;
+}
+/**
+ * Whether the type declares person-ownership (`access.owned === true`). An owned type
+ * has exactly one `trusted:'actorId'` field (enforced by chokepoint 1) — its column is
+ * the owner column. Only owned types pre-fetch their owner before the gate.
+ */
+function isOwned(reg) {
+    return reg.access.owned === true;
+}
+/**
+ * The physical column of the `trusted:'actorId'` (owner) field, or `null` if the type
+ * has none. For an owned type chokepoint 1 guarantees exactly one exists.
+ */
+function ownerColumn(reg) {
+    const f = reg.fields.find((x) => x.trusted === 'actorId');
+    return f ? columnOf(f) : null;
+}
+/** The physical column of the `trusted:'tenantId'` field, or `null` if the type has none. */
+function tenantColumnOf(reg) {
+    const f = reg.fields.find((x) => x.trusted === 'tenantId');
+    return f ? columnOf(f) : null;
+}
+/** The physical column of the field bearing `role`, or null if unclaimed. */
+function columnForRole(reg, role) {
+    const f = reg.fields.find((x) => x.role === role);
+    return f?.column ?? f?.key ?? null;
+}
+/** Boot-enforce that exactly-one field claims `role`; throw if none. */
+function requireRole(reg, role) {
+    if (!reg.fields.some((f) => f.role === role)) {
+        throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': requires a field with role '${role}'.`);
+    }
+}
+function validate(reg) {
+    if (!reg.typeKey)
+        throw new errors_js_1.RegistrationError('registration.typeKey is required');
+    if (!reg.table)
+        throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': table is required`);
+    if (reg.fields.length === 0) {
+        throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': at least one field is required`);
+    }
+    const keys = new Set();
+    for (const f of reg.fields) {
+        if (keys.has(f.key)) {
+            throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': duplicate field key '${f.key}'`);
+        }
+        keys.add(f.key);
+    }
+    if (reg.primaryKey.kind === 'composite' && reg.primaryKey.columns.length < 2) {
+        throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': composite primary key needs >= 2 columns`);
+    }
+    validateAccess(reg);
+}
+/**
+ * Chokepoint 1 (§4.1 of the framework-owns-data-layer design). Every registered
+ * object type MUST declare its access explicitly — this closes tenant-leak-by-omission
+ * and ungoverned-record holes at BOOT (dev/CI), never as a silent prod hole:
+ *
+ *  1. `access` is REQUIRED — absent → boot fails (no silent default).
+ *  2. `system` is MUTUALLY EXCLUSIVE with `tenantScoped`/`owned` — a contradictory
+ *     combo → boot fails.
+ *  3. `owned:true` REQUIRES a `trusted:'actorId'` owner column — else boot fails.
+ *  4. `tenantScoped:true` REQUIRES a `trusted:'tenantId'` column — else boot fails.
+ *
+ * NOTE: a `system` type MAY still carry a `trusted:'actorId'` field (a `created_by`
+ * audit column, e.g. company_membership/membership_posting) — `system` only forbids
+ * being DECLARED owned/tenantScoped, NOT having such a column. (No record-rule check
+ * here — that is Phase 2's completeness sweep.)
+ */
+function validateAccess(reg) {
+    const access = reg.access;
+    if (!access) {
+        throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': an access declaration is required ` +
+            `(access: { plane, tenantScoped?, owned?, system? }) — no silent default.`);
+    }
+    // SECURITY (root-cap axis): `plane` is REQUIRED + explicit. Omitting it would default a
+    // new administrative type to `data` and wrongly deny root, with NO error — the exact
+    // posture-by-omission hole `access` itself already forbids. Only the two literal
+    // CapabilityPlane values are accepted; absent/other fails loud at boot. (`decide()`
+    // still keeps `data` as its runtime fail-safe floor; this enforces the CHOICE at boot.)
+    if (access.plane !== 'control' && access.plane !== 'data') {
+        throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': access.plane is required and must be ` +
+            `'control' or 'data', got ${access.plane === undefined ? 'undefined' : `'${String(access.plane)}'`}. ` +
+            `control = who-may-act administration (root allowed); data = business content ` +
+            `(root denied). No silent default.`);
+    }
+    // SECURITY: gate on real booleans, NOT `=== true`. A truthy-non-boolean flag
+    // (`owned: 1`, `system: 'yes'`) is a MALFORMED declaration — rejecting it here closes
+    // the bypass where such a value would (a) escape the mutual-exclusion / column-required
+    // checks below (which key off `=== true`) yet (b) mark the type "governed", producing a
+    // type with no owner/tenant column and thus ZERO isolation. Only `true`/`false`/absent
+    // are valid; anything else fails loud at boot.
+    const flag = (name) => {
+        const v = access[name];
+        if (v !== undefined && typeof v !== 'boolean') {
+            throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': access.${name} must be a boolean, got ` +
+                `${typeof v} (${String(v)}).`);
+        }
+        return v === true;
+    };
+    const tenantScoped = flag('tenantScoped');
+    const owned = flag('owned');
+    const system = flag('system');
+    // No silent "global by empty object": {} / all-false is "declared nothing" — the same
+    // hole as an absent declaration. At least ONE posture must be an explicit choice. Truly
+    // global (no tenant, no owner) is expressed with `system: true` (grant-governed) — a
+    // DELIBERATE decision, never the accidental default of an empty/all-false object.
+    if (!tenantScoped && !owned && !system) {
+        throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': access declares no posture ` +
+            `(need at least one of tenantScoped/owned/system=true). A global, ungoverned ` +
+            `type must be declared system:true — 'global' is a decision, not an empty object.`);
+    }
+    if (system && (tenantScoped || owned)) {
+        throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': access.system is mutually exclusive with ` +
+            `tenantScoped/owned.`);
+    }
+    const hasTrusted = (source) => reg.fields.some((f) => f.trusted === source);
+    if (owned && !hasTrusted('actorId')) {
+        throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': access.owned requires a field with ` +
+            `trusted:'actorId' (the owner column).`);
+    }
+    if (tenantScoped && !hasTrusted('tenantId')) {
+        throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': access.tenantScoped requires a field with ` +
+            `trusted:'tenantId' (the tenant column).`);
+    }
+}

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Public types for @astram/engine — the paved road.
+ *
+ * A feature contributes exactly ONE thing: a {@link ObjectType} (metadata =
+ * the contract). From it the engine derives the physical table shape, validation,
+ * the `decide()` resource identity, and the audit event. The feature then calls the
+ * {@link RecordEngine} facade for all CRUD — it never touches a pool/query-runner.
+ *
+ * Core types (`Principal`, `Action`, `Resource`) are imported TYPE-ONLY from
+ * `@astram/core` (erased at build; the CJS↔ESM lesson — no runtime require of the
+ * ESM-only core). Re-exported from the engine barrel so a consumer has ONE import
+ * surface.
+ */
+import type { Principal, CapabilityPlane } from '@astram/core';
+/** Supported field value kinds the pipe can validate + persist (Phase 1 set). */
+export type FieldType = 'string' | 'number' | 'boolean' | 'uuid' | 'timestamp' | 'json';
+/** One field on a registered table (core column). */
+export interface FieldSpec {
+    /** Stable field key (business-meaningful; maps to a physical column). */
+    readonly key: string;
+    /** Physical column name (defaults to `key` if omitted). */
+    readonly column?: string;
+    readonly type: FieldType;
+    /** Required on create (validate stage rejects a missing value). */
+    readonly required?: boolean;
+    /**
+     * A server-trusted attribute: on write the engine OVERWRITES any client-supplied
+     * value with a value derived from the actor/context (anti-forgery). The resolver
+     * key names which trusted source fills it (e.g. `tenantId`, `actorId`). Client
+     * input for this field is IGNORED.
+     */
+    readonly trusted?: TrustedSource;
+    /**
+     * An identity-role marker (see {@link IdentityRole}) — lets the framework find a
+     * field by ROLE regardless of the app's chosen column name. Orthogonal to
+     * `trusted`: `trusted` marks WRITE-CONTEXT roles (tenantId/actorId, enforced by
+     * the derive-write-context stage); `role` marks IDENTITY roles (username,
+     * password, etc.) and carries no write-time behavior of its own.
+     */
+    readonly role?: IdentityRole;
+}
+/** Server-trusted write-context sources (derive-write-context stage). */
+export type TrustedSource = 'tenantId' | 'actorId';
+/** Identity/field ROLE vocabulary — marks WHAT a field IS, so the framework finds it
+ *  by role regardless of the app's chosen column name. `trusted` (tenantId/actorId) are
+ *  the WRITE-CONTEXT roles and remain separate; these are the IDENTITY roles. */
+export type IdentityRole = 'primaryKey' | 'username' | 'password' | 'status' | 'active' | 'effectiveFrom' | 'effectiveUntil';
+/**
+ * The REQUIRED access declaration on every {@link ObjectType} — two orthogonal flags
+ * plus a `system` escape. Replaces "tenant/owner by omission" (a forgotten column =
+ * a silent cross-tenant or ungoverned hole) with "by explicit, boot-enforced
+ * declaration". Enforced at registration (chokepoint 1 in {@link TableRegistry}):
+ *
+ *  - `owned: true` REQUIRES exactly-one field with `trusted:'actorId'` (the owner
+ *    column) — else registration throws.
+ *  - `tenantScoped: true` REQUIRES exactly-one field with `trusted:'tenantId'` — else
+ *    registration throws.
+ *  - `system: true` is MUTUALLY EXCLUSIVE with `tenantScoped`/`owned`. A `system`
+ *    type may still carry a `trusted:'actorId'` field (e.g. a `created_by` audit
+ *    column) — `system` only forbids being DECLARED owned/tenantScoped, not having
+ *    such a column.
+ *
+ * `tenantScoped` and `owned` are independent (a normal data record is BOTH). An
+ * absent `access` fails registration (no silent default).
+ *
+ * `plane` is a SECOND, ORTHOGONAL axis (do not confuse it with the ownership flags
+ * above). The ownership flags answer "who reaches an individual ROW?" (gate 6, the
+ * record owner-baseline). `plane` answers "may the capped ROOT super-user perform this?"
+ * (gate 5, the root cap). They do NOT correlate: a `system` type may be `control`
+ * (`role` — administration, root allowed) OR `data` (`company` — business content, root
+ * denied). `plane` is REQUIRED and boot-validated for the same reason `access` itself is
+ * — a plane is a security posture, and posture-by-omission is a silent hole (a forgotten
+ * `plane` would default a new administrative type to `data` and wrongly deny root, with
+ * no error). It is DECLARED per type (uniform across the type's actions); the framework
+ * defines only the `CapabilityPlane` vocabulary — the consumer app owns the assignment.
+ */
+export interface AccessDeclaration {
+    /** true → tenant-isolated; a `trusted:'tenantId'` field is REQUIRED. */
+    readonly tenantScoped?: boolean;
+    /**
+     * true → records are person-owned; a `trusted:'actorId'` (owner) field is REQUIRED.
+     * Owner = the CREATING principal (DAC).
+     */
+    readonly owned?: boolean;
+    /**
+     * true → identity/infrastructure type (company/user/role): neither person-owned nor
+     * simply tenant-scoped; grant-governed, framework-managed. MUTUALLY EXCLUSIVE with
+     * `tenantScoped`/`owned`.
+     */
+    readonly system?: boolean;
+    /**
+     * REQUIRED capability plane (the root-cap axis; see the interface note above).
+     * `'control'` → identity/access administration; the capped root MAY perform it without
+     * a grant. `'data'` → tenant business content; root is DENIED by construction
+     * (`root_data_plane_denied`), even fully granted. Absent → registration fails
+     * (chokepoint 1) — no silent `data` default at the declaration layer. (`decide()`
+     * keeps `data` as its RUNTIME fail-safe floor, but boot requires an explicit choice.)
+     */
+    readonly plane: CapabilityPlane;
+}
+/** Primary-key strategy for a registered table. */
+export type PkStrategy = {
+    readonly kind: 'uuid';
+    readonly column: string;
+} | {
+    readonly kind: 'composite';
+    readonly columns: readonly string[];
+};
+/** A composite-key junction table this object owns/syncs. */
+export interface JunctionSpec {
+    /** Stable name (business key, e.g. `user_roles`). */
+    readonly name: string;
+    /** Physical junction table. */
+    readonly table: string;
+    /** Column holding THIS record's id (the local side). */
+    readonly localColumn: string;
+    /** Column holding the referenced id (the foreign side). */
+    readonly foreignColumn: string;
+    /** Optional extra payload columns (e.g. `is_active`) with server-set defaults. */
+    readonly payloadDefaults?: Readonly<Record<string, unknown>>;
+}
+/** A feature's declaration — the complete contract for one table on the pipe. */
+export interface ObjectType {
+    /** Stable object-type key — the `decide()` resource typeKey + audit type key. */
+    readonly typeKey: string;
+    /** Physical table name. */
+    readonly table: string;
+    /** Schema/database the table lives in (defaults to the engine's app schema). */
+    readonly schema?: string;
+    readonly primaryKey: PkStrategy;
+    readonly fields: readonly FieldSpec[];
+    readonly junctions?: readonly JunctionSpec[];
+    /** Opt into the runtime extension-field sidecar for this table. */
+    readonly extensible?: boolean;
+    /**
+     * REQUIRED access declaration (tenantScoped/owned/system). Absent → registration
+     * fails (chokepoint 1). See {@link AccessDeclaration}.
+     */
+    readonly access: AccessDeclaration;
+}
+/** Input to a create/update — field keys → values (+ optional junction refs). */
+export interface RecordInput {
+    /** Core + extension field values, keyed by field key. */
+    readonly fields: Readonly<Record<string, unknown>>;
+    /**
+     * Multi-reference junction values, keyed by junction name → array of foreign ids
+     * (DELETE+INSERT synced by the junction-sync stage).
+     */
+    readonly junctions?: Readonly<Record<string, readonly string[]>>;
+}
+/** A record id — a uuid string, or a composite key map for junction-style tables. */
+export type RecordId = string | Readonly<Record<string, string>>;
+/** A read-projected record (UUID→label resolution + unauthorized columns hidden). */
+export interface RecordView {
+    readonly id: RecordId;
+    readonly fields: Readonly<Record<string, unknown>>;
+    readonly junctions?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Free-text search across one or more registered field keys — a single search box
+ * that ORs a `LIKE '%term%'` over each named field. Field keys are whitelisted via
+ * the registration (unknown → RegistrationError); the term is bound as a `?` param
+ * (never interpolated), and LIKE wildcards in the term are escaped so a literal `%`
+ * or `_` the user types matches literally instead of acting as a wildcard.
+ */
+export interface SearchQuery {
+    /** Registered field keys to search (each resolved to its column + whitelisted). */
+    readonly fields: readonly string[];
+    /** The search term — bound as `%term%` per field (wildcards escaped). */
+    readonly term: string;
+}
+/**
+ * A list query — tenant-scoped filtering + simple paging, plus optional search
+ * (LIKE across fields) and sort (ORDER BY). All field references are registered
+ * field KEYS, resolved+whitelisted to columns; all user values are bound `?` params.
+ */
+export interface ListQuery {
+    readonly limit?: number;
+    readonly offset?: number;
+    /** Equality filters on core field keys. */
+    readonly where?: Readonly<Record<string, unknown>>;
+    /** Free-text LIKE search across named field keys (ANDed with `where` + tenant). */
+    readonly search?: SearchQuery;
+    /** A registered field KEY to ORDER BY (unknown → RegistrationError). */
+    readonly sortBy?: string;
+    /** Sort direction; anything other than 'desc' is treated as ascending. */
+    readonly sortOrder?: 'asc' | 'desc';
+}
+/** A page of read-projected records. */
+export interface RecordPage {
+    readonly rows: readonly RecordView[];
+    readonly total: number;
+}
+/**
+ * The ONLY data-access surface a feature is given. Every method flows through the
+ * full pipe (permission gate + audit are mandatory). No pool, query runner, or
+ * repository is ever handed to feature scope — that is the physical wall.
+ */
+export interface RecordEngine {
+    create(typeKey: string, input: RecordInput, actor: Principal): Promise<RecordId>;
+    update(typeKey: string, id: RecordId, input: RecordInput, actor: Principal): Promise<void>;
+    delete(typeKey: string, id: RecordId, actor: Principal): Promise<void>;
+    get(typeKey: string, id: RecordId, actor: Principal): Promise<RecordView | null>;
+    list(typeKey: string, query: ListQuery, actor: Principal): Promise<RecordPage>;
+}
+export type { Principal };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}