dynalitics 0.0.0-stage → 0.1.0

package/dist/dialect/types.d.ts

@@ -0,0 +1,79 @@
+import type { Interval } from '../protocol.js';
+import type { TableRef } from '../model/identifiers.js';
+import type { ColumnDef, ColumnModel, Dialect, SqlValue } from '../model/types.js';
+export interface CompiledQuery {
+    readonly sql: string;
+    readonly params: readonly SqlValue[];
+}
+export type Row = Readonly<Record<string, unknown>>;
+/** Normalised catalog row, identical across dialects. */
+export interface ColumnInfo {
+    readonly name: string;
+    readonly dataType: string;
+    readonly maxLength: number | null;
+    readonly nullable: boolean;
+    readonly hasDefault: boolean;
+    readonly generated: boolean;
+    readonly precision: number | null;
+    readonly tableType: string;
+    /** The schema (database for MySQL) the catalog found the table in; used to qualify names from then on. */
+    readonly schema?: string;
+}
+export interface GrantOptions {
+    readonly table: TableRef;
+    readonly writerRole: string;
+    readonly readerRole: string;
+    /** Column-level SELECT for the writer, only needed for write-time first-visit detection. */
+    readonly writerSelectColumns?: readonly string[];
+}
+/** SQL fragments used by the read API. Inputs that are not column names are validated before use. */
+export interface ReadSyntax {
+    /** UTC start of the bucket as ISO text, e.g. 2026-10-25T00:00:00.000Z. Weeks start on Monday, independent of session settings. */
+    bucket(col: string, interval: Interval): string;
+    /** An exact instant as ISO text (ms precision, UTC). */
+    tsText(col: string): string;
+    isTrue(col: string): string;
+    /** True only for a non-NULL false value. */
+    isFalse(col: string): string;
+    /** Text value of a JSON key. `key` must match the custom key pattern; it comes from host config, never from a request. */
+    jsonKey(col: string, key: string): string;
+    castText(col: string, kind: 'string' | 'integer' | 'number' | 'boolean'): string;
+    /** A JSON key as a number, NULL when the stored value is not numeric (explorer number filters, spec 18.2). */
+    jsonNumber(col: string, key: string): string;
+    /** Row count that cannot overflow: COUNT_BIG(*) on SQL Server (COUNT is a 32-bit int there). */
+    readonly count: string;
+    /** `TOP n ` for SQL Server, '' otherwise. n must be a positive integer. */
+    top(n: number): string;
+    /** ` LIMIT n` for PostgreSQL and MySQL, '' for SQL Server. */
+    limit(n: number): string;
+}
+/** Pure SQL text generation. No driver imports, no I/O. */
+export interface SqlDialect {
+    readonly name: Dialect;
+    readonly limits: {
+        readonly maxParams: number;
+        readonly maxRowsPerInsert: number;
+        readonly maxIdentifier: number;
+    };
+    quoteIdent(name: string): string;
+    qualifiedTable(table: TableRef): string;
+    placeholder(index: number): string;
+    columnType(c: ColumnDef): string;
+    timestampParam(d: Date): string;
+    buildInsert(model: ColumnModel, rows: readonly (readonly SqlValue[])[]): CompiledQuery;
+    firstVisitLookup(model: ColumnModel, kind: 'u' | 'i', values: readonly string[]): CompiledQuery;
+    introspectSql(table: TableRef): CompiledQuery;
+    mapColumnRow(row: Row): ColumnInfo;
+    privilegeSql(table: TableRef): readonly CompiledQuery[];
+    parsePrivileges(results: readonly (readonly Row[])[], table: TableRef): ReadonlySet<string>;
+    createTableSql(model: ColumnModel): string;
+    createIndexSql(model: ColumnModel): readonly string[];
+    grantSql(opts: GrantOptions): readonly string[];
+    addColumnSql(table: TableRef, c: ColumnDef): string;
+    dropNotNullSql(table: TableRef, c: ColumnDef): string;
+    alterTypeSql(table: TableRef, c: ColumnDef): string;
+    readonly read: ReadSyntax;
+    /** Renders a role/user for GRANT: placeholders pass through, real names are validated and quoted. */
+    renderRole(role: string): string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/dialect/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/driver/types.d.ts

@@ -0,0 +1,74 @@
+import { DynaliticsError, type SafeCause } from '../errors.js';
+import type { CompiledQuery, Row } from '../dialect/types.js';
+import type { Redactor } from '../redact.js';
+import type { Dialect } from '../model/types.js';
+import type { Credential } from '../types.js';
+import type { ADAPTER_API_VERSION } from '../adapter-version.js';
+export interface DriverOptions {
+    readonly credential: Credential;
+    /** Pool size for pools dynalitics creates. */
+    readonly max: number;
+    readonly connectTimeoutMs: number;
+    readonly redact: Redactor;
+    /** Default request timeout for pools dynalitics creates. */
+    readonly requestTimeoutMs?: number;
+}
+/** Runtime part of an adapter: a thin wrapper around a pool. All SQL text comes from the dialect. */
+export interface Driver {
+    query(q: CompiledQuery, opts: {
+        timeoutMs: number;
+    }): Promise<readonly Row[]>;
+    isTransient(err: unknown): boolean;
+    /** No-op when the pool belongs to the host. */
+    close(): Promise<void>;
+}
+/**
+ * What an adapter package (dynalitics-postgres, -mysql, -mssql) exports. The only code that imports a driver.
+ */
+export interface DriverAdapter {
+    readonly apiVersion: typeof ADAPTER_API_VERSION;
+    readonly dialect: Dialect;
+    /** e.g. 'dynalitics-postgres'; shown in errors only. */
+    readonly packageName: string;
+    /** Called once per credential. Must build every error with toDriverError and never close a host pool. */
+    createDriver(options: DriverOptions): Promise<Driver>;
+}
+/** Cross-copy brand: an adapter that resolved a second copy of dynalitics still produces recognisable errors. */
+declare const DRIVER_ERROR_BRAND: unique symbol;
+/** The only error type drivers throw: redacted message, sanitised cause, never the raw driver error. */
+export declare class DriverError extends DynaliticsError {
+    readonly [DRIVER_ERROR_BRAND] = true;
+    readonly transient: boolean;
+    readonly timeout: boolean;
+    /** A data or constraint error caused by ONE row's values (as opposed to one that would fail every row). */
+    readonly data: boolean;
+    /** The database user lacks a privilege (batch-wide: retrying row by row cannot help). */
+    readonly permission: boolean;
+    constructor(safeCause: SafeCause, transient: boolean, timeout: boolean, data?: boolean, permission?: boolean);
+}
+export interface Classification {
+    readonly transient: boolean;
+    readonly timeout: boolean;
+    /** Data/constraint error: its message may contain the offending visitor value, so it is never forwarded. */
+    readonly data?: boolean;
+    readonly permission?: boolean;
+    /** Connection, authentication and network classes: the (redacted, scrubbed) message is forwarded. */
+    readonly forward?: boolean;
+}
+/** Drops quoted literals and parenthesised values (where databases print offending values) and caps the length. */
+export declare function scrubMessage(message: string): string;
+/**
+ * Message policy (F-02): data/constraint errors forward no text (it can contain the offending value), permission
+ * errors a fixed sentence, connection/auth/network/timeout classes their redacted and scrubbed message, and every
+ * other class only its name and code.
+ */
+export declare function toDriverError(err: unknown, redact: Redactor, classify: (err: unknown) => Classification): DriverError;
+/** `instanceof DriverError`, also true for a DriverError built by another copy of this package (spec v0.5, A5). */
+export declare function isDriverError(err: unknown): err is DriverError;
+export declare const isTransientError: (err: unknown) => boolean;
+export declare const errCode: (err: unknown) => string;
+export declare const errMessage: (err: unknown) => string;
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+export declare const IDLE_TIMEOUT_MS = 30000;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/driver/types.js

@@ -0,0 +1,66 @@
+import { DynaliticsError } from '../errors.js';
+import { sanitizeError } from '../redact.js';
+/** Cross-copy brand: an adapter that resolved a second copy of dynalitics still produces recognisable errors. */
+const DRIVER_ERROR_BRAND = Symbol.for('dynalitics.DriverError');
+/** The only error type drivers throw: redacted message, sanitised cause, never the raw driver error. */
+export class DriverError extends DynaliticsError {
+    [DRIVER_ERROR_BRAND] = true;
+    transient;
+    timeout;
+    /** A data or constraint error caused by ONE row's values (as opposed to one that would fail every row). */
+    data;
+    /** The database user lacks a privilege (batch-wide: retrying row by row cannot help). */
+    permission;
+    constructor(safeCause, transient, timeout, data = false, permission = false) {
+        super('DYNALITICS_DRIVER', safeCause.message, safeCause);
+        this.transient = transient;
+        this.timeout = timeout;
+        this.data = data;
+        this.permission = permission;
+    }
+}
+const MAX_MESSAGE = 300;
+const QUOTED = /'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|\([^()]*\)/g;
+/** Drops quoted literals and parenthesised values (where databases print offending values) and caps the length. */
+export function scrubMessage(message) {
+    return message
+        .replace(QUOTED, (m) => (m.startsWith('(') ? '(…)' : m.startsWith('"') ? '"…"' : "'…'"))
+        .slice(0, MAX_MESSAGE);
+}
+/**
+ * Message policy (F-02): data/constraint errors forward no text (it can contain the offending value), permission
+ * errors a fixed sentence, connection/auth/network/timeout classes their redacted and scrubbed message, and every
+ * other class only its name and code.
+ */
+export function toDriverError(err, redact, classify) {
+    const { transient, timeout, data = false, permission = false, forward = false } = classify(err);
+    const base = sanitizeError(err, redact);
+    const withCode = base.code === undefined ? '' : ` (${base.code})`;
+    const head = { name: base.name, ...(base.code === undefined ? {} : { code: base.code }) };
+    let message;
+    if (data)
+        message = `data or constraint error${withCode}; the offending value is not shown`;
+    else if (permission)
+        message = 'permission denied; the database user lacks a required privilege';
+    else if (forward || timeout || transient)
+        message = scrubMessage(base.message);
+    else
+        message = `database error${withCode}; details are not forwarded`;
+    return new DriverError({ ...head, message }, transient, timeout, data, permission);
+}
+/** `instanceof DriverError`, also true for a DriverError built by another copy of this package (spec v0.5, A5). */
+export function isDriverError(err) {
+    return (err instanceof DriverError ||
+        (typeof err === 'object' &&
+            err !== null &&
+            err[DRIVER_ERROR_BRAND] === true));
+}
+export const isTransientError = (err) => isDriverError(err) && err.transient;
+export const errCode = (err) => {
+    const code = err?.code;
+    return typeof code === 'string' || typeof code === 'number' ? String(code) : '';
+};
+export const errMessage = (err) => (err instanceof Error ? err.message : String(err)).toLowerCase();
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+export const IDLE_TIMEOUT_MS = 30_000;
+//# sourceMappingURL=types.js.map

package/dist/errors.d.ts

@@ -0,0 +1,39 @@
+/** Sanitised copy of a lower-level error. The raw error is never attached to ours (it may carry credentials). */
+export interface SafeCause {
+    readonly name: string;
+    readonly code?: string;
+    readonly message: string;
+}
+export declare class DynaliticsError extends Error {
+    readonly code: string;
+    readonly safeCause: SafeCause | undefined;
+    constructor(code: string, message: string, safeCause?: SafeCause);
+}
+/** Thrown synchronously for invalid configuration. Lists every issue found. */
+export declare class DynaliticsConfigError extends DynaliticsError {
+    readonly issues: readonly string[];
+    constructor(issues: readonly string[]);
+}
+/** Thrown when a database cannot be reached or a driver is missing. Message is already redacted. */
+export declare class DynaliticsConnectionError extends DynaliticsError {
+    constructor(message: string, safeCause?: SafeCause);
+}
+export type SchemaProblemCode = 'missing_table' | 'not_a_table' | 'missing_column' | 'type_mismatch' | 'too_short' | 'not_nullable' | 'extra_required_column' | 'timestamp_session_timezone' | 'identity_not_discoverable';
+export interface SchemaProblem {
+    readonly code: SchemaProblemCode;
+    readonly message: string;
+    readonly column?: string;
+}
+export interface SchemaWarning {
+    readonly code: string;
+    readonly message: string;
+    readonly column?: string;
+}
+/** Thrown at startup when the table does not match the column model. `fixSql` is printed text, never executed. */
+export declare class DynaliticsSchemaError extends DynaliticsError {
+    readonly problems: readonly SchemaProblem[];
+    readonly warnings: readonly SchemaWarning[];
+    readonly fixSql: string;
+    constructor(report: string, problems: readonly SchemaProblem[], warnings: readonly SchemaWarning[], fixSql: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,39 @@
+export class DynaliticsError extends Error {
+    code;
+    safeCause;
+    constructor(code, message, safeCause) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+        this.safeCause = safeCause;
+    }
+}
+/** Thrown synchronously for invalid configuration. Lists every issue found. */
+export class DynaliticsConfigError extends DynaliticsError {
+    issues;
+    constructor(issues) {
+        super('DYNALITICS_CONFIG', issues.length === 1
+            ? `Invalid dynalitics configuration: ${issues[0] ?? ''}`
+            : `Invalid dynalitics configuration (${issues.length} issues):\n${issues.map((i) => `  - ${i}`).join('\n')}`);
+        this.issues = [...issues];
+    }
+}
+/** Thrown when a database cannot be reached or a driver is missing. Message is already redacted. */
+export class DynaliticsConnectionError extends DynaliticsError {
+    constructor(message, safeCause) {
+        super('DYNALITICS_CONNECTION', message, safeCause);
+    }
+}
+/** Thrown at startup when the table does not match the column model. `fixSql` is printed text, never executed. */
+export class DynaliticsSchemaError extends DynaliticsError {
+    problems;
+    warnings;
+    fixSql;
+    constructor(report, problems, warnings, fixSql) {
+        super('DYNALITICS_SCHEMA', report);
+        this.problems = [...problems];
+        this.warnings = [...warnings];
+        this.fixSql = fixSql;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createDynalitics } from './create.js';
+export { DynaliticsError, DynaliticsConfigError, DynaliticsConnectionError, DynaliticsSchemaError, } from './errors.js';
+export type { SchemaProblem, SchemaWarning, SafeCause } from './errors.js';
+export type { Logger } from './logger.js';
+export type { Credential, Dynalitics, DynaliticsConfig, DynaliticsStats, ErrorCode, ErrorInfo, FlushResult, TrackResult, Visit, } from './types.js';
+export type { ColumnDef, ColumnModel, CustomFieldDef, CustomValue, Dialect, IpMode, Role, SchemaConfig, } from './model/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createDynalitics } from './create.js';
+export { DynaliticsError, DynaliticsConfigError, DynaliticsConnectionError, DynaliticsSchemaError, } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/internals.d.ts

@@ -0,0 +1,20 @@
+import type { SqlDialect } from './dialect/types.js';
+import type { Driver } from './driver/types.js';
+import type { ColumnModel, IpMode } from './model/types.js';
+import type { Logger } from './logger.js';
+import type { Redactor } from './redact.js';
+import type { Dynalitics, ErrorInfo } from './types.js';
+/** What the read handler needs from a Dynalitics instance. Not part of the public API. */
+export interface Internals {
+    readonly reader: Driver | undefined;
+    readonly dialect: SqlDialect;
+    readonly model: ColumnModel;
+    readonly ipMode: IpMode;
+    readonly redact: Redactor;
+    readonly report: (info: ErrorInfo) => void;
+    readonly logger: Logger;
+    readonly now: () => Date;
+}
+export declare function registerInternals(dyn: Dynalitics, internals: Internals): void;
+export declare function getInternals(dyn: Dynalitics): Internals | undefined;
+//# sourceMappingURL=internals.d.ts.map

package/dist/internals.js

@@ -0,0 +1,8 @@
+const registry = new WeakMap();
+export function registerInternals(dyn, internals) {
+    registry.set(dyn, internals);
+}
+export function getInternals(dyn) {
+    return registry.get(dyn);
+}
+//# sourceMappingURL=internals.js.map

package/dist/logger.d.ts

@@ -0,0 +1,10 @@
+import type { Redactor } from './redact.js';
+export interface Logger {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+export declare const consoleLogger: Logger;
+/** Redacts every message and swallows logger exceptions, so logging can never leak a secret or break the host. */
+export declare function safeLogger(inner: Logger, redact: Redactor): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.js

@@ -0,0 +1,24 @@
+/* eslint-disable no-console -- the default logger is the one place that writes to the console */
+export const consoleLogger = {
+    info: (msg) => console.info(`[dynalitics] ${msg}`),
+    warn: (msg) => console.warn(`[dynalitics] ${msg}`),
+    error: (msg) => console.error(`[dynalitics] ${msg}`),
+};
+/* eslint-enable no-console */
+/** Redacts every message and swallows logger exceptions, so logging can never leak a secret or break the host. */
+export function safeLogger(inner, redact) {
+    const wrap = (fn) => (msg) => {
+        try {
+            fn(redact(msg));
+        }
+        catch {
+            // a broken logger must not break tracking
+        }
+    };
+    return {
+        info: wrap((m) => inner.info(m)),
+        warn: wrap((m) => inner.warn(m)),
+        error: wrap((m) => inner.error(m)),
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/model/column-model.d.ts

@@ -0,0 +1,7 @@
+import type { ColumnModel, SchemaConfig } from './types.js';
+/**
+ * Pure and deterministic: the single source of truth that the generator, row builder, startup validator
+ * and (later) the read queries all consume. Never mutates its input. Throws DynaliticsConfigError listing all issues.
+ */
+export declare function buildColumnModel(schema: SchemaConfig): ColumnModel;
+//# sourceMappingURL=column-model.d.ts.map

package/dist/model/column-model.js

@@ -0,0 +1,240 @@
+import { DynaliticsConfigError } from '../errors.js';
+import { identifierMessage, isCustomKey, isIdentifier, parseTableRef } from './identifiers.js';
+import { OPTIONAL_STORED_ROLES } from './types.js';
+const DEFAULT_PAGE_LENGTH = 512;
+const MAX_PAGE_LENGTH = 700;
+const DEFAULT_CUSTOM_LENGTH = 128;
+const MAX_CUSTOM_LENGTH = 1024;
+const REQUIRED = ['timestamp', 'consent', 'pageVisited'];
+const str = (maxLength) => () => ({ kind: 'string', maxLength });
+/** Recommended-table defaults, in DDL order (spec 3.3). */
+const ROLE_SPECS = [
+    ['id', { name: 'id', type: () => ({ kind: 'id' }), nullable: false, personal: false }],
+    [
+        'timestamp',
+        { name: 'visited_at', type: () => ({ kind: 'timestamp' }), nullable: false, personal: false },
+    ],
+    [
+        'consent',
+        { name: 'consent', type: () => ({ kind: 'boolean' }), nullable: false, personal: false },
+    ],
+    [
+        'pageVisited',
+        {
+            name: 'page_visited',
+            type: (len) => ({ kind: 'string', maxLength: len }),
+            nullable: false,
+            personal: false,
+        },
+    ],
+    ['ip', { name: 'ip_address', type: str(64), nullable: true, personal: true }],
+    ['userId', { name: 'user_id', type: str(128), nullable: true, personal: true }],
+    ['username', { name: 'username', type: str(128), nullable: true, personal: true }],
+    ['email', { name: 'email', type: str(320), nullable: true, personal: true }],
+    [
+        'isFirstVisit',
+        { name: 'is_first_visit', type: () => ({ kind: 'boolean' }), nullable: true, personal: true },
+    ],
+    ['custom', { name: 'custom', type: () => ({ kind: 'json' }), nullable: true, personal: false }],
+];
+function resolveTable(schema, issues) {
+    try {
+        return parseTableRef(schema.table);
+    }
+    catch (e) {
+        issues.push(...(e instanceof DynaliticsConfigError ? e.issues : [String(e)]));
+        return { name: 'invalid' };
+    }
+}
+function resolveRoleColumns(schema, firstVisitEnabled, pageLength, issues) {
+    const overrides = schema.columns ?? {};
+    const out = [];
+    for (const [role, spec] of ROLE_SPECS) {
+        const override = overrides[role];
+        if (override === false && REQUIRED.includes(role)) {
+            issues.push(`columns.${role} is required and cannot be false (timestamp, consent and pageVisited must be stored).`);
+            continue;
+        }
+        if (role === 'isFirstVisit') {
+            if (!firstVisitEnabled) {
+                if (typeof override === 'string') {
+                    issues.push('columns.isFirstVisit is mapped but firstVisit.enabled is false. Enable write-time first-visit detection or unmap the column.');
+                }
+                continue;
+            }
+            if (override === false) {
+                issues.push('firstVisit.enabled needs columns.isFirstVisit; it cannot be false.');
+                continue;
+            }
+        }
+        if (override === false)
+            continue;
+        const name = override ?? spec.name;
+        if (!isIdentifier(name)) {
+            issues.push(identifierMessage(name, `columns.${role}`));
+            continue;
+        }
+        out.push({
+            role,
+            key: role,
+            name,
+            type: spec.type(pageLength),
+            nullable: spec.nullable,
+            personal: spec.personal,
+            dbGenerated: role === 'id',
+        });
+    }
+    return out;
+}
+const REQUIRED_MESSAGE = (role) => `columns.${role} is required when tableMode is "existing" (timestamp, consent and pageVisited must be mapped).`;
+/**
+ * tableMode "existing": `columns` is an explicit mapping. A role that is not listed (or is false) is unmapped and its
+ * data is not stored. Only the three required roles are mandatory. Physical types are checked at startup (7.2).
+ */
+function resolveExistingRoleColumns(schema, firstVisitEnabled, pageLength, issues) {
+    const overrides = schema.columns ?? {};
+    const out = [];
+    for (const [role, spec] of ROLE_SPECS) {
+        const override = overrides[role];
+        if (typeof override !== 'string') {
+            if (REQUIRED.includes(role))
+                issues.push(REQUIRED_MESSAGE(role));
+            continue;
+        }
+        if (role === 'isFirstVisit' && !firstVisitEnabled) {
+            issues.push('columns.isFirstVisit is mapped but firstVisit.enabled is false. Enable write-time first-visit detection or unmap the column.');
+            continue;
+        }
+        if (!isIdentifier(override)) {
+            issues.push(identifierMessage(override, `columns.${role}`));
+            continue;
+        }
+        out.push({
+            role,
+            key: role,
+            name: override,
+            type: spec.type(pageLength),
+            nullable: spec.nullable,
+            personal: spec.personal,
+            dbGenerated: role === 'id',
+        });
+    }
+    return out;
+}
+function promotedType(def, maxLength) {
+    return def.type === 'string' ? { kind: 'string', maxLength } : { kind: def.type };
+}
+function resolveCustomFields(schema, hasJsonColumn, issues) {
+    const fields = new Map();
+    const promoted = [];
+    for (const [key, def] of Object.entries(schema.customFields ?? {})) {
+        if (!isCustomKey(key)) {
+            issues.push(`${JSON.stringify(key)} is not a valid custom field key. Allowed: ^[A-Za-z_][A-Za-z0-9_]{0,63}$ (not __proto__, constructor or prototype).`);
+            continue;
+        }
+        const maxLength = def.maxLength ?? DEFAULT_CUSTOM_LENGTH;
+        if (!Number.isInteger(maxLength) || maxLength < 1 || maxLength > MAX_CUSTOM_LENGTH) {
+            issues.push(`customFields.${key}.maxLength must be an integer 1..${MAX_CUSTOM_LENGTH}.`);
+            continue;
+        }
+        const personal = def.personal ?? true;
+        if (def.keepWhenDenied === true && personal) {
+            issues.push(`customFields.${key}.keepWhenDenied requires personal: false (a personal field is never stored without consent).`);
+            continue;
+        }
+        if (def.breakdown === true && personal) {
+            issues.push(`customFields.${key}.breakdown requires personal: false.`);
+            continue;
+        }
+        let column;
+        if (def.column !== undefined) {
+            const name = def.column === true ? key : def.column;
+            if (!isIdentifier(name)) {
+                issues.push(identifierMessage(name, `customFields.${key}.column`));
+                continue;
+            }
+            column = {
+                role: 'promoted',
+                key,
+                name,
+                type: promotedType(def, maxLength),
+                nullable: true,
+                personal,
+                dbGenerated: false,
+            };
+            promoted.push(column);
+        }
+        else if (!hasJsonColumn) {
+            issues.push(`customFields.${key} is not promoted to a column and no JSON column is mapped. Set customFields.${key}.column or map columns.custom.`);
+            continue;
+        }
+        fields.set(key, {
+            key,
+            type: def.type,
+            maxLength,
+            personal,
+            breakdown: def.breakdown === true,
+            keepWhenDenied: def.keepWhenDenied === true,
+            ...(column === undefined ? {} : { column }),
+        });
+    }
+    return { fields, promoted };
+}
+function findDuplicateNames(columns, issues) {
+    const seen = new Map();
+    for (const c of columns) {
+        const k = c.name.toLowerCase();
+        const prev = seen.get(k);
+        if (prev !== undefined) {
+            issues.push(`${label(prev)} and ${label(c)} both map to "${c.name}"; each role needs its own column (names compare case-insensitively).`);
+        }
+        else {
+            seen.set(k, c);
+        }
+    }
+}
+const label = (c) => c.role === 'promoted' ? `customFields.${c.key}` : `columns.${c.key}`;
+/**
+ * Pure and deterministic: the single source of truth that the generator, row builder, startup validator
+ * and (later) the read queries all consume. Never mutates its input. Throws DynaliticsConfigError listing all issues.
+ */
+export function buildColumnModel(schema) {
+    const issues = [];
+    const existing = schema.tableMode === 'existing';
+    const table = resolveTable(schema, issues);
+    const pageLength = schema.page?.maxLength ?? DEFAULT_PAGE_LENGTH;
+    if (!Number.isInteger(pageLength) || pageLength < 1 || pageLength > MAX_PAGE_LENGTH) {
+        issues.push(`page.maxLength must be an integer 1..${MAX_PAGE_LENGTH}.`);
+    }
+    const firstVisitEnabled = schema.firstVisit?.enabled === true;
+    const roleColumns = (existing ? resolveExistingRoleColumns : resolveRoleColumns)(schema, firstVisitEnabled, pageLength, issues);
+    const hasJson = roleColumns.some((c) => c.role === 'custom');
+    const { fields, promoted } = resolveCustomFields(schema, hasJson, issues);
+    const columns = [...roleColumns, ...promoted];
+    findDuplicateNames(columns, issues);
+    const byRole = (role) => columns.find((c) => c.role === role);
+    const userId = byRole('userId');
+    const ip = byRole('ip');
+    if (existing) {
+        if (firstVisitEnabled &&
+            (byRole('isFirstVisit') === undefined || (userId === undefined && ip === undefined))) {
+            issues.push('firstVisit.enabled needs columns.isFirstVisit and at least one of columns.userId, columns.ip.');
+        }
+    }
+    else if (firstVisitEnabled && userId === undefined && ip === undefined) {
+        issues.push('firstVisit.enabled needs at least one of columns.userId, columns.ip.');
+    }
+    if (issues.length > 0)
+        throw new DynaliticsConfigError(issues);
+    return {
+        table,
+        mode: existing ? 'existing' : 'recommended',
+        columns,
+        insertColumns: columns.filter((c) => !c.dbGenerated),
+        unmappedRoles: OPTIONAL_STORED_ROLES.filter((r) => byRole(r) === undefined),
+        customFields: fields,
+        identity: { ...(userId === undefined ? {} : { userId }), ...(ip === undefined ? {} : { ip }) },
+        firstVisitEnabled,
+    };
+}
+//# sourceMappingURL=column-model.js.map

package/dist/model/identifiers.d.ts

@@ -0,0 +1,19 @@
+export interface TableRef {
+    readonly database?: string;
+    readonly schema?: string;
+    readonly name: string;
+}
+export declare function isIdentifier(name: unknown): name is string;
+export declare function isCustomKey(name: unknown): name is string;
+export declare function identifierMessage(name: string, what: string): string;
+export declare function assertIdentifier(name: string, what: string): string;
+export declare function assertCustomKey(key: string): string;
+/** Parses 'name', 'schema.name', 'db.schema.name' or an object into a validated TableRef. */
+export declare function parseTableRef(input: string | {
+    database?: string;
+    schema?: string;
+    name: string;
+}): TableRef;
+/** Dialect-specific restrictions on table references (spec 3.7). */
+export declare function assertTableForDialect(ref: TableRef, dialect: 'postgres' | 'mysql' | 'mssql'): void;
+//# sourceMappingURL=identifiers.d.ts.map