@happyvertical/smrt-fields 0.40.59 → 0.40.61

package/AGENTS.md

@@ -36,9 +36,11 @@ per-field `{defaultValue, visibility, help, label, order, locked}` for any
 2. App rows — `scopeType: 'app'`, `tenantId`/`userId` null
 3. Tenant rows — hierarchy walk root → leaf via an injected
    `tenantHierarchyLoader` (smrt-features shape); the default loader
-   dynamic-imports `@happyvertical/smrt-users` (missing-package failures —
-   `ERR_MODULE_NOT_FOUND` / "Cannot find package" across the cause chain —
-   fall back to a flat single-tenant chain). A node that breaks permission
+   uses `@happyvertical/smrt-users`' `TenantCollection`; an injected loader
+   may return no provider (or no chain for a tenant), which falls back to a
+   flat single-tenant chain. `smrt-users` itself is a required Fields runtime
+   dependency for policy authorization, not an optional hierarchy dependency.
+   A node that breaks permission
    inheritance discards every earlier tenant contribution (chain-structural),
    so only the suffix from the LAST break participates — in merging AND in
    the explained layers, which therefore replay to the merged result
@@ -75,9 +77,11 @@ per-field `{defaultValue, visibility, help, label, order, locked}` for any
 - **Write-time org checks reuse the resolver**: the required-demotion default
   and the user-write lock are computed by `resolveFieldPolicy` over the org
   tiers (default hierarchy loader), so cascading ancestor-tenant defaults and
-  locks are honored at save time too. On updates the resolver sees the row's
-  persisted version (no self-exclusion), so the resolver-side safety net
-  remains the authoritative enforcement at read time.
+  locks are honored at save time too. On updates the persisted row is excluded
+  from projected lower-layer resolution, so clearing the row's only default
+  while demoting a required field is rejected before mutation; that projected
+  lookup bypasses the shared cache. The resolver-side safety net remains
+  authoritative when a different row is later deleted.
 - **Isolation — a MISSING identity component DENIES, it never skips.** This
   is the package rule; both the write guard
   (`FieldPolicy.assertScopeOwnedByAmbientContext`) and the read guard
@@ -88,12 +92,13 @@ per-field `{defaultValue, visibility, help, label, order, locked}` for any
   `withTenant({ tenantId })`) may not touch the user tier at all. Skipping
   that check instead of denying it was a live ownership bypass: user rows are
   `tenantId: null` by design, so nothing else contains such a write. App-scope
-  writes inside a tenant context require super-admin bypass. With NO ambient
-  identity at all (tenancy ALS never entered), only app-scope writes/deletes
-  are accepted; context-LESS *reads* stay allowed because
-  `resolveFieldPolicy` is a trusted server-side API. Residual: ALS-less
-  deployments can still write APP rows with any authenticated principal until
-  the #2049 permission layer adds `fields:policy:manage`. `save()`/`delete()`
+  writes inside a tenant context require super-admin bypass. `fields.policy.manage`
+  authorizes app/tenant policy mutations; `fields.policy.personalize` authorizes
+  only the caller's user tier (default-seeded for built-in roles). With NO ambient
+  identity at all (tenancy ALS never entered), policy writes/deletes fail closed;
+  trusted system and super-admin contexts retain their explicit bypasses.
+  Context-LESS *reads* stay allowed because `resolveFieldPolicy` is a trusted
+  server-side API. `save()`/`delete()`
   on an existing row additionally authorize against the row's PERSISTED
   scope, looked up by primary key AND — because a generated create always
   mints a fresh UUID while the `conflictColumns` upsert still replaces the
@@ -171,6 +176,47 @@ per-field `{defaultValue, visibility, help, label, order, locked}` for any
   (`_smrt_field_policies`), and both are pinned in
   `generated-surfaces.test.ts`.
 
