@happyvertical/smrt-preferences 0.0.0-stage → 0.55.10

package/dist/overview.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The overview layer (#3727 phase 3): overview-shaped load, save, reset,
+ * page load and widget load over the generic preference store, kind
+ * `overview`, surface id = `OverviewDefinition.id`.
+ *
+ * Tiers, low to high: the page's `definition.defaults`, the tenant default,
+ * then the user's override. The tenant tier merges into the defaults first
+ * and the user tier applies to that result, so a user override is a delta
+ * against the tenant default. Saves are strict (`checkOverviewOverride`, only
+ * the canonical override is stored); loads are lenient (a bad entry is
+ * dropped and reported, the rest render).
+ */
+import { type LoadedOverview, type LoadOverviewOptions, type OverviewDefinition, type OverviewDocument, type OverviewIssue, type OverviewOverride, type WidgetLoadInput, type WidgetRegistry } from '@happyvertical/smrt-svelte/overview/server';
+import type { DatabaseInterface } from '@happyvertical/sql';
+import type { PreferenceScope } from './kinds.js';
+import { type PreferenceStore } from './store.js';
+/** One stored tier, resolved. */
+export interface OverviewTierState {
+    /** The document this tier applies to (sanitized). */
+    base: OverviewDocument;
+    /** The document after this tier (sanitized). */
+    document: OverviewDocument;
+    /** The stored override, canonical with invalid entries removed, or `null`. */
+    override: OverviewOverride | null;
+    /** Concurrency token: echo it back on save or reset; `null` = no row. */
+    revision: string | null;
+    /** Entries of the stored override dropped on load, and why. */
+    issues: OverviewIssue[];
+}
+/** What a page load needs to render and edit one overview. */
+export interface OverviewState {
+    overviewId: string;
+    /** The tenant default over `definition.defaults`. */
+    tenant: OverviewTierState;
+    /** The user's override over the tenant default; `null` without a user. */
+    user: OverviewTierState | null;
+    /** What the principal sees: the user tier's document, else the tenant's. */
+    document: OverviewDocument;
+    /** Every stored-tier issue (tenant first). Page-default issues excluded. */
+    issues: OverviewIssue[];
+    /** Feed `createOverview({ canCustomize })` for the tier being edited. */
+    canCustomize: {
+        tenant: boolean;
+        user: boolean;
+    };
+}
+export type OverviewWriteFailure = {
+    ok: false;
+    reason: 'not_allowed';
+} | {
+    ok: false;
+    reason: 'conflict';
+} | {
+    ok: false;
+    reason: 'invalid';
+    issues: OverviewIssue[];
+};
+export type OverviewSaveResult = {
+    ok: true;
+    override: OverviewOverride | null;
+    revision: string | null;
+} | OverviewWriteFailure;
+export type OverviewResetResult = {
+    ok: true;
+} | OverviewWriteFailure;
+export interface OverviewSaveInput {
+    scope: PreferenceScope;
+    /** The client's override (untrusted). `null` resets the tier. */
+    override: unknown;
+    /**
+     * The `revision` the client loaded for this tier (`null` when it loaded no
+     * row). A stale revision fails with `conflict`, never overwrites.
+     */
+    revision: string | null;
+}
+export interface OverviewResetInput {
+    scope: PreferenceScope;
+    /**
+     * The revision the client loaded: a string guards the delete, `null`
+     * conflicts when a row exists, and omitting it resets regardless.
+     */
+    revision?: string | null;
+}
+export interface OverviewPageOptions extends LoadOverviewOptions {
+    /** Which tier's document to load: `user` (default) or `tenant` (editing defaults). */
+    scope?: PreferenceScope;
+}
+export type OverviewWidgetResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    reason: 'not_allowed';
+} | {
+    ok: false;
+    reason: 'invalid';
+    issues: OverviewIssue[];
+} | {
+    ok: false;
+    reason: 'load_failed';
+    code: 'load_failed' | 'timeout' | 'invalid_data';
+};
+export interface OverviewStoreOptions {
+    db: DatabaseInterface;
+    /** Share a generic store (default: one over `db`). */
+    preferences?: PreferenceStore;
+}
+export interface OverviewStore {
+    /** Read both tiers for the principal and resolve the merge. */
+    load(definition: OverviewDefinition, registry: WidgetRegistry): Promise<OverviewState>;
+    /** Validate and store one tier's override (canonical form only). */
+    save(definition: OverviewDefinition, registry: WidgetRegistry, input: OverviewSaveInput): Promise<OverviewSaveResult>;
+    /** Delete one tier's row, returning that tier to the tier below. */
+    reset(definition: OverviewDefinition, input: OverviewResetInput): Promise<OverviewResetResult>;
+    /** `load` plus `loadOverview`, for a page's server load. */
+    loadPage(definition: OverviewDefinition, registry: WidgetRegistry, ctx: WidgetLoadInput, options?: OverviewPageOptions): Promise<OverviewState & {
+        loaded: LoadedOverview;
+    }>;
+    /** The data of one widget, for the controller's `loadWidget` remote function. */
+    loadWidget(definition: OverviewDefinition, registry: WidgetRegistry, widget: unknown, ctx: WidgetLoadInput, options?: LoadOverviewOptions): Promise<OverviewWidgetResult>;
+}
+/**
+ * The persistence and server-load API of overview surfaces. Every call acts
+ * as the ambient principal.
+ */
+export declare function createOverviewStore(options: OverviewStoreOptions): OverviewStore;
+//# sourceMappingURL=overview.d.ts.map

