@stonyx/orm 0.3.2-alpha.7 → 0.3.2-alpha.71

package/config/environment.js

@@ -33,6 +33,9 @@ const {
   TIMESCALE_DATABASE,
   TIMESCALE_CONNECTION_LIMIT,
   TIMESCALE_MIGRATIONS_DIR,
+  DYNAMODB_REGION,
+  DYNAMODB_ENDPOINT,
+  DYNAMODB_TABLE_PREFIX,
 } = process.env;
 
 export default {
@@ -84,6 +87,11 @@ export default {
     migrationsDir: TIMESCALE_MIGRATIONS_DIR ?? 'migrations',
     migrationsTable: '__migrations',
   } : undefined,
+  dynamodb: DYNAMODB_REGION ? {
+    region: DYNAMODB_REGION,
+    endpoint: DYNAMODB_ENDPOINT || undefined,
+    tablePrefix: DYNAMODB_TABLE_PREFIX || '',
+  } : undefined,
   restServer: {
     enabled: ORM_USE_REST_SERVER ?? 'true', // Whether to load restServer for automatic route setup or
     route: ORM_REST_ROUTE ?? '/',

package/dist/access-verdict.d.ts

@@ -0,0 +1,59 @@
+import type { AccessMethod, AccessOperation, LinkageFilter } from './types/orm-types.js';
+/**
+ * The classified reading of one `access()` return value.
+ *
+ * `granted: false` is a total denial. `granted: true` with no `filter` is an
+ * unconditional grant. `granted: true` WITH a filter means "grant, subject to
+ * this per-record predicate" -- the function return shape, which is the
+ * per-record hook `AccessContext` deliberately does not provide.
+ */
+export interface AccessVerdict {
+    granted: boolean;
+    filter?: (record: unknown) => boolean;
+}
+/**
+ * Classify one `access()` return value. Extracted verbatim from `auth()`, which
+ * now calls this; the branch ORDER is load-bearing and is preserved exactly.
+ *
+ * `operation` is the verb being authorised. `undefined` -- reachable, because
+ * express delivers HEAD to the GET handler and `methodAccessMap` has no entry
+ * for it -- falls through `permitted.includes(undefined)` to a denial, which is
+ * the same answer `auth()` gave before the extraction.
+ */
+export declare function interpretAccess(access: AccessMethod, operation: AccessOperation | undefined): AccessVerdict;
+/**
+ * Build a request-scoped linkage filter.
+ *
+ * TWO CACHES, AND BOTH ARE LOAD-BEARING RATHER THAN AN OPTIMISATION:
+ *
+ *   - one verdict per TYPE. Resolving means CALLING the consumer's `access()`,
+ *     which is arbitrary code with arbitrary cost and which the module has
+ *     already had to guard for throwing.
+ *   - one decision per `(type, id)`. `included` is deduplicated by
+ *     `buildResponse`; LINKAGE is not deduplicated at all, so it re-asks once
+ *     per record. Measured on a bare `GET /animals` with no `include=`:
+ *     48 linkage entries -> 7 distinct `(type, id)` pairs (owner 20, trait 28),
+ *     a 6.9x reduction and 41 predicate calls saved.
+ *
+ * The `(type, id)` cache is a `Map` per type keyed on the RAW id, not on a
+ * template-string composite. `Map` compares with SameValueZero, so the numeric
+ * id `1` and the string id `'1'` stay DISTINCT, where `` `${type}:${id}` `` --
+ * or a bare `String(id)` -- collapses them onto one entry and answers the second
+ * record with the first record's verdict.
+ *
+ * WHAT THAT DOES AND DOES NOT PROTECT. It cannot cross MODELS. `decisions` is
+ * already partitioned per type by `byType`, so a composite key inside a per-type
+ * map is one-to-one with the raw one and no owner's verdict could ever answer
+ * for an animal -- the claim that once stood here. The real exposure is narrower
+ * and entirely WITHIN one model: two records of the same type whose ids differ
+ * only by JavaScript type, which a per-record predicate may legitimately answer
+ * differently about (an id read off a JSON body is a string; the same id
+ * assigned by the server is a number). Pinned by unit assertion, because this
+ * fixture cannot produce the collision on its own -- `owner` ids are strings and
+ * `animal` ids are numbers.
+ *
+ * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
+ * it -- a verdict cached across requests would answer a second caller with the
+ * first caller's authorization.
+ */
+export declare function createLinkageFilter(request: unknown): LinkageFilter;

package/dist/access-verdict.js

@@ -0,0 +1,222 @@
+/**
+ * The shared access-verdict primitive (abofs/stonyx-orm#234).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS: ONE INTERPRETER, NOT TWO
+ * ---------------------------------------------------------------------------
+ * A consumer `access()` may return six differently-shaped things -- `false`, a
+ * bare permission string, a permission array, `true`, a per-record function, or
+ * something the contract does not define at all -- and the reading of each one
+ * is a security decision. `auth()` has held that reading inline since #190.
+ * Every surface that needs to ask "may this caller see model X's record?" needs
+ * the SAME reading, or the second copy becomes an unreviewed second
+ * authorization vocabulary that answers differently about the same value.
+ *
+ * So `interpretAccess` is extracted here and `auth()` now calls it. It is the
+ * only place a return shape is classified, and abofs/stonyx-orm#232 and #233
+ * rebase onto it rather than re-deriving it.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT A LINKAGE FILTER IS, AND WHY THE CALLER BUILDS IT
+ * ---------------------------------------------------------------------------
+ * `Record.toJSON()` APPLIES a verdict; it never RESOLVES one. That is not a
+ * style choice, it is forced, and it was measured before it was decided:
+ *
+ *   INPUT: origin/dev @ c5f7907, unpatched                  -> 967 pass / 0 fail
+ *   INPUT: same + fail-closed resolution INSIDE toJSON()    -> 964 pass / 3 fail
+ *
+ * and all three reds were over-denial of PERMITTED records, not the leak. Two
+ * independent reasons:
+ *
+ *   1. `toJSON()` has no request. The shipped, documented sample reads
+ *      `request.path` for its `/archived` sub-path rule -- the one read of
+ *      argument one the README sanctions -- and fail-closes when it is absent.
+ *      Measured against the live registry:
+ *
+ *        getAccess('owner')(undefined, { model:'owner',  operation:'read' }) -> false
+ *        getAccess('animal')(undefined,{ model:'animal', operation:'read' }) -> [Function]
+ *
+ *      Same predicate object, two models, two different degradation modes,
+ *      chosen by the consumer. Without a request there is no trustworthy
+ *      answer to get.
+ *
+ *   2. `toJSON` is also the `JSON.stringify` hook, so `JSON.stringify({data:
+ *      record})` calls `record.toJSON('data')` -- a STRING in the options slot.
+ *      An implicit caller has no syntactic place to pass anything
+ *      (abofs/stonyx-orm#230). The no-argument document must therefore stay
+ *      byte-identical to what shipped, which also rules out fail-closed by
+ *      default: `Orm.instance.accessFunctions` is `{}` in any process that
+ *      never ran `setup-rest-server` (CLI, SQL-only, unit tests), so a
+ *      fail-closed default would empty every relationship on every document in
+ *      processes that have no REST surface to protect.
+ *
+ * The caller -- which still holds the request -- resolves the predicate,
+ * interprets it here, caches the answer, and hands `toJSON()` an already-decided
+ * `(type, record) => boolean`.
+ */
+import Orm from '@stonyx/orm';
+import log from 'stonyx/log';
+const DENIED = Object.freeze({ granted: false });
+const GRANTED = Object.freeze({ granted: true });
+/**
+ * Classify one `access()` return value. Extracted verbatim from `auth()`, which
+ * now calls this; the branch ORDER is load-bearing and is preserved exactly.
+ *
+ * `operation` is the verb being authorised. `undefined` -- reachable, because
+ * express delivers HEAD to the GET handler and `methodAccessMap` has no entry
+ * for it -- falls through `permitted.includes(undefined)` to a denial, which is
+ * the same answer `auth()` gave before the extraction.
+ */
+export function interpretAccess(access, operation) {
+    if (!access)
+        return DENIED;
+    // The function return shape IS the per-record hook. Grant the request and
+    // carry the predicate; the caller applies it per record.
+    if (typeof access === 'function')
+        return { granted: true, filter: access };
+    if (access === true)
+        return GRANTED;
+    // `AccessMethod` declares `string` legal and it fell through every branch
+    // above. A bare string is ONE permission, not a grant of all four -- reading
+    // it as a full grant is what once let `return 'read'` authorise DELETE.
+    const permitted = typeof access === 'string' ? [access] : access;
+    // Anything that is not a permission array by this point -- an object, a
+    // number, a Symbol -- is a consumer mistake, and the only safe reading of a
+    // shape the contract does not define is a denial. Fail CLOSED.
+    if (!Array.isArray(permitted))
+        return DENIED;
+    if (!permitted.includes(operation))
+        return DENIED;
+    return GRANTED;
+}
+/**
+ * Resolve model `type`'s verdict for a read, against the live `request`.
+ *
+ * Fails closed on both ambiguous inputs:
+ *
+ *   - `getAccess(type)` -> `undefined`. That is NOT "this model is
+ *     unrestricted". `setup-rest-server` catches an access-class load failure,
+ *     warns, and publishes whatever PARTIAL map it had, so `undefined` covers
+ *     both "no access class claims this model" and "the class that claims it
+ *     failed to load" -- and the caller cannot tell them apart. Deny.
+ *   - the predicate THROWS. Same reading `auth()` and `isDenied` already use:
+ *     a throw is a denial, logged, never a 500 and never a grant.
+ *
+ * NOTE ON CROSS-MODEL ASKS -- READ THIS BEFORE REBASING #232 OR #233 ONTO IT.
+ * The predicate is asked about `type` while the request in hand was dispatched
+ * to a DIFFERENT model's route. This function makes another model's class
+ * REACHABLE and asks it the model-correct question (`{ model: type }`); whether
+ * the ANSWER is model-correct is the CONSUMER's, because only a predicate that
+ * READS `context.model` can give one. Since #222 this repo's fixture does. A
+ * consumer's arity-1 predicate does not, and there is no supported way to tell
+ * which kind was resolved (the boot-time arity warning is
+ * abofs/stonyx-orm#213/#221, unshipped).
+ *
+ * BOTH DEGRADATION DIRECTIONS ARE REACHABLE, AND THE SECOND ONE GRANTS. This is
+ * measured, not reasoned:
+ *
+ *   - CLOSED. The migrated fixture's surviving `request.path` read means asking
+ *     the OWNER predicate on a request dispatched to `GET /animals/archived`
+ *     returns a bare `false` -- a whole-request deny bleeding across models,
+ *     treated here as "deny this linkage", not as an error. That over-denies a
+ *     PERMITTED record.
+ *   - OPEN. An arity-1 predicate -- the shape `setup-rest-server.ts:15-18`
+ *     still declares valid and the README calls the default in every consumer
+ *     tree -- identifies its collection from the request, so asked about
+ *     `owner` on a request dispatched to `/animals` it answers about ANIMALS.
+ *     Measured against this repo's own fixture with `reg.owner` replaced by an
+ *     arity-1 predicate that hides angela on `/owners`:
+ *
+ *       GET /owners     -> ["gina","michael","bob"]   angela hidden, correctly
+ *       GET /animals    -> owners named: [angela, ...]              LEAK
+ *       GET /animals/1  -> owner.data {"type":"owner","id":"angela"}
+ *
+ *     That is byte-for-byte the abofs/stonyx-orm#234 defect, on the surface
+ *     #234 was filed for, AFTER this fix. It is not a regression -- dev
+ *     published the same id unconditionally -- and this file cannot close it,
+ *     because the arity signal is #213/#221. Do NOT write, here or anywhere
+ *     else, that the cross-model ask degrades closed. The standing rule this
+ *     paragraph is held to is in docs/project-structure.md.
+ */
+function resolveVerdict(request, type) {
+    const predicate = Orm.instance?.getAccess?.(type);
+    if (typeof predicate !== 'function')
+        return DENIED;
+    let access;
+    try {
+        access = predicate(request, { model: type, operation: 'read' });
+    }
+    catch (error) {
+        log.error?.(`[@stonyx/orm] access() threw while resolving linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
+        return DENIED;
+    }
+    return interpretAccess(access, 'read');
+}
+/**
+ * Build a request-scoped linkage filter.
+ *
+ * TWO CACHES, AND BOTH ARE LOAD-BEARING RATHER THAN AN OPTIMISATION:
+ *
+ *   - one verdict per TYPE. Resolving means CALLING the consumer's `access()`,
+ *     which is arbitrary code with arbitrary cost and which the module has
+ *     already had to guard for throwing.
+ *   - one decision per `(type, id)`. `included` is deduplicated by
+ *     `buildResponse`; LINKAGE is not deduplicated at all, so it re-asks once
+ *     per record. Measured on a bare `GET /animals` with no `include=`:
+ *     48 linkage entries -> 7 distinct `(type, id)` pairs (owner 20, trait 28),
+ *     a 6.9x reduction and 41 predicate calls saved.
+ *
+ * The `(type, id)` cache is a `Map` per type keyed on the RAW id, not on a
+ * template-string composite. `Map` compares with SameValueZero, so the numeric
+ * id `1` and the string id `'1'` stay DISTINCT, where `` `${type}:${id}` `` --
+ * or a bare `String(id)` -- collapses them onto one entry and answers the second
+ * record with the first record's verdict.
+ *
+ * WHAT THAT DOES AND DOES NOT PROTECT. It cannot cross MODELS. `decisions` is
+ * already partitioned per type by `byType`, so a composite key inside a per-type
+ * map is one-to-one with the raw one and no owner's verdict could ever answer
+ * for an animal -- the claim that once stood here. The real exposure is narrower
+ * and entirely WITHIN one model: two records of the same type whose ids differ
+ * only by JavaScript type, which a per-record predicate may legitimately answer
+ * differently about (an id read off a JSON body is a string; the same id
+ * assigned by the server is a number). Pinned by unit assertion, because this
+ * fixture cannot produce the collision on its own -- `owner` ids are strings and
+ * `animal` ids are numbers.
+ *
+ * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
+ * it -- a verdict cached across requests would answer a second caller with the
+ * first caller's authorization.
+ */
+export function createLinkageFilter(request) {
+    const byType = new Map();
+    return function isLinkable(type, record) {
+        let entry = byType.get(type);
+        if (!entry) {
+            entry = { verdict: resolveVerdict(request, type), decisions: new Map() };
+            byType.set(type, entry);
+        }
+        const { verdict, decisions } = entry;
+        if (!verdict.granted)
+            return false;
+        if (!verdict.filter)
+            return true;
+        const id = record?.id;
+        const cached = decisions.get(id);
+        if (cached !== undefined)
+            return cached;
+        let allowed;
+        try {
+            allowed = Boolean(verdict.filter(record));
+        }
+        catch (error) {
+            // A predicate that throws is a denial -- the same reading `isDenied` uses
+            // one layer down. Logged, because a predicate that throws on every record
+            // empties every relationship and, silently, that is indistinguishable
+            // from a database with no relationships in it.
+            log.error?.(`[@stonyx/orm] access filter threw while filtering linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
+            allowed = false;
+        }
+        decisions.set(id, allowed);
+        return allowed;
+    };
+}

package/dist/commands.js

@@ -20,6 +20,11 @@ const commands = {
         description: 'Generate a MySQL migration from current model schemas',
         bootstrap: true,
         run: async (args) => {
+            const config = (await import('stonyx/config')).default;
+            if (config.orm.dynamodb) {
+                console.log('DynamoDB does not use file-based migrations. Use db:sync to provision tables.');
+                return;
+            }
             const description = args?.join(' ') || 'migration';
             const { generateMigration } = await import('./mysql/migration-generator.js');
             const result = await generateMigration(description);
@@ -31,12 +36,33 @@ const commands = {
             }
         }
     },
+    'db:sync': {
+        description: 'Provision DynamoDB tables and GSIs from current model schemas',
+        bootstrap: true,
+        run: async () => {
+            const config = (await import('stonyx/config')).default;
+            if (!config.orm.dynamodb) {
+                console.error('DynamoDB is not configured. Set DYNAMODB_REGION (and optionally DYNAMODB_ENDPOINT) to enable DynamoDB mode.');
+                process.exit(1);
+            }
+            const { default: DynamoDBDB } = await import('./dynamodb/dynamodb-db.js');
+            const db = new DynamoDBDB();
+            await db.init();
+            await db.startup();
+            await db.shutdown();
+            console.log('DynamoDB tables synced successfully.');
+        }
+    },
     'db:migrate': {
         description: 'Apply pending MySQL migrations',
         bootstrap: true,
         run: async () => {
             const config = (await import('stonyx/config')).default;
             const mysqlConfig = config.orm.mysql;
+            if (config.orm.dynamodb) {
+                console.log('DynamoDB does not use file-based migrations. Use db:sync to provision tables.');
+                return;
+            }
             if (!mysqlConfig) {
                 console.error('MySQL is not configured. Set MYSQL_HOST to enable MySQL mode.');
                 process.exit(1);
@@ -75,6 +101,10 @@ const commands = {
         bootstrap: true,
         run: async () => {
             const config = (await import('stonyx/config')).default;
+            if (config.orm.dynamodb) {
+                console.log('DynamoDB does not support migration rollback. Manage table changes via the AWS console or db:sync.');
+                return;
+            }
             const mysqlConfig = config.orm.mysql;
             if (!mysqlConfig) {
                 console.error('MySQL is not configured. Set MYSQL_HOST to enable MySQL mode.');
@@ -113,6 +143,10 @@ const commands = {
         bootstrap: true,
         run: async () => {
             const config = (await import('stonyx/config')).default;
+            if (config.orm.dynamodb) {
+                console.log('DynamoDB does not use file-based migrations. Use db:sync to provision tables.');
+                return;
+            }
             const mysqlConfig = config.orm.mysql;
             if (!mysqlConfig) {
                 console.error('MySQL is not configured. Set MYSQL_HOST to enable MySQL mode.');

package/dist/dynamodb/connection.d.ts

@@ -0,0 +1,31 @@
+/**
+ * DynamoDB connection factory.
+ *
+ * Dynamically imports @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb
+ * so these are optional peerDependencies (matching the pg/mysql2 pattern).
+ */
+export interface DynamoDBConfig {
+    region?: string;
+    endpoint?: string;
+    tablePrefix?: string;
+    [key: string]: unknown;
+}
+export type DocumentClient = {
+    send(command: unknown): Promise<unknown>;
+};
+export type DynamoDBClientConstructor = new (options: unknown) => {
+    config: unknown;
+};
+export type DocumentClientFromFn = {
+    from(client: unknown): DocumentClient;
+};
+/**
+ * Create a DynamoDBDocumentClient from the given config.
+ * Uses dynamic import so @aws-sdk/* are optional peer deps.
+ */
+export declare function createDocumentClient(dbConfig: DynamoDBConfig): Promise<DocumentClient>;
+/**
+ * Nullify the document client reference (DynamoDB connections are HTTP-based
+ * and stateless — no explicit pool close needed, but we clear the reference).
+ */
+export declare function destroyDocumentClient(_client: DocumentClient | null): null;

package/dist/dynamodb/connection.js

@@ -0,0 +1,28 @@
+/**
+ * DynamoDB connection factory.
+ *
+ * Dynamically imports @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb
+ * so these are optional peerDependencies (matching the pg/mysql2 pattern).
+ */
+/**
+ * Create a DynamoDBDocumentClient from the given config.
+ * Uses dynamic import so @aws-sdk/* are optional peer deps.
+ */
+export async function createDocumentClient(dbConfig) {
+    const { DynamoDBClient } = await import('@aws-sdk/client-dynamodb');
+    const { DynamoDBDocumentClient } = await import('@aws-sdk/lib-dynamodb');
+    const clientOptions = {};
+    if (dbConfig.region)
+        clientOptions.region = dbConfig.region;
+    if (dbConfig.endpoint)
+        clientOptions.endpoint = dbConfig.endpoint;
+    const rawClient = new DynamoDBClient(clientOptions);
+    return DynamoDBDocumentClient.from(rawClient);
+}
+/**
+ * Nullify the document client reference (DynamoDB connections are HTTP-based
+ * and stateless — no explicit pool close needed, but we clear the reference).
+ */
+export function destroyDocumentClient(_client) {
+    return null;
+}

package/dist/dynamodb/dynamodb-db.d.ts

@@ -0,0 +1,142 @@
+/**
+ * DynamoDB driver implementing the SqlDb PAL contract.
+ *
+ * Drop-in replacement for PostgresDB / MysqlDB — zero ORM core changes.
+ * Selected via config.orm.dynamodb.
+ */
+import { createDocumentClient, destroyDocumentClient } from './connection.js';
+import type { DocumentClient, DynamoDBConfig } from './connection.js';
+import { buildPutItem, buildGetItem, buildUpdateItem, buildDeleteItem, buildScan, buildQuery } from './operation-builder.js';
+import { introspectModels, getTopologicalOrder } from '../postgres/schema-introspector.js';
+import { getDynamoKeyType } from './type-map.js';
+import { store } from '@stonyx/orm';
+import { createRecord } from '../manage-record.js';
+import { getPluralName } from '../plural-registry.js';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import type { OrmRecord } from '../types/orm-types.js';
+/**
+ * Load the DynamoDB DocumentClient command constructors via dynamic import.
+ * Returns a frozen object so it can be cached in deps.
+ */
+export declare function loadDocClientCommands(): Promise<{
+    PutCommand: new (params: unknown) => unknown;
+    GetCommand: new (params: unknown) => unknown;
+    UpdateCommand: new (params: unknown) => unknown;
+    DeleteCommand: new (params: unknown) => unknown;
+    ScanCommand: new (params: unknown) => unknown;
+    QueryCommand: new (params: unknown) => unknown;
+}>;
+export declare function loadTableCommands(): Promise<{
+    DynamoDBClient: new (opts: unknown) => {
+        send(cmd: unknown): Promise<unknown>;
+    };
+    DescribeTableCommand: new (params: unknown) => unknown;
+    CreateTableCommand: new (params: unknown) => unknown;
+    UpdateTableCommand: new (params: unknown) => unknown;
+}>;
+interface PersistContext {
+    record?: OrmRecord;
+    recordId?: unknown;
+    oldState?: Record<string, unknown>;
+    rawData?: Record<string, unknown>;
+}
+interface PersistResponse {
+    data?: {
+        id?: unknown;
+    };
+}
+/** Minimal Orm module shape needed at runtime — avoids circular import at top-level. */
+interface OrmModule {
+    default: {
+        instance: {
+            getRecordClasses(name: string): {
+                modelClass: {
+                    memory?: boolean;
+                };
+            };
+            isView?(name: string): boolean;
+        };
+    };
+}
+export interface DynamoDBDeps {
+    createDocumentClient: typeof createDocumentClient;
+    destroyDocumentClient: typeof destroyDocumentClient;
+    loadDocClientCommands: typeof loadDocClientCommands;
+    loadTableCommands: typeof loadTableCommands;
+    buildPutItem: typeof buildPutItem;
+    buildGetItem: typeof buildGetItem;
+    buildUpdateItem: typeof buildUpdateItem;
+    buildDeleteItem: typeof buildDeleteItem;
+    buildScan: typeof buildScan;
+    buildQuery: typeof buildQuery;
+    introspectModels: typeof introspectModels;
+    getTopologicalOrder: typeof getTopologicalOrder;
+    getDynamoKeyType: typeof getDynamoKeyType;
+    createRecord: typeof createRecord;
+    store: typeof store;
+    getPluralName: typeof getPluralName;
+    config: typeof config;
+    log: typeof log;
+    /** Injected for testing — import('@stonyx/orm') replacement */
+    _importOrm?: () => Promise<OrmModule>;
+    [key: string]: unknown;
+}
+export default class DynamoDBDB {
+    static instance: DynamoDBDB | undefined;
+    deps: DynamoDBDeps;
+    client: DocumentClient | null;
+    dbConfig: DynamoDBConfig;
+    /** GSI registry built during init from model introspection. */
+    private _gsiRegistry;
+    constructor(deps?: Partial<DynamoDBDeps>);
+    private requireClient;
+    private _resolveTableName;
+    /** Resolve Orm singleton — falls back to real import in production. */
+    private _getOrm;
+    init(): Promise<void>;
+    /**
+     * For each model, DescribeTable — CreateTable if missing (with GSIs, PAY_PER_REQUEST).
+     * For existing tables, check for missing GSIs and UpdateTable + poll for ACTIVE.
+     */
+    startup(): Promise<void>;
+    shutdown(): Promise<void>;
+    /**
+     * DynamoDB does NOT use write serialization (#156).
+     *
+     * Unlike MySQL/PostgreSQL, DynamoDB has no server-side foreign key
+     * constraints and no multi-row transactions in standard single-item
+     * operations (PutItem, UpdateItem, DeleteItem). Each operation is
+     * atomic at the item level and cannot deadlock against other items.
+     * Concurrent fire-and-forget writes therefore cannot produce the
+     * cross-row lock contention that causes InnoDB/PG deadlocks.
+     */
+    persist(operation: string, modelName: string, context: PersistContext, response: PersistResponse): Promise<void>;
+    findRecord(modelName: string, id: unknown): Promise<OrmRecord | undefined>;
+    findAll(modelName: string, conditions?: Record<string, unknown>): Promise<OrmRecord[]>;
+    loadMemoryRecords(): Promise<void>;
+    private _persistCreate;
+    private _persistUpdate;
+    private _persistDelete;
+    private _paginatedScan;
+    private _paginatedQuery;
+    /**
+     * Build the GSI registry from model introspection.
+     * Registry: modelName → attrName → gsiName
+     *
+     * FK columns (belonging to belongsTo relationships) get a GSI automatically.
+     */
+    private _buildGsiRegistry;
+    /**
+     * Find a GSI that can serve the given conditions.
+     */
+    private _findGsiMatch;
+    private _buildAttributeDefinitions;
+    private _buildGsiDefinitions;
+    private _waitForTableActive;
+    private _itemToRawData;
+    private _recordToItem;
+    private _evictIfNotMemory;
+    loadAllRecords(): Promise<void>;
+}
+export {};