+## Svelte generated forms (#2049)
+
+- `ObjectForm` accepts direct generated `fields` plus a resolved `policy` for
+  SSR and explicit hosts, or accepts only `objectRef` beneath an
+  `ObjectFormSourceProvider`. `ObjectFormSourceRegistry` is per app and maps
+  canonical refs to generated web collection definitions before calling the
+  generated `resolveBatch` custom action. It uses structural types only: this
+  package must never import `smrt-web`.
+- Generated custom-action clients resolve `Promise<any>`; validate their
+  `policies[objectRef]` response at the registry boundary and fail closed on a
+  missing/mismatched definition or policy. The component renders an accessible
+  loading state and alert rather than a partial form.
+- Browser manifest types are `text`, `integer`, `decimal`, `boolean`,
+  `datetime`, `json`, `foreignKey`, and `crossPackageRef`; there is no `select`
+  wire type. Apps use the per-app `FieldInputRegistry.registerField` seam for
+  select-like widgets. Reference fields intentionally default to identifier
+  inputs unless an app supplies a chooser.
+- `policyToVisibleColumnIds(policy, columns)` feeds smrt-ui `DataTable`'s
+  `visibleColumnIds`; it filters policy-hidden mapped fields, preserves unmapped
+  computed/action columns, and cannot reveal a static `column.hidden` column.
+
+## Defaults control panel (#2050)
+
+- `buildFieldPolicySettingsCatalog()` is the server-side, URL/GET-driven
+  catalog builder. It structurally targets `SettingsCatalog`, but this package
+  must not import `smrt-svelte`; hosts inject `SettingsCatalog` into
+  `FieldPolicyControlPanel` and retain their own route and transport adapters.
+- `policyAudit` is the only routed organization roll-up. It requires
+  `fields.policy.manage`, returns only the caller tenant's editable rows and
+  read-only app summaries, and represents other users strictly as per-field
+  counts. It resolves only requested page refs; never pre-resolve the catalog.
+- Display code/app/org values by replaying the explained resolver layers, not
+  by independently calculating precedence. Reset and drift prune are ordinary
+  model deletes, so existing scope/permission validation remains authoritative.
+  The panel asks for an explicit confirmation before either destructive action;
+  SSR hosts can inject that confirmation decision instead of relying on
+  `window.confirm`.
+- `fieldPolicyControlPanelNavItem()` is a structural AdminShell tenant-nav
+  seam. It never imports `smrt-svelte` or `smrt-web`; the host supplies the
+  returned entry and must enforce its real route permission server-side.
+
 ## Related
 
 - `@happyvertical/smrt-prompts` / `smrt-languages` / `smrt-features` — the

package/README.md