package/dist/overview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overview.d.ts","sourceRoot":"","sources":["../src/overview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EAExB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EAKrB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,4CAA4C,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAO5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAEzE,iCAAiC;AACjC,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,IAAI,EAAE,gBAAgB,CAAC;IACvB,gDAAgD;IAChD,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAClC,yEAAyE;IACzE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+DAA+D;IAC/D,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,0EAA0E;IAC1E,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,yEAAyE;IACzE,YAAY,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;CAClD;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACjC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACxE,oBAAoB,CAAC;AAEzB,MAAM,MAAM,mBAAmB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,oBAAoB,CAAC;AAEtE,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,eAAe,CAAC;IACvB,iEAAiE;IACjE,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,eAAe,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D,sFAAsF;IACtF,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,aAAa,EAAE,CAAA;CAAE,GACzD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,cAAc,CAAC;CAClD,CAAC;AAEN,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,iBAAiB,CAAC;IACtB,sDAAsD;IACtD,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,IAAI,CACF,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B,oEAAoE;IACpE,IAAI,CACF,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC/B,oEAAoE;IACpE,KAAK,CACH,UAAU,EAAE,kBAAkB,EAC9B,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CACN,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE,cAAc,EACxB,GAAG,EAAE,eAAe,EACpB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,aAAa,GAAG;QAAE,MAAM,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IACvD,iFAAiF;IACjF,UAAU,CACR,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,OAAO,EACf,GAAG,EAAE,eAAe,EACpB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAClC;AAcD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CA6Jf"}

package/dist/permissions.d.ts

@@ -0,0 +1,22 @@
+import { type PermissionDefinition } from '@happyvertical/smrt-users';
+/** Authorizes changing and resetting a tenant's default overview layouts. */
+export declare const CUSTOMIZE_OVERVIEW_PERMISSION = "overviews.customize";
+/** Authorizes a principal to keep their own overview layouts. */
+export declare const PERSONALIZE_OVERVIEW_PERMISSION = "overviews.personalize";
+/** Authorizes changing and resetting a tenant's default shell layout. */
+export declare const CUSTOMIZE_SHELL_PERMISSION = "shell.customize";
+/** Authorizes a principal to keep their own shell layout and settings. */
+export declare const PERSONALIZE_SHELL_PERMISSION = "shell.personalize";
+export declare const PREFERENCE_PERMISSION_DEFINITIONS: PermissionDefinition[];
+/** Register the built-in preference permissions once. */
+export declare function ensurePreferencePermissionsRegistered(): void;
+/**
+ * `collection.action` parts of a permission slug for the users operation
+ * guards: the action is the last segment (`fields.policy.manage` is
+ * collection `fields.policy`, action `manage`).
+ */
+export declare function splitPermissionSlug(slug: string): {
+    collection: string;
+    action: string;
+};
+//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,2BAA2B,CAAC;AAEnC,6EAA6E;AAC7E,eAAO,MAAM,6BAA6B,wBAAwB,CAAC;AAEnE,iEAAiE;AACjE,eAAO,MAAM,+BAA+B,0BAA0B,CAAC;AAEvE,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,oBAAoB,CAAC;AAE5D,0EAA0E;AAC1E,eAAO,MAAM,4BAA4B,sBAAsB,CAAC;AAEhE,eAAO,MAAM,iCAAiC,EAAE,oBAAoB,EA4BnE,CAAC;AAIF,yDAAyD;AACzD,wBAAgB,qCAAqC,IAAI,IAAI,CAM5D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB,CAMA"}

