@adminiumjs/engine 0.1.0-rc.1

package/dist/classify/names.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Name normalization for classifier rules — 05-introspection-engine.md §7:
+ * "Name matching operates on a normalized token form: lowercase, camelCase
+ * split to snake_case." Every regex in columns.ts/pii.ts/tables.ts runs
+ * against `normalizeName(name)`, never the raw identifier.
+ */
+/** `userId` → `user_id`, `HTMLBody` → `html_body`, `Created-At` → `created_at`. */
+export declare function normalizeName(name: string): string;
+/** Split a normalized name into tokens (`unit_price` → ['unit','price']). */
+export declare function nameTokens(name: string): string[];
+//# sourceMappingURL=names.d.ts.map

package/dist/classify/names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../src/classify/names.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEjD"}

package/dist/classify/names.js

@@ -0,0 +1,19 @@
+/**
+ * Name normalization for classifier rules — 05-introspection-engine.md §7:
+ * "Name matching operates on a normalized token form: lowercase, camelCase
+ * split to snake_case." Every regex in columns.ts/pii.ts/tables.ts runs
+ * against `normalizeName(name)`, never the raw identifier.
+ */
+/** `userId` → `user_id`, `HTMLBody` → `html_body`, `Created-At` → `created_at`. */
+export function normalizeName(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .replace(/[\s-]+/g, '_')
+        .toLowerCase();
+}
+/** Split a normalized name into tokens (`unit_price` → ['unit','price']). */
+export function nameTokens(name) {
+    return normalizeName(name).split('_').filter(Boolean);
+}
+//# sourceMappingURL=names.js.map

package/dist/classify/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../../src/classify/names.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,mFAAmF;AACnF,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI;SACR,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,OAAO,CAAC,uBAAuB,EAAE,OAAO,CAAC;SACzC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,WAAW,EAAE,CAAC;AACnB,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACxD,CAAC"}

package/dist/classify/pii.d.ts

@@ -0,0 +1,29 @@
+/**
+ * PII detection and masking defaults — 05-introspection-engine.md §7.2.
+ *
+ * PII is a flag layer INDEPENDENT of the primary semantic: it runs after the
+ * §7.1 rule pipeline and can flag any column regardless of which primary tag
+ * won. Masking is a display/export transform applied downstream by the
+ * server serialization layer (08-server-api.md) — this module only decides
+ * `pii` kind and `maskedByDefault`.
+ */
+import type { ColumnModel, PiiKind, SemanticTag } from '../schema-model.js';
+export interface PiiResult {
+    pii: PiiKind | null;
+    maskedByDefault: boolean;
+    reasons: string[];
+}
+export interface PiiContext {
+    /** People-shaped table per the §8 directory trigger (see tables.ts). */
+    peopleish: boolean;
+    /** Set when the column is half of a classified geo lat/lng pair. */
+    isGeoPointPair: boolean;
+}
+/**
+ * §7.2 kinds and triggers. Rules 17/18/26 (email/phone/ip) arrive as the
+ * already-decided primary tag; person-name PII only applies to
+ * first/last/full name columns on people-shaped tables; geo-precise only to
+ * lat/lng pairs on people-shaped tables.
+ */
+export declare function detectPii(column: ColumnModel, primary: SemanticTag, ctx: PiiContext): PiiResult;
+//# sourceMappingURL=pii.d.ts.map

package/dist/classify/pii.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pii.d.ts","sourceRoot":"","sources":["../../src/classify/pii.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAe5E,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAC;CACzB;AAID;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,UAAU,GACd,SAAS,CAmCX"}

package/dist/classify/pii.js