@@ -39,10 +39,15 @@ const explained = await resolveFieldPolicyExplained(
 ```
 
 Resolution layers (low → high): code seed → app rows → tenant rows
-(hierarchy walk via an optional `tenantHierarchyLoader`; flat fallback
-without `@happyvertical/smrt-users`) → user rows. A NULL column inherits
+(hierarchy walk via the users tenant loader, or a flat fallback when an
+injected hierarchy provider cannot resolve the tenant) → user rows. A NULL column inherits
 from the lower layer; resetting a customization is a row delete.
 
+`@happyvertical/smrt-users` is a required runtime dependency: Field Policy
+uses its permission catalog and operation guard for every write and gear
+action. The hierarchy fallback concerns tenant ancestry only; it is not a
+users-authorization fallback.
+
 Writes are validated against the live `ObjectRegistry`: unknown
 objects/fields are rejected, defaults are type-checked, and defaults on
 `transient`/`sensitive`/`readPermission`-gated fields are refused. Required
@@ -50,3 +55,86 @@ fields can only be demoted from `basic` when a usable default resolves —
 and the resolver re-enforces that invariant at read time.
 
 See `AGENTS.md` for the full architecture notes.
+
+## Svelte ObjectForm
+
+`@happyvertical/smrt-fields/svelte` provides provider-free generated forms.
+Pass only the generated browser field definitions and the matching resolved
+policy; `ObjectForm` renders their safe intersection, honors policy visibility
+and ordering, and keeps form state transport-neutral.
+
+```svelte
+<script lang="ts">
+  import { ObjectForm, createFieldInputRegistry } from '@happyvertical/smrt-fields/svelte';
+
+  const inputRegistry = createFieldInputRegistry();
+  // inputRegistry.registerField(objectRef, 'body', RichTextInput);
+</script>
+
+<ObjectForm {objectRef} fields={collectionDefinition.fields} {policy}
+  bind:value={record} {inputRegistry} />
+```
+
+Pass an `actions` snippet to place host controls inside the owned native form.
+The snippet renders after ObjectForm's policy-ordered fields, so a regular
+submit button keeps native Enter/click submission and ObjectForm's validation
+and `onsubmit` handling without querying the DOM.
+
+```svelte
+<ObjectForm {objectRef} fields={collectionDefinition.fields} {policy}
+  bind:value={record} onsubmit={save}>
+  {#snippet actions()}
+    <button type="submit">Save</button>
+  {/snippet}
+</ObjectForm>
+```
+
+An app can register all of its generated collection definitions once and put
+the `resolveBatch` custom-action client behind an `ObjectFormSourceProvider`.
+Then forms need only their canonical object reference; the registry validates
+the generated definition and the untyped custom-action response before it is
+rendered, failing closed with an accessible error state on a missing or
+mismatched response.
+
+```svelte
+<script lang="ts">
+  import {
+    ObjectForm,
+    ObjectFormSourceProvider,
+    ObjectFormSourceRegistry,
+  } from '@happyvertical/smrt-fields/svelte';
+
+  const source = new ObjectFormSourceRegistry(fieldPoliciesClient);
+  for (const definition of Object.values(collectionDefinitions)) source.register(definition);
+</script>
+
+<ObjectFormSourceProvider {source}>
+  <ObjectForm objectRef="@happyvertical/smrt-products:Product" bind:value={record} />
+</ObjectFormSourceProvider>
+```
+
+The built-ins support text, integer, decimal, boolean, datetime, JSON, and
+reference identifiers. `FieldInputRegistry` is per app: a field-specific
+renderer takes precedence over a wire-type renderer. SMRT has no `select` wire
+type: keep the persisted wire type (normally `text`) and register a
+field-specific select-like renderer with `registerField(objectRef, fieldName,
+component)`. Reference fields deliberately remain provider-free identifier
+inputs unless an app registers its own chooser. `policyToVisibleColumnIds`
+adapts the same resolved policy to `DataTable` without hiding unmapped action or
+computed columns; static `column.hidden` remains authoritative.
+
+When a mounted create form starts another record, replace the bound record with
+an empty object or change `createSessionKey`; both begin a new default-prefill
+session without reapplying defaults after an in-form user clear.
+
+## Policy settings gear
+
+`FieldPolicyGearProvider` makes the context-derived `editor-state` action
+available to any policy-aware form without choosing a client transport. Pass an
+adapter around the generated collection client's `getEditorState`, `create`,
+`update`, and `delete` calls; it must not accept tenant or user identifiers.
+Use `FieldPolicyGearButton` where the form wants its affordance, or set
+`showPolicyGear` on `ObjectForm`. `registerFieldPolicyFocusTool(shell,
+objectRef, tool)` is a structural AdminShell seam: it registers the required
+`{ type: 'object-form', id: objectRef }` subject and returns the shell's
+disposer without making Fields depend on `smrt-svelte`.

package/dist/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/__smrt-register__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__smrt-register__.d.ts","sourceRoot":"","sources":["../src/__smrt-register__.ts"],"names":[],"mappings":""}

package/dist/cache.d.ts

@@ -0,0 +1,18 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+import { ExplainedObjectFieldPolicy } from './types.js';
+export declare function getFieldPolicyCacheTtlMs(): number;
+export declare function getCachedFieldPolicy(objectRef: string, tenantId: string | null | undefined, userId: string | null | undefined, db: DatabaseInterface | unknown, hierarchyLoader?: unknown): ExplainedObjectFieldPolicy | null;
+export declare function setCachedFieldPolicy(objectRef: string, tenantId: string | null | undefined, userId: string | null | undefined, db: DatabaseInterface | unknown, value: ExplainedObjectFieldPolicy, hierarchyLoader?: unknown): void;
+/**
+ * Drop every cached resolution for `(db, objectRef)`.
+ *
+ * Deliberately coarser than the prompts precedent (which deletes a single
+ * `(key, tenantId)` entry when the tenant is known): tenant HIERARCHY makes a
+ * parent-tenant row change affect every descendant tenant's resolution, and a
+ * lock or app-row change affects user-tier entries too, so precise
+ * invalidation would have to know the whole tenant tree. Per-objectRef prefix
+ * invalidation is always correct and the 30s TTL keeps the cost bounded.
+ */
+export declare function invalidateFieldPolicyCache(objectRef: string, db: DatabaseInterface | unknown): void;
+export declare function clearFieldPolicyCache(): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AA2F7D,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,EAAE,EAAE,iBAAiB,GAAG,OAAO,EAC/B,eAAe,CAAC,EAAE,OAAO,GACxB,0BAA0B,GAAG,IAAI,CAoBnC;AAED,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,EAAE,EAAE,iBAAiB,GAAG,OAAO,EAC/B,KAAK,EAAE,0BAA0B,EACjC,eAAe,CAAC,EAAE,OAAO,GACxB,IAAI,CAQN;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,iBAAiB,GAAG,OAAO,GAC9B,IAAI,CAON;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}

package/dist/collections/FieldPolicyCollection.d.ts

@@ -0,0 +1,95 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { FieldPolicy } from '../models/FieldPolicy.js';
+import { FieldPolicyAuditSnapshot, FieldPolicyBatchResult, FieldPolicyEditorStateResult } from '../types.js';
+/** Public cap shared by the server catalog and browser adapter. */
+export declare const MAX_FIELD_POLICY_AUDIT_OBJECT_REFS = 100;
+/** Count queries are projected, so they can cover a page plus an off-page selection. */
+export declare const MAX_FIELD_POLICY_AUDIT_COUNT_REFS: number;
+/**
+ * Collection surface for {@link FieldPolicy} rows plus the batch resolve
+ * action consumed by client bootstrapping (#2048).
+ *
+ * `resolveBatch` is a custom collection-scoped action (NOT a system route —
+ * core's generated system trio is closed): the generated route parses the
+ * body, calls the method on the app-configured collection instance (which
+ * carries the app database), and serializes the plain result.
+ *
+ * Exposure note: a decorated collection's config becomes the RUNTIME registry
+ * authority for its item class (core merges the collection registration onto
+ * the item slot), while build-time generation reads each manifest object's
+ * own config. This config therefore mirrors FieldPolicy's API posture —
+ * writes open plus the batch action, reads CLOSED (generated list/get would
+ * enumerate every tenant's/user's rows) — and closes the runtime CLI/MCP
+ * surfaces entirely (the ContentContributions precedent; the cli↔api
+ * coherence gate does not admit standard CRUD entries on a collection's
+ * `cli.include`). Keep the api include lists in lockstep with FieldPolicy's.
+ */
+export declare class FieldPolicyCollection extends SmrtCollection<FieldPolicy> {
+    static readonly _itemClass: typeof FieldPolicy;
+    /**
+     * Permission-gated, tenant-scoped audit read for the defaults control
+     * panel. It returns editable own-tenant rows, read-only app summaries,
+     * projected user override counts, and identity-only manifest drift rows.
+     */
+    policyAudit(options?: {
+        objectRefs?: string[];
+        countObjectRefs?: string[];
+        /** Capability-only bootstrap for catalog builders before page selection. */
+        summaryOnly?: boolean;
+        /** Return row/count roll-ups without resolving field-policy layers. */
+        countsOnly?: boolean;
+        /** Return the first bounded page of manifest drift candidates. */
+        includeDrift?: boolean;
+    }): Promise<FieldPolicyAuditSnapshot>;
+    private resolveAuditPolicies;
+    /** All app-scope rows for an object, keyed by field name. */
+    getAppRows(objectRef: string): Promise<Map<string, FieldPolicy>>;
+    /**
+     * All tenant-scope rows for an object across a tenant chain, keyed
+     * `tenantId → fieldName → row`.
+     */
+    getTenantRows(objectRef: string, tenantIds: string[]): Promise<Map<string, Map<string, FieldPolicy>>>;
+    /** All user-scope rows for an object and user, keyed by field name. */
+    getUserRows(objectRef: string, userId: string): Promise<Map<string, FieldPolicy>>;
+    /**
+     * Resolve merged field policy for a set of objectRefs for the CURRENT
+     * caller, gated for public consumption.
+     *
+     * Caller identity comes exclusively from the ambient tenant context
+     * (established by the app's auth hook, e.g. smrt-users' session context) —
+     * the request body cannot select another tenant or user (fail closed).
+     * Server-side consumers wanting explicit identities call
+     * `resolveFieldPolicy()` directly instead.
+     *
+     * Field gating mirrors the REST serializer's derivation (`sensitive` /
+     * `readPermission` read from both the top level and `_meta`): sensitive and
+     * read-permission-gated fields are ABSENT from the response for every
+     * caller (the generated action route cannot convey per-caller grants to
+     * this method, so gated fields fail closed), and transient fields are
+     * stripped for parity with generated client field definitions.
+     */
+    resolveBatch(options?: {
+        objectRefs?: string[];
+    }): Promise<FieldPolicyBatchResult>;
+    /**
+     * Context-derived bootstrap data for the policy gear. This is deliberately
+     * a collection action instead of reopening list/get: a caller can inspect
+     * only their safe effective policy and rows/layers they are permitted to
+     * edit, never arbitrary tenant or user policy rows.
+     */
+    getEditorState(options?: {
+        objectRef?: string;
+    }): Promise<FieldPolicyEditorStateResult>;
+    /**
+     * Compute the non-disclosing fallback signal used only by personal drafts.
+     * Passing no user id resolves exactly code/app/tenant precedence, including
+     * the real tenant hierarchy, while keeping every lower-layer value server
+     * side. The public map is limited to fields already admitted by the editor
+     * response's security rail.
+     */
+    private getPersonalLowerDefaultUsability;
+    private gateResolvedForPublicResponse;
+    private gateExplainedForEditorResponse;
+    private toEditorRows;
+}
+//# sourceMappingURL=FieldPolicyCollection.d.ts.map

package/dist/collections/FieldPolicyCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldPolicyCollection.d.ts","sourceRoot":"","sources":["../../src/collections/FieldPolicyCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAQ,MAAM,0BAA0B,CAAC;AAiBhE,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAKvD,OAAO,KAAK,EAGV,wBAAwB,EACxB,sBAAsB,EAItB,4BAA4B,EAE7B,MAAM,aAAa,CAAC;AAIrB,mEAAmE;AACnE,eAAO,MAAM,kCAAkC,MAAwB,CAAC;AACxE,wFAAwF;AACxF,eAAO,MAAM,iCAAiC,QAA4B,CAAC;AAE3E;;;;;;;;;;;;;;;;;;GAkBG;AAQH,qBAoCa,qBAAsB,SAAQ,cAAc,CAAC,WAAW,CAAC;IACpE,MAAM,CAAC,QAAQ,CAAC,UAAU,qBAAe;IAEzC;;;;OAIG;IACG,WAAW,CACf,OAAO,GAAE;QACP,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3B,4EAA4E;QAC5E,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,uEAAuE;QACvE,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,kEAAkE;QAClE,YAAY,CAAC,EAAE,OAAO,CAAC;KACnB,GACL,OAAO,CAAC,wBAAwB,CAAC;YA+NtB,oBAAoB;IA6BlC,6DAA6D;IACvD,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAWtE;;;OAGG;IACG,aAAa,CACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EAAE,GAClB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAuBjD,uEAAuE;IACjE,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAWpC;;;;;;;;;;;;;;;;OAgBG;IACG,YAAY,CAChB,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;KAAO,GACtC,OAAO,CAAC,sBAAsB,CAAC;IAuClC;;;;;OAKG;IACG,cAAc,CAClB,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,4BAA4B,CAAC;IAsGxC;;;;;;OAMG;YACW,gCAAgC;YAuBhC,6BAA6B;YAwB7B,8BAA8B;IAiC5C,OAAO,CAAC,YAAY;CAsBrB"}

package/dist/field-definitions.d.ts

@@ -0,0 +1,77 @@
+import { FieldUIHints, ObjectRegistry } from '@happyvertical/smrt-core';
+import { FieldPolicyDelta, FieldPolicyVisibility } from './types.js';
+/**
+ * Field map for one object, keyed by field name (includes inherited fields).
+ * Derived structurally from the PUBLIC `ObjectRegistry.getAllFields` return
+ * type — core does not export its internal `RegisteredField` name.
+ */
+export type FieldDefinitionMap = Awaited<ReturnType<typeof ObjectRegistry.getAllFields>>;
+/** One field's registered metadata, as returned by `getAllFields`. */
+export type RegisteredFieldInfo = FieldDefinitionMap extends Map<string, infer F> ? F : never;
+/**
+ * Resolve `objectRef` (qualified `@package/name:ClassName`) against the live
+ * registry, throwing a descriptive error when the class is unknown.
+ */
+export declare function requireRegisteredObject(objectRef: string): void;
+/** Load the full (inherited) field map for a registered objectRef. */
+export declare function getObjectFieldMap(objectRef: string): Promise<FieldDefinitionMap>;
+/**
+ * Narrow a manifest `_meta.ui` bag to the known {@link FieldUIHints} keys with
+ * their expected primitive types, dropping junk (mirrors the sanitization the
+ * web emission applies in core's `web-collections.ts`).
+ */
+export declare function sanitizeFieldUIHints(value: unknown): FieldUIHints | undefined;
+/** Security rail: `sensitive` may live top-level or under `_meta` (STI merges). */
+export declare function isSensitiveField(field: RegisteredFieldInfo): boolean;
+/** Security rail: `readPermission` may live top-level or under `_meta`. */
+export declare function getFieldReadPermission(field: RegisteredFieldInfo): string | undefined;
+export declare function isTransientField(field: RegisteredFieldInfo): boolean;
+/**
+ * True when a registered field can receive a policy row.  Keep this shared by
+ * the resolver and the catalog audit: otherwise a row that never resolves can
+ * accidentally be presented as an editable setting.
+ */
+export declare function isPolicyAddressableField(field: RegisteredFieldInfo): boolean;
+/**
+ * A field is required when flagged required and not explicitly nullable.
+ *
+ * `nullable` is read from BOTH the top level and `_meta` for the same reason
+ * `sensitive`/`readPermission`/`transient` are: registrations reach the
+ * registry through several paths (decorator, manifest, STI merge) and land the
+ * flag in either place. Checking only one side made the pair asymmetric —
+ * `required` was read from both while `nullable` was read from one.
+ */
+export declare function isRequiredField(field: RegisteredFieldInfo): boolean;
+/** The manifest/code default for a field, boxed; `undefined` when none. */
+export declare function getCodeDefault(field: RegisteredFieldInfo): {
+    value: unknown;
+} | undefined;
+/**
+ * A resolved default satisfies the required-field invariant only when it is a
+ * value a form could actually submit: explicit `null` and the empty string do
+ * not count (a required text field "defaulting" to `''` is still unfilled).
+ */
+export declare function isUsableRequiredDefault(defaultBox: {
+    value: unknown;
+} | undefined): boolean;
+/**
+ * Compute the code-seed visibility for every field of an object using the
+ * cold-start rule (#2046): with no `ui.basic` markers anywhere on the object,
+ * every field is `basic`; once any field is marked `basic: true`, unmarked
+ * fields default to `advanced` (and an explicit `basic: false` is always
+ * `advanced`).
+ */
+export declare function buildCodeSeedVisibility(fields: FieldDefinitionMap): Map<string, FieldPolicyVisibility>;
+/** Code-seed delta for one field (visibility supplied by the cold-start pass). */
+export declare function buildCodeSeedDelta(field: RegisteredFieldInfo, visibility: FieldPolicyVisibility): FieldPolicyDelta;
+/** Code-seed grouping key (`ui.group`) — not overridable by stored rows. */
+export declare function getCodeSeedGroup(field: RegisteredFieldInfo): string | null;
+/**
+ * Type-check a parsed default value against the manifest field type.
+ *
+ * Explicit `null` is allowed only for optional fields (a required field with a
+ * null default has no usable default). Unsupported field types reject defaults
+ * outright (fail closed).
+ */
+export declare function assertDefaultValueMatchesFieldType(objectRef: string, fieldName: string, field: RegisteredFieldInfo, value: unknown): void;
+//# sourceMappingURL=field-definitions.d.ts.map

package/dist/field-definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-definitions.d.ts","sourceRoot":"","sources":["../src/field-definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CACtC,UAAU,CAAC,OAAO,cAAc,CAAC,YAAY,CAAC,CAC/C,CAAC;AAEF,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAC7B,kBAAkB,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE9D;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAa/D;AAED,sEAAsE;AACtE,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,kBAAkB,CAAC,CAG7B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAc7E;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAEpE;AAED,2EAA2E;AAC3E,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,mBAAmB,GACzB,MAAM,GAAG,SAAS,CAMpB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAO5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAKnE;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAC5B,KAAK,EAAE,mBAAmB,GACzB;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAQhC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GACzC,OAAO,CAKT;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,kBAAkB,GACzB,GAAG,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAuBpC;AAED,kFAAkF;AAClF,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,mBAAmB,EAC1B,UAAU,EAAE,qBAAqB,GAChC,gBAAgB,CAiBlB;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,CAE1E;AAUD;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAChD,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,OAAO,GACb,IAAI,CAsEN"}

package/dist/field-policy-resolver.d.ts

@@ -0,0 +1,46 @@
+import { ExplainedObjectFieldPolicy, ResolvedObjectFieldPolicy, ResolveFieldPolicyOptions } from './types.js';
+/**
+ * Resolve the merged field policy for `objectRef` in the given
+ * `(tenantId, userId)` context: code seed → app rows → tenant rows (hierarchy
+ * walk root → leaf) → user rows. Defaults AND visibility both resolve through
+ * the user tier.
+ *
+ * Results are cached per `(database, objectRef, tenantId, userId)` with a
+ * short TTL; `FieldPolicy.save()`/`.delete()` invalidate the object's entries.
+ */
+export declare function resolveFieldPolicy(objectRef: string, options?: ResolveFieldPolicyOptions): Promise<ResolvedObjectFieldPolicy>;
+/**
+ * The tenant ids whose rows participate in precedence for a tenant, root to
+ * leaf. Catalog code uses this instead of reimplementing inheritance-break
+ * handling when it decides whether an inherited override is customized.
+ */
+export declare function resolveSurvivingTenantChainIds(tenantId: string, options?: ResolveFieldPolicyOptions): Promise<string[]>;
+/**
+ * Explain variant: the merged result plus ordered per-layer contributions for
+ * each field, so the gear UI (#2049, "shows inherited base") and the control
+ * panel (#2050, effective-value-per-layer) never re-derive precedence.
+ *
+ * A user-layer row suppressed by an effective org lock is omitted from the
+ * layer list too — the listed layers always reproduce the merged result.
+ */
+export declare function resolveFieldPolicyExplained(objectRef: string, options?: ResolveFieldPolicyOptions): Promise<ExplainedObjectFieldPolicy>;
+/**
+ * Whether an import failure means `@happyvertical/smrt-users` is simply not
+ * installed (→ flat-tenant fallback) rather than installed-but-broken
+ * (→ rethrow, surfacing the problem instead of silently losing ancestor
+ * locks/defaults).
+ *
+ * The decision is made on the missing-module TARGET parsed from Node's
+ * `Cannot find package/module '<specifier>'` message (walking the full
+ * `cause` chain): only a target that IS smrt-users (or one of its subpaths)
+ * counts. A transitive failure INSIDE an installed smrt-users names the
+ * other package as the target — with the users path merely appearing as the
+ * importer — and therefore rethrows. `importWorkspaceModule`'s own
+ * source-fallback wrapper ("Failed to load @happyvertical/smrt-users for
+ * ...") is also accepted: it is thrown only when the users package itself
+ * cannot be located.
+ *
+ * Exported for direct testing; not re-exported from the package index.
+ */
+export declare function isMissingUsersDependency(error: unknown): boolean;
+//# sourceMappingURL=field-policy-resolver.d.ts.map

package/dist/field-policy-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-policy-resolver.d.ts","sourceRoot":"","sources":["../src/field-policy-resolver.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EACV,0BAA0B,EAQ1B,yBAAyB,EACzB,yBAAyB,EAE1B,MAAM,YAAY,CAAC;AAYpB;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,yBAAyB,CAAC,CAGpC;AAED;;;;GAIG;AACH,wBAAsB,8BAA8B,CAClD,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,MAAM,EAAE,CAAC,CAInB;AAED;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAC/C,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,0BAA0B,CAAC,CA0JrC;AA0MD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAsBhE"}