@happyvertical/smrt-fields 0.40.59 → 0.40.61

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-fields",
-  "packageVersion": "0.40.59",
+  "packageVersion": "0.40.61",
   "objects": {
     "@happyvertical/smrt-fields:FieldPolicyCollection": {
       "name": "fieldpolicycollection",
@@ -13,6 +13,20 @@
       "packageName": "@happyvertical/smrt-fields",
       "fields": {},
       "methods": {
+        "policyAudit": {
+          "name": "policyAudit",
+          "async": true,
+          "parameters": [
+            {
+              "name": "options",
+              "type": "object",
+              "optional": true
+            }
+          ],
+          "returnType": "Promise<FieldPolicyAuditSnapshot>",
+          "isStatic": false,
+          "isPublic": true
+        },
         "getAppRows": {
           "name": "getAppRows",
           "async": true,
@@ -78,6 +92,20 @@
           "returnType": "Promise<FieldPolicyBatchResult>",
           "isStatic": false,
           "isPublic": true
+        },
+        "getEditorState": {
+          "name": "getEditorState",
+          "async": true,
+          "parameters": [
+            {
+              "name": "options",
+              "type": "object",
+              "optional": true
+            }
+          ],
+          "returnType": "Promise<FieldPolicyEditorStateResult>",
+          "isStatic": false,
+          "isPublic": true
         }
       },
       "decoratorConfig": {
@@ -92,13 +120,26 @@
             "create",
             "update",
             "delete",
-            "resolveBatch"
+            "resolveBatch",
+            "getEditorState",
+            "policyAudit"
           ],
+          "principalContext": true,
           "routes": {
             "resolveBatch": {
               "scope": "collection",
               "method": "POST",
               "path": "resolve"
+            },
+            "getEditorState": {
+              "scope": "collection",
+              "method": "POST",
+              "path": "editor-state"
+            },
+            "policyAudit": {
+              "scope": "collection",
+              "method": "POST",
+              "path": "policy-audit"
             }
           }
         },
@@ -327,7 +368,8 @@
             "create",
             "update",
             "delete"
-          ]
+          ],
+          "principalContext": true
         },
         "cli": {
           "include": [

package/dist/models/FieldPolicy.d.ts

@@ -0,0 +1,163 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { FieldPolicyOptions, FieldPolicyScopeType, FieldPolicyVisibility } from '../types.js';
+/**
+ * Sparse, layered field policy override (epic #2045, issue #2047).
+ *
+ * One row personalizes a subset of `{defaultValue, visibility, help, label,
+ * displayOrder, locked}` for a single `(objectRef, fieldName)` at one scope
+ * tier. A NULL column means "inherit from the lower layer" (code seed → app →
+ * tenant → user), so resetting a customization is a row DELETE — later
+ * lower-layer changes then flow through (sparse-delta rationale, #1770).
+ *
+ * Rows are validated at write time against the live `ObjectRegistry` (the
+ * manifest is the definition registry): unknown objects/fields are rejected,
+ * defaults are type-checked, and the security rail (`sensitive` /
+ * `readPermission` / `transient`) refuses stored defaults outright.
+ */
+export declare class FieldPolicy extends SmrtObject {
+    /** Qualified class name of the target object (`@package/name:ClassName`). */
+    objectRef: string;
+    /** Field name on the target object (validated against the registry). */
+    fieldName: string;
+    /** Scope tier this row belongs to ('app' | 'tenant' | 'user'). */
+    scopeType: FieldPolicyScopeType;
+    /** Owning tenant for tenant-scope rows; NULL otherwise (native UUID on PG). */
+    tenantId: string | null;
+    /** Owning user for user-scope rows; NULL otherwise. */
+    userId: string | null;
+    /**
+     * Computed uniqueness key (`userId ?? tenantId ?? '__app__'`), set in
+     * `save()`. Used ONLY by `conflictColumns` so the unique index stays total
+     * while `tenantId`/`userId` are nullable — mirrors `PromptOverride.context`.
+     * Never read it for scoping logic; `scopeType` + the typed columns own that.
+     */
+    scopeKey: string;
+    /** JSON-encoded default value; NULL = inherit. JSON `null` = "default to null". */
+    defaultValue: string | null;
+    /** Visibility override ('basic' | 'advanced' | 'hidden'); NULL = inherit. */
+    visibility: FieldPolicyVisibility | null;
+    /** Help text override; NULL = inherit (code seed: field description). */
+    help: string | null;
+    /** Label override; NULL = inherit (consumers derive from the field name). */
+    label: string | null;
+    /**
+     * Sort-order override; NULL = inherit (code seed: `ui.order`). Named
+     * `displayOrder` because a column literally named `order` is an SQL keyword
+     * the runtime INSERT path does not quote; resolved output exposes `order`.
+     */
+    displayOrder: number | null;
+    /**
+     * Org lock (app/tenant rows only): when the effective lock is true, the
+     * user tier may not override this field. NULL = inherit (code seed:
+     * `ui.locked`); org rows may set `false` to explicitly unlock.
+     */
+    locked: boolean | null;
+    /** Audit attribution for #2050 ("who changed what"); not validated. */
+    updatedBy: string | null;
+    constructor(options?: FieldPolicyOptions);
+    /** Parse the stored JSON default. `undefined` = no stored default (inherit). */
+    getDefaultValue(): unknown;
+    /** Serialize a default value; `undefined` clears the override (inherit). */
+    setDefaultValue(value: unknown): void;
+    save(): Promise<this>;
+    private saveAfterIdentityChange;
+    private saveAfterIdentityChangeInTransaction;
+    private saveAfterIdentityChangeWithDeferredDelete;
+    delete(): Promise<void>;
+    private validateFieldPolicy;
+    /**
+     * Effective org-tier (code → app → tenant hierarchy) policy for this row's
+     * field, computed by the RESOLVER so write-time checks share the one
+     * precedence implementation — including ancestor-tenant cascades via the
+     * default hierarchy loader. The chain tenant is the row's own tenant for
+     * tenant-scope rows, the ambient context tenant for user-scope rows, and
+     * none for app-scope rows (their only lower layer is the code seed).
+     *
+     * During an update, the persisted row is excluded from the lower-layer
+     * projection. That makes a clear-default + required-field demotion validate
+     * the post-write policy rather than accidentally counting the row being
+     * replaced.
+     */
+    private resolveOrgTierFieldPolicy;
+    /**
+     * Exactly-one-owner scope shape: app rows carry neither id, tenant rows
+     * carry only `tenantId`, user rows carry only `userId` (the user tier is
+     * keyed by user alone so preferences follow the user across tenants).
+     */
+    private validateScopeConsistency;
+    /** `userId ?? tenantId ?? '__app__'` — the `conflictColumns` scope key. */
+    private computeScopeKey;
+    /**
+     * Derive a scope-owner column the transport could not carry (#2047).
+     *
+     * Core's mass-assignment guard treats `tenantId` as server-managed and
+     * strips it from EVERY generated create/update body, and `FieldPolicy` is
+     * deliberately not `@TenantScoped`, so the tenancy interceptor never
+     * repopulates it. A `POST {scopeType:'tenant', tenantId}` therefore always
+     * reached `validateScopeConsistency` with `tenantId === null`, making the
+     * org tier write-dead over every generated surface — the model, as the
+     * single validation authority for these rows, fills it in instead.
+     *
+     * This grants nothing: `assertScopeOwnedByAmbientContext` already requires
+     * a non-bypass caller's tenant/user rows to name exactly the ambient
+     * tenant/user, so the derived value is the ONLY value that could ever have
+     * been accepted. An explicit value is never overwritten (a super-admin
+     * bypass caller keeps naming other scopes), and with neither tenancy nor
+     * authenticated-session context nothing is derived — scope-shape validation
+     * rejects the row as before.
+     * Consequence: a bypass caller writing ANOTHER tenant's row must pass
+     * `tenantId` through a server-side model call, because the generated routes
+     * still strip it.
+     */
+    private attributeScopeToAmbientContext;
+    /**
+     * Fail-closed write boundary against the ambient tenant context, applied to
+     * the NEW scope on save and to the PERSISTED scope on save/delete of an
+     * existing row.
+     *
+     * With NO ambient identity at all (neither tenant ALS nor authenticated
+     * session-permission ALS), only app-scope rows are accepted: tenant- and
+     * user-scope rows are unattributable without a context, so they are
+     * rejected outright rather than allowed by default. Inside a non-bypass
+     * context, a caller may only touch rows for its own tenant, and user rows
+     * only for its own user id — a context that carries NO user id may not
+     * touch the user tier at all.
+     * App-wide rows then require super-admin bypass (or a context-less/system
+     * caller).
+     *
+     * Package rule: a missing identity component DENIES, it never skips.
+     */
+    private assertScopeOwnedByAmbientContext;
+    private validateTenantContextBoundary;
+    /**
+     * Permission boundary for policy mutations. Scope ownership is checked
+     * separately (and first) because permission never grants cross-tenant or
+     * cross-user access. Existing rows are checked against their persisted
+     * scope before an identity-changing save can mutate or delete them.
+     */
+    private assertScopePermission;
+    private validateDefaultAgainstSecurityRail;
+    private parseDefaultValueOrThrow;
+    /**
+     * The persisted row this save/delete would replace, looked up by primary
+     * key and — when that misses — by the NATURAL key.
+     *
+     * The natural-key fallback is load-bearing for authorization: every
+     * generated create arrives with a freshly minted UUID, so a primary-key
+     * lookup always misses, yet the `conflictColumns` upsert still overwrites
+     * whatever row already occupies `(objectRef, fieldName, scopeType,
+     * scopeKey)`. Authorizing on the primary key alone therefore skipped the
+     * persisted-scope guard on exactly the path that can replace an existing
+     * row's contents.
+     */
+    private getPersistedIdentity;
+    private getPersistedRowById;
+    /**
+     * The row occupying this row's `conflictColumns` tuple, if any. Column
+     * names are the physical snake_case ones: this reads the driver directly
+     * rather than through a collection (the model has no collection handle).
+     */
+    private getPersistedRowByNaturalKey;
+    private normalizeDefaultValueForPersistence;
+}
+//# sourceMappingURL=FieldPolicy.d.ts.map

package/dist/models/FieldPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldPolicy.d.ts","sourceRoot":"","sources":["../../src/models/FieldPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,UAAU,EAEX,MAAM,0BAA0B,CAAC;AA4BlC,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAE3B,MAAM,aAAa,CAAC;AA6GrB;;;;;;;;;;;;;GAaG;AASH,qBAgBa,WAAY,SAAQ,UAAU;IACzC,6EAA6E;IAE7E,SAAS,EAAE,MAAM,CAAM;IAEvB,wEAAwE;IAExE,SAAS,EAAE,MAAM,CAAM;IAEvB,kEAAkE;IAElE,SAAS,EAAE,oBAAoB,CAAS;IAExC,+EAA+E;IAE/E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,uDAAuD;IAEvD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE7B;;;;;OAKG;IAEH,QAAQ,EAAE,MAAM,CAAM;IAEtB,mFAAmF;IAEnF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEnC,6EAA6E;IAE7E,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAAQ;IAEhD,yEAAyE;IAEzE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE3B,6EAA6E;IAE7E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE5B;;;;OAIG;IAEH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEnC;;;;OAIG;IAEH,MAAM,EAAE,OAAO,GAAG,IAAI,CAAQ;IAE9B,uEAAuE;IAEvE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAEpB,OAAO,GAAE,kBAAuB;IAsC5C,gFAAgF;IAChF,eAAe,IAAI,OAAO;IAW1B,4EAA4E;IAC5E,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAkDtB,uBAAuB;YAQvB,oCAAoC;YA+BpC,yCAAyC;IA6BxC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;YAiBxB,mBAAmB;IA8HjC;;;;;;;;;;;;OAYG;YACW,yBAAyB;IAuBvC;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAwBhC,2EAA2E;IAC3E,OAAO,CAAC,eAAe;IAIvB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,8BAA8B;IAatC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,gCAAgC;IA0ExC,OAAO,CAAC,6BAA6B;IAWrC;;;;;OAKG;YACW,qBAAqB;IAoBnC,OAAO,CAAC,kCAAkC;IAwB1C,OAAO,CAAC,wBAAwB;IAkBhC;;;;;;;;;;;OAWG;YACW,oBAAoB;YAkCpB,mBAAmB;IAQjC;;;;OAIG;YACW,2BAA2B;IAgBzC,OAAO,CAAC,mCAAmC;CAiB5C"}

package/dist/permissions.d.ts

@@ -0,0 +1,9 @@
+import { PermissionDefinition } from '@happyvertical/smrt-users';
+/** Authorizes app- and tenant-scope field-policy administration. */
+export declare const MANAGE_FIELD_POLICY_PERMISSION = "fields.policy.manage";
+/** Authorizes a principal to maintain their own user-scope field policy. */
+export declare const PERSONALIZE_FIELD_POLICY_PERMISSION = "fields.policy.personalize";
+export declare const FIELD_POLICY_PERMISSION_DEFINITIONS: PermissionDefinition[];
+/** Register field-policy permissions once when smrt-fields is loaded. */
+export declare function ensureFieldPolicyPermissionsRegistered(): void;
+//# 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,oEAAoE;AACpE,eAAO,MAAM,8BAA8B,yBAAyB,CAAC;AAErE,4EAA4E;AAC5E,eAAO,MAAM,mCAAmC,8BAA8B,CAAC;AAE/E,eAAO,MAAM,mCAAmC,EAAE,oBAAoB,EAarE,CAAC;AAIF,yEAAyE;AACzE,wBAAgB,sCAAsC,IAAI,IAAI,CAM7D"}

package/dist/playground.d.ts

@@ -0,0 +1,2 @@
+export { default } from './svelte/playground.js';
+//# sourceMappingURL=playground.d.ts.map

package/dist/playground.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playground.d.ts","sourceRoot":"","sources":["../src/playground.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/playground.js

@@ -0,0 +1,39 @@
+//#region src/svelte/playground.ts
+var loadFieldPolicyForm = () => import("./svelte/playground/FieldPolicyFormPreview.svelte");
+var loadObjectForm = () => import("./svelte/playground/ObjectFormPreview.svelte");
+var playground_default = {
+	packageName: "@happyvertical/smrt-fields",
+	displayName: "Field Policies",
+	description: "Headless form primitives: FieldPolicyProvider, PolicyField, basic/advanced modes, and manifest-sourced help.",
+	entries: [{
+		id: "policy-form",
+		title: "Policy-Driven Form",
+		description: "A hand-written product form adopting PolicyField on a subset of fields — visibility by mode, default prefill, help hints, and the form-level glossary.",
+		loadComponent: loadFieldPolicyForm,
+		order: 1,
+		tags: [
+			"forms",
+			"fields",
+			"policy",
+			"defaults"
+		],
+		modes: { mock: { label: "Mock" } }
+	}, {
+		id: "object-form",
+		title: "Generated ObjectForm",
+		description: "A reusable create/edit form from generated web fields and resolved policy, including advanced groups and a per-field custom renderer.",
+		loadComponent: loadObjectForm,
+		order: 2,
+		tags: [
+			"forms",
+			"fields",
+			"object-form",
+			"registry"
+		],
+		modes: { mock: { label: "Mock" } }
+	}]
+};
+//#endregion
+export { playground_default as default };
+
+//# sourceMappingURL=playground.js.map

package/dist/playground.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playground.js","names":[],"sources":["../src/svelte/playground.ts"],"sourcesContent":["/**\n * Field-policy playground previews (#2048).\n *\n * Registered with the shared playground host via the auto-discovered\n * \"packages/STAR/src/svelte/playground.ts\" convention (smrt-playground vite\n * plugin).\n */\nconst loadFieldPolicyForm = () =>\n  import('./playground/FieldPolicyFormPreview.svelte');\nconst loadObjectForm = () => import('./playground/ObjectFormPreview.svelte');\n\nexport default {\n  packageName: '@happyvertical/smrt-fields',\n  displayName: 'Field Policies',\n  description:\n    'Headless form primitives: FieldPolicyProvider, PolicyField, basic/advanced modes, and manifest-sourced help.',\n  entries: [\n    {\n      id: 'policy-form',\n      title: 'Policy-Driven Form',\n      description:\n        'A hand-written product form adopting PolicyField on a subset of fields — visibility by mode, default prefill, help hints, and the form-level glossary.',\n      loadComponent: loadFieldPolicyForm,\n      order: 1,\n      tags: ['forms', 'fields', 'policy', 'defaults'],\n      modes: {\n        mock: {\n          label: 'Mock',\n        },\n      },\n    },\n    {\n      id: 'object-form',\n      title: 'Generated ObjectForm',\n      description:\n        'A reusable create/edit form from generated web fields and resolved policy, including advanced groups and a per-field custom renderer.',\n      loadComponent: loadObjectForm,\n      order: 2,\n      tags: ['forms', 'fields', 'object-form', 'registry'],\n      modes: { mock: { label: 'Mock' } },\n    },\n  ],\n};\n"],"mappings":";AAOA,IAAM,4BACJ,OAAO;AACT,IAAM,uBAAuB,OAAO;AAEpC,IAAA,qBAAe;CACb,aAAa;CACb,aAAa;CACb,aACE;CACF,SAAS,CACP;EACE,IAAI;EACJ,OAAO;EACP,aACE;EACF,eAAe;EACf,OAAO;EACP,MAAM;GAAC;GAAS;GAAU;GAAU;EAAU;EAC9C,OAAO,EACL,MAAM,EACJ,OAAO,OACT,EACF;CACF,GACA;EACE,IAAI;EACJ,OAAO;EACP,aACE;EACF,eAAe;EACf,OAAO;EACP,MAAM;GAAC;GAAS;GAAU;GAAe;EAAU;EACnD,OAAO,EAAE,MAAM,EAAE,OAAO,OAAO,EAAE;CACnC,CACF;AACF"}

package/dist/settings-catalog.d.ts

@@ -0,0 +1,73 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { FieldPolicyCollection } from './collections/FieldPolicyCollection.js';
+import { FieldPolicyAuditSnapshot } from './types.js';
+export interface FieldPolicyCatalogField {
+    type: 'text' | 'integer' | 'decimal' | 'boolean' | 'datetime' | 'json' | 'foreignKey' | 'crossPackageRef';
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+    ui?: {
+        basic?: boolean;
+        group?: string;
+        order?: number;
+        locked?: boolean;
+    };
+}
+export interface FieldPolicySummaryItem {
+    id: string;
+    label: string;
+    description?: string;
+    eyebrow?: string;
+    status?: string;
+    objectRef: string;
+    fieldName: string;
+    className: string;
+    packageName: string;
+}
+export interface FieldPolicyDetailItem extends FieldPolicySummaryItem {
+    fields: Record<string, FieldPolicyCatalogField>;
+}
+/** Structural SettingsCatalogPage mirror; `SettingsCatalog` accepts it directly. */
+export interface FieldPolicySettingsCatalogPage {
+    items: FieldPolicySummaryItem[];
+    selected: FieldPolicyDetailItem | null;
+    query: string;
+    page: number;
+    pageSize: number;
+    total: number;
+}
+export interface FieldPolicyCatalogObjectSummary {
+    objectRef: string;
+    className: string;
+    packageName: string;
+    fieldCount: number;
+}
+export interface FieldPolicySettingsCatalogData {
+    page: FieldPolicySettingsCatalogPage;
+    audit: FieldPolicyAuditSnapshot;
+    objects: FieldPolicyCatalogObjectSummary[];
+    packages: string[];
+    filters: {
+        packageFilter: string | null;
+        objectFilter: string | null;
+        customizedOnly: boolean;
+    };
+}
+export interface FieldPolicySettingsCatalogQuery {
+    query?: string | null;
+    page?: number | null;
+    pageSize?: number | null;
+    selectedId?: string | null;
+    packageFilter?: string | null;
+    objectFilter?: string | null;
+    customizedOnly?: boolean;
+}
+export interface BuildFieldPolicySettingsCatalogOptions extends FieldPolicySettingsCatalogQuery {
+    db?: SmrtClassOptions['db'];
+    collection?: FieldPolicyCollection;
+    objectRefs?: string[];
+}
+export declare function fieldPolicyCatalogItemId(objectRef: string, fieldName: string): string;
+export declare function parseFieldPolicyCatalogQuery(params: URLSearchParams): FieldPolicySettingsCatalogQuery;
+export declare function buildFieldPolicySettingsCatalog(options: BuildFieldPolicySettingsCatalogOptions): Promise<FieldPolicySettingsCatalogData>;
+//# sourceMappingURL=settings-catalog.d.ts.map

package/dist/settings-catalog.d.ts.map

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

package/dist/smrt-knowledge.json

@@ -2,27 +2,35 @@
   "schemaVersion": 1,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-fields",
-  "packageVersion": "0.40.59",
+  "packageVersion": "0.40.61",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "6ecb2cee7792ee1e7d091c4a1c79f331e89bc148a324fb3123b4f89bcb59f54e",
-    "packageJson": "a347821b7feaf36c9e748e86eddb3abcf4eab892646e1e700de9154d215ec4b9",
-    "agents": "efe605cdabdde966a22fc43d94af0275bfb1ce5e2027b52809c69837e3d5dc0c"
+    "manifest": "7bda54a2c54dad0a830732576d2880a42cb75e291729b23a1604243775a735c7",
+    "packageJson": "6a20590d3e6f0e8aa1f5e5adb1e862ac103f10ef4bda818a6212e3625a17d1f8",
+    "agents": "6e3f776e4a585c5d21f0d9168687bf2eafefe17508c69a1c8870e9034ac2ec72"
   },
   "exports": [
     ".",
     "./manifest",
-    "./manifest.json"
+    "./manifest.json",
+    "./playground",
+    "./svelte"
   ],
   "dependencies": {
     "@happyvertical/smrt-core": "workspace:*",
     "@happyvertical/smrt-tenancy": "workspace:*",
+    "@happyvertical/smrt-ui": "workspace:*",
+    "@happyvertical/smrt-users": "workspace:*",
     "@happyvertical/sql": "catalog:",
     "@happyvertical/smrt-cli": "workspace:*",
-    "@happyvertical/smrt-users": "workspace:*",
     "@happyvertical/smrt-vitest": "workspace:*",
+    "@sveltejs/package": "^2.5.8",
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@testing-library/svelte": "^5.4.2",
     "@types/node": "24.13.2",
+    "svelte": "^5.56.4",
+    "svelte-check": "^4.7.1",
     "typescript": "5.9.3",
     "vite": "8.1.4",
     "vitest": "4.1.10"
@@ -31,6 +39,7 @@
     "@happyvertical/smrt-cli",
     "@happyvertical/smrt-core",
     "@happyvertical/smrt-tenancy",
+    "@happyvertical/smrt-ui",
     "@happyvertical/smrt-users",
     "@happyvertical/smrt-vitest"
   ],
@@ -51,8 +60,10 @@
       "relationships": [],
       "methods": [
         "getAppRows",
+        "getEditorState",
         "getTenantRows",
         "getUserRows",
+        "policyAudit",
         "resolveBatch"
       ],
       "surfaces": [
@@ -87,6 +98,22 @@
           "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection",
           "path": "/fieldpolicies/resolveBatch",
           "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "fieldpolicies.getEditorState",
+          "operation": "getEditorState",
+          "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection",
+          "path": "/fieldpolicies/getEditorState",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "fieldpolicies.policyAudit",
+          "operation": "policyAudit",
+          "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection",
+          "path": "/fieldpolicies/policyAudit",
+          "method": "POST"
         }
       ],
       "relationshipFeatures": [
@@ -291,6 +318,22 @@
       "path": "/fieldpolicies/resolveBatch",
       "method": "POST"
     },