package/dist/read-guard.d.ts

@@ -0,0 +1,9 @@
+/** Whether the ambient principal may see `row`. */
+export declare function isPreferenceRowVisible(row: unknown): boolean;
+/**
+ * Register the owner-read interceptor (idempotent). Called when the model
+ * module loads and again before every store read, so a cleared interceptor
+ * registry (tests, `GlobalInterceptors.clear()`) cannot silently drop it.
+ */
+export declare function ensurePreferenceReadGuard(): void;
+//# sourceMappingURL=read-guard.d.ts.map

package/dist/read-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-guard.d.ts","sourceRoot":"","sources":["../src/read-guard.ts"],"names":[],"mappings":"AAoCA,mDAAmD;AACnD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAO5D;AAkDD;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAmEhD"}

package/dist/smrt-knowledge.json

@@ -0,0 +1,341 @@
+{
+  "schemaVersion": 1,
+  "sensitiveFieldsExcluded": true,
+  "generatedAt": "1970-01-01T00:00:00.000Z",
+  "packageName": "@happyvertical/smrt-preferences",
+  "packageVersion": "0.55.10",
+  "sourceManifestPath": "dist/manifest.json",
+  "agentDocPath": "AGENTS.md",
+  "sourceHashes": {
+    "manifest": "77cf90e3f71e50d105f986834e28d7a4e94c5fd71e14fe78dbc68e0738663e09",
+    "packageJson": "a22fe7ae3d0a58bda4cb389ed3f8336d7651a2969a8844ce83a409305f266bed",
+    "agents": "ff8ef8173cb499f021a99d03561d2bf50145c010e5a21c989f476caf5698ed30",
+    "moduleDoc:agents/preference-kinds.md": "b2e3301b279445a693a95494cd98b0fd791d70fb80e411e0444006c07d259f2a"
+  },
+  "exports": [
+    ".",
+    "./manifest",
+    "./manifest.json"
+  ],
+  "dependencies": {
+    "@happyvertical/smrt-core": "workspace:*",
+    "@happyvertical/smrt-svelte": "workspace:*",
+    "@happyvertical/smrt-tenancy": "workspace:*",
+    "@happyvertical/smrt-users": "workspace:*",
+    "@happyvertical/sql": "catalog:",
+    "@happyvertical/smrt-vitest": "workspace:*",
+    "@types/node": "24.13.6",
+    "svelte": "^5.57.1",
+    "typescript": "6.0.3",
+    "vite": "8.1.4",
+    "vitest": "4.1.10"
+  },
+  "smrtDependencies": [
+    "@happyvertical/smrt-core",
+    "@happyvertical/smrt-svelte",
+    "@happyvertical/smrt-tenancy",
+    "@happyvertical/smrt-users",
+    "@happyvertical/smrt-vitest"
+  ],
+  "sdkDependencies": [
+    "@happyvertical/sql"
+  ],
+  "tags": [
+    "cross-package",
+    "multi-tenancy",
+    "overview",
+    "preferences",
+    "shell",
+    "smrt"
+  ],
+  "risks": [
+    "cross-package-refs:2",
+    "sensitive-fields-excluded"
+  ],
+  "objects": [
+    {
+      "name": "UiPreferenceRecordCollection",
+      "qualifiedName": "@happyvertical/smrt-preferences:UiPreferenceRecordCollection",
+      "collection": "uipreferencerecords",
+      "description": "Reads of UiPreferenceRecord. Not decorated: the model has no generated surface, so a decorated collection would only add a second manifest schema for the same table.",
+      "tableName": "_smrt_ui_preferences",
+      "packageName": "@happyvertical/smrt-preferences",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findTier"
+      ],
+      "methodSignatures": [
+        {
+          "name": "findTier",
+          "async": true,
+          "params": [
+            "tenantId: string",
+            "kind: string",
+            "surfaceId: string",
+            "scope: PreferenceScope",
+            "userId?: string"
+          ],
+          "returns": "Promise<UiPreferenceRecord | null>"
+        }
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "uipreferencerecords.findTier",
+          "operation": "findTier",
+          "objectName": "@happyvertical/smrt-preferences:UiPreferenceRecordCollection",
+          "path": "/uipreferencerecords/findTier",
+          "method": "POST"
+        },
+        {
+          "kind": "mcp",
+          "name": "uipreferencerecordcollection_findtier",
+          "operation": "findTier",
+          "objectName": "@happyvertical/smrt-preferences:UiPreferenceRecordCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "UiPreferenceRecord",
+      "qualifiedName": "@happyvertical/smrt-preferences:UiPreferenceRecord",
+      "collection": "uipreferencerecords",
+      "description": "One stored user-interface preference (#3727): the canonical payload of a registered preference kind (overview, shell-layout, ...) for one surface at one tier of one tenant.",
+      "tableName": "_smrt_ui_preferences",
+      "packageName": "@happyvertical/smrt-preferences",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "kind",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": ""
+        },
+        {
+          "name": "surfaceId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": ""
+        },
+        {
+          "name": "scopeType",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": "tenant"
+        },
+        {
+          "name": "userId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "scopeKey",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "payloadJson",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "formatVersion",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "updatedBy",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "userId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "updatedBy",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "getPayload",
+        "loadFromId",
+        "loadFromSlug",
+        "save",
+        "setPayload"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: DeleteOptions"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "getPayload",
+          "returns": "unknown"
+        },
+        {
+          "name": "loadFromId",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "loadFromSlug",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: SaveOptions"
+          ],
+          "returns": "Promise<this>"
+        },
+        {
+          "name": "setPayload",
+          "params": [
+            "value: unknown"
+          ],
+          "returns": "void"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "kind",
+        "surface_id",
+        "scope_type",
+        "scope_key"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "getPayload",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-preferences:UiPreferenceRecord"
+        },
+        {
+          "kind": "api",
+          "operation": "loadFromId",
+          "code": "lifecycle-method",
+          "reason": "`loadFromId` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-preferences:UiPreferenceRecord"
+        },
+        {
+          "kind": "api",
+          "operation": "loadFromSlug",
+          "code": "lifecycle-method",
+          "reason": "`loadFromSlug` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-preferences:UiPreferenceRecord"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-preferences:UiPreferenceRecord"
+        },
+        {
+          "kind": "api",
+          "operation": "setPayload",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-preferences:UiPreferenceRecord"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    }
+  ],
+  "surfaces": [
+    {
+      "kind": "api",
+      "name": "uipreferencerecords.findTier",
+      "operation": "findTier",
+      "objectName": "@happyvertical/smrt-preferences:UiPreferenceRecordCollection",
+      "path": "/uipreferencerecords/findTier",
+      "method": "POST"
+    },
+    {
+      "kind": "mcp",
+      "name": "uipreferencerecordcollection_findtier",
+      "operation": "findTier",
+      "objectName": "@happyvertical/smrt-preferences:UiPreferenceRecordCollection"
+    }
+  ],
+  "prompts": [],
+  "relationshipsV2": {
+    "foreignKeyFields": 0,
+    "crossPackageRefFields": 2,
+    "junctionCollections": 0,
+    "hierarchicalObjects": 0,
+    "polymorphicAssociations": 0,
+    "uuidColumns": 8
+  },
+  "agentDoc": "# smrt-preferences\n\nUser-interface preferences (#3727): one `_smrt_ui_preferences` system table\nfor tenant defaults and per-user preferences of any registered **kind**, the\nkind registry, the generic store, and two built-in kinds: `overview`\n(customizable overview pages of `@happyvertical/smrt-svelte/overview`, with an\noverview-shaped layer on top) and `shell-layout` (the AdminShell\n`ShellSettingsDelta`). The kind contract is in\n[agents/preference-kinds.md](agents/preference-kinds.md); the overview\nsurface itself is in\n[smrt-svelte overview-surfaces.md](../smrt-svelte/agents/overview-surfaces.md).\n\n## Why a package of its own\n\nThe repo puts each layered-override table in the package that owns its\nresolution (`smrt-prompts`, `smrt-playbooks`, `smrt-features`,\n`smrt-fields`). `smrt-svelte` has no runtime dependency on core, tenancy or\nusers and holds no tables. This package imports only smrt-svelte's\nSvelte-free entries (`./overview/server`, `./workspace/server`).\n\n## Pieces\n\n| File | Contents |\n| --- | --- |\n| `src/models/UiPreferenceRecord.ts` | The row; owns identity, scope shape and authorization; refuses unregistered kinds |\n| `src/collections/UiPreferenceRecordCollection.ts` | Undecorated reads (`findTier`); internal, not exported; no generated surface |\n| `src/write-capability.ts` | The store-only write capability (internal) |\n| `src/read-guard.ts` | The owner-read interceptor (internal) |\n| `src/kinds.ts` | `registerPreferenceKind`, `requirePreferenceKind`, `UnknownPreferenceKindError`, the validation contract |\n| `src/store.ts` | `createPreferenceStore({ db })`: generic `load` / `save` / `reset(kind, surfaceId, ...)` |\n| `src/kinds/overview.ts`, `src/overview.ts` | The `overview` kind and `createOverviewStore` (`load`, `save`, `reset`, `loadPage`, `loadWidget`, `withTenantDefaults`) |\n| `src/kinds/shell-layout.ts` | The `shell-layout` kind and `createShellSettingsPreferences` (the server half of a `ShellSettingsAdapter`) |\n| `src/kinds/builtin.ts` | Registers the two built-in kinds (imported by the entry and the store) |\n| `src/context.ts` | The ambient principal and `PreferenceAccessError` |\n| `src/permissions.ts` | `overviews.customize` / `overviews.personalize`, `shell.customize` / `shell.personalize` |\n\n## Table\n\n`_smrt_ui_preferences`: `tenant_id` (UUID), `kind`, `surface_id`,\n`scope_type` (`tenant` | `user`), `user_id` (UUID, NULL on tenant rows),\n`scope_key` (`__tenant__` or the user id), `payload_json` (the kind's\ncanonical payload), `format_version`, `updated_by`, plus the SmrtObject\ncolumns. Unique key `(tenant_id, kind, surface_id, scope_type, scope_key)`;\nevery key column is NOT NULL, so the index is total on every engine. It ships\nthrough manifest-driven migrations (`smrt db:migrate`), never runtime DDL;\n`src/__tests__/migration.test.ts` applies it with `migrateSmrtSchemas` on\nSQLite and DuckDB and asserts parity afterwards. On DuckDB only this table is\nmigrated in tests: smrt-users' tables carry ON UPDATE CASCADE foreign keys\nDuckDB cannot create.\n\n## Invariants\n\n- **Kinds gate everything.** The store and the model refuse a kind that is\n  not registered (`UnknownPreferenceKindError`), so no row exists that no code\n  can validate. A kind's `validate` runs strictly on save (refuse unless `ok`,\n  store only `canonical`, `null` deletes the row) and leniently on load (use\n  `canonical`, report `issues`, never rewrite the row). A row written at a\n  newer `format_version` than the kind's is dropped and reported.\n- **Store-only writes.** Only the store writes rows: it passes a\n  module-private symbol capability (`src/write-capability.ts`, not exported;\n  the smrt-approvals pattern) bound to the exact `payloadJson` the kind\n  validated, single-use, and grants each delete the same way. The model\n  refuses any insert, update (also in `validateBeforeSave`, so bulk creates\n  are covered) or delete without it, so `new UiPreferenceRecord(...).save()`,\n  a collection `create()` or `row.setPayload(); row.save()` never store an\n  unvalidated payload. Tests seed corrupt storage with raw SQL\n  (`src/__tests__/raw-rows.ts`). This guards in-process callers, not raw SQL.\n- **Owner-safe reads, in the predicate.** A principal never reads another\n  user's row. `src/read-guard.ts` (registered when the model loads and again\n  before every store read) adds `scope_key IN ('__tenant__', <own user id>)`\n  (tenant rows only without a user id) to the read predicate BEFORE SQL\n  runs, intersecting any caller `scopeKey in`. Core's read entry points and\n  the hook each runs: `list`, `listByIds`, `findAll`, `listWithLatestRelated`\n  (`beforeList` + `afterList`); `get`, `findById`, `findOne`, `getOrUpsert`,\n  `update` / `delete` lookups, and model hydration `loadFromId` /\n  `loadFromSlug` (`beforeGet`; collection `get` also `afterGet`); `count`,\n  `counts`, `facets` (`beforeList` only, so ownership must be in the\n  predicate); `semanticSearch*`, `findSimilar*` (`beforeList`, some also\n  `afterList`); `query` (`beforeQuery` + `afterQuery`; raw SQL cannot carry\n  the predicate, so the guard refuses it). Every read path runs at least one\n  hook. The after-read hooks re-check hydrated rows as defence in depth (a\n  row whose scope cannot be told is dropped), and hydration also re-checks in\n  the model. `count()` and `facets()` therefore count only visible rows.\n- **Not an app API.** `UiPreferenceRecord` stays a root export only because\n  generated consumer registration imports every public manifest object from\n  the root; the collection is not exported. Apps use `createPreferenceStore`,\n  `createOverviewStore` and `createShellSettingsPreferences`.\n- **Tiers.** The tenant row is the default; the user row applies on top, and\n  `validate` for the user tier receives the tenant tier's canonical payload\n  (`ctx.tenant`). User rows are per tenant: preferences name tenant data.\n- **Identity is ambient.** No API takes a tenant or user id. A missing\n  principal throws `PreferenceAccessError`; a principal without a user id has\n  no user tier and cannot write one. A session-only principal (users\n  `createSessionHandler()` without `enterTenantContext`) is entered as a\n  tenant context with the same identity before any table access.\n- **Tenancy.** The model is `@TenantScoped({ mode: 'required' })`, and every\n  store read also names the tenant explicitly (a super-admin bypass context\n  does not filter reads). `save()`/`delete()` refuse a row whose stored\n  tenant, kind, surface or tier differs from memory (matched by predicate:\n  DuckDB returns raw UUID columns as lossy HUGEINTs), a foreign tenant, and a\n  user row that is not the principal's.\n- **Permissions are per kind.** Each kind names `{ tenant, user }` slugs;\n  the model asserts them (`assertOperationPermission`, fail closed) and the\n  store reports them as `canCustomize` (`checkOperationPermission`). A slug\n  must be in the users catalog or it never grants. The users resolver denies\n  a principal with no user id even with the slug in its set. The built-in\n  `personalize` slugs are in users' self-personalization list (seeded for\n  owner/admin/member/viewer once registered).\n- **Permission source.** The principal's permission set is authoritative,\n  including an explicit empty set: a tenancy adapter without\n  `resolvePermissions` refuses everyone (fails closed). Hosts must configure\n  it, or enter identity through users' `enterTenantContext`; never widen it\n  here.\n- **Concurrency.** Optimistic: a save passes the `revision` (ISO\n  `updated_at`) it loaded, `null` meaning \"no row\". Updates use core's\n  revision CAS (`save({ expectedUpdatedAt })`), a first write is a strict\n  insert (`_insertOnly`) so a racing first write hits the unique index, and\n  a delete is guarded the same way. `reset` treats `revision: null` like\n  save does (a row that exists now conflicts); only an omitted revision\n  resets unguarded. Mismatch: `{ ok: false, reason: 'conflict' }`. Exception, documented: `createShellSettingsPreferences().write`\n  without a revision reads the current one first, i.e. last-writer-wins,\n  because the shell's `ShellSettingsAdapter.write(delta)` carries none.\n- **Overview `loadWidget`** lets a principal without either customize\n  permission load only a widget on their resolved overview; anything else is\n  `not_allowed`. The widget is sanitized against the page definition first.\n- **No generated surface** (`api: { include: [] }`, `cli: false`,\n  `mcp: { include: [] }`): a generated route would skip kind validation.\n\n## Tests\n\n`pnpm test` runs the overview suite and the kinds suite on SQLite and DuckDB\nplus the migration suite; `pnpm test:postgres` runs both suites on PostgreSQL\n(`*.optional.test.ts`, skipped without a database).\n",
+  "moduleDocs": [
+    {
+      "path": "agents/preference-kinds.md",
+      "module": "preference-kinds",
+      "content": "# Preference kinds\n\nThe contract between `_smrt_ui_preferences` and the code that owns a\npreference's meaning (#3727). Package rules are in [../AGENTS.md](../AGENTS.md).\n\n## Registering a kind\n\n```ts\nregisterPreferenceKind({\n  kind: 'board-columns',            // /^[a-z][a-z0-9-]{0,47}$/\n  formatVersion: 1,                 // positive integer, stored per row\n  permissions: { tenant: 'boards.customize', user: 'boards.personalize' },\n  validate(payload, ctx) {          // never throws\n    return { ok, canonical, issues };\n  },\n}, { replace? }) // -> dispose()\n```\n\nRegistration is code at module scope, process-wide (one registry per\nprocess). Registering a kind twice throws unless `{ replace: true }`. Both\nslugs must be `collection.action` and registered in the users catalog\n(`registerPermissionDefinitions`), or they never grant; add a `personalize`\nslug to users' built-in self-personalization list only when every built-in\nrole should hold it.\n\nThe store authorizes against the principal's permission set from the\nambient context and never widens it. A tenancy adapter (SvelteKit, Express)\nwithout `resolvePermissions` supplies an explicit empty set, which the store\ntreats as authoritative: every write is `not_allowed` and `canCustomize` is\nfalse for everyone, owners included. Configure `resolvePermissions`, or let\nusers' `createSessionHandler({ enterTenantContext: true })` enter the context.\n\n## `validate(payload, ctx)`\n\n| `ctx` field | Meaning |\n| --- | --- |\n| `kind`, `surfaceId` | What is being validated (`surfaceId` matches `PREFERENCE_SURFACE_PATTERN`) |\n| `scope` | `tenant` or `user` |\n| `phase` | `save` (strict) or `load` (lenient) |\n| `formatVersion` | The version the payload was written at (the kind's own on save); migrate older payloads here |\n| `tenant` | User tier only: the tenant tier's canonical payload, or `null` |\n| `options` | Host-supplied, kind-specific inputs, passed through from `load` / `save` |\n\nReturn `canonical`: the payload with every invalid part removed (`null` means\nno preference), `issues`: what was removed and why (`{ path, code, message,\ndetail? }`), and `ok`: false whenever anything was removed or refused.\n\n- On **save** the store refuses unless `ok`, stores only `canonical` (as\n  JSON with the kind's `formatVersion`), and deletes the row when `canonical`\n  is `null`.\n- On **load** the store uses `canonical` and reports `issues` per tier; the\n  row is not rewritten. Unparseable JSON and rows from a newer\n  `formatVersion` are dropped before `validate` runs. A `validate` that\n  throws on load drops the tier with a `validator_error` issue; on save the\n  error propagates and nothing is stored. Validators should not throw.\n- A payload is data, never code: no query strings, URLs or expressions a\n  reader would execute. Authorization happens where the data is read, never\n  through payload values.\n\n## Built-in kinds\n\n| Kind | Payload | Validator | Permissions | `options` |\n| --- | --- | --- | --- | --- |\n| `overview` | `OverviewOverride` (sparse, version 1) | save: `checkOverviewOverride`; load: `resolveOverview` + `diffOverview`, against the page definition (user tier: tenant-merged via `withTenantDefaults`) | `overviews.customize` / `overviews.personalize` | `{ definition, registry }`; `definition.id` must equal the surface id |\n| `shell-layout` | `ShellSettingsDelta` | `sanitizeShellSettingsDelta` from `@happyvertical/smrt-svelte/workspace/server` | `shell.customize` / `shell.personalize` | none |\n\n## Store calls\n\n`createPreferenceStore({ db })` returns `load(kind, surfaceId, { options })`\n(both tiers, `canCustomize` from the kind's pair), `save(kind, surfaceId, {\nscope, payload, revision, options })` and `reset(kind, surfaceId, { scope,\nrevision? })` (`null` conflicts when a row exists; omitted is unguarded). Failures are `{ ok: false, reason: 'not_allowed' | 'conflict'\n| 'invalid' }`; an unregistered kind throws `UnknownPreferenceKindError`.\n\nKind-shaped layers sit on top: `createOverviewStore` (the overview page API)\nand `createShellSettingsPreferences` (the server half of the shell's\n`ShellSettingsAdapter`: `read(surfaceId)` merges tenant and user with\n`mergeShellSettingsDelta`; `write(surfaceId, delta, { scope?, revision? })`\nis last-writer-wins only when the revision is omitted).\n"
+    }
+  ],
+  "browser": {
+    "status": "server-only",
+    "issues": [
+      "#3617",
+      "#3624",
+      "#3626"
+    ],
+    "via": [
+      "@happyvertical/smrt-profiles",
+      "@happyvertical/smrt-tenancy",
+      "@happyvertical/smrt-users"
+    ]
+  }
+}

