@happyvertical/smrt-fields 0.40.60 → 0.40.62

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/models/FieldPolicySuggestion.d.ts

@@ -0,0 +1,132 @@
+import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { FieldPolicySuggestionData, FieldPolicySuggestionKind, FieldPolicySuggestionStatus } from '../types.js';
+/**
+ * `activeKey` sentinel for the single ACTIVE (pending) suggestion per
+ * `(objectRef, fieldName, tenantId, kind)`. Settled rows key themselves by id,
+ * so history never competes for the slot.
+ */
+export declare const ACTIVE_SUGGESTION_KEY = "active";
+export interface FieldPolicySuggestionOptions extends SmrtObjectOptions {
+    objectRef?: string;
+    fieldName?: string;
+    tenantId?: string;
+    kind?: FieldPolicySuggestionKind;
+    proposedValue?: string | null;
+    evidence?: string;
+    status?: FieldPolicySuggestionStatus;
+    cooldownUntil?: Date | null;
+    decidedBy?: string | null;
+    decidedAt?: Date | null;
+}
+/**
+ * A pending, human-reviewable field-policy improvement proposed from real
+ * usage (epic #2045, issue #2051): promote a field to the `basic` tier, or
+ * seed an org default with the dominant observed value.
+ *
+ * Suggestion-first by design — a row DOES NOTHING until a
+ * `fields.policy.manage` holder accepts it, and acceptance writes the
+ * org-scope {@link ../models/FieldPolicy.FieldPolicy} row through NORMAL
+ * validation (registry check, type check, security rail, required-field
+ * invariant, ownership + permission split). Dismissing sets a cool-down that
+ * suppresses regeneration of the same suggestion.
+ *
+ * **One ACTIVE suggestion per identity, structurally** (not merely by a
+ * check-then-insert): {@link activeKey} is a computed column holding the
+ * sentinel {@link ACTIVE_SUGGESTION_KEY} while the row is `pending` and the
+ * row's own id once it settles, and it participates in `conflictColumns`. The
+ * unique index therefore admits at most ONE pending row per
+ * `(objectRef, fieldName, tenantId, kind)` while every settled row keys
+ * itself — so two overlapping generation runs (e.g. a global and a
+ * tenant-specific schedule) UPSERT onto the same row instead of duplicating,
+ * with no transaction spanning their reads. It is the `FieldPolicy.scopeKey`
+ * trick applied to a lifecycle slot. On settle the column flips to the row's
+ * id, which frees the slot for a post-cool-down regeneration while keeping the
+ * dismissed/accepted history (and its id) intact — core conflicts a persisted
+ * row on its primary key (#1472), so the flip is a plain UPDATE.
+ *
+ * #1885 seam: this substrate is fully independent of personas'
+ * `DirectiveProposal` review queue (no shared producer discriminator —
+ * deliberately out of scope). Tenant learning agents MAY create
+ * FieldPolicySuggestion rows through this model's normal validation; the
+ * reviewed `fields.policy.manage` acceptance gate is unchanged by who
+ * proposed.
+ */
+export declare class FieldPolicySuggestion 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;
+    /** Owning tenant (required — suggestions always target one org). */
+    tenantId?: string;
+    /** What the suggestion proposes ('promote' | 'default'). */
+    kind: FieldPolicySuggestionKind;
+    /**
+     * JSON-encoded proposed default (`kind: 'default'` only) — the exact
+     * encoding `FieldPolicy.defaultValue` stores, so acceptance passes it
+     * through unchanged. NULL for `promote`.
+     */
+    proposedValue: string | null;
+    /**
+     * Human-readable evidence as a JSON string: a `summary` sentence plus the
+     * structured window/threshold numbers behind it (see
+     * `buildFieldUsageEvidence`).
+     */
+    evidence: string;
+    /** Lifecycle status ('pending' | 'accepted' | 'dismissed'). */
+    status: FieldPolicySuggestionStatus;
+    /**
+     * Computed lifecycle-slot key, set in `save()`: {@link ACTIVE_SUGGESTION_KEY}
+     * while `pending`, else the row's own id. It exists ONLY to make the
+     * `conflictColumns` unique index express "at most one ACTIVE suggestion per
+     * identity, unlimited settled history" (the `FieldPolicy.scopeKey`
+     * precedent) — never read it for logic; `status` owns that.
+     */
+    activeKey: string;
+    /**
+     * Until this instant, a dismissed suggestion suppresses regeneration of the
+     * same `(objectRef, fieldName, tenantId, kind)` suggestion. NULL until
+     * dismissed.
+     */
+    cooldownUntil: Date | null;
+    /** Who accepted/dismissed (audit attribution, #2050); not validated. */
+    decidedBy: string | null;
+    /** When the suggestion was accepted/dismissed. */
+    decidedAt: Date | null;
+    constructor(options?: FieldPolicySuggestionOptions);
+    /** Parse the stored evidence object (guarded; junk parses as empty). */
+    getEvidence(): Record<string, unknown>;
+    /** Serialize an evidence object into the stored JSON string. */
+    setEvidence(evidence: Record<string, unknown>): void;
+    /** Parse the proposed value; `undefined` when none is stored. */
+    getProposedValue(): unknown;
+    /** Serialized row shape for the collection actions. */
+    toSuggestionData(): FieldPolicySuggestionData;
+    save(): Promise<this>;
+    /**
+     * Recompute the lifecycle-slot key: the shared sentinel while pending (so
+     * the unique index admits exactly one), the row's own id once settled (so
+     * history never competes for the slot and the freed slot allows a
+     * post-cool-down regeneration). A settled row that has not been persisted
+     * yet is assigned its id here — the key must be unique from the first write.
+     */
+    private applyActiveKey;
+    delete(): Promise<void>;
+    /**
+     * The "normal validation" the #1885 seam promises producers: registry-known
+     * field, policy-addressable, never sensitive/read-permission-gated/transient
+     * (those fields are count-only in usage data and get no suggestions), valid
+     * kind/status, and for `default` suggestions a JSON proposed value that
+     * type-checks against the manifest field type.
+     */
+    private validateFieldPolicySuggestion;
+    /**
+     * Tenant write boundary (the FieldPolicy posture): inside a non-bypass
+     * tenant context a caller may only touch its own tenant's suggestions —
+     * checked against BOTH the in-memory scope and, for persisted rows, the
+     * PERSISTED tenant (a foreign row cannot be re-scoped into the caller's
+     * tenant). Trusted execution (no context / bypass) is exempt — that is what
+     * lets the scheduled generation job and platform flows operate.
+     */
+    private assertRowOwnedByAmbientContext;
+}
+//# sourceMappingURL=FieldPolicySuggestion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FieldPolicySuggestion.d.ts","sourceRoot":"","sources":["../../src/models/FieldPolicySuggestion.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,UAAU,EACV,KAAK,iBAAiB,EAEvB,MAAM,0BAA0B,CAAC;AAclC,OAAO,EAGL,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EACjC,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,WAAW,CAAC;AAE9C,MAAM,WAAW,4BAA6B,SAAQ,iBAAiB;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,yBAAyB,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,2BAA2B,CAAC;IACrC,aAAa,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAOH,qBAaa,qBAAsB,SAAQ,UAAU;IACnD,6EAA6E;IAE7E,SAAS,EAAE,MAAM,CAAM;IAEvB,wEAAwE;IAExE,SAAS,EAAE,MAAM,CAAM;IAEvB,oEAAoE;IAEpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,4DAA4D;IAE5D,IAAI,EAAE,yBAAyB,CAAa;IAE5C;;;;OAIG;IAEH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEpC;;;;OAIG;IAEH,QAAQ,EAAE,MAAM,CAAQ;IAExB,+DAA+D;IAE/D,MAAM,EAAE,2BAA2B,CAAa;IAEhD;;;;;;OAMG;IAEH,SAAS,EAAE,MAAM,CAAyB;IAE1C;;;;OAIG;IAEH,aAAa,EAAE,IAAI,GAAG,IAAI,CAAQ;IAElC,wEAAwE;IAExE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEhC,kDAAkD;IAElD,SAAS,EAAE,IAAI,GAAG,IAAI,CAAQ;gBAElB,OAAO,GAAE,4BAAiC;IAkBtD,wEAAwE;IACxE,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAWtC,gEAAgE;IAChE,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIpD,iEAAiE;IACjE,gBAAgB,IAAI,OAAO;IAW3B,uDAAuD;IACvD,gBAAgB,IAAI,yBAAyB;IAgB9B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAOpC;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAWP,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtC;;;;;;OAMG;YACW,6BAA6B;IAiF3C;;;;;;;OAOG;YACW,8BAA8B;CAyC7C"}