+    {
+      "kind": "api",
+      "name": "fieldpolicies.getEditorState",
+      "operation": "getEditorState",
+      "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection",
+      "path": "/fieldpolicies/getEditorState",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "fieldpolicies.policyAudit",
+      "operation": "policyAudit",
+      "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection",
+      "path": "/fieldpolicies/policyAudit",
+      "method": "POST"
+    },
     {
       "kind": "api",
       "name": "fieldpolicies.create",
@@ -343,5 +386,5 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 5
   },
-  "agentDoc": "# smrt-fields\n\nLayered field policy store and resolution engine (epic #2045). Personalizes\nper-field `{defaultValue, visibility, help, label, order, locked}` for any\n`@smrt()` object at app, tenant, and user scope over the code seed.\n\n## Core pieces\n\n- `FieldPolicy` (`_smrt_field_policies` table) — sparse override rows keyed\n  `(objectRef, fieldName, scopeType, scopeKey)`; NULL column = inherit from\n  the lower layer, reset = row DELETE (later lower-layer changes flow through)\n- `FieldPolicyCollection` — write surface plus the `resolveBatch` custom\n  collection-scoped action (`POST /<collection>/resolve`). NO generated\n  surface exposes read verbs: API `list`/`get` on this non-tenant-scoped\n  model would enumerate every tenant's and user's rows; the model's CLI is\n  writes-only (the generated CLI invokes over HTTP, and the cli↔api\n  coherence gate rejects CLI entries without API routes); the runtime\n  CLI/MCP surfaces are closed by the collection config (ContentContributions\n  precedent). Reads go through `resolveBatch` (context-scoped) or the\n  server-side resolver. Keep the api include lists in lockstep: a decorated\n  collection's config is the RUNTIME registry authority for its item class,\n  while build-time generation reads each manifest object's own config. Both\n  transports dispatch the action: generated SvelteKit routes natively, and\n  core's runtime `APIGenerator` via its decorator-route dispatch\n  (single-segment collection-scoped paths; multi-segment custom paths remain\n  SvelteKit-only).\n- `resolveFieldPolicy(objectRef, { tenantId, userId, db })` — merged policy\n- `resolveFieldPolicyExplained(...)` — merged policy plus ordered per-layer\n  contributions (code/app/tenant/user) for gear/admin UIs (#2049/#2050)\n\n## Resolution layers (priority low → high)\n\n1. Code seed — manifest field defaults, `description` as help, `_meta.ui`\n   hints (#2046: `basic`/`group`/`order`/`locked`; cold-start rule: no\n   `basic` markers ⇒ everything basic, any marker ⇒ unmarked fields advanced)\n2. App rows — `scopeType: 'app'`, `tenantId`/`userId` null\n3. Tenant rows — hierarchy walk root → leaf via an injected\n   `tenantHierarchyLoader` (smrt-features shape); the default loader\n   dynamic-imports `@happyvertical/smrt-users` (missing-package failures —\n   `ERR_MODULE_NOT_FOUND` / \"Cannot find package\" across the cause chain —\n   fall back to a flat single-tenant chain). A node that breaks permission\n   inheritance discards every earlier tenant contribution (chain-structural),\n   so only the suffix from the LAST break participates — in merging AND in\n   the explained layers, which therefore replay to the merged result\n4. User rows — keyed by `userId` alone (preferences follow the user); both\n   defaults AND visibility resolve through this tier\n\n## Invariants\n\n- **Scope shape**: app ⇒ `tenantId`+`userId` null; tenant ⇒ only `tenantId`;\n  user ⇒ only `userId`. `scopeKey` (`userId ?? tenantId ?? '__app__'`) exists\n  ONLY to keep the `conflictColumns` unique index total — never read it for\n  scoping logic.\n- **Manifest as definition registry**: writes validate against the live\n  `ObjectRegistry` (never checked-in manifest.json artifacts): unknown\n  objectRef/fieldName rejected; defaults type-checked against the field type;\n  system fields, relationship pseudo-fields, and STI meta storage fields are\n  not policy-addressable (the resolver excludes them, so rows would silently\n  never apply).\n- **Security rail**: defaults are refused on `transient`, `sensitive`, and\n  `readPermission`-gated fields (both top-level and `_meta` flags checked).\n  Reference-field (`foreignKey`/`crossPackageRef`) defaults must be UUID\n  strings unless the field declares `idType: 'text'` — the columns are\n  native UUID on PostgreSQL/DuckDB and a non-UUID default would fail at\n  insert time. `resolveBatch` responses omit sensitive/read-permission-gated\n  fields for every caller (fail closed) and transient fields\n  (client-emission parity).\n- **Required-field invariant**: demoting a required field to\n  advanced/hidden requires a usable resolved default (not null/empty) —\n  enforced at write time AND re-enforced at resolution (a required field with\n  no usable default always resolves `basic`, flagged `visibilityForced`).\n- **Org lock**: `locked` may be set on app/tenant rows only; while the\n  code/app/tenant tiers resolve locked, user-scope writes are rejected and\n  existing user rows are skipped at resolution.\n- **Write-time org checks reuse the resolver**: the required-demotion default\n  and the user-write lock are computed by `resolveFieldPolicy` over the org\n  tiers (default hierarchy loader), so cascading ancestor-tenant defaults and\n  locks are honored at save time too. On updates the resolver sees the row's\n  persisted version (no self-exclusion), so the resolver-side safety net\n  remains the authoritative enforcement at read time.\n- **Isolation — a MISSING identity component DENIES, it never skips.** This\n  is the package rule; both the write guard\n  (`FieldPolicy.assertScopeOwnedByAmbientContext`) and the read guard\n  (`assertResolutionAllowedInContext`) obey it. A non-bypass tenant context\n  may only resolve/write its own tenant, and the user tier only for its own\n  user id — a context carrying permissions but NO `userId` (no `resolveUserId`\n  hook configured: API-key auth, service principals, background jobs, a bare\n  `withTenant({ tenantId })`) may not touch the user tier at all. Skipping\n  that check instead of denying it was a live ownership bypass: user rows are\n  `tenantId: null` by design, so nothing else contains such a write. App-scope\n  writes inside a tenant context require super-admin bypass. With NO ambient\n  identity at all (tenancy ALS never entered), only app-scope writes/deletes\n  are accepted; context-LESS *reads* stay allowed because\n  `resolveFieldPolicy` is a trusted server-side API. Residual: ALS-less\n  deployments can still write APP rows with any authenticated principal until\n  the #2049 permission layer adds `fields:policy:manage`. `save()`/`delete()`\n  on an existing row additionally authorize against the row's PERSISTED\n  scope, looked up by primary key AND — because a generated create always\n  mints a fresh UUID while the `conflictColumns` upsert still replaces the\n  occupant — by NATURAL key. `resolveBatch` takes identity exclusively from\n  the ambient context; the request body cannot select another tenant or user.\n- **Scope attribution**: inside an ambient context the model DERIVES a\n  missing `tenantId` (tenant rows) or `userId` (user rows) from that context,\n  and always stamps `updatedBy` from it. Core's mass-assignment guard treats\n  `tenantId` as server-managed and strips it from every generated write body\n  while `FieldPolicy` is deliberately not `@TenantScoped`, so without this the\n  org tier is write-dead over REST/SvelteKit (scope-shape validation throws).\n  Deriving grants nothing — the ownership guard already pinned the value to\n  the ambient one. An explicit value is never overwritten, so a super-admin\n  bypass caller writing ANOTHER tenant's row must go through a server-side\n  model call; the generated routes still strip it.\n\n## Caching and invalidation\n\n- Resolver results cached per\n  `(dbNamespace, objectRef, tenantId, userId, hierarchyLoader)` with a 30s TTL\n  (`cache.ts` mirrors smrt-prompts' `getDbNamespace`). The loader identity is\n  part of the key because an injected `tenantHierarchyLoader` yields a\n  different ancestor chain — and so different defaults/locks — for the same\n  `(db, objectRef, tenant, user)`; it goes LAST so the `(db, objectRef)`\n  prefix scan still invalidates every loader's entries.\n- `FieldPolicy.save()`/`.delete()` invalidate ALL entries for the row's\n  `(db, objectRef)` — coarser than prompts because tenant hierarchy makes a\n  parent-tenant row affect every descendant's resolution.\n- `_smrt_field_policies` rows do NOT ride the client change feed: core's\n  change-feed writer deliberately skips `_smrt_`-prefixed system tables, and\n  the emit side is private. Live client invalidation is a core-side decision;\n  do not add custom push/emit paths here.\n\n## Gotchas\n\n- Defaults have TWO explicit constructor channels, never sniffed:\n  `defaultValue` is ALREADY JSON-encoded (the wire contract — generated write\n  routes hand the request body straight to the constructor, and #2049's gear\n  posts `JSON.stringify(draft.defaultValue)`), while `defaultValueRaw` is a\n  plain value that is always serialized, strings included. Passing both throws.\n  One option cannot carry both meanings: `'\"TBD\"'` and `'TBD'` are\n  indistinguishable, so `{ defaultValue: 'Net 30' }` is a parse error that\n  names `defaultValueRaw` in its message. `setDefaultValue()` is the\n  method-level plain channel.\n- The sort-order column is `displayOrder` (resolved output exposes `order`):\n  a column literally named `order` is an SQL keyword the runtime INSERT path\n  does not quote.\n- `FieldPolicy` deliberately has NO class-level `@TenantScoped` (the\n  prompts/features precedent): resolution legitimately reads app rows and\n  ancestor-tenant rows, which the tenancy interceptor would block. Isolation\n  is enforced at the resolver/save boundaries instead.\n- Identity changes (objectRef/fieldName/scope) on a persisted row go through\n  delete-then-insert (transactional when the driver supports it) because the\n  natural-key upsert would otherwise collide with the primary key.\n- `FieldPolicyCollection` MUST repeat FieldPolicy's `conflictColumns`. A\n  decorated collection emits its OWN manifest schema for the item's table, and\n  without the natural key that schema falls back to SmrtObject's default unique\n  `(slug, context)` index; manifest-driven migrations aggregate both onto\n  `_smrt_field_policies`, where the stray index rejects legitimate layered rows\n  (all policy rows have NULL slug/context). The runtime registry cannot catch\n  this — `getAllSchemas()` is keyed by TABLE name, so the two schemas collapse\n  into one entry. Pinned against the generated manifest in\n  `generated-surfaces.test.ts`.\n- `withSystemContext()` does NOT unlock tenant/user-scope writes:\n  `getCurrentTenant()` returns undefined inside it, so the context-absent rule\n  rejects those tiers before any bypass check. Seeds and migrations that must\n  write org/user rows use a `superAdminBypass` context instead.\n- The MODEL's `cli`/`mcp` decorator config is dead at runtime: the registry\n  re-registers the item slot with the COLLECTION's config wholesale, so\n  `FieldPolicyCollection`'s `cli: false, mcp: false` is what actually closes\n  those surfaces. Keep both in lockstep anyway — build-time generation reads\n  the model's own config. Related: `ObjectRegistry.getTableName(\n  'FieldPolicyCollection')` resolves to the UNPREFIXED collection fallback\n  `field_policies`; persistence uses the item class\n  (`_smrt_field_policies`), and both are pinned in\n  `generated-surfaces.test.ts`.\n\n## Related\n\n- `@happyvertical/smrt-prompts` / `smrt-languages` / `smrt-features` — the\n  same architecture family (override rows + layered resolver + TTL cache)\n- Core `FieldUIHints` (#2046) — the `@field({ ui })` code seed this package\n  resolves over\n"
+  "agentDoc": "# smrt-fields\n\nLayered field policy store and resolution engine (epic #2045). Personalizes\nper-field `{defaultValue, visibility, help, label, order, locked}` for any\n`@smrt()` object at app, tenant, and user scope over the code seed.\n\n## Core pieces\n\n- `FieldPolicy` (`_smrt_field_policies` table) — sparse override rows keyed\n  `(objectRef, fieldName, scopeType, scopeKey)`; NULL column = inherit from\n  the lower layer, reset = row DELETE (later lower-layer changes flow through)\n- `FieldPolicyCollection` — write surface plus the `resolveBatch` custom\n  collection-scoped action (`POST /<collection>/resolve`). NO generated\n  surface exposes read verbs: API `list`/`get` on this non-tenant-scoped\n  model would enumerate every tenant's and user's rows; the model's CLI is\n  writes-only (the generated CLI invokes over HTTP, and the cli↔api\n  coherence gate rejects CLI entries without API routes); the runtime\n  CLI/MCP surfaces are closed by the collection config (ContentContributions\n  precedent). Reads go through `resolveBatch` (context-scoped) or the\n  server-side resolver. Keep the api include lists in lockstep: a decorated\n  collection's config is the RUNTIME registry authority for its item class,\n  while build-time generation reads each manifest object's own config. Both\n  transports dispatch the action: generated SvelteKit routes natively, and\n  core's runtime `APIGenerator` via its decorator-route dispatch\n  (single-segment collection-scoped paths; multi-segment custom paths remain\n  SvelteKit-only).\n- `resolveFieldPolicy(objectRef, { tenantId, userId, db })` — merged policy\n- `resolveFieldPolicyExplained(...)` — merged policy plus ordered per-layer\n  contributions (code/app/tenant/user) for gear/admin UIs (#2049/#2050)\n\n## Resolution layers (priority low → high)\n\n1. Code seed — manifest field defaults, `description` as help, `_meta.ui`\n   hints (#2046: `basic`/`group`/`order`/`locked`; cold-start rule: no\n   `basic` markers ⇒ everything basic, any marker ⇒ unmarked fields advanced)\n2. App rows — `scopeType: 'app'`, `tenantId`/`userId` null\n3. Tenant rows — hierarchy walk root → leaf via an injected\n   `tenantHierarchyLoader` (smrt-features shape); the default loader\n   uses `@happyvertical/smrt-users`' `TenantCollection`; an injected loader\n   may return no provider (or no chain for a tenant), which falls back to a\n   flat single-tenant chain. `smrt-users` itself is a required Fields runtime\n   dependency for policy authorization, not an optional hierarchy dependency.\n   A node that breaks permission\n   inheritance discards every earlier tenant contribution (chain-structural),\n   so only the suffix from the LAST break participates — in merging AND in\n   the explained layers, which therefore replay to the merged result\n4. User rows — keyed by `userId` alone (preferences follow the user); both\n   defaults AND visibility resolve through this tier\n\n## Invariants\n\n- **Scope shape**: app ⇒ `tenantId`+`userId` null; tenant ⇒ only `tenantId`;\n  user ⇒ only `userId`. `scopeKey` (`userId ?? tenantId ?? '__app__'`) exists\n  ONLY to keep the `conflictColumns` unique index total — never read it for\n  scoping logic.\n- **Manifest as definition registry**: writes validate against the live\n  `ObjectRegistry` (never checked-in manifest.json artifacts): unknown\n  objectRef/fieldName rejected; defaults type-checked against the field type;\n  system fields, relationship pseudo-fields, and STI meta storage fields are\n  not policy-addressable (the resolver excludes them, so rows would silently\n  never apply).\n- **Security rail**: defaults are refused on `transient`, `sensitive`, and\n  `readPermission`-gated fields (both top-level and `_meta` flags checked).\n  Reference-field (`foreignKey`/`crossPackageRef`) defaults must be UUID\n  strings unless the field declares `idType: 'text'` — the columns are\n  native UUID on PostgreSQL/DuckDB and a non-UUID default would fail at\n  insert time. `resolveBatch` responses omit sensitive/read-permission-gated\n  fields for every caller (fail closed) and transient fields\n  (client-emission parity).\n- **Required-field invariant**: demoting a required field to\n  advanced/hidden requires a usable resolved default (not null/empty) —\n  enforced at write time AND re-enforced at resolution (a required field with\n  no usable default always resolves `basic`, flagged `visibilityForced`).\n- **Org lock**: `locked` may be set on app/tenant rows only; while the\n  code/app/tenant tiers resolve locked, user-scope writes are rejected and\n  existing user rows are skipped at resolution.\n- **Write-time org checks reuse the resolver**: the required-demotion default\n  and the user-write lock are computed by `resolveFieldPolicy` over the org\n  tiers (default hierarchy loader), so cascading ancestor-tenant defaults and\n  locks are honored at save time too. On updates the persisted row is excluded\n  from projected lower-layer resolution, so clearing the row's only default\n  while demoting a required field is rejected before mutation; that projected\n  lookup bypasses the shared cache. The resolver-side safety net remains\n  authoritative when a different row is later deleted.\n- **Isolation — a MISSING identity component DENIES, it never skips.** This\n  is the package rule; both the write guard\n  (`FieldPolicy.assertScopeOwnedByAmbientContext`) and the read guard\n  (`assertResolutionAllowedInContext`) obey it. A non-bypass tenant context\n  may only resolve/write its own tenant, and the user tier only for its own\n  user id — a context carrying permissions but NO `userId` (no `resolveUserId`\n  hook configured: API-key auth, service principals, background jobs, a bare\n  `withTenant({ tenantId })`) may not touch the user tier at all. Skipping\n  that check instead of denying it was a live ownership bypass: user rows are\n  `tenantId: null` by design, so nothing else contains such a write. App-scope\n  writes inside a tenant context require super-admin bypass. `fields.policy.manage`\n  authorizes app/tenant policy mutations; `fields.policy.personalize` authorizes\n  only the caller's user tier (default-seeded for built-in roles). With NO ambient\n  identity at all (tenancy ALS never entered), policy writes/deletes fail closed;\n  trusted system and super-admin contexts retain their explicit bypasses.\n  Context-LESS *reads* stay allowed because `resolveFieldPolicy` is a trusted\n  server-side API. `save()`/`delete()`\n  on an existing row additionally authorize against the row's PERSISTED\n  scope, looked up by primary key AND — because a generated create always\n  mints a fresh UUID while the `conflictColumns` upsert still replaces the\n  occupant — by NATURAL key. `resolveBatch` takes identity exclusively from\n  the ambient context; the request body cannot select another tenant or user.\n- **Scope attribution**: inside an ambient context the model DERIVES a\n  missing `tenantId` (tenant rows) or `userId` (user rows) from that context,\n  and always stamps `updatedBy` from it. Core's mass-assignment guard treats\n  `tenantId` as server-managed and strips it from every generated write body\n  while `FieldPolicy` is deliberately not `@TenantScoped`, so without this the\n  org tier is write-dead over REST/SvelteKit (scope-shape validation throws).\n  Deriving grants nothing — the ownership guard already pinned the value to\n  the ambient one. An explicit value is never overwritten, so a super-admin\n  bypass caller writing ANOTHER tenant's row must go through a server-side\n  model call; the generated routes still strip it.\n\n## Caching and invalidation\n\n- Resolver results cached per\n  `(dbNamespace, objectRef, tenantId, userId, hierarchyLoader)` with a 30s TTL\n  (`cache.ts` mirrors smrt-prompts' `getDbNamespace`). The loader identity is\n  part of the key because an injected `tenantHierarchyLoader` yields a\n  different ancestor chain — and so different defaults/locks — for the same\n  `(db, objectRef, tenant, user)`; it goes LAST so the `(db, objectRef)`\n  prefix scan still invalidates every loader's entries.\n- `FieldPolicy.save()`/`.delete()` invalidate ALL entries for the row's\n  `(db, objectRef)` — coarser than prompts because tenant hierarchy makes a\n  parent-tenant row affect every descendant's resolution.\n- `_smrt_field_policies` rows do NOT ride the client change feed: core's\n  change-feed writer deliberately skips `_smrt_`-prefixed system tables, and\n  the emit side is private. Live client invalidation is a core-side decision;\n  do not add custom push/emit paths here.\n\n## Gotchas\n\n- Defaults have TWO explicit constructor channels, never sniffed:\n  `defaultValue` is ALREADY JSON-encoded (the wire contract — generated write\n  routes hand the request body straight to the constructor, and #2049's gear\n  posts `JSON.stringify(draft.defaultValue)`), while `defaultValueRaw` is a\n  plain value that is always serialized, strings included. Passing both throws.\n  One option cannot carry both meanings: `'\"TBD\"'` and `'TBD'` are\n  indistinguishable, so `{ defaultValue: 'Net 30' }` is a parse error that\n  names `defaultValueRaw` in its message. `setDefaultValue()` is the\n  method-level plain channel.\n- The sort-order column is `displayOrder` (resolved output exposes `order`):\n  a column literally named `order` is an SQL keyword the runtime INSERT path\n  does not quote.\n- `FieldPolicy` deliberately has NO class-level `@TenantScoped` (the\n  prompts/features precedent): resolution legitimately reads app rows and\n  ancestor-tenant rows, which the tenancy interceptor would block. Isolation\n  is enforced at the resolver/save boundaries instead.\n- Identity changes (objectRef/fieldName/scope) on a persisted row go through\n  delete-then-insert (transactional when the driver supports it) because the\n  natural-key upsert would otherwise collide with the primary key.\n- `FieldPolicyCollection` MUST repeat FieldPolicy's `conflictColumns`. A\n  decorated collection emits its OWN manifest schema for the item's table, and\n  without the natural key that schema falls back to SmrtObject's default unique\n  `(slug, context)` index; manifest-driven migrations aggregate both onto\n  `_smrt_field_policies`, where the stray index rejects legitimate layered rows\n  (all policy rows have NULL slug/context). The runtime registry cannot catch\n  this — `getAllSchemas()` is keyed by TABLE name, so the two schemas collapse\n  into one entry. Pinned against the generated manifest in\n  `generated-surfaces.test.ts`.\n- `withSystemContext()` does NOT unlock tenant/user-scope writes:\n  `getCurrentTenant()` returns undefined inside it, so the context-absent rule\n  rejects those tiers before any bypass check. Seeds and migrations that must\n  write org/user rows use a `superAdminBypass` context instead.\n- The MODEL's `cli`/`mcp` decorator config is dead at runtime: the registry\n  re-registers the item slot with the COLLECTION's config wholesale, so\n  `FieldPolicyCollection`'s `cli: false, mcp: false` is what actually closes\n  those surfaces. Keep both in lockstep anyway — build-time generation reads\n  the model's own config. Related: `ObjectRegistry.getTableName(\n  'FieldPolicyCollection')` resolves to the UNPREFIXED collection fallback\n  `field_policies`; persistence uses the item class\n  (`_smrt_field_policies`), and both are pinned in\n  `generated-surfaces.test.ts`.\n\n## Svelte generated forms (#2049)\n\n- `ObjectForm` accepts direct generated `fields` plus a resolved `policy` for\n  SSR and explicit hosts, or accepts only `objectRef` beneath an\n  `ObjectFormSourceProvider`. `ObjectFormSourceRegistry` is per app and maps\n  canonical refs to generated web collection definitions before calling the\n  generated `resolveBatch` custom action. It uses structural types only: this\n  package must never import `smrt-web`.\n- Generated custom-action clients resolve `Promise<any>`; validate their\n  `policies[objectRef]` response at the registry boundary and fail closed on a\n  missing/mismatched definition or policy. The component renders an accessible\n  loading state and alert rather than a partial form.\n- Browser manifest types are `text`, `integer`, `decimal`, `boolean`,\n  `datetime`, `json`, `foreignKey`, and `crossPackageRef`; there is no `select`\n  wire type. Apps use the per-app `FieldInputRegistry.registerField` seam for\n  select-like widgets. Reference fields intentionally default to identifier\n  inputs unless an app supplies a chooser.\n- `policyToVisibleColumnIds(policy, columns)` feeds smrt-ui `DataTable`'s\n  `visibleColumnIds`; it filters policy-hidden mapped fields, preserves unmapped\n  computed/action columns, and cannot reveal a static `column.hidden` column.\n\n## Defaults control panel (#2050)\n\n- `buildFieldPolicySettingsCatalog()` is the server-side, URL/GET-driven\n  catalog builder. It structurally targets `SettingsCatalog`, but this package\n  must not import `smrt-svelte`; hosts inject `SettingsCatalog` into\n  `FieldPolicyControlPanel` and retain their own route and transport adapters.\n- `policyAudit` is the only routed organization roll-up. It requires\n  `fields.policy.manage`, returns only the caller tenant's editable rows and\n  read-only app summaries, and represents other users strictly as per-field\n  counts. It resolves only requested page refs; never pre-resolve the catalog.\n- Display code/app/org values by replaying the explained resolver layers, not\n  by independently calculating precedence. Reset and drift prune are ordinary\n  model deletes, so existing scope/permission validation remains authoritative.\n  The panel asks for an explicit confirmation before either destructive action;\n  SSR hosts can inject that confirmation decision instead of relying on\n  `window.confirm`.\n- `fieldPolicyControlPanelNavItem()` is a structural AdminShell tenant-nav\n  seam. It never imports `smrt-svelte` or `smrt-web`; the host supplies the\n  returned entry and must enforce its real route permission server-side.\n\n## Related\n\n- `@happyvertical/smrt-prompts` / `smrt-languages` / `smrt-features` — the\n  same architecture family (override rows + layered resolver + TTL cache)\n- Core `FieldUIHints` (#2046) — the `@field({ ui })` code seed this package\n  resolves over\n"
 }