@happyvertical/smrt-fields 0.40.60 → 0.40.62

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

@@ -1,52 +1,153 @@
 # @happyvertical/smrt-fields
 
-Layered field policy for SMRT objects: personalize per-field defaults,
-visibility tiers (basic/advanced/hidden), help text, labels, ordering, and
-org locks at app, tenant, and user scope — over the code-authored
-`@field({ ui })` seed.
+`@happyvertical/smrt-fields` lets an application adjust an object's form
+defaults, labels, help, order, visibility, and locks without changing the
+object's source. Policies layer organization and personal choices over the
+code-authored field definition.
+
+For the complete application and operator guide, see the
+[field policy guide](https://happyvertical.github.io/smrt/field-policies).
+
+## Install
+
+```bash
+pnpm add @happyvertical/smrt-fields
+```
+
+The package includes `@happyvertical/smrt-users` because policy writes and
+operator actions use its permission and tenant context services.
+
+## Define a safe code seed
+
+The decorated model remains the definition of a field. Use its description
+and `ui` hints to supply a useful first form before any policy row exists.
 
 ```typescript
-import {
-  FieldPolicy,
-  FieldPolicyCollection,
-  resolveFieldPolicy,
-  resolveFieldPolicyExplained,
-} from '@happyvertical/smrt-fields';
-
-// An org (tenant) demotes an optional field and sets a default
-const policies = await FieldPolicyCollection.create({ db });
-await policies.create({
-  objectRef: '@happyvertical/smrt-content:Article',
-  fieldName: 'summary',
-  scopeType: 'tenant',
-  tenantId,
-  visibility: 'advanced',
-  defaultValue: JSON.stringify('TBD'),
-});
-
-// Resolve the effective policy for a user in that tenant
-const resolved = await resolveFieldPolicy(
-  '@happyvertical/smrt-content:Article',
-  { tenantId, userId, db },
-);
-resolved.fields.summary.visibility; // 'advanced'
+import { field, SmrtObject, smrt } from '@happyvertical/smrt-core';
+
+@smrt({ packageName: '@acme/billing' })
+export class Invoice extends SmrtObject {
+  @field({
+    required: true,
+    description: 'Shown on the customer invoice.',
+    ui: { basic: true, group: 'billing', order: 1 },
+  })
+  title = '';
 
-// Explain variant: per-layer contributions for admin/gear UIs
-const explained = await resolveFieldPolicyExplained(
-  '@happyvertical/smrt-content:Article',
-  { tenantId, userId, db },
+  @field({ ui: { basic: false, group: 'billing', order: 2 } })
+  internalNotes = '';
+}
+```
+
+If no field has `ui.basic: true`, fields start in the basic view. Once at
+least one field is marked basic, unmarked fields start advanced. `group` and
+`order` are code-owned hints; `locked: true` seeds a lock that can prevent a
+personal override.
+
+## Resolve on the server
+
+Use the resolver in trusted server code when rendering SSR or applying a
+server-owned workflow. It merges code → app → tenant ancestry → user.
+
+```typescript
+import { resolveFieldPolicy } from '@happyvertical/smrt-fields';
+
+const policy = await resolveFieldPolicy(
+  '@acme/billing:Invoice',
+  { tenantId: requestTenant.id, userId: session.user.id, db },
 );
+
+const title = policy.fields.title;
 ```
 
-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
-from the lower layer; resetting a customization is a row delete.
+The client-facing generated `resolveBatch` action derives the tenant and user
+from the authenticated request context. Do not accept those identifiers from a
+browser request. It returns only fields that are safe to expose; sensitive,
+transient, and read-permission-gated fields are omitted.
+
+## Use policy-aware Svelte forms
+
+For a custom form, provide a resolved policy with `FieldPolicyProvider` and
+wrap each input in `PolicyField`. The wrapper applies visibility, labels, help,
+and new-record defaults while preserving your markup and input component.
+
+```svelte
+<script lang="ts">
+  import {
+    FieldPolicyProvider,
+    PolicyField,
+  } from '@happyvertical/smrt-fields/svelte';
+
+  let { policy, invoice = $bindable({}) } = $props();
+</script>
+
+<FieldPolicyProvider {policy}>
+  <PolicyField name="title">
+    <input id="title" bind:value={invoice.title} />
+  </PolicyField>
+</FieldPolicyProvider>
+```
+
+For generated forms, register the application's generated collection
+definitions once in an `ObjectFormSourceRegistry`, place it in an
+`ObjectFormSourceProvider`, then render an `ObjectForm` by canonical
+`objectRef`. The registry validates both the generated field definition and
+the `resolveBatch` response before rendering. See the guide for the complete
+setup, including field-specific input renderers and policy-aware tables.
+
+## Administration and personal settings
+
+Use `FieldPolicyGearProvider` with an adapter to the generated
+`getEditorState`, create, update, and delete actions. It derives identity on
+the server; adapter methods intentionally do not accept tenant or user ids.
+Use `FieldPolicyGearButton` or `showPolicyGear` on `ObjectForm` to expose
+the editor.
+
+For a settings destination, the server builds data with
+`buildFieldPolicySettingsCatalog()` and the browser renders it through
+`FieldPolicyControlPanel`. Hosts supply route, transport, confirmation, and
+AdminShell adapters. `fieldPolicyControlPanelNavItem()` and
+`registerFieldPolicyFocusTool()` are structural seams, so Fields does not
+take a dependency on a particular application shell.
+
+`fields.policy.manage` permits app and tenant administration.
+`fields.policy.personalize` permits only the current user's personal choices.
+The host must still establish a trusted authenticated principal context and
+enforce the route permission before rendering an operator destination.
+
+## Important behavior
+
+- A policy row is sparse: `null` means inherit the lower layer. Delete a row
+  to reset that scope completely.
+- `defaultValue` is the JSON-encoded wire channel. Server code with a plain
+  value should use `defaultValueRaw` or `setDefaultValue()`.
+- Required fields cannot be hidden or moved to advanced without a usable
+  resolved default. Resolution forces a required, default-less field back to
+  basic as a safety net.
+- App and tenant rows may lock a field. While the resolved organization policy
+  is locked, personal writes are rejected and old personal rows do not apply.
+- Defaults are rejected for sensitive, transient, and read-permission-gated
+  fields. Reference defaults must use a valid UUID unless that reference
+  declares a text id type.
+
+## Usage learning
+
+Optional usage capture records bounded, aggregated submissions from
+authenticated tenant members and turns qualified patterns into
+administrator-reviewed tenant-policy suggestions. It never auto-applies a
+suggestion. `ObjectForm` reports only after its host confirms persistence;
+browser values transit only for low-cardinality boolean and reference fields,
+and telemetry failures never affect the saved submit.
+
+Operators enable the dormant maintenance and suggestion schedules explicitly
+with `ensureFieldUsageLearningSchedules({ db })`. The learning loop retains
+aggregates and uses conservative thresholds; its accepted/dismissed suggestion
+queue is restricted to `fields.policy.manage`. See the
+[field policy guide](https://happyvertical.github.io/smrt/field-policies#usage-learning-and-suggestions)
+for the capture, privacy, retention, and schedule contract.
 
-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
-fields can only be demoted from `basic` when a usable default resolves —
-and the resolver re-enforces that invariant at read time.
+## Example application
 
-See `AGENTS.md` for the full architecture notes.
+The [SMRT SaaS starter field-policy walkthrough](https://github.com/happyvertical/smrt-saas-starter/pull/51)
+uses SMRT `0.40.61` and shows the owner/admin controls and the member-facing
+personal form flow in a working application.

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"}