package/dist/models/FieldUsageCounter.d.ts

@@ -0,0 +1,178 @@
+import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * Cap on distinct-user ids stored per bucket. For threshold questions
+ * ("did at least N distinct users set this field?") the capped set is EXACT up
+ * to the cap; once overflowed, {@link FieldUsageCounter.distinctUserCount} is
+ * an honest LOWER BOUND that trivially satisfies any threshold ≤ the cap.
+ */
+export declare const MAX_DISTINCT_USERS_PER_BUCKET = 100;
+/** Cap on histogram buckets per counter row (bounded storage). */
+export declare const MAX_VALUE_HISTOGRAM_BUCKETS = 25;
+/** Longest histogram key recorded; longer samples are skipped (count-only). */
+export declare const MAX_VALUE_HISTOGRAM_KEY_LENGTH = 64;
+/** `period` bucket format: UTC calendar day. */
+export declare const FIELD_USAGE_PERIOD_PATTERN: RegExp;
+/** The UTC day bucket for a timestamp (`YYYY-MM-DD`). */
+export declare function fieldUsagePeriodForDate(date: Date): string;
+/**
+ * A prototype-free histogram map.
+ *
+ * Histogram keys are user-supplied values (an `idType: 'text'` reference id may
+ * legitimately be `constructor`, `toString`, or `__proto__`). On a plain object
+ * those either resolve to inherited members — making an absent bucket look
+ * present and corrupting its count — or, for `__proto__`, invoke the prototype
+ * setter instead of creating an own key. A null-prototype object has no such
+ * members, so every key behaves like data. Use this everywhere histogram counts
+ * are accumulated (storage AND merge paths).
+ */
+export declare function emptyHistogram(): Record<string, number>;
+export interface FieldUsageCounterOptions extends SmrtObjectOptions {
+    objectRef?: string;
+    fieldName?: string;
+    tenantId?: string;
+    period?: string;
+    submissionCount?: number;
+    setCount?: number;
+    distinctUserCount?: number;
+    distinctUserIds?: string;
+    distinctUsersOverflowed?: boolean;
+    valueHistogram?: string | null;
+    valueHistogramOverflowed?: boolean;
+}
+/**
+ * Period-bucketed field usage counter (epic #2045, issue #2051).
+ *
+ * One row aggregates field submissions for a single
+ * `(objectRef, fieldName, tenantId, period)` — the substrate the
+ * suggestion-generation job reads. Counters are deliberately APPROXIMATE:
+ * ingestion is fire-and-forget and concurrent bucket merges may lose an
+ * increment (read-modify-write), which is acceptable for usage statistics and
+ * documented here rather than papered over.
+ *
+ * TWO counters, because they answer different questions:
+ * - {@link submissionCount} — EVERY observed submission of the field
+ *   (default-matching or not). It is the denominator for value dominance:
+ *   "N% of submissions used value V". Without it, a value seen only in
+ *   deviations would look 100% dominant even against thousands of
+ *   default-valued submissions.
+ * - {@link setCount} — submissions whose value DIFFERED from the resolved
+ *   default (server-derived). It plus {@link distinctUserIds} is the
+ *   promote signal ("real users are actively filling this in").
+ *
+ * Content rails (enforced by the ingestion action, which derives everything
+ * from the live registry and never trusts the client):
+ * - Sensitive and read-permission-gated fields are COUNT-ONLY: their raw
+ *   values are never recorded anywhere in usage data — not even for
+ *   default-matching submissions.
+ * - Value histograms exist only for low-cardinality field types (`boolean`,
+ *   `foreignKey`, `crossPackageRef`) — never free text, even non-sensitive
+ *   text (PII risk) — with a bounded bucket count and key length. They cover
+ *   ALL submissions (not just deviations) so the dominance ratio is a true
+ *   fraction of {@link submissionCount}.
+ * - `distinctUserIds` is a capped set with an overflow marker (see
+ *   {@link MAX_DISTINCT_USERS_PER_BUCKET} for the honesty contract).
+ */
+export declare class FieldUsageCounter extends SmrtObject {
+    /** Qualified class name of the target object (`@package/name:ClassName`). */
+    objectRef: string;
+    /** Field name on the target object. */
+    fieldName: string;
+    /**
+     * Owning tenant. REQUIRED: ingestion fails closed without an ambient tenant
+     * context, so every row is attributable (and the conflict-column tuple
+     * stays total). Native UUID on PostgreSQL/DuckDB.
+     */
+    tenantId?: string;
+    /** UTC day bucket (`YYYY-MM-DD`); lexicographic order is time order. */
+    period: string;
+    /**
+     * EVERY observed submission of this field in the bucket, whether or not the
+     * value matched the resolved default — the dominance denominator.
+     *
+     * Rows written before this column existed carry `0` while `setCount > 0`;
+     * {@link isLegacyBucket} detects that shape and the generation job then
+     * treats the total as UNKNOWN and skips `default` suggestions for the group
+     * (promote, which needs no denominator, still works).
+     */
+    submissionCount: number;
+    /**
+     * Submissions whose value DIFFERED from the server-resolved default (the
+     * promote signal). Always `<= submissionCount` on rows written by the
+     * current ingestion path.
+     */
+    setCount: number;
+    /**
+     * Size of the stored distinct-user set. When
+     * {@link distinctUsersOverflowed} is true this is a LOWER BOUND (the set is
+     * capped), never an estimate.
+     */
+    distinctUserCount: number;
+    /** JSON array of distinct user ids, capped (see the class doc). */
+    distinctUserIds: string;
+    /** True once a distinct user was NOT added because the set is at its cap. */
+    distinctUsersOverflowed: boolean;
+    /**
+     * JSON object `serializedValue -> count` for histogram-eligible fields;
+     * NULL when the field is count-only. Keys are bounded in number and length.
+     */
+    valueHistogram: string | null;
+    /** True once a sample was dropped because the bucket cap was reached. */
+    valueHistogramOverflowed: boolean;
+    constructor(options?: FieldUsageCounterOptions);
+    /** Parse the stored distinct-user set (guarded; junk parses as empty). */
+    getDistinctUserIds(): string[];
+    /**
+     * Add a user to the distinct set, honoring the cap. At the cap the id is
+     * NOT added and the overflow marker is set instead, keeping
+     * {@link distinctUserCount} an honest lower bound.
+     */
+    addDistinctUser(userId: string): void;
+    /**
+     * Parse the stored histogram (guarded; junk parses as empty).
+     *
+     * Returns a NULL-PROTOTYPE object. Histogram keys are user-supplied ids —
+     * an `idType: 'text'` reference may legitimately be `constructor`,
+     * `toString`, or `__proto__` — and on a plain object those inherit truthy
+     * prototype values (so a missing bucket reads as present) or, for
+     * `__proto__`, hit the prototype setter instead of creating an own key.
+     * Both would silently corrupt counts. See {@link emptyHistogram}.
+     */
+    getValueHistogram(): Record<string, number>;
+    /**
+     * Record one histogram sample under an already-serialized key, honoring the
+     * bucket cap (a NEW key past the cap is dropped and the overflow marker
+     * set; existing keys keep counting).
+     *
+     * Bucket presence is an OWN-key test, never a truthiness/`undefined` read,
+     * so prototype-shaped ids behave like any other key.
+     */
+    recordHistogramSample(key: string): void;
+    /**
+     * Whether this bucket predates the {@link submissionCount} column (or was
+     * corrupted): it records deviations without a total, so no honest dominance
+     * ratio can be computed from it. The generation job skips `default`
+     * suggestions for any group containing such a bucket.
+     */
+    isLegacyBucket(): boolean;
+    save(): Promise<this>;
+    delete(): Promise<void>;
+    private validateFieldUsageCounter;
+    /**
+     * Tenant write boundary (the FieldPolicy posture — no class-level
+     * `@TenantScoped`, because the learning jobs legitimately operate
+     * cross-tenant in trusted execution): inside a non-bypass tenant context a
+     * caller may only touch rows of its own tenant; without a context (system/
+     * job execution) writes are trusted.
+     *
+     * Checked against BOTH the in-memory tenant and — for a row that already
+     * exists — the PERSISTED one. The persisted check is what makes the boundary
+     * real: bucket ids are deterministic and the deriving helper is exported, so
+     * a foreign row is trivially addressable, and an in-memory-only check would
+     * let a caller load it, re-stamp `tenantId` with its own, and adopt or delete
+     * another tenant's counters (the #2047 FieldPolicy pattern).
+     */
+    private assertRowOwnedByAmbientContext;
+    /** The stored tenant for this row's id; `null` when it is not persisted. */
+    private getPersistedTenantId;
+}
+//# sourceMappingURL=FieldUsageCounter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FieldUsageCounter.d.ts","sourceRoot":"","sources":["../../src/models/FieldUsageCounter.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,UAAU,EACV,KAAK,iBAAiB,EAEvB,MAAM,0BAA0B,CAAC;AAQlC;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,MAAM,CAAC;AAEjD,kEAAkE;AAClE,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,+EAA+E;AAC/E,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,QAAwB,CAAC;AAEhE,yDAAyD;AACzD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEvD;AAED,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAMH,qBAOa,iBAAkB,SAAQ,UAAU;IAC/C,6EAA6E;IAE7E,SAAS,EAAE,MAAM,CAAM;IAEvB,uCAAuC;IAEvC,SAAS,EAAE,MAAM,CAAM;IAEvB;;;;OAIG;IAEH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,wEAAwE;IAExE,MAAM,EAAE,MAAM,CAAM;IAEpB;;;;;;;;OAQG;IAEH,eAAe,EAAE,MAAM,CAAK;IAE5B;;;;OAIG;IAEH,QAAQ,EAAE,MAAM,CAAK;IAErB;;;;OAIG;IAEH,iBAAiB,EAAE,MAAM,CAAK;IAE9B,mEAAmE;IAEnE,eAAe,EAAE,MAAM,CAAQ;IAE/B,6EAA6E;IAE7E,uBAAuB,EAAE,OAAO,CAAS;IAEzC;;;OAGG;IAEH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAQ;IAErC,yEAAyE;IAEzE,wBAAwB,EAAE,OAAO,CAAS;gBAE9B,OAAO,GAAE,wBAA6B;IA2BlD,0EAA0E;IAC1E,kBAAkB,IAAI,MAAM,EAAE;IAW9B;;;;OAIG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAcrC;;;;;;;;;OASG;IACH,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAwB3C;;;;;;;OAOG;IACH,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAiBxC;;;;;OAKG;IACH,cAAc,IAAI,OAAO;IAIV,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAMrB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtC,OAAO,CAAC,yBAAyB;IAoCjC;;;;;;;;;;;;;OAaG;YACW,8BAA8B;IAgC5C,4EAA4E;YAC9D,oBAAoB;CAYnC"}

package/dist/models/FieldUsageReportReceipt.d.ts

@@ -0,0 +1,25 @@
+import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * Durable daily receipt for one member's contribution to one field.
+ *
+ * The counter action creates this before incrementing its aggregate. Its
+ * natural key makes the anti-inflation rule durable across requests and
+ * replicas: one `(tenant, user, object, field, UTC day)` sample may affect
+ * usage evidence. Receipts intentionally retain no submitted value.
+ */
+export declare class FieldUsageReportReceipt extends SmrtObject {
+    tenantId?: string;
+    userId: string;
+    objectRef: string;
+    fieldName: string;
+    period: string;
+    constructor(options?: FieldUsageReportReceiptOptions);
+}
+export interface FieldUsageReportReceiptOptions extends SmrtObjectOptions {
+    tenantId?: string;
+    userId?: string;
+    objectRef?: string;
+    fieldName?: string;
+    period?: string;
+}
+//# sourceMappingURL=FieldUsageReportReceipt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FieldUsageReportReceipt.d.ts","sourceRoot":"","sources":["../../src/models/FieldUsageReportReceipt.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,UAAU,EACV,KAAK,iBAAiB,EAEvB,MAAM,0BAA0B,CAAC;AAGlC;;;;;;;GAOG;AACH,qBAaa,uBAAwB,SAAQ,UAAU;IAErD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,MAAM,EAAE,MAAM,CAAM;IAGpB,SAAS,EAAE,MAAM,CAAM;IAGvB,SAAS,EAAE,MAAM,CAAM;IAGvB,MAAM,EAAE,MAAM,CAAM;gBAER,OAAO,GAAE,8BAAmC;CAQzD;AAED,MAAM,WAAW,8BAA+B,SAAQ,iBAAiB;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

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