package/dist/store.d.ts

@@ -0,0 +1,86 @@
+import './kinds/builtin.js';
+import type { DatabaseInterface } from '@happyvertical/sql';
+import { type PreferenceIssue, type PreferenceScope } from './kinds.js';
+/** One stored tier, validated for use. */
+export interface PreferenceTier {
+    /** The kind's canonical payload, invalid parts removed; `null` = none. */
+    payload: unknown | null;
+    /** Concurrency token: echo it back on save or reset; `null` = no row. */
+    revision: string | null;
+    /** What was dropped from the stored payload on load, and why. */
+    issues: PreferenceIssue[];
+}
+export interface PreferenceState {
+    kind: string;
+    surfaceId: string;
+    /** The tenant default. */
+    tenant: PreferenceTier;
+    /** The principal's own preference; `null` without a user. */
+    user: PreferenceTier | null;
+    /** Every tier's issues, tenant first. */
+    issues: PreferenceIssue[];
+    /** Whether the principal may write each tier (the kind's permission pair). */
+    canCustomize: {
+        tenant: boolean;
+        user: boolean;
+    };
+}
+export type PreferenceWriteFailure = {
+    ok: false;
+    reason: 'not_allowed';
+} | {
+    ok: false;
+    reason: 'conflict';
+} | {
+    ok: false;
+    reason: 'invalid';
+    issues: PreferenceIssue[];
+};
+export type PreferenceSaveResult = {
+    ok: true;
+    payload: unknown | null;
+    revision: string | null;
+} | PreferenceWriteFailure;
+export type PreferenceResetResult = {
+    ok: true;
+} | PreferenceWriteFailure;
+export interface PreferenceLoadInput {
+    /** Kind-specific validation inputs (passed to `validate` as `options`). */
+    options?: unknown;
+}
+export interface PreferenceSaveInput extends PreferenceLoadInput {
+    scope: PreferenceScope;
+    /** The client's payload (untrusted). `null` resets the tier. */
+    payload: unknown;
+    /**
+     * The `revision` the client loaded for this tier (`null` when it loaded no
+     * row). A stale revision fails with `conflict`, never overwrites.
+     */
+    revision: string | null;
+}
+export interface PreferenceResetInput {
+    scope: PreferenceScope;
+    /**
+     * The revision the client loaded: a string guards the delete, `null`
+     * ("I loaded no row") conflicts when a row exists, and omitting it resets
+     * regardless.
+     */
+    revision?: string | null;
+}
+export interface PreferenceStoreOptions {
+    db: DatabaseInterface;
+}
+export interface PreferenceStore {
+    /** Read and validate both tiers of `(kind, surfaceId)` for the principal. */
+    load(kind: string, surfaceId: string, input?: PreferenceLoadInput): Promise<PreferenceState>;
+    /** Validate and store one tier's payload (canonical form only). */
+    save(kind: string, surfaceId: string, input: PreferenceSaveInput): Promise<PreferenceSaveResult>;
+    /** Delete one tier's row, returning that tier to the tier below. */
+    reset(kind: string, surfaceId: string, input: PreferenceResetInput): Promise<PreferenceResetResult>;
+}
+/**
+ * The generic preference store. One per database; every call acts as the
+ * ambient principal and names a registered kind.
+ */
+export declare function createPreferenceStore(options: PreferenceStoreOptions): PreferenceStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAWA,OAAO,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAO5D,OAAO,EAEL,KAAK,eAAe,EAEpB,KAAK,eAAe,EAErB,MAAM,YAAY,CAAC;AAUpB,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iEAAiE;IACjE,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,MAAM,EAAE,cAAc,CAAC;IACvB,6DAA6D;IAC7D,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,yCAAyC;IACzC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,8EAA8E;IAC9E,YAAY,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;CAClD;AAED,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACjC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AAEhE,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC9D,sBAAsB,CAAC;AAE3B,MAAM,MAAM,qBAAqB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,sBAAsB,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D,KAAK,EAAE,eAAe,CAAC;IACvB,gEAAgE;IAChE,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,eAAe,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,iBAAiB,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,mBAAmB,GAC1B,OAAO,CAAC,eAAe,CAAC,CAAC;IAC5B,mEAAmE;IACnE,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACjC,oEAAoE;IACpE,KAAK,CACH,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACnC;AAmHD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,GAC9B,eAAe,CAwNjB"}