@@ -0,0 +1,55 @@
+import { normalizeName } from './names.js';
+/** §7.2 name triggers that are independent of the §7.1 primary tag. */
+const ADDRESS_RE = /(^|_)(address|street|city|zip|postal_code|postcode)(_|$)/;
+const DOB_RE = /(^|_)(birth(date|day)?|dob|date_of_birth)(_|$)/;
+const GOV_ID_RE = /(ssn|social_security|tax_id|vat(_number)?|passport|national_id|driver_licen[cs]e)/;
+/**
+ * §7.2 lists this unanchored, but short tokens (`pan`, `bic`) then match as
+ * substrings of ordinary words — `company_name` contains "pan". We anchor
+ * every alternative on token boundaries to avoid that false positive.
+ */
+const PAYMENT_ID_RE = /(^|_)(card_number|pan|iban|account_number|routing_number|bic|swift)(_|$)/;
+const TEXTISH = new Set(['text', 'varchar', 'unknown']);
+/**
+ * §7.2 kinds and triggers. Rules 17/18/26 (email/phone/ip) arrive as the
+ * already-decided primary tag; person-name PII only applies to
+ * first/last/full name columns on people-shaped tables; geo-precise only to
+ * lat/lng pairs on people-shaped tables.
+ */
+export function detectPii(column, primary, ctx) {
+    const name = normalizeName(column.name);
+    if (primary === 'email') {
+        return pii('email', 'primary semantic is email (§7.1 rule 17)');
+    }
+    if (primary === 'phone') {
+        return pii('phone', 'primary semantic is phone (§7.1 rule 18)');
+    }
+    if (primary === 'ip-address') {
+        return pii('ip', 'primary semantic is ip-address (§7.1 rule 26)');
+    }
+    if (primary === 'person-name' &&
+        ctx.peopleish &&
+        /^(first_name|last_name|full_name)$/.test(name)) {
+        return pii('person-name', 'first/last/full name on a people-shaped table (§7.2)');
+    }
+    if (primary === 'geo-point' && ctx.peopleish && ctx.isGeoPointPair) {
+        return pii('geo-precise', 'lat/lng pair on a people-shaped table (§7.2)');
+    }
+    if (GOV_ID_RE.test(name)) {
+        return pii('gov-id', `name matches gov-id pattern (§7.2)`);
+    }
+    if (PAYMENT_ID_RE.test(name)) {
+        return pii('payment-id', `name matches payment-id pattern (§7.2)`);
+    }
+    if (DOB_RE.test(name)) {
+        return pii('dob', `name matches date-of-birth pattern (§7.2)`);
+    }
+    if (ADDRESS_RE.test(name) && TEXTISH.has(column.logicalType)) {
+        return pii('address', `name matches address pattern (§7.2)`);
+    }
+    return { pii: null, maskedByDefault: false, reasons: [] };
+}
+function pii(kind, reason) {
+    return { pii: kind, maskedByDefault: true, reasons: [`pii:${kind} — ${reason}`] };
+}
+//# sourceMappingURL=pii.js.map

package/dist/classify/pii.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pii.js","sourceRoot":"","sources":["../../src/classify/pii.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,uEAAuE;AACvE,MAAM,UAAU,GAAG,0DAA0D,CAAC;AAC9E,MAAM,MAAM,GAAG,gDAAgD,CAAC;AAChE,MAAM,SAAS,GAAG,mFAAmF,CAAC;AACtG;;;;GAIG;AACH,MAAM,aAAa,GACjB,0EAA0E,CAAC;AAe7E,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;AAExD;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,MAAmB,EACnB,OAAoB,EACpB,GAAe;IAEf,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAExC,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACxB,OAAO,GAAG,CAAC,OAAO,EAAE,0CAA0C,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACxB,OAAO,GAAG,CAAC,OAAO,EAAE,0CAA0C,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,OAAO,KAAK,YAAY,EAAE,CAAC;QAC7B,OAAO,GAAG,CAAC,IAAI,EAAE,+CAA+C,CAAC,CAAC;IACpE,CAAC;IACD,IACE,OAAO,KAAK,aAAa;QACzB,GAAG,CAAC,SAAS;QACb,oCAAoC,CAAC,IAAI,CAAC,IAAI,CAAC,EAC/C,CAAC;QACD,OAAO,GAAG,CAAC,aAAa,EAAE,sDAAsD,CAAC,CAAC;IACpF,CAAC;IACD,IAAI,OAAO,KAAK,WAAW,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,cAAc,EAAE,CAAC;QACnE,OAAO,GAAG,CAAC,aAAa,EAAE,8CAA8C,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,CAAC,QAAQ,EAAE,oCAAoC,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,OAAO,GAAG,CAAC,YAAY,EAAE,wCAAwC,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,GAAG,CAAC,KAAK,EAAE,2CAA2C,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7D,OAAO,GAAG,CAAC,SAAS,EAAE,qCAAqC,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AAC5D,CAAC;AAED,SAAS,GAAG,CAAC,IAAa,EAAE,MAAc;IACxC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,OAAO,IAAI,MAAM,MAAM,EAAE,CAAC,EAAE,CAAC;AACpF,CAAC"}

package/dist/classify/tables.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Table-shape classification — 05-introspection-engine.md §8 (roles) plus
+ * the §6 structural detectors that live at table granularity: join-table
+ * detection (rule 2), self-FK hierarchy (rule 3), and the polymorphic
+ * pattern flag (rule 4). Also selects each table's display column and
+ * natural key, which the generator uses for FK chips, cards, and detail
+ * titles (research/widget-registry.md §15).
+ *
+ * Two outputs per table:
+ *  - `semantics`: the persisted `TableSemantics` (role/hierarchy/polymorphic
+ *    per the schema-model enum: entity | join-table | log | people |
+ *    messages | line-items | system).
+ *  - `shape`: the broader generator-facing `TableShape` kind used by
+ *    template scoring (people | workflow | events | catalog | join | log |
+ *    settings | geo | generic) with human-readable reasons.
+ */
+import type { DatabaseModel, TableModel, TableSemantics } from '../schema-model.js';
+import { type ClassifiedColumn } from './columns.js';
+export declare const TABLE_SHAPE_KINDS: readonly ["people", "workflow", "events", "catalog", "join", "log", "settings", "geo", "generic"];
+export type TableShapeKind = (typeof TABLE_SHAPE_KINDS)[number];
+export interface TableShape {
+    kind: TableShapeKind;
+    reasons: string[];
+}
+export interface ClassifiedTable {
+    tableId: string;
+    shape: TableShape;
+    semantics: TableSemantics;
+    /**
+     * First text-ish unique/title/name column — what grids, FK chips, and
+     * detail headers render for a row. Null when the table has no text-ish
+     * candidate (pure join tables, numeric-only tables).
+     */
+    displayColumn: string | null;
+    /** First unique text-ish column (slug/email/username/code) — human key. */
+    naturalKey: string | null;
+    columns: ClassifiedColumn[];
+}
+export interface JoinTableResult {
+    isJoin: boolean;
+    confidence: number;
+    fkColumns: string[];
+    reasons: string[];
+}
+/**
+ * A table qualifies when: exactly 2 FK-like columns referencing two tables
+ * (possibly the same one), and at most 2 additional columns drawn from
+ * {surrogate id, created-at-classified, position/sort_order, one small
+ * metadata column}. Boosters: composite PK/unique over the pair (+0.1),
+ * name matching the two target names (+0.1). Base 0.7 → typical 0.8–0.9;
+ * accepted at ≥ 0.8 (§6 thresholds).
+ */
+export declare function detectJoinTable(table: TableModel, columns: ClassifiedColumn[]): JoinTableResult;
+/**
+ * Per 05 (assignment note): "first text-ish unique/title/name column".
+ * Preference order: exact title/name → `_name`-suffixed → unique text-ish
+ * (slug/email/username) → first text-ish non-PK non-secret column.
+ */
+export declare function selectDisplayColumn(table: TableModel, columns: ClassifiedColumn[]): string | null;
+/** First unique text-ish column — the human-facing natural key, if any. */
+export declare function selectNaturalKey(table: TableModel, columns: ClassifiedColumn[]): string | null;
+/** Classify a single table (columns are classified as part of this). */
+export declare function classifyTable(model: DatabaseModel, table: TableModel): ClassifiedTable;
+//# sourceMappingURL=tables.d.ts.map

package/dist/classify/tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../src/classify/tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAEV,aAAa,EACb,UAAU,EACV,cAAc,EACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AAOtB,eAAO,MAAM,iBAAiB,mGAUpB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,2EAA2E;IAC3E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAqCD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,eAAe,CA6DjB;AAyDD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,MAAM,GAAG,IAAI,CAcf;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,EAAE,GAAG,MAAM,GAAG,IAAI,CAe9F;AAMD,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,UAAU,GAAG,eAAe,CAwItF"}

package/dist/classify/tables.js

@@ -0,0 +1,303 @@
+import { buildColumnClassifyContext, classifyColumn, PEOPLE_TABLE_RE, } from './columns.js';
+import { normalizeName } from './names.js';
+// ---------------------------------------------------------------------------
+// Output shapes
+// ---------------------------------------------------------------------------
+export const TABLE_SHAPE_KINDS = [
+    'people',
+    'workflow',
+    'events',
+    'catalog',
+    'join',
+    'log',
+    'settings',
+    'geo',
+    'generic',
+];
+// ---------------------------------------------------------------------------
+// Vocab
+// ---------------------------------------------------------------------------
+/** §8 trigger: `page-log-viewer` name pattern. */
+const LOG_TABLE_RE = /(^|_)(audit|logs?|events?|history|deliveries)(_|$)/;
+const SETTINGS_TABLE_RE = /(^|_)(settings?|preferences?|configs?|configurations?|options)(_|$)/;
+/** §8.2 system-table vocabulary. */
+const SYSTEM_TABLE_RE = /^(adminium_.*|_prisma_migrations|schema_migrations|ar_internal_metadata|django_migrations|knex_migrations.*|sqlite_sequence|mysql\..*)$/;
+/** §6 rule 3 — self-FK column names that imply a hierarchy. */
+const HIERARCHY_COLUMN_RE = /^(parent|manager|supervisor|reports_to|superior)(_id)?$/;
+/** Join-table "allowed extra" columns (§6 rule 2). */
+const POSITION_RE = /^(position|sort_order|rank|ordering)$/;
+/** Line-items detection: quantity × rate numerics on a 2-FK child table. */
+const QTY_RE = /(^|_)(qty|quantity|units|count)(_|$)/;
+const RATE_RE = /(^|_)(price|rate|amount|cost|unit_price)(_|$)/;
+/** Messages detection: sender FK + body text + created-at. */
+const SENDER_RE = /(^|_)(sender|author|user|from_user|creator)(_id)?$/;
+const BODY_RE = /^(body|message|content|text)$/;
+/** §8 log shape: "verb-ish text" = a short action/event/verb column. */
+const VERBISH_RE = /(^|_)(action|event|activity|verb|operation)(_type|_name)?(_|$)/;
+/** Events-shaped table names (guards the calendar trigger against orders-like tables). */
+const EVENTS_TABLE_RE = /(^|_)(events?|meetings?|appointments?|schedules?|shifts?|bookings?|sessions?|releases?)(_|$)/;
+/** Display-column name preference. */
+const TITLE_RE = /^(title|name|label|subject|headline|summary)$/;
+const TITLE_SUFFIX_RE = /_(title|name|label|subject)$/;
+const TEXTISH = new Set(['text', 'varchar']);
+/**
+ * A table qualifies when: exactly 2 FK-like columns referencing two tables
+ * (possibly the same one), and at most 2 additional columns drawn from
+ * {surrogate id, created-at-classified, position/sort_order, one small
+ * metadata column}. Boosters: composite PK/unique over the pair (+0.1),
+ * name matching the two target names (+0.1). Base 0.7 → typical 0.8–0.9;
+ * accepted at ≥ 0.8 (§6 thresholds).
+ */
+export function detectJoinTable(table, columns) {
+    const none = { isJoin: false, confidence: 0, fkColumns: [], reasons: [] };
+    const byName = new Map(columns.map((c) => [c.column, c]));
+    const fkCols = table.columns.filter((c) => byName.get(c.name)?.semantics.primary === 'fk'
+        || (c.references !== null));
+    // Composite-PK FK columns classify as pk-id (rule 2 precedes rule 3), so
+    // count declared references too — the structural signal is the FK itself.
+    const fkNames = [...new Set(fkCols.map((c) => c.name))];
+    if (fkNames.length !== 2)
+        return none;
+    const extras = table.columns.filter((c) => !fkNames.includes(c.name));
+    if (extras.length > 2)
+        return none;
+    let metadataBudget = 1;
+    for (const extra of extras) {
+        const name = normalizeName(extra.name);
+        const primary = byName.get(extra.name)?.semantics.primary;
+        const surrogateId = primary === 'pk-id';
+        const createdAt = primary === 'created-at';
+        const position = POSITION_RE.test(name);
+        if (surrogateId || createdAt || position)
+            continue;
+        if (metadataBudget > 0) {
+            metadataBudget -= 1;
+            continue;
+        }
+        return none;
+    }
+    // Accumulate in integer hundredths — 0.7 + 0.1 must reach the 0.8 gate
+    // exactly, not as 0.7999999999999999.
+    let confidenceHundredths = 70;
+    const reasons = [`exactly 2 FK columns (${fkNames.join(', ')}) and no other data columns`];
+    const pairSet = new Set(fkNames);
+    const coveredByPk = table.primaryKey.length === 2 && table.primaryKey.every((c) => pairSet.has(c));
+    const coveredByUnique = table.uniques.some((u) => u.columns.length === 2 && u.columns.every((c) => pairSet.has(c)));
+    if (coveredByPk || coveredByUnique) {
+        confidenceHundredths += 10;
+        reasons.push('composite PK/unique constraint covers the FK pair (+0.1)');
+    }
+    const targets = fkCols
+        .map((c) => c.references?.tableId.split('.').pop() ?? '')
+        .filter(Boolean)
+        .map((t) => t.replace(/s$/, ''));
+    if (targets.length === 2) {
+        const tableName = normalizeName(table.name);
+        const [a, b] = targets;
+        if (tableName.includes(a) && tableName.includes(b)) {
+            confidenceHundredths += 10;
+            reasons.push('table name is composed of both target names (+0.1)');
+        }
+    }
+    const confidence = Math.min(100, confidenceHundredths) / 100;
+    return { isJoin: confidenceHundredths >= 80, confidence, fkColumns: fkNames, reasons };
+}
+// ---------------------------------------------------------------------------
+// §6 rules 3–4 — hierarchy + polymorphic flags
+// ---------------------------------------------------------------------------
+function detectHierarchy(model, table) {
+    for (const column of table.columns) {
+        if (!HIERARCHY_COLUMN_RE.test(normalizeName(column.name)))
+            continue;
+        if (column.references?.tableId === table.id)
+            return { parentColumn: column.name };
+        const selfRelation = model.relations.some((r) => r.selfReferential &&
+            r.from.tableId === table.id &&
+            r.from.columns.includes(column.name) &&
+            r.confidence >= 0.8);
+        if (selfRelation)
+            return { parentColumn: column.name };
+    }
+    return null;
+}
+function detectPolymorphic(model, table) {
+    const results = [];
+    const names = new Map(table.columns.map((c) => [normalizeName(c.name), c]));
+    const tableNames = new Set(model.tables.map((t) => normalizeName(t.name)));
+    const enumsById = new Map(model.enums.map((e) => [e.id, e]));
+    for (const column of table.columns) {
+        const name = normalizeName(column.name);
+        const match = /^(?<base>[a-z0-9_]+)_type$/.exec(name);
+        if (match?.groups === undefined)
+            continue;
+        if (!TEXTISH.has(column.logicalType) && column.logicalType !== 'enum')
+            continue;
+        const idColumn = names.get(`${match.groups['base']}_id`);
+        if (idColumn === undefined)
+            continue;
+        // Rails-style `commentable_type/commentable_id` also matches this shape.
+        let targets = [];
+        if (column.enumRef !== null) {
+            const values = enumsById.get(column.enumRef)?.values ?? [];
+            targets = values.map((v) => normalizeName(v)).filter((v) => tableNames.has(v));
+        }
+        results.push({ typeColumn: column.name, idColumn: idColumn.name, targets });
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Display column + natural key
+// ---------------------------------------------------------------------------
+function isTextish(column) {
+    return TEXTISH.has(column.logicalType);
+}
+/**
+ * Per 05 (assignment note): "first text-ish unique/title/name column".
+ * Preference order: exact title/name → `_name`-suffixed → unique text-ish
+ * (slug/email/username) → first text-ish non-PK non-secret column.
+ */
+export function selectDisplayColumn(table, columns) {
+    const secret = new Set(columns.filter((c) => c.semantics.flags.secret).map((c) => c.column));
+    const candidates = table.columns.filter((c) => isTextish(c) && !c.isPrimaryKey && !secret.has(c.name));
+    const exact = candidates.find((c) => TITLE_RE.test(normalizeName(c.name)));
+    if (exact)
+        return exact.name;
+    const suffixed = candidates.find((c) => TITLE_SUFFIX_RE.test(normalizeName(c.name)));
+    if (suffixed)
+        return suffixed.name;
+    const unique = candidates.find((c) => c.isUnique);
+    if (unique)
+        return unique.name;
+    return candidates[0]?.name ?? null;
+}
+/** First unique text-ish column — the human-facing natural key, if any. */
+export function selectNaturalKey(table, columns) {
+    const secret = new Set(columns.filter((c) => c.semantics.flags.secret).map((c) => c.column));
+    const singleColumnUniques = new Set(table.uniques.filter((u) => u.columns.length === 1).map((u) => u.columns[0]));
+    const candidate = table.columns.find((c) => isTextish(c) &&
+        !c.isPrimaryKey &&
+        !secret.has(c.name) &&
+        (c.isUnique || singleColumnUniques.has(c.name)));
+    return candidate?.name ?? null;
+}
+// ---------------------------------------------------------------------------
+// Shape + role classification
+// ---------------------------------------------------------------------------
+/** Classify a single table (columns are classified as part of this). */
+export function classifyTable(model, table) {
+    const ctx = buildColumnClassifyContext(model, table);
+    const columns = table.columns.map((column) => classifyColumn(column, ctx));
+    const primaryOf = (name) => columns.find((c) => c.column === name)?.semantics.primary ?? 'plain';
+    const has = (tag) => columns.some((c) => c.semantics.primary === tag);
+    const join = detectJoinTable(table, columns);
+    const hierarchy = detectHierarchy(model, table);
+    const polymorphic = detectPolymorphic(model, table);
+    const tableName = normalizeName(table.name);
+    const reasons = [];
+    let kind = 'generic';
+    let role = 'entity';
+    const fkTargetIsPeopleish = (column) => {
+        const target = column.references?.tableId;
+        if (target === undefined || target === null)
+            return false;
+        const targetTable = model.tables.find((t) => t.id === target);
+        return targetTable !== undefined && PEOPLE_TABLE_RE.test(normalizeName(targetTable.name));
+    };
+    const actorFk = table.columns.some((c) => (primaryOf(c.name) === 'fk' || c.references !== null) &&
+        (SENDER_RE.test(normalizeName(c.name)) || fkTargetIsPeopleish(c)));
+    // -- precedence: structural/system signals first, generic last ----------
+    if (table.system || SYSTEM_TABLE_RE.test(tableName)) {
+        kind = 'generic';
+        role = 'system';
+        reasons.push('system/migration table (§8.2) — excluded and hidden by default');
+    }
+    else if (join.isJoin) {
+        kind = 'join';
+        role = 'join-table';
+        reasons.push(...join.reasons, `join-table confidence ${join.confidence.toFixed(2)}`);
+    }
+    else if (LOG_TABLE_RE.test(tableName) ||
+        (has('created-at') &&
+            !has('updated-at') &&
+            actorFk &&
+            table.columns.some((c) => TEXTISH.has(c.logicalType) &&
+                (c.maxLength === null || c.maxLength <= 64) &&
+                VERBISH_RE.test(normalizeName(c.name))))) {
+        kind = 'log';
+        role = 'log';
+        reasons.push(LOG_TABLE_RE.test(tableName)
+            ? 'table name matches audit/log/events/history vocabulary (§8)'
+            : 'append-only shape: created-at + actor FK + text, no updated-at (§8)');
+    }
+    else if (SETTINGS_TABLE_RE.test(tableName)) {
+        kind = 'settings';
+        reasons.push('table name matches settings/preferences vocabulary');
+    }
+    else if (ctx.peopleish && (has('person-name') || has('email'))) {
+        kind = 'people';
+        role = 'people';
+        reasons.push('people shape: person-name/email columns on a people-ish table (§8 directory trigger)');
+    }
+    else if (has('status-workflow')) {
+        kind = 'workflow';
+        reasons.push('status-workflow enum present (§7.1 rule 7 → kanban trigger)');
+    }
+    else if ((has('event-timestamp') || has('date-range')) &&
+        (EVENTS_TABLE_RE.test(tableName) || has('date-range'))) {
+        kind = 'events';
+        reasons.push('event timestamps with an events-shaped name or start/end pair (§8 calendar trigger)');
+    }
+    else {
+        // Line-items / messages roles are orthogonal to the remaining kinds.
+        const geoColumns = columns.filter((c) => c.semantics.primary === 'geo-region' || c.semantics.primary === 'geo-point');
+        const dataColumns = table.columns.filter((c) => !c.isPrimaryKey);
+        if (geoColumns.length >= 2 &&
+            dataColumns.length > 0 &&
+            geoColumns.length / dataColumns.length >= 0.6) {
+            kind = 'geo';
+            reasons.push(`${geoColumns.length}/${dataColumns.length} data columns are geographic (§7.1 rules 14–15)`);
+        }
+        else {
+            const displayColumn = selectDisplayColumn(table, columns);
+            const catalogSignal = has('money') || has('category-enum') || has('image-url');
+            if (displayColumn !== null && catalogSignal) {
+                kind = 'catalog';
+                reasons.push('display column plus money/category/image columns — catalog shape');
+            }
+            else {
+                reasons.push('no §8 trigger matched');
+            }
+        }
+    }
+    // -- roles that refine `entity` without changing the shape kind ---------
+    if (role === 'entity') {
+        const fkCount = table.columns.filter((c) => c.references !== null).length;
+        const hasQty = table.columns.some((c) => QTY_RE.test(normalizeName(c.name)) && ['integer', 'bigint', 'decimal', 'float'].includes(c.logicalType));
+        const hasRate = table.columns.some((c) => RATE_RE.test(normalizeName(c.name)) && ['integer', 'bigint', 'decimal', 'float'].includes(c.logicalType));
+        const hasBody = table.columns.some((c) => BODY_RE.test(normalizeName(c.name)) && TEXTISH.has(c.logicalType));
+        if (fkCount >= 2 && hasQty && hasRate) {
+            role = 'line-items';
+            reasons.push('line-items role: child of 2 FKs with qty × rate numerics (§8 invoice trigger)');
+        }
+        else if (actorFk && hasBody && has('created-at')) {
+            role = 'messages';
+            reasons.push('messages role: sender FK + body text + created-at (§8 chat trigger)');
+        }
+    }
+    const semantics = { role, hierarchy, polymorphic };
+    if (hierarchy !== null) {
+        reasons.push(`self-FK hierarchy via "${hierarchy.parentColumn}" (§6 rule 3)`);
+    }
+    for (const p of polymorphic) {
+        reasons.push(`polymorphic pair ${p.typeColumn}/${p.idColumn} (§6 rule 4 — no relation fabricated)`);
+    }
+    return {
+        tableId: table.id,
+        shape: { kind, reasons },
+        semantics,
+        displayColumn: selectDisplayColumn(table, columns),
+        naturalKey: selectNaturalKey(table, columns),
+        columns,
+    };
+}
+//# sourceMappingURL=tables.js.map

package/dist/classify/tables.js.map

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

package/dist/config-schema/envelope.d.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+/**
+ * The config envelope every stored config document uses (01-architecture.md
+ * §6.1, 07-meta-store.md §3.17). The envelope persists verbatim into
+ * `adminium_pages.config`; the stored version path the config-migration
+ * runner keys on is `config.v`.
+ */
+export declare const CONFIG_KINDS: readonly ["page", "dashboard", "view", "nav", "manifest-module"];
+export declare const configKindSchema: z.ZodEnum<{
+    view: "view";
+    page: "page";
+    dashboard: "dashboard";
+    nav: "nav";
+    "manifest-module": "manifest-module";
+}>;
+export type ConfigKind = z.infer<typeof configKindSchema>;
+/**
+ * Prefixed document id: `page_`/`view_`/`nav_` + slug or ULID suffix.
+ * Engine-generated ids carry ULID suffixes (`page_01HZX…`); hand-authored and
+ * seeded documents may use readable slugs (`page_customers`, per the §3.17
+ * examples), so the suffix alphabet is not restricted to Crockford base32.
+ */
+export declare const configIdPattern: RegExp;
+/** Nav placement block (01-architecture.md §6.1). */
+export declare const navConfigSchema: z.ZodObject<{
+    group: z.ZodString;
+    icon: z.ZodString;
+    order: z.ZodNumber;
+    slug: z.ZodOptional<z.ZodString>;
+    badge: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type NavConfig = z.infer<typeof navConfigSchema>;
+export declare const pageEnvelopeSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    kind: z.ZodEnum<{
+        view: "view";
+        page: "page";
+        dashboard: "dashboard";
+        nav: "nav";
+        "manifest-module": "manifest-module";
+    }>;
+    id: z.ZodString;
+    template: z.ZodString;
+    title: z.ZodObject<{
+        key: z.ZodString;
+        fallback: z.ZodString;
+    }, z.core.$strip>;
+    source: z.ZodObject<{
+        connectionId: z.ZodNullable<z.ZodString>;
+        table: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    nav: z.ZodObject<{
+        group: z.ZodString;
+        icon: z.ZodString;
+        order: z.ZodNumber;
+        slug: z.ZodOptional<z.ZodString>;
+        badge: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    access: z.ZodObject<{
+        minRole: z.ZodString;
+        permissions: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type PageEnvelope = z.infer<typeof pageEnvelopeSchema>;
+/** Canonical alias used across the workplan documents. */
+export type PageConfig = PageEnvelope;
+/**
+ * A validated dashboard widget instance (01-architecture.md §6.1): a grid
+ * layout item whose `config.binding`, when present, must be a declarative
+ * query descriptor (04-widget-registry.md §5.1).
+ */
+export declare const widgetConfigSchema: z.ZodObject<{
+    i: z.ZodString;
+    widget: z.ZodString;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    w: z.ZodNumber;
+    h: z.ZodNumber;
+    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type WidgetConfig = z.infer<typeof widgetConfigSchema>;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/config-schema/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/config-schema/envelope.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,YAAY,kEAAmE,CAAC;AAC7F,eAAO,MAAM,gBAAgB;;;;;;EAAuB,CAAC;AACrD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAgD,CAAC;AAI7E,qDAAqD;AACrD,eAAO,MAAM,eAAe;;;;;;iBAM1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AA6BxD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,0DAA0D;AAC1D,MAAM,MAAM,UAAU,GAAG,YAAY,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;iBAY7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}