@happyvertical/smrt-fields 0.40.57

package/dist/smrt-knowledge.json

@@ -0,0 +1,347 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "1970-01-01T00:00:00.000Z",
+  "packageName": "@happyvertical/smrt-fields",
+  "packageVersion": "0.40.57",
+  "sourceManifestPath": "dist/manifest.json",
+  "agentDocPath": "AGENTS.md",
+  "sourceHashes": {
+    "manifest": "bbe9ab11eab7eb6f158f406f86999254fab6b92cc866fd7082d8bf5d674be2c6",
+    "packageJson": "0a79f8eeb56359dff3d0a635fa47b4aa06857311e23227eeaada315fbd7063b0",
+    "agents": "efe605cdabdde966a22fc43d94af0275bfb1ce5e2027b52809c69837e3d5dc0c"
+  },
+  "exports": [
+    ".",
+    "./manifest",
+    "./manifest.json"
+  ],
+  "dependencies": {
+    "@happyvertical/smrt-core": "workspace:*",
+    "@happyvertical/smrt-tenancy": "workspace:*",
+    "@happyvertical/sql": "catalog:",
+    "@happyvertical/smrt-cli": "workspace:*",
+    "@happyvertical/smrt-users": "workspace:*",
+    "@happyvertical/smrt-vitest": "workspace:*",
+    "@types/node": "24.13.2",
+    "typescript": "5.9.3",
+    "vite": "8.1.4",
+    "vitest": "4.1.10"
+  },
+  "smrtDependencies": [
+    "@happyvertical/smrt-cli",
+    "@happyvertical/smrt-core",
+    "@happyvertical/smrt-tenancy",
+    "@happyvertical/smrt-users",
+    "@happyvertical/smrt-vitest"
+  ],
+  "sdkDependencies": [
+    "@happyvertical/sql"
+  ],
+  "tags": [],
+  "risks": [],
+  "objects": [
+    {
+      "name": "FieldPolicyCollection",
+      "qualifiedName": "@happyvertical/smrt-fields:FieldPolicyCollection",
+      "collection": "fieldpolicies",
+      "tableName": "_smrt_field_policies",
+      "packageName": "@happyvertical/smrt-fields",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "getAppRows",
+        "getTenantRows",
+        "getUserRows",
+        "resolveBatch"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "fieldpolicies.create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection",
+          "path": "/fieldpolicies",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "fieldpolicies.update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection",
+          "path": "/fieldpolicies/[id]",
+          "method": "PATCH"
+        },
+        {
+          "kind": "api",
+          "name": "fieldpolicies.delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection",
+          "path": "/fieldpolicies/[id]",
+          "method": "DELETE"
+        },
+        {
+          "kind": "api",
+          "name": "fieldpolicies.resolveBatch",
+          "operation": "resolveBatch",
+          "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection",
+          "path": "/fieldpolicies/resolveBatch",
+          "method": "POST"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "FieldPolicy",
+      "qualifiedName": "@happyvertical/smrt-fields:FieldPolicy",
+      "collection": "fieldpolicies",
+      "tableName": "_smrt_field_policies",
+      "packageName": "@happyvertical/smrt-fields",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "objectRef",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "fieldName",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "scopeType",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "userId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "scopeKey",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "defaultValue",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "visibility",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "help",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "label",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "displayOrder",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "locked",
+          "type": "boolean",
+          "required": false,
+          "columnType": "BOOLEAN"
+        },
+        {
+          "name": "updatedBy",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "userId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "updatedBy",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "getDefaultValue",
+        "save",
+        "setDefaultValue"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "fieldpolicies.create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-fields:FieldPolicy",
+          "path": "/fieldpolicies",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "fieldpolicies.update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-fields:FieldPolicy",
+          "path": "/fieldpolicies/[id]",
+          "method": "PATCH"
+        },
+        {
+          "kind": "api",
+          "name": "fieldpolicies.delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-fields:FieldPolicy",
+          "path": "/fieldpolicies/[id]",
+          "method": "DELETE"
+        },
+        {
+          "kind": "cli",
+          "name": "fieldpolicy_create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-fields:FieldPolicy"
+        },
+        {
+          "kind": "cli",
+          "name": "fieldpolicy_update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-fields:FieldPolicy"
+        },
+        {
+          "kind": "cli",
+          "name": "fieldpolicy_delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-fields:FieldPolicy"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    }
+  ],
+  "surfaces": [
+    {
+      "kind": "api",
+      "name": "fieldpolicies.create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection",
+      "path": "/fieldpolicies",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "fieldpolicies.update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection",
+      "path": "/fieldpolicies/[id]",
+      "method": "PATCH"
+    },
+    {
+      "kind": "api",
+      "name": "fieldpolicies.delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection",
+      "path": "/fieldpolicies/[id]",
+      "method": "DELETE"
+    },
+    {
+      "kind": "api",
+      "name": "fieldpolicies.resolveBatch",
+      "operation": "resolveBatch",
+      "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection",
+      "path": "/fieldpolicies/resolveBatch",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "fieldpolicies.create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-fields:FieldPolicy",
+      "path": "/fieldpolicies",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "fieldpolicies.update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-fields:FieldPolicy",
+      "path": "/fieldpolicies/[id]",
+      "method": "PATCH"
+    },
+    {
+      "kind": "api",
+      "name": "fieldpolicies.delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-fields:FieldPolicy",
+      "path": "/fieldpolicies/[id]",
+      "method": "DELETE"
+    },
+    {
+      "kind": "cli",
+      "name": "fieldpolicy_create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-fields:FieldPolicy"
+    },
+    {
+      "kind": "cli",
+      "name": "fieldpolicy_update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-fields:FieldPolicy"
+    },
+    {
+      "kind": "cli",
+      "name": "fieldpolicy_delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-fields:FieldPolicy"
+    }
+  ],
+  "prompts": [],
+  "relationshipsV2": {
+    "foreignKeyFields": 0,
+    "crossPackageRefFields": 2,
+    "junctionCollections": 0,
+    "hierarchicalObjects": 0,
+    "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"
+}

package/dist/types.d.ts

@@ -0,0 +1,203 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+
+/**
+ * `scopeKey` value for app-scope rows. `scopeKey` exists ONLY so the
+ * `conflictColumns` unique index stays total while `tenantId`/`userId` are
+ * nullable (nullable columns would allow duplicate NULL rows) — the same
+ * trick as `PromptOverride.context`.
+ */
+export declare const APP_FIELD_POLICY_SCOPE_KEY = "__app__";
+
+/**
+ * Explain variant: merged result plus the ordered per-layer contributions for
+ * each field, so admin/gear UIs (#2049/#2050) never re-derive precedence.
+ * Layers are listed in application order (code, app, tenant chain root → leaf,
+ * user) and contain ONLY contributions that survive into the merged result:
+ * tenant ancestors discarded by a permission-inheritance break and user rows
+ * suppressed by an effective org lock are omitted, so sequentially replaying
+ * the listed deltas reproduces the merged policy.
+ */
+export declare interface ExplainedObjectFieldPolicy extends ResolvedObjectFieldPolicy {
+    layers: Record<string, FieldPolicyLayerContribution[]>;
+}
+
+export declare const FIELD_POLICY_SCOPE_TYPES: readonly FieldPolicyScopeType[];
+
+export declare const FIELD_POLICY_VISIBILITIES: readonly FieldPolicyVisibility[];
+
+/** Result shape of the batch resolve action (`FieldPolicyCollection.resolveBatch`). */
+export declare interface FieldPolicyBatchResult {
+    policies: Record<string, ResolvedObjectFieldPolicy>;
+}
+
+/**
+ * The sparse contribution of one layer (code seed or one stored row).
+ *
+ * `default` is boxed so an explicit JSON `null` default (meaning "default to
+ * null") stays distinguishable from "this layer contributes no default".
+ */
+export declare interface FieldPolicyDelta {
+    default?: {
+        value: unknown;
+    };
+    visibility?: FieldPolicyVisibility;
+    help?: string;
+    label?: string;
+    order?: number;
+    locked?: boolean;
+}
+
+/** One layer's contribution to a field's resolved policy (explain variant). */
+export declare interface FieldPolicyLayerContribution {
+    layer: 'code' | 'app' | 'tenant' | 'user';
+    /** Chain node id for `tenant` layers (root → leaf order). */
+    tenantId?: string;
+    /** User id for the `user` layer. */
+    userId?: string;
+    delta: FieldPolicyDelta;
+}
+
+export declare interface FieldPolicyOptions extends SmrtObjectOptions {
+    objectRef?: string;
+    fieldName?: string;
+    scopeType?: FieldPolicyScopeType;
+    tenantId?: string | null;
+    userId?: string | null;
+    /**
+     * ENCODED channel: an already-JSON-encoded default, exactly as the column
+     * stores it (`'"Net 30"'`, `'42'`, `'null'`), or `null` to inherit.
+     *
+     * This is the wire contract: the generated write routes hand the request
+     * body straight to the constructor, and the #2049/#2050 gear posts
+     * `JSON.stringify(draft.defaultValue)`. It must therefore keep meaning
+     * "already encoded" — auto-serializing here would double-encode every gear
+     * write.
+     *
+     * Use {@link FieldPolicyOptions.defaultValueRaw} for a plain value. The two
+     * are mutually exclusive: `'"TBD"'` and `'TBD'` are indistinguishable once
+     * a single option carries both meanings, so the channel must be explicit
+     * rather than sniffed.
+     */
+    defaultValue?: string | null;
+    /**
+     * PLAIN channel: any value, always serialized — strings included. The
+     * constructor-option twin of {@link FieldPolicy.setDefaultValue}, so
+     * `{ defaultValueRaw: 'Net 30' }` stores `'"Net 30"'` rather than the
+     * unparseable literal `Net 30`.
+     */
+    defaultValueRaw?: unknown;
+    visibility?: FieldPolicyVisibility | null;
+    help?: string | null;
+    label?: string | null;
+    displayOrder?: number | null;
+    locked?: boolean | null;
+    updatedBy?: string | null;
+}
+
+/**
+ * Scope tier a {@link FieldPolicy} row belongs to.
+ *
+ * Resolution precedence is code seed → `app` → `tenant` (hierarchy walk,
+ * root → leaf) → `user`. Unlike smrt-features (which ships only
+ * `global`/`tenant`), the user tier is implemented end to end here — both
+ * defaults and visibility resolve through it.
+ */
+export declare type FieldPolicyScopeType = 'app' | 'tenant' | 'user';
+
+/**
+ * Loader-function DI seam (NOT a container registration): the resolver calls
+ * it lazily and treats `null` as "no hierarchy available" (flat-tenant
+ * fallback). The default loader dynamic-imports `@happyvertical/smrt-users`
+ * and returns `null` when it is not installed.
+ */
+export declare type FieldPolicyTenantHierarchyLoader = (options: SmrtClassOptions) => Promise<FieldPolicyTenantHierarchyProvider | null>;
+
+/** Provider returning the root → leaf tenant chain (mirrors smrt-features). */
+export declare interface FieldPolicyTenantHierarchyProvider {
+    getChain(tenantId: string): Promise<FieldPolicyTenantNode[]>;
+}
+
+/** Minimal tenant node consumed by the hierarchy walk (mirrors smrt-features). */
+export declare interface FieldPolicyTenantNode {
+    id: string;
+    inheritPermissions: boolean;
+    cascadePermissions: boolean;
+}
+
+export declare interface FieldPolicyUsersModule {
+    TenantCollection: {
+        create(options: SmrtClassOptions): Promise<{
+            get(criteria: {
+                id: string;
+            }): Promise<FieldPolicyUsersTenantRecord | null>;
+            getAncestorsFromRoot(tenantId: string): Promise<FieldPolicyUsersTenantRecord[]>;
+        }>;
+    };
+}
+
+/**
+ * Minimal structural shape of the tenant surface loaded from
+ * `@happyvertical/smrt-users` by the default hierarchy loader. Only the
+ * permission-cascade fields consumed by the chain walk are modeled.
+ */
+export declare interface FieldPolicyUsersTenantRecord {
+    id: string;
+    inheritPermissions?: boolean;
+    cascadePermissions?: boolean;
+}
+
+/**
+ * Visibility tier for a field in generated/consuming form UIs.
+ *
+ * - `basic`: shown before the advanced disclosure
+ * - `advanced`: shown behind the advanced disclosure
+ * - `hidden`: not rendered (requires the field to be optional or have a
+ *   resolved default — the required-field invariant)
+ */
+export declare type FieldPolicyVisibility = 'basic' | 'advanced' | 'hidden';
+
+/** Fully merged policy for a single field. */
+export declare interface ResolvedFieldPolicy {
+    fieldName: string;
+    /** True when any layer resolved a default (including an explicit null). */
+    hasDefault: boolean;
+    /** Parsed default value; `undefined` when {@link hasDefault} is false. */
+    defaultValue: unknown;
+    visibility: FieldPolicyVisibility;
+    help: string | null;
+    label: string | null;
+    order: number | null;
+    /** Grouping key — code-seed only (`ui.group`), not overridable by rows. */
+    group: string | null;
+    locked: boolean;
+    /** Mirror of the manifest required flag (nullable fields are optional). */
+    required: boolean;
+    /**
+     * True when the resolver forced `basic` visibility because the field is
+     * required and no usable default resolved (the resolver-side safety net for
+     * the required-field invariant).
+     */
+    visibilityForced?: boolean;
+}
+
+/** Merged policy for every field of one object. */
+export declare interface ResolvedObjectFieldPolicy {
+    objectRef: string;
+    fields: Record<string, ResolvedFieldPolicy>;
+}
+
+export declare interface ResolveFieldPolicyOptions {
+    tenantId?: string | null;
+    userId?: string | null;
+    /**
+     * Database holding `_smrt_field_policies`. Without it, only the code seed
+     * resolves (stored layers are skipped) — the smrt-prompts precedent.
+     */
+    db?: SmrtClassOptions['db'];
+    tenantHierarchyLoader?: FieldPolicyTenantHierarchyLoader;
+}
+
+export { SmrtClassOptions }
+
+export { }

package/dist/types.js

@@ -0,0 +1,16 @@
+//#region src/types.ts
+var APP_FIELD_POLICY_SCOPE_KEY = "__app__";
+var FIELD_POLICY_SCOPE_TYPES = [
+	"app",
+	"tenant",
+	"user"
+];
+var FIELD_POLICY_VISIBILITIES = [
+	"basic",
+	"advanced",
+	"hidden"
+];
+//#endregion
+export { APP_FIELD_POLICY_SCOPE_KEY, FIELD_POLICY_SCOPE_TYPES, FIELD_POLICY_VISIBILITIES };
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["import type {\n  SmrtClassOptions,\n  SmrtObjectOptions,\n} from '@happyvertical/smrt-core';\n\n/**\n * Scope tier a {@link FieldPolicy} row belongs to.\n *\n * Resolution precedence is code seed → `app` → `tenant` (hierarchy walk,\n * root → leaf) → `user`. Unlike smrt-features (which ships only\n * `global`/`tenant`), the user tier is implemented end to end here — both\n * defaults and visibility resolve through it.\n */\nexport type FieldPolicyScopeType = 'app' | 'tenant' | 'user';\n\n/**\n * Visibility tier for a field in generated/consuming form UIs.\n *\n * - `basic`: shown before the advanced disclosure\n * - `advanced`: shown behind the advanced disclosure\n * - `hidden`: not rendered (requires the field to be optional or have a\n *   resolved default — the required-field invariant)\n */\nexport type FieldPolicyVisibility = 'basic' | 'advanced' | 'hidden';\n\n/**\n * `scopeKey` value for app-scope rows. `scopeKey` exists ONLY so the\n * `conflictColumns` unique index stays total while `tenantId`/`userId` are\n * nullable (nullable columns would allow duplicate NULL rows) — the same\n * trick as `PromptOverride.context`.\n */\nexport const APP_FIELD_POLICY_SCOPE_KEY = '__app__';\n\nexport const FIELD_POLICY_SCOPE_TYPES: readonly FieldPolicyScopeType[] = [\n  'app',\n  'tenant',\n  'user',\n];\n\nexport const FIELD_POLICY_VISIBILITIES: readonly FieldPolicyVisibility[] = [\n  'basic',\n  'advanced',\n  'hidden',\n];\n\nexport interface FieldPolicyOptions extends SmrtObjectOptions {\n  objectRef?: string;\n  fieldName?: string;\n  scopeType?: FieldPolicyScopeType;\n  tenantId?: string | null;\n  userId?: string | null;\n  /**\n   * ENCODED channel: an already-JSON-encoded default, exactly as the column\n   * stores it (`'\"Net 30\"'`, `'42'`, `'null'`), or `null` to inherit.\n   *\n   * This is the wire contract: the generated write routes hand the request\n   * body straight to the constructor, and the #2049/#2050 gear posts\n   * `JSON.stringify(draft.defaultValue)`. It must therefore keep meaning\n   * \"already encoded\" — auto-serializing here would double-encode every gear\n   * write.\n   *\n   * Use {@link FieldPolicyOptions.defaultValueRaw} for a plain value. The two\n   * are mutually exclusive: `'\"TBD\"'` and `'TBD'` are indistinguishable once\n   * a single option carries both meanings, so the channel must be explicit\n   * rather than sniffed.\n   */\n  defaultValue?: string | null;\n  /**\n   * PLAIN channel: any value, always serialized — strings included. The\n   * constructor-option twin of {@link FieldPolicy.setDefaultValue}, so\n   * `{ defaultValueRaw: 'Net 30' }` stores `'\"Net 30\"'` rather than the\n   * unparseable literal `Net 30`.\n   */\n  defaultValueRaw?: unknown;\n  visibility?: FieldPolicyVisibility | null;\n  help?: string | null;\n  label?: string | null;\n  displayOrder?: number | null;\n  locked?: boolean | null;\n  updatedBy?: string | null;\n}\n\n/**\n * The sparse contribution of one layer (code seed or one stored row).\n *\n * `default` is boxed so an explicit JSON `null` default (meaning \"default to\n * null\") stays distinguishable from \"this layer contributes no default\".\n */\nexport interface FieldPolicyDelta {\n  default?: { value: unknown };\n  visibility?: FieldPolicyVisibility;\n  help?: string;\n  label?: string;\n  order?: number;\n  locked?: boolean;\n}\n\n/** One layer's contribution to a field's resolved policy (explain variant). */\nexport interface FieldPolicyLayerContribution {\n  layer: 'code' | 'app' | 'tenant' | 'user';\n  /** Chain node id for `tenant` layers (root → leaf order). */\n  tenantId?: string;\n  /** User id for the `user` layer. */\n  userId?: string;\n  delta: FieldPolicyDelta;\n}\n\n/** Fully merged policy for a single field. */\nexport interface ResolvedFieldPolicy {\n  fieldName: string;\n  /** True when any layer resolved a default (including an explicit null). */\n  hasDefault: boolean;\n  /** Parsed default value; `undefined` when {@link hasDefault} is false. */\n  defaultValue: unknown;\n  visibility: FieldPolicyVisibility;\n  help: string | null;\n  label: string | null;\n  order: number | null;\n  /** Grouping key — code-seed only (`ui.group`), not overridable by rows. */\n  group: string | null;\n  locked: boolean;\n  /** Mirror of the manifest required flag (nullable fields are optional). */\n  required: boolean;\n  /**\n   * True when the resolver forced `basic` visibility because the field is\n   * required and no usable default resolved (the resolver-side safety net for\n   * the required-field invariant).\n   */\n  visibilityForced?: boolean;\n}\n\n/** Merged policy for every field of one object. */\nexport interface ResolvedObjectFieldPolicy {\n  objectRef: string;\n  fields: Record<string, ResolvedFieldPolicy>;\n}\n\n/**\n * Explain variant: merged result plus the ordered per-layer contributions for\n * each field, so admin/gear UIs (#2049/#2050) never re-derive precedence.\n * Layers are listed in application order (code, app, tenant chain root → leaf,\n * user) and contain ONLY contributions that survive into the merged result:\n * tenant ancestors discarded by a permission-inheritance break and user rows\n * suppressed by an effective org lock are omitted, so sequentially replaying\n * the listed deltas reproduces the merged policy.\n */\nexport interface ExplainedObjectFieldPolicy extends ResolvedObjectFieldPolicy {\n  layers: Record<string, FieldPolicyLayerContribution[]>;\n}\n\n/** Minimal tenant node consumed by the hierarchy walk (mirrors smrt-features). */\nexport interface FieldPolicyTenantNode {\n  id: string;\n  inheritPermissions: boolean;\n  cascadePermissions: boolean;\n}\n\n/** Provider returning the root → leaf tenant chain (mirrors smrt-features). */\nexport interface FieldPolicyTenantHierarchyProvider {\n  getChain(tenantId: string): Promise<FieldPolicyTenantNode[]>;\n}\n\n/**\n * Loader-function DI seam (NOT a container registration): the resolver calls\n * it lazily and treats `null` as \"no hierarchy available\" (flat-tenant\n * fallback). The default loader dynamic-imports `@happyvertical/smrt-users`\n * and returns `null` when it is not installed.\n */\nexport type FieldPolicyTenantHierarchyLoader = (\n  options: SmrtClassOptions,\n) => Promise<FieldPolicyTenantHierarchyProvider | null>;\n\nexport interface ResolveFieldPolicyOptions {\n  tenantId?: string | null;\n  userId?: string | null;\n  /**\n   * Database holding `_smrt_field_policies`. Without it, only the code seed\n   * resolves (stored layers are skipped) — the smrt-prompts precedent.\n   */\n  db?: SmrtClassOptions['db'];\n  tenantHierarchyLoader?: FieldPolicyTenantHierarchyLoader;\n}\n\n/**\n * Minimal structural shape of the tenant surface loaded from\n * `@happyvertical/smrt-users` by the default hierarchy loader. Only the\n * permission-cascade fields consumed by the chain walk are modeled.\n */\nexport interface FieldPolicyUsersTenantRecord {\n  id: string;\n  inheritPermissions?: boolean;\n  cascadePermissions?: boolean;\n}\n\nexport interface FieldPolicyUsersModule {\n  TenantCollection: {\n    create(options: SmrtClassOptions): Promise<{\n      get(criteria: {\n        id: string;\n      }): Promise<FieldPolicyUsersTenantRecord | null>;\n      getAncestorsFromRoot(\n        tenantId: string,\n      ): Promise<FieldPolicyUsersTenantRecord[]>;\n    }>;\n  };\n}\n\n/** Result shape of the batch resolve action (`FieldPolicyCollection.resolveBatch`). */\nexport interface FieldPolicyBatchResult {\n  policies: Record<string, ResolvedObjectFieldPolicy>;\n}\n\nexport type { SmrtClassOptions };\n"],"mappings":";AA+BO,IAAM,6BAA6B;AAEnC,IAAM,2BAA4D;CACvE;CACA;CACA;AACF;AAEO,IAAM,4BAA8D;CACzE;CACA;CACA;AACF"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@happyvertical/smrt-fields",
+  "version": "0.40.57",
+  "description": "Layered field policy store and resolver (defaults, visibility tiers, help text) for SMRT objects",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "CLAUDE.md",
+    "AGENTS.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./manifest": "./dist/manifest.json",
+    "./manifest.json": "./dist/manifest.json"
+  },
+  "dependencies": {
+    "@happyvertical/sql": "^0.84.0",
+    "@happyvertical/smrt-core": "0.40.57",
+    "@happyvertical/smrt-tenancy": "0.40.57"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.2",
+    "typescript": "5.9.3",
+    "vite": "8.1.4",
+    "vitest": "4.1.10",
+    "@happyvertical/smrt-cli": "0.40.57",
+    "@happyvertical/smrt-users": "0.40.57",
+    "@happyvertical/smrt-vitest": "0.40.57"
+  },
+  "keywords": [
+    "smrt",
+    "field-policy",
+    "form-defaults",
+    "visibility",
+    "multi-tenant"
+  ],
+  "author": "HappyVertical",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/happyvertical/smrt.git",
+    "directory": "packages/fields"
+  },
+  "scripts": {
+    "build": "vite build --mode library",
+    "build:watch": "vite build --mode library --watch",
+    "clean": "rm -rf dist",
+    "dev": "vite dev",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "verify:pack": "node ../../scripts/verify-package-types-exports.js ."
+  }
+}