@protoyard/blueprint 0.0.0-stage → 1.1.1

package/dist/share.d.ts

@@ -0,0 +1,78 @@
+import type { AnyBlueprint } from './kinds/envelope.ts';
+import type { Blueprint } from './schema.ts';
+import { type UntrustedBlueprintIssue } from './untrusted.ts';
+/**
+ * Share links (ADR-030): a blueprint travels in a URL fragment, `#bp=1.<data>`,
+ * where `<data>` is the canonical JSON, deflate-raw compressed, in base64url.
+ * Fragments never reach a server. Decoding treats the link as untrusted:
+ * size caps apply before any work, decompression stops at the loader's byte
+ * cap (no zip bombs), and the text goes through `loadUntrustedBlueprint`.
+ *
+ * Uses `CompressionStream` / `DecompressionStream` (browsers, Node 20+).
+ */
+/** Version prefix of the current share format. */
+export declare const SHARE_LINK_VERSION = "1";
+/** The fragment parameter a player reads: `#bp=<encoded>`. */
+export declare const SHARE_FRAGMENT_PARAM = "bp";
+/** Encoded links longer than this are refused (they stop fitting chat tools). */
+export declare const MAX_SHARE_ENCODED_LENGTH: number;
+/** Decompression stops past this many bytes: the untrusted loader's input cap. */
+export declare const MAX_SHARE_DECODED_BYTES: number;
+/** The same cap for links to any kind (`decodeDocumentShare`): the document loader's input cap. */
+export declare const MAX_SHARE_DOCUMENT_DECODED_BYTES: number;
+export type ShareLinkIssue = Omit<UntrustedBlueprintIssue, 'code'> & {
+    code: UntrustedBlueprintIssue['code'] | 'invalid-link' | 'unsupported-version' | 'unsupported-browser';
+};
+/** The browsers whose `CompressionStream` / `DecompressionStream` handle `deflate-raw`. */
+export declare const SHARE_LINK_BROWSERS = "Chrome 103+, Safari 16.4+, Firefox 113+";
+/** Whether this environment can encode and decode share links. */
+export declare function supportsShareLinks(): boolean;
+export type ShareDecodeResult = {
+    success: true;
+    blueprint: Blueprint;
+    issues: [];
+} | {
+    success: false;
+    blueprint: null;
+    issues: ShareLinkIssue[];
+};
+export type DocumentShareDecodeResult = {
+    success: true;
+    blueprint: AnyBlueprint;
+    issues: [];
+} | {
+    success: false;
+    blueprint: null;
+    issues: ShareLinkIssue[];
+};
+/** Thrown by `encodeBlueprintShare` when a blueprint does not fit in a link. */
+export declare class ShareLinkTooLargeError extends Error {
+    readonly encodedLength: number;
+    constructor(encodedLength: number);
+}
+/**
+ * Encodes a blueprint of any kind as `1.<base64url(deflate-raw(canonical JSON))>`.
+ * The same blueprint always gives the same link, whatever its key order. Throws
+ * `ShareLinkTooLargeError` past `MAX_SHARE_ENCODED_LENGTH`.
+ */
+export declare function encodeBlueprintShare(blueprint: AnyBlueprint): Promise<string>;
+/** `#bp=<encoded>`, ready to append to the player's URL. */
+export declare function blueprintShareFragment(encoded: string): string;
+/**
+ * The encoded blueprint in a URL fragment (`#bp=…`, alone or among other
+ * `&`-separated parameters), or null when there is none.
+ */
+export declare function readBlueprintShareFragment(hash: string): string | null;
+/**
+ * Decodes an app share link payload (`1.<data>`, or a whole `#bp=` fragment)
+ * into a validated app blueprint or typed issues (`loadUntrustedBlueprint`).
+ * Never throws.
+ */
+export declare function decodeBlueprintShare(input: string): Promise<ShareDecodeResult>;
+/**
+ * Decodes a share link to a blueprint of any kind (app, deck, page, doc)
+ * through `loadUntrustedDocument`: content caps, multiline fields and the
+ * kind's body schema. Decompression stops at the document loader's byte cap.
+ * Never throws.
+ */
+export declare function decodeDocumentShare(input: string): Promise<DocumentShareDecodeResult>;

package/dist/share.js

@@ -0,0 +1,234 @@
+import { canonicalJson } from "./identity.js";
+import { DEFAULT_UNTRUSTED_DOCUMENT_LIMITS } from "./kinds/limits.js";
+import { DEFAULT_UNTRUSTED_BLUEPRINT_LIMITS, loadUntrustedBlueprint, loadUntrustedDocument, } from "./untrusted.js";
+/**
+ * Share links (ADR-030): a blueprint travels in a URL fragment, `#bp=1.<data>`,
+ * where `<data>` is the canonical JSON, deflate-raw compressed, in base64url.
+ * Fragments never reach a server. Decoding treats the link as untrusted:
+ * size caps apply before any work, decompression stops at the loader's byte
+ * cap (no zip bombs), and the text goes through `loadUntrustedBlueprint`.
+ *
+ * Uses `CompressionStream` / `DecompressionStream` (browsers, Node 20+).
+ */
+/** Version prefix of the current share format. */
+export const SHARE_LINK_VERSION = '1';
+/** The fragment parameter a player reads: `#bp=<encoded>`. */
+export const SHARE_FRAGMENT_PARAM = 'bp';
+/** Encoded links longer than this are refused (they stop fitting chat tools). */
+export const MAX_SHARE_ENCODED_LENGTH = 16 * 1024;
+/** Decompression stops past this many bytes: the untrusted loader's input cap. */
+export const MAX_SHARE_DECODED_BYTES = DEFAULT_UNTRUSTED_BLUEPRINT_LIMITS.maxBytes;
+/** The same cap for links to any kind (`decodeDocumentShare`): the document loader's input cap. */
+export const MAX_SHARE_DOCUMENT_DECODED_BYTES = DEFAULT_UNTRUSTED_DOCUMENT_LIMITS.maxBytes;
+const PREFIX = `${SHARE_LINK_VERSION}.`;
+const BASE64URL = /^[A-Za-z0-9_-]*$/;
+/** The browsers whose `CompressionStream` / `DecompressionStream` handle `deflate-raw`. */
+export const SHARE_LINK_BROWSERS = 'Chrome 103+, Safari 16.4+, Firefox 113+';
+/** Whether this environment can encode and decode share links. */
+export function supportsShareLinks() {
+    if (typeof CompressionStream === 'undefined' || typeof DecompressionStream === 'undefined') {
+        return false;
+    }
+    try {
+        new DecompressionStream('deflate-raw');
+        new CompressionStream('deflate-raw');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Thrown by `encodeBlueprintShare` when a blueprint does not fit in a link. */
+export class ShareLinkTooLargeError extends Error {
+    encodedLength;
+    constructor(encodedLength) {
+        super(`This blueprint needs a ${encodedLength}-character link; links are limited to ${MAX_SHARE_ENCODED_LENGTH}. Share the blueprint.json file instead.`);
+        this.name = 'ShareLinkTooLargeError';
+        this.encodedLength = encodedLength;
+    }
+}
+const fail = (code, message, fix) => ({
+    success: false,
+    blueprint: null,
+    issues: [{ code, path: [], message, fix }],
+});
+function streamOf(bytes) {
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+}
+async function collect(stream, cap) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > cap) {
+            await reader.cancel().catch(() => undefined);
+            return null;
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+function toBase64Url(bytes) {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function fromBase64Url(text) {
+    if (text.length % 4 === 1)
+        return null;
+    const padded = text.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (text.length % 4)) % 4);
+    try {
+        const binary = atob(padded);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i += 1)
+            bytes[i] = binary.charCodeAt(i);
+        return bytes;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Encodes a blueprint of any kind as `1.<base64url(deflate-raw(canonical JSON))>`.
+ * The same blueprint always gives the same link, whatever its key order. Throws
+ * `ShareLinkTooLargeError` past `MAX_SHARE_ENCODED_LENGTH`.
+ */
+export async function encodeBlueprintShare(blueprint) {
+    if (!supportsShareLinks()) {
+        throw new Error(`This environment cannot create share links: it lacks CompressionStream("deflate-raw") (${SHARE_LINK_BROWSERS}). Share the blueprint.json file instead.`);
+    }
+    const { $schema: _schema, ...content } = blueprint;
+    const json = new TextEncoder().encode(canonicalJson(content));
+    const compressed = await collect(streamOf(json).pipeThrough(new CompressionStream('deflate-raw')), Number.POSITIVE_INFINITY);
+    const encoded = `${PREFIX}${toBase64Url(compressed ?? new Uint8Array())}`;
+    if (encoded.length > MAX_SHARE_ENCODED_LENGTH)
+        throw new ShareLinkTooLargeError(encoded.length);
+    return encoded;
+}
+/** `#bp=<encoded>`, ready to append to the player's URL. */
+export function blueprintShareFragment(encoded) {
+    return `#${SHARE_FRAGMENT_PARAM}=${encoded}`;
+}
+/**
+ * The encoded blueprint in a URL fragment (`#bp=…`, alone or among other
+ * `&`-separated parameters), or null when there is none.
+ */
+export function readBlueprintShareFragment(hash) {
+    const body = hash.startsWith('#') ? hash.slice(1) : hash;
+    for (const part of body.split('&')) {
+        const [key, ...rest] = part.split('=');
+        if (key === SHARE_FRAGMENT_PARAM)
+            return rest.join('=');
+    }
+    return null;
+}
+/** The link payload's JSON text, or the issue that stopped it (size, version, encoding). */
+async function inflateShare(input, maxBytes) {
+    try {
+        const raw = typeof input === 'string' ? input.trim() : '';
+        const encoded = raw.startsWith('#') ? (readBlueprintShareFragment(raw) ?? '') : raw;
+        if (encoded.length > MAX_SHARE_ENCODED_LENGTH) {
+            return {
+                ok: false,
+                result: fail('too-large', `The link is ${encoded.length} characters; share links are limited to ${MAX_SHARE_ENCODED_LENGTH}.`, 'Open the blueprint.json file instead of a link.'),
+            };
+        }
+        const dot = encoded.indexOf('.');
+        if (dot < 1) {
+            return {
+                ok: false,
+                result: fail('invalid-link', 'The link has no format version.', 'Copy the whole link, including the part after "#bp=".'),
+            };
+        }
+        const version = encoded.slice(0, dot);
+        if (version !== SHARE_LINK_VERSION) {
+            return {
+                ok: false,
+                result: fail('unsupported-version', `The link uses share format "${version.slice(0, 8)}"; this player reads format ${SHARE_LINK_VERSION}.`, 'Open the link in a newer player, or share the blueprint.json file.'),
+            };
+        }
+        if (!supportsShareLinks()) {
+            return {
+                ok: false,
+                result: fail('unsupported-browser', `This browser cannot open share links: it lacks DecompressionStream("deflate-raw") (${SHARE_LINK_BROWSERS}).`, 'Open the link in a current browser, or ask for the blueprint.json file and open it.'),
+            };
+        }
+        const data = encoded.slice(dot + 1);
+        const bytes = BASE64URL.test(data) && data.length > 0 ? fromBase64Url(data) : null;
+        if (!bytes) {
+            return {
+                ok: false,
+                result: fail('invalid-link', 'The link is not valid base64url data.', 'Copy the whole link again; it may have been cut or changed.'),
+            };
+        }
+        let inflated;
+        try {
+            inflated = await collect(streamOf(bytes).pipeThrough(new DecompressionStream('deflate-raw')), maxBytes);
+        }
+        catch {
+            return {
+                ok: false,
+                result: fail('invalid-link', 'The link data could not be decompressed.', 'Copy the whole link again; it may have been cut or changed.'),
+            };
+        }
+        if (!inflated) {
+            return {
+                ok: false,
+                result: fail('too-large', `The blueprint in this link is larger than ${maxBytes} bytes.`, 'Open the blueprint.json file instead of a link.'),
+            };
+        }
+        let text;
+        try {
+            text = new TextDecoder('utf-8', { fatal: true }).decode(inflated);
+        }
+        catch {
+            return {
+                ok: false,
+                result: fail('invalid-link', 'The link data is not UTF-8 text.', 'Copy the whole link again.'),
+            };
+        }
+        return { ok: true, text };
+    }
+    catch {
+        return {
+            ok: false,
+            result: fail('invalid-link', 'The link could not be read.', 'Copy the whole link again, or open the blueprint.json file.'),
+        };
+    }
+}
+/**
+ * Decodes an app share link payload (`1.<data>`, or a whole `#bp=` fragment)
+ * into a validated app blueprint or typed issues (`loadUntrustedBlueprint`).
+ * Never throws.
+ */
+export async function decodeBlueprintShare(input) {
+    const inflated = await inflateShare(input, MAX_SHARE_DECODED_BYTES);
+    return inflated.ok ? loadUntrustedBlueprint(inflated.text) : inflated.result;
+}
+/**
+ * Decodes a share link to a blueprint of any kind (app, deck, page, doc)
+ * through `loadUntrustedDocument`: content caps, multiline fields and the
+ * kind's body schema. Decompression stops at the document loader's byte cap.
+ * Never throws.
+ */
+export async function decodeDocumentShare(input) {
+    const inflated = await inflateShare(input, MAX_SHARE_DOCUMENT_DECODED_BYTES);
+    return inflated.ok ? loadUntrustedDocument(inflated.text) : inflated.result;
+}

package/dist/sheet-screen.d.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+/**
+ * The `sheet` screen: an entity's records as a spreadsheet (one row per
+ * record, one column per field), with a totals row that sums number, integer
+ * and money columns, CSV download, and cell edits saved through the entity's
+ * update service. Rendered by `@protoyard/crud/screens/sheet` over
+ * `@protoyard/views-ui/sheet`.
+ *
+ * Kept in its own module so the screen union in `schema.ts` only names it.
+ */
+/** Field kinds whose cells can be edited (typed text is checked by the entity schema on save). */
+export declare const SHEET_EDITABLE_KINDS: readonly ["text", "longText", "number", "integer", "money", "boolean", "date", "enum", "email", "url", "phone"];
+/** Field kinds a sheet shows read-only: their value is a label or a list, not one cell input. */
+export declare const SHEET_READONLY_KINDS: readonly ["datetime", "relation", "persona", "tags"];
+/** Every field kind a sheet column may name. */
+export declare const SHEET_COLUMN_KINDS: ReadonlySet<string>;
+/** Field kinds a totals row can sum. */
+export declare const SHEET_TOTAL_KINDS: ReadonlySet<string>;
+/** At most this many columns (A–Z). */
+export declare const SHEET_MAX_COLUMNS = 26;
+/**
+ * The screen's schema, built from `schema.ts`'s shared screen base and field
+ * name rule (passed in, so this module imports nothing from `schema.ts`).
+ */
+export declare function sheetScreenSchema<Base extends z.ZodRawShape>(base: Base, fieldName: z.ZodString): z.ZodObject<Base & {
+    type: z.ZodLiteral<"sheet">;
+    entity: z.ZodString;
+    /** Fields shown as columns, in order; omitted means every column the entity can show. */
+    columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /** Number, integer or money columns summed in a totals row. */
+    totals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+} extends infer T ? { -readonly [P in keyof T]: T[P]; } : never, z.core.$strict>;
+interface SheetFieldLike {
+    name: string;
+    kind: string;
+}
+/** Cross-reference issues for one sheet screen of `entity` (`add(path, message)`). */
+export declare function sheetScreenIssues(entity: {
+    name: string;
+    fields: readonly SheetFieldLike[];
+}, screen: {
+    columns?: readonly string[] | undefined;
+    totals?: readonly string[] | undefined;
+}, path: readonly (string | number)[], add: (path: (string | number)[], message: string) => void): void;
+/** The columns a sheet shows: the listed ones, or every field a sheet can show (at most 26). */
+export declare function sheetColumns<F extends SheetFieldLike>(entity: {
+    fields: readonly F[];
+}, columns?: readonly string[]): F[];
+export {};

package/dist/sheet-screen.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+/**
+ * The `sheet` screen: an entity's records as a spreadsheet (one row per
+ * record, one column per field), with a totals row that sums number, integer
+ * and money columns, CSV download, and cell edits saved through the entity's
+ * update service. Rendered by `@protoyard/crud/screens/sheet` over
+ * `@protoyard/views-ui/sheet`.
+ *
+ * Kept in its own module so the screen union in `schema.ts` only names it.
+ */
+/** Field kinds whose cells can be edited (typed text is checked by the entity schema on save). */
+export const SHEET_EDITABLE_KINDS = [
+    'text',
+    'longText',
+    'number',
+    'integer',
+    'money',
+    'boolean',
+    'date',
+    'enum',
+    'email',
+    'url',
+    'phone',
+];
+/** Field kinds a sheet shows read-only: their value is a label or a list, not one cell input. */
+export const SHEET_READONLY_KINDS = ['datetime', 'relation', 'persona', 'tags'];
+/** Every field kind a sheet column may name. */
+export const SHEET_COLUMN_KINDS = new Set([
+    ...SHEET_EDITABLE_KINDS,
+    ...SHEET_READONLY_KINDS,
+]);
+/** Field kinds a totals row can sum. */
+export const SHEET_TOTAL_KINDS = new Set(['number', 'integer', 'money']);
+/** At most this many columns (A–Z). */
+export const SHEET_MAX_COLUMNS = 26;
+/**
+ * The screen's schema, built from `schema.ts`'s shared screen base and field
+ * name rule (passed in, so this module imports nothing from `schema.ts`).
+ */
+export function sheetScreenSchema(base, fieldName) {
+    return z.strictObject({
+        ...base,
+        type: z.literal('sheet'),
+        entity: z.string().min(1),
+        /** Fields shown as columns, in order; omitted means every column the entity can show. */
+        columns: z.array(fieldName).min(1).max(SHEET_MAX_COLUMNS).optional(),
+        /** Number, integer or money columns summed in a totals row. */
+        totals: z.array(fieldName).max(SHEET_MAX_COLUMNS).optional(),
+    });
+}
+/** Cross-reference issues for one sheet screen of `entity` (`add(path, message)`). */
+export function sheetScreenIssues(entity, screen, path, add) {
+    const fields = new Map(entity.fields.map((field) => [field.name, field]));
+    const seen = new Set();
+    screen.columns?.forEach((name, j) => {
+        const field = fields.get(name);
+        if (!field)
+            add([...path, 'columns', j], `unknown field "${name}" on "${entity.name}"`);
+        else if (!SHEET_COLUMN_KINDS.has(field.kind)) {
+            add([...path, 'columns', j], `a ${field.kind} field cannot be a sheet column ("${name}")`);
+        }
+        if (seen.has(name))
+            add([...path, 'columns', j], `duplicate column "${name}"`);
+        seen.add(name);
+    });
+    const shown = new Set(screen.columns ?? sheetColumns(entity).map((field) => field.name));
+    screen.totals?.forEach((name, j) => {
+        const field = fields.get(name);
+        if (!field)
+            add([...path, 'totals', j], `unknown field "${name}" on "${entity.name}"`);
+        else if (!SHEET_TOTAL_KINDS.has(field.kind)) {
+            add([...path, 'totals', j], `totals "${name}" must be a number, integer or money field`);
+        }
+        else if (!shown.has(name)) {
+            add([...path, 'totals', j], `totals "${name}" is not one of the sheet's columns`);
+        }
+    });
+}
+/** The columns a sheet shows: the listed ones, or every field a sheet can show (at most 26). */
+export function sheetColumns(entity, columns) {
+    if (columns) {
+        const byName = new Map(entity.fields.map((field) => [field.name, field]));
+        return columns.flatMap((name) => {
+            const field = byName.get(name);
+            return field ? [field] : [];
+        });
+    }
+    return entity.fields
+        .filter((field) => SHEET_COLUMN_KINDS.has(field.kind))
+        .slice(0, SHEET_MAX_COLUMNS);
+}

package/dist/storage.d.ts

@@ -0,0 +1,43 @@
+import type { IntegrityRules } from '@protoyard/core';
+import { type Blueprint, type BlueprintEntity, type BlueprintField } from './schema.ts';
+/**
+ * Domain tables for optional entity features. They are ordinary stores (not
+ * `py_*`) so enabling a feature on a blueprint does not force a reserved-table
+ * migration on every existing prototype database.
+ */
+export declare const FEATURE_TABLES: {
+    readonly audit: "auditEntries";
+    readonly files: "files";
+    readonly notifications: "notifications";
+};
+/** Dexie store strings for the feature tables (stable column order). */
+export declare const FEATURE_STORE_STRINGS: Record<(typeof FEATURE_TABLES)[keyof typeof FEATURE_TABLES], string>;
+/**
+ * Row property / Dexie index for a field that always gets a structural column
+ * (relations, personas, tags, files). Plain scalar fields are only indexed
+ * when listed in `indexes`, `titleField` or `defaultSort`.
+ */
+export declare function storeIndexForField(field: BlueprintField): string | undefined;
+/** Integrity / row property name for a relation or persona column (no `*`). */
+export declare function relationProperty(field: BlueprintField): string | undefined;
+/**
+ * Dexie store string for one entity table. A relation's declaring entity owns
+ * its foreign key; the inverse is discovered from target-side relation fields
+ * by the generated related-detail UI and does not create a second stored key.
+ * Column order is deterministic:
+ * `id`, structural field indexes in declaration order, then explicit
+ * indexes / title / defaultSort, then `createdAt`, `updatedAt`, and
+ * `deletedAt` when soft-delete is on.
+ */
+export declare function entityStoreString(entity: BlueprintEntity): string;
+/**
+ * Dexie `stores` map for a blueprint (version-1 shape). Entity tables keep
+ * declaration order; feature tables are appended in a fixed name order so two
+ * parses of the same blueprint always yield byte-identical JSON.
+ */
+export declare function deriveStores(blueprint: Blueprint): Record<string, string>;
+/**
+ * `IntegrityRules` matching `validateWorld`: every relation / persona / file
+ * id column, plus created/updated/(deleted) timestamps and date fields.
+ */
+export declare function deriveIntegrity(blueprint: Blueprint): IntegrityRules;

package/dist/storage.js

@@ -0,0 +1,179 @@
+import { dateWindowDays, entityTable, } from "./schema.js";
+/**
+ * Domain tables for optional entity features. They are ordinary stores (not
+ * `py_*`) so enabling a feature on a blueprint does not force a reserved-table
+ * migration on every existing prototype database.
+ */
+export const FEATURE_TABLES = {
+    audit: 'auditEntries',
+    files: 'files',
+    notifications: 'notifications',
+};
+/** Dexie store strings for the feature tables (stable column order). */
+export const FEATURE_STORE_STRINGS = {
+    auditEntries: 'id, entity, recordId, actorId, action, at',
+    files: 'id, ownerId, entity, recordId, createdAt',
+    notifications: 'id, personaId, readAt, [personaId+readAt], createdAt',
+};
+/**
+ * Row property / Dexie index for a field that always gets a structural column
+ * (relations, personas, tags, files). Plain scalar fields are only indexed
+ * when listed in `indexes`, `titleField` or `defaultSort`.
+ */
+export function storeIndexForField(field) {
+    switch (field.kind) {
+        case 'relation':
+            return field.cardinality === 'many' ? `*${field.name}Ids` : `${field.name}Id`;
+        case 'persona':
+            return `${field.name}Id`;
+        case 'tags':
+            return `*${field.name}`;
+        case 'file':
+            return field.multiple ? `*${field.name}Ids` : `${field.name}Id`;
+        default:
+            return undefined;
+    }
+}
+/** Integrity / row property name for a relation or persona column (no `*`). */
+export function relationProperty(field) {
+    const index = storeIndexForField(field);
+    return index?.replace(/^\*/, '');
+}
+function indexForNamedField(entity, fieldName) {
+    const field = entity.fields.find((f) => f.name === fieldName);
+    if (!field)
+        return undefined;
+    return storeIndexForField(field) ?? fieldName;
+}
+/**
+ * Dexie store string for one entity table. A relation's declaring entity owns
+ * its foreign key; the inverse is discovered from target-side relation fields
+ * by the generated related-detail UI and does not create a second stored key.
+ * Column order is deterministic:
+ * `id`, structural field indexes in declaration order, then explicit
+ * indexes / title / defaultSort, then `createdAt`, `updatedAt`, and
+ * `deletedAt` when soft-delete is on.
+ */
+export function entityStoreString(entity) {
+    const parts = [];
+    const seen = new Set();
+    const add = (index) => {
+        if (seen.has(index))
+            return;
+        seen.add(index);
+        parts.push(index);
+    };
+    add('id');
+    for (const field of entity.fields) {
+        const index = storeIndexForField(field);
+        if (index)
+            add(index);
+    }
+    for (const name of entity.indexes) {
+        const index = indexForNamedField(entity, name);
+        if (index)
+            add(index);
+    }
+    {
+        const index = indexForNamedField(entity, entity.titleField);
+        if (index)
+            add(index);
+    }
+    if (entity.defaultSort) {
+        const index = indexForNamedField(entity, entity.defaultSort.field);
+        if (index)
+            add(index);
+    }
+    add('createdAt');
+    add('updatedAt');
+    if (entity.features.softDelete)
+        add('deletedAt');
+    return parts.join(', ');
+}
+function featureFlags(blueprint) {
+    return {
+        audit: blueprint.entities.some((e) => e.features.audit),
+        files: blueprint.entities.some((e) => e.features.files),
+        notifications: blueprint.notifications.length > 0 ||
+            blueprint.entities.some((e) => e.features.notifications),
+    };
+}
+/**
+ * Dexie `stores` map for a blueprint (version-1 shape). Entity tables keep
+ * declaration order; feature tables are appended in a fixed name order so two
+ * parses of the same blueprint always yield byte-identical JSON.
+ */
+export function deriveStores(blueprint) {
+    const stores = {};
+    for (const entity of blueprint.entities) {
+        stores[entityTable(entity)] = entityStoreString(entity);
+    }
+    const flags = featureFlags(blueprint);
+    // Fixed order (alphabetical by table name) independent of which entity opted in.
+    if (flags.audit)
+        stores[FEATURE_TABLES.audit] = FEATURE_STORE_STRINGS.auditEntries;
+    if (flags.files)
+        stores[FEATURE_TABLES.files] = FEATURE_STORE_STRINGS.files;
+    if (flags.notifications) {
+        stores[FEATURE_TABLES.notifications] = FEATURE_STORE_STRINGS.notifications;
+    }
+    return stores;
+}
+/**
+ * `IntegrityRules` matching `validateWorld`: every relation / persona / file
+ * id column, plus created/updated/(deleted) timestamps and date fields.
+ */
+export function deriveIntegrity(blueprint) {
+    const byName = new Map(blueprint.entities.map((e) => [e.name, e]));
+    const relations = {};
+    const timestamps = {};
+    for (const entity of blueprint.entities) {
+        const table = entityTable(entity);
+        const rels = {};
+        const times = ['createdAt', 'updatedAt'];
+        for (const field of entity.fields) {
+            if (field.kind === 'relation') {
+                const target = byName.get(field.to);
+                if (!target)
+                    continue;
+                const property = relationProperty(field);
+                if (property)
+                    rels[property] = entityTable(target);
+            }
+            else if (field.kind === 'persona') {
+                rels[`${field.name}Id`] = 'py_personas';
+            }
+            else if (field.kind === 'file') {
+                const property = relationProperty(field);
+                if (property)
+                    rels[property] = FEATURE_TABLES.files;
+            }
+            else if (field.kind === 'date' || field.kind === 'datetime') {
+                // A window that reaches past now (due dates, bookings) is allowed in
+                // the future, so only its "not before the organization" bound applies
+                // through generation; it is left out of the reference-time check.
+                if (dateWindowDays(field.window).to <= 0)
+                    times.push(field.name);
+            }
+        }
+        if (entity.features.softDelete)
+            times.push('deletedAt');
+        if (Object.keys(rels).length > 0)
+            relations[table] = rels;
+        timestamps[table] = times;
+    }
+    const flags = featureFlags(blueprint);
+    if (flags.audit) {
+        relations[FEATURE_TABLES.audit] = { actorId: 'py_personas' };
+        timestamps[FEATURE_TABLES.audit] = ['at'];
+    }
+    if (flags.files) {
+        relations[FEATURE_TABLES.files] = { ownerId: 'py_personas' };
+        timestamps[FEATURE_TABLES.files] = ['createdAt'];
+    }
+    if (flags.notifications) {
+        relations[FEATURE_TABLES.notifications] = { personaId: 'py_personas' };
+        timestamps[FEATURE_TABLES.notifications] = ['createdAt', 'readAt'];
+    }
+    return { relations, timestamps };
+}