@happyvertical/smrt-fields 0.40.61 → 0.40.63

package/dist/svelte/suggestions.js

@@ -0,0 +1,68 @@
+/**
+ * Structural browser contracts for field-policy suggestion review.
+ *
+ * These types intentionally omit tenant, user, authorization, and field
+ * sensitivity data. Hosts bind methods to authenticated generated clients;
+ * the server derives identity and validates every action.
+ */
+/**
+ * Validate generated custom-action output at the browser boundary. A malformed
+ * response is an error, never an empty queue that could conceal work.
+ */
+export function parsePendingFieldPolicySuggestions(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    const candidate = value;
+    const total = candidate.total;
+    if (!Array.isArray(candidate.suggestions) ||
+        typeof total !== 'number' ||
+        !Number.isSafeInteger(total) ||
+        total < 0) {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    const suggestions = candidate.suggestions.map(parseSuggestion);
+    if (total < suggestions.length) {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    return { suggestions, total };
+}
+function parseSuggestion(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    const candidate = value;
+    if (typeof candidate.id !== 'string' ||
+        typeof candidate.objectRef !== 'string' ||
+        typeof candidate.fieldName !== 'string' ||
+        (candidate.kind !== 'promote' && candidate.kind !== 'default') ||
+        (candidate.proposedValue !== null &&
+            typeof candidate.proposedValue !== 'string') ||
+        !isRecord(candidate.evidence) ||
+        (candidate.status !== undefined && candidate.status !== 'pending')) {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    return {
+        id: candidate.id,
+        objectRef: candidate.objectRef,
+        fieldName: candidate.fieldName,
+        kind: candidate.kind,
+        proposedValue: candidate.proposedValue,
+        evidence: candidate.evidence,
+    };
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/** Human-readable evidence without assuming a server-side evidence schema. */
+export function fieldPolicySuggestionEvidence(suggestion) {
+    const summary = suggestion.evidence.summary;
+    if (typeof summary === 'string' && summary.trim())
+        return summary;
+    const distinctUsers = suggestion.evidence.distinctUsers;
+    const setCount = suggestion.evidence.setCount;
+    if (typeof distinctUsers === 'number' && typeof setCount === 'number') {
+        return `${distinctUsers} users set this field ${setCount} times.`;
+    }
+    return 'Based on recent organization field usage.';
+}

package/dist/svelte/usage-capture.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Browser-safe usage capture primitives for the field-policy learning loop.
+ *
+ * Hosts own the authenticated transport. This module deliberately carries no
+ * tenant, user, permission, or field-sensitivity information: the server
+ * derives all of that from its ambient context and live object registry.
+ */
+/** One submitted field value sent to the host's usage transport. */
+export interface FieldUsageEntry {
+    objectRef: string;
+    fieldName: string;
+    value?: unknown;
+    /** Optional value-less hint; normal ObjectForm capture sends the value. */
+    matchedDefault?: boolean;
+}
+/** Resolved default metadata used only for a value-less count signal. */
+export interface FieldUsageDefault {
+    hasDefault: boolean;
+    defaultValue: unknown;
+}
+/**
+ * Structural host transport for the counters collection's batched action.
+ * A reporter must never be allowed to affect a successful form submission.
+ */
+export interface FieldUsageReporter {
+    reportUsage(input: {
+        entries: readonly FieldUsageEntry[];
+    }): unknown;
+}
+export interface CollectFieldUsageEntriesOptions {
+    objectRef: string;
+    values: Readonly<Record<string, unknown>>;
+    /**
+     * Rendered field names and their persisted browser wire type. The type is
+     * used only to minimize value transit — it is never a sensitivity or
+     * authorization decision.
+     */
+    fields?: Readonly<Record<string, FieldUsageWireType>>;
+    /**
+     * Resolved defaults for rendered fields. For count-only values, a matching
+     * default is sent as a positive hint so the server does not treat it as a
+     * deviation. Absent or non-matching defaults deliberately send no hint.
+     */
+    defaults?: Readonly<Record<string, FieldUsageDefault>>;
+}
+export type FieldUsageWireType = 'text' | 'integer' | 'decimal' | 'boolean' | 'datetime' | 'json' | 'foreignKey' | 'crossPackageRef';
+/** Values may transit only for bounded, identifier-like wire types. */
+export declare function canCaptureFieldUsageValue(type: FieldUsageWireType | undefined): boolean;
+/**
+ * Collect every non-blank submitted field, including values matching a
+ * resolved default. Values transit only for bounded boolean/reference fields;
+ * free text, numbers, dates, and JSON emit count-only signals. Capturing only
+ * deviations would make the default's dominance denominator disappear. The
+ * server still derives eligibility, sensitivity, and every aggregate.
+ */
+export declare function collectFieldUsageEntries(options: CollectFieldUsageEntriesOptions): FieldUsageEntry[];
+/** Zero and false are submissions; only absent/null/empty-string values are not. */
+export declare function isBlankFieldValue(value: unknown): boolean;
+/** JSON-safe equality for the count-only default-match hint. */
+export declare function fieldUsageValuesEqual(left: unknown, right: unknown): boolean;
+/** Fire-and-forget by design: metrics transport failures never reject submit. */
+export declare function reportFieldUsage(reporter: FieldUsageReporter | undefined, entries: readonly FieldUsageEntry[]): void;
+//# sourceMappingURL=usage-capture.d.ts.map

package/dist/svelte/usage-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-capture.d.ts","sourceRoot":"","sources":["../../src/svelte/usage-capture.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,SAAS,eAAe,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC;CACtE;AAED,MAAM,WAAW,+BAA+B;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;IACtD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;CACxD;AAED,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,SAAS,GACT,SAAS,GACT,SAAS,GACT,UAAU,GACV,MAAM,GACN,YAAY,GACZ,iBAAiB,CAAC;AAEtB,uEAAuE;AACvE,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,kBAAkB,GAAG,SAAS,GACnC,OAAO,CAIT;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,+BAA+B,GACvC,eAAe,EAAE,CAyBnB;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED,gEAAgE;AAChE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAO5E;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,kBAAkB,GAAG,SAAS,EACxC,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,IAAI,CASN"}

package/dist/svelte/usage-capture.js

@@ -0,0 +1,61 @@
+/** Values may transit only for bounded, identifier-like wire types. */
+export function canCaptureFieldUsageValue(type) {
+    return (type === 'boolean' || type === 'foreignKey' || type === 'crossPackageRef');
+}
+/**
+ * Collect every non-blank submitted field, including values matching a
+ * resolved default. Values transit only for bounded boolean/reference fields;
+ * free text, numbers, dates, and JSON emit count-only signals. Capturing only
+ * deviations would make the default's dominance denominator disappear. The
+ * server still derives eligibility, sensitivity, and every aggregate.
+ */
+export function collectFieldUsageEntries(options) {
+    const fields = options.fields ??
+        Object.fromEntries(Object.keys(options.values).map((fieldName) => [fieldName, undefined]));
+    const entries = [];
+    for (const [fieldName, type] of Object.entries(fields)) {
+        const value = options.values[fieldName];
+        if (isBlankFieldValue(value))
+            continue;
+        if (canCaptureFieldUsageValue(type)) {
+            entries.push({ objectRef: options.objectRef, fieldName, value });
+            continue;
+        }
+        const fieldDefault = options.defaults?.[fieldName];
+        entries.push({
+            objectRef: options.objectRef,
+            fieldName,
+            ...(fieldDefault?.hasDefault &&
+                fieldUsageValuesEqual(value, fieldDefault.defaultValue)
+                ? { matchedDefault: true }
+                : {}),
+        });
+    }
+    return entries;
+}
+/** Zero and false are submissions; only absent/null/empty-string values are not. */
+export function isBlankFieldValue(value) {
+    return value === undefined || value === null || value === '';
+}
+/** JSON-safe equality for the count-only default-match hint. */
+export function fieldUsageValuesEqual(left, right) {
+    if (left === right)
+        return true;
+    try {
+        return JSON.stringify(left) === JSON.stringify(right);
+    }
+    catch {
+        return false;
+    }
+}
+/** Fire-and-forget by design: metrics transport failures never reject submit. */
+export function reportFieldUsage(reporter, entries) {
+    if (!reporter || entries.length === 0)
+        return;
+    try {
+        void Promise.resolve(reporter.reportUsage({ entries })).catch(() => undefined);
+    }
+    catch {
+        // A synchronous host adapter failure is non-fatal by the same contract.
+    }
+}

package/dist/types.d.ts

@@ -272,5 +272,45 @@ export interface FieldPolicyEditorStateDenied {
     status: 403;
 }
 export type FieldPolicyEditorStateResult = FieldPolicyEditorState | FieldPolicyEditorStateDenied;
+export type FieldPolicySuggestionKind = 'promote' | 'default';
+export declare const FIELD_POLICY_SUGGESTION_KINDS: readonly FieldPolicySuggestionKind[];
+export type FieldPolicySuggestionStatus = 'pending' | 'accepted' | 'dismissed';
+export declare const FIELD_POLICY_SUGGESTION_STATUSES: readonly FieldPolicySuggestionStatus[];
+/** One bounded client-side form submission sample. */
+export interface FieldUsageReportEntry {
+    objectRef: string;
+    fieldName: string;
+    value?: unknown;
+    /** Used only for value-less samples; server comparison wins when present. */
+    matchedDefault?: boolean;
+}
+export interface FieldUsageReportResult {
+    accepted: number;
+    dropped: number;
+}
+export interface FieldPolicySuggestionData {
+    id: string;
+    objectRef: string;
+    fieldName: string;
+    tenantId: string;
+    kind: FieldPolicySuggestionKind;
+    proposedValue: string | null;
+    evidence: Record<string, unknown>;
+    status: FieldPolicySuggestionStatus;
+    cooldownUntil: string | null;
+    decidedBy: string | null;
+    decidedAt: string | null;
+}
+export interface PendingFieldPolicySuggestionsResult {
+    suggestions: FieldPolicySuggestionData[];
+    total: number;
+}
+export interface AcceptFieldPolicySuggestionResult {
+    suggestion: FieldPolicySuggestionData;
+    policyRowId: string;
+}
+export interface DismissFieldPolicySuggestionResult {
+    suggestion: FieldPolicySuggestionData;
+}
 export type { SmrtClassOptions };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -10,7 +10,13 @@ var FIELD_POLICY_VISIBILITIES = [
 	"advanced",
 	"hidden"
 ];
+var FIELD_POLICY_SUGGESTION_KINDS = ["promote", "default"];
+var FIELD_POLICY_SUGGESTION_STATUSES = [
+	"pending",
+	"accepted",
+	"dismissed"
+];
 //#endregion
-export { APP_FIELD_POLICY_SCOPE_KEY, FIELD_POLICY_SCOPE_TYPES, FIELD_POLICY_VISIBILITIES };
+export { APP_FIELD_POLICY_SCOPE_KEY, FIELD_POLICY_SCOPE_TYPES, FIELD_POLICY_SUGGESTION_KINDS, FIELD_POLICY_SUGGESTION_STATUSES, FIELD_POLICY_VISIBILITIES };
 
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +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   * Internal write-validation seam: omit persisted rows while evaluating a\n   * proposed replacement. Excluded resolutions bypass the shared cache so a\n   * projected result can never poison ordinary reads.\n   */\n  excludePolicyIds?: ReadonlySet<string>;\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\n/** A policy row safe to expose through the context-scoped gear action. */\nexport interface FieldPolicyEditorRow {\n  defaultValue: string | null;\n  displayOrder: number | null;\n  fieldName: string;\n  help: string | null;\n  id: string;\n  label: string | null;\n  locked: boolean | null;\n  scopeType: FieldPolicyScopeType;\n  tenantId: string | null;\n  updatedBy: string | null;\n  userId: string | null;\n  visibility: FieldPolicyVisibility | null;\n}\n\n/** Context-derived authorization state for the field-policy gear. */\nexport interface FieldPolicyEditorCapabilities {\n  manage: boolean;\n  personalize: boolean;\n}\n\n/**\n * Gear bootstrap response. `policy` is always filtered by the public-field\n * rail; raw rows and explanation layers appear only for scopes the caller is\n * authorized to mutate. Row ids are present for reset/delete operations.\n */\nexport interface FieldPolicyEditorState {\n  capabilities: FieldPolicyEditorCapabilities;\n  /**\n   * For the caller's personal layer only, whether removing that layer's\n   * default still leaves a usable default at code/app/tenant precedence.\n   * This intentionally exposes no lower-layer rows or default values.\n   */\n  personalLowerDefaultUsable: Record<string, boolean>;\n  policy: ExplainedObjectFieldPolicy;\n  rows: {\n    app: FieldPolicyEditorRow[];\n    tenant: FieldPolicyEditorRow[];\n    user: FieldPolicyEditorRow[];\n  };\n}\n\n/** A stored organization row with the immutable audit metadata needed by #2050. */\nexport interface FieldPolicyAuditRow extends FieldPolicyEditorRow {\n  objectRef: string;\n  createdAt: string | null;\n  updatedAt: string | null;\n}\n\n/** Why a persisted policy row is no longer usable by the live registry. */\nexport type FieldPolicyDriftReason =\n  | 'unknown-object'\n  | 'unknown-field'\n  | 'excluded-field';\n\n/** Drift is deliberately identity-only: stale values are never serialized. */\nexport interface FieldPolicyDriftRow {\n  id: string;\n  objectRef: string;\n  fieldName: string;\n  scopeType: FieldPolicyScopeType;\n  tenantId: string | null;\n  userId: string | null;\n  updatedBy: string | null;\n  createdAt: string | null;\n  updatedAt: string | null;\n  reason: FieldPolicyDriftReason;\n  prunable: boolean;\n}\n\n/**\n * Tenant-admin catalog read surface. Foreign user rows are represented only\n * by counts; their values and identifiers never leave the collection.\n */\nexport interface FieldPolicyAuditSnapshot {\n  orgRows: FieldPolicyAuditRow[];\n  appRows: FieldPolicyAuditRow[];\n  inheritedOrgKeys: Record<string, string[]>;\n  userOverrideCounts: Record<string, Record<string, number>>;\n  driftRows: FieldPolicyDriftRow[];\n  policies: Record<string, ExplainedObjectFieldPolicy>;\n  caller: {\n    tenantId: string | null;\n    userId: string | null;\n    canManageOrg: boolean;\n    canPersonalize: boolean;\n  };\n}\n\n/** Explicit 403 result used by generated custom-action transports. */\nexport interface FieldPolicyEditorStateDenied {\n  code: 'permission_denied';\n  message: string;\n  ok: false;\n  status: 403;\n}\n\nexport type FieldPolicyEditorStateResult =\n  | FieldPolicyEditorState\n  | FieldPolicyEditorStateDenied;\n\nexport type { SmrtClassOptions };\n"],"mappings":";AA+BO,IAAM,6BAA6B;AAEnC,IAAM,2BAA4D;CACvE;CACA;CACA;AACF;AAEO,IAAM,4BAA8D;CACzE;CACA;CACA;AACF"}
+{"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   * Internal write-validation seam: omit persisted rows while evaluating a\n   * proposed replacement. Excluded resolutions bypass the shared cache so a\n   * projected result can never poison ordinary reads.\n   */\n  excludePolicyIds?: ReadonlySet<string>;\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\n/** A policy row safe to expose through the context-scoped gear action. */\nexport interface FieldPolicyEditorRow {\n  defaultValue: string | null;\n  displayOrder: number | null;\n  fieldName: string;\n  help: string | null;\n  id: string;\n  label: string | null;\n  locked: boolean | null;\n  scopeType: FieldPolicyScopeType;\n  tenantId: string | null;\n  updatedBy: string | null;\n  userId: string | null;\n  visibility: FieldPolicyVisibility | null;\n}\n\n/** Context-derived authorization state for the field-policy gear. */\nexport interface FieldPolicyEditorCapabilities {\n  manage: boolean;\n  personalize: boolean;\n}\n\n/**\n * Gear bootstrap response. `policy` is always filtered by the public-field\n * rail; raw rows and explanation layers appear only for scopes the caller is\n * authorized to mutate. Row ids are present for reset/delete operations.\n */\nexport interface FieldPolicyEditorState {\n  capabilities: FieldPolicyEditorCapabilities;\n  /**\n   * For the caller's personal layer only, whether removing that layer's\n   * default still leaves a usable default at code/app/tenant precedence.\n   * This intentionally exposes no lower-layer rows or default values.\n   */\n  personalLowerDefaultUsable: Record<string, boolean>;\n  policy: ExplainedObjectFieldPolicy;\n  rows: {\n    app: FieldPolicyEditorRow[];\n    tenant: FieldPolicyEditorRow[];\n    user: FieldPolicyEditorRow[];\n  };\n}\n\n/** A stored organization row with the immutable audit metadata needed by #2050. */\nexport interface FieldPolicyAuditRow extends FieldPolicyEditorRow {\n  objectRef: string;\n  createdAt: string | null;\n  updatedAt: string | null;\n}\n\n/** Why a persisted policy row is no longer usable by the live registry. */\nexport type FieldPolicyDriftReason =\n  | 'unknown-object'\n  | 'unknown-field'\n  | 'excluded-field';\n\n/** Drift is deliberately identity-only: stale values are never serialized. */\nexport interface FieldPolicyDriftRow {\n  id: string;\n  objectRef: string;\n  fieldName: string;\n  scopeType: FieldPolicyScopeType;\n  tenantId: string | null;\n  userId: string | null;\n  updatedBy: string | null;\n  createdAt: string | null;\n  updatedAt: string | null;\n  reason: FieldPolicyDriftReason;\n  prunable: boolean;\n}\n\n/**\n * Tenant-admin catalog read surface. Foreign user rows are represented only\n * by counts; their values and identifiers never leave the collection.\n */\nexport interface FieldPolicyAuditSnapshot {\n  orgRows: FieldPolicyAuditRow[];\n  appRows: FieldPolicyAuditRow[];\n  inheritedOrgKeys: Record<string, string[]>;\n  userOverrideCounts: Record<string, Record<string, number>>;\n  driftRows: FieldPolicyDriftRow[];\n  policies: Record<string, ExplainedObjectFieldPolicy>;\n  caller: {\n    tenantId: string | null;\n    userId: string | null;\n    canManageOrg: boolean;\n    canPersonalize: boolean;\n  };\n}\n\n/** Explicit 403 result used by generated custom-action transports. */\nexport interface FieldPolicyEditorStateDenied {\n  code: 'permission_denied';\n  message: string;\n  ok: false;\n  status: 403;\n}\n\nexport type FieldPolicyEditorStateResult =\n  | FieldPolicyEditorState\n  | FieldPolicyEditorStateDenied;\n\n// ---------------------------------------------------------------------------\n// Usage capture + promotion suggestions (#2051)\n// ---------------------------------------------------------------------------\n\nexport type FieldPolicySuggestionKind = 'promote' | 'default';\nexport const FIELD_POLICY_SUGGESTION_KINDS: readonly FieldPolicySuggestionKind[] =\n  ['promote', 'default'];\n\nexport type FieldPolicySuggestionStatus = 'pending' | 'accepted' | 'dismissed';\nexport const FIELD_POLICY_SUGGESTION_STATUSES: readonly FieldPolicySuggestionStatus[] =\n  ['pending', 'accepted', 'dismissed'];\n\n/** One bounded client-side form submission sample. */\nexport interface FieldUsageReportEntry {\n  objectRef: string;\n  fieldName: string;\n  value?: unknown;\n  /** Used only for value-less samples; server comparison wins when present. */\n  matchedDefault?: boolean;\n}\n\nexport interface FieldUsageReportResult {\n  accepted: number;\n  dropped: number;\n}\n\nexport interface FieldPolicySuggestionData {\n  id: string;\n  objectRef: string;\n  fieldName: string;\n  tenantId: string;\n  kind: FieldPolicySuggestionKind;\n  proposedValue: string | null;\n  evidence: Record<string, unknown>;\n  status: FieldPolicySuggestionStatus;\n  cooldownUntil: string | null;\n  decidedBy: string | null;\n  decidedAt: string | null;\n}\n\nexport interface PendingFieldPolicySuggestionsResult {\n  suggestions: FieldPolicySuggestionData[];\n  total: number;\n}\n\nexport interface AcceptFieldPolicySuggestionResult {\n  suggestion: FieldPolicySuggestionData;\n  policyRowId: string;\n}\n\nexport interface DismissFieldPolicySuggestionResult {\n  suggestion: FieldPolicySuggestionData;\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;AA0RO,IAAM,gCACX,CAAC,WAAW,SAAS;AAGhB,IAAM,mCACX;CAAC;CAAW;CAAY;AAAW"}

package/dist/usage-learning.d.ts

@@ -0,0 +1,201 @@
+import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { DatabaseInterface } from '@happyvertical/sql';
+import { FieldPolicySuggestionKind } from './types.js';
+export interface FieldUsageMaintenanceConfig {
+    /** Drop counter buckets older than this (by `period`). Default 90 days. */
+    counterMaxAgeMs: number;
+    /** Keep at most this many counter rows (oldest pruned first). Default 100k. */
+    counterMaxRows: number;
+    /** Drop ACCEPTED suggestions decided longer ago than this. Default 180 days. */
+    suggestionAcceptedMaxAgeMs: number;
+}
+export declare const FIELD_USAGE_MAINTENANCE_DEFAULTS: FieldUsageMaintenanceConfig;
+export interface FieldUsageSuggestionConfig {
+    /** Usage window the thresholds evaluate over. Default 30 days. */
+    windowDays: number;
+    /** Distinct users required for a `promote` suggestion. Default 5. */
+    minDistinctUsers: number;
+    /** Submissions required before a `default` suggestion. Default 10. */
+    minSetCount: number;
+    /**
+     * Share of windowed submissions a single value must reach for a `default`
+     * suggestion (denominator is TOTAL setCount, so histogram overflow can only
+     * make this more conservative). Default 0.8.
+     */
+    defaultDominanceRatio: number;
+}
+export declare const FIELD_USAGE_SUGGESTION_DEFAULTS: FieldUsageSuggestionConfig;
+export interface FieldUsageMaintenanceSummary {
+    countersPruned: number;
+    receiptsPruned: number;
+    suggestionsPruned: number;
+}
+export interface FieldUsageSuggestionRunSummary {
+    /**
+     * Suggestions this run wrote. Under overlapping runs both may report a
+     * create for the same candidate while the model's active-slot unique index
+     * converges them onto ONE row (see `FieldPolicySuggestion.activeKey`) — the
+     * tally is per-run work, not a row count.
+     */
+    created: number;
+    /** Candidates suppressed by a pending or cooling-down suggestion. */
+    suppressed: number;
+    /** Distinct (tenant, objectRef, fieldName) groups evaluated. */
+    groupsConsidered: number;
+    /**
+     * Groups whose evaluation threw and was skipped. A failing group never
+     * aborts the run — a global pass must keep serving every other tenant.
+     */
+    groupsFailed: number;
+    /**
+     * Bounded sample of failure messages (`MAX_REPORTED_GROUP_FAILURES`) so an
+     * operator can see WHY without the summary growing with the queue.
+     */
+    failures: string[];
+}
+/** Cap on {@link FieldUsageSuggestionRunSummary.failures} entries. */
+export declare const MAX_REPORTED_GROUP_FAILURES = 5;
+export interface FieldUsageCounterRetention {
+    maxAgeMs?: number;
+    maxRows?: number;
+    /** Restrict pruning to one tenant (ambient-context runs). */
+    tenantId?: string | null;
+}
+/**
+ * Prune counter rows to bound growth. Applies whichever bounds are provided
+ * (at least one required): `maxAgeMs` drops buckets whose `period` day is
+ * older than the cutoff; `maxRows` keeps only the newest N rows by
+ * `(period, id)`, deleting oldest-first. Mirrors core's `pruneChangeFeed`.
+ */
+export declare function pruneFieldUsageCounters(db: DatabaseInterface, retention: FieldUsageCounterRetention): Promise<{
+    pruned: number;
+}>;
+/**
+ * Drop durable anti-inflation receipts at the same age cutoff as counters.
+ *
+ * Deliberately do NOT delete a receipt merely because its counter row is
+ * absent: report ingestion claims its receipt before merging the counter, so
+ * an orphan sweep could otherwise reopen the once-per-user/day quota during
+ * that in-flight interval. A max-row counter trim likewise leaves its recent
+ * receipts until the age cutoff — retaining a de-duplication guard is safer
+ * than allowing a second contribution for that day.
+ */
+export declare function pruneFieldUsageReportReceipts(db: DatabaseInterface, options: {
+    maxAgeMs: number;
+    tenantId?: string | null;
+}): Promise<{
+    pruned: number;
+}>;
+export interface FieldPolicySuggestionRetention {
+    /** Drop ACCEPTED suggestions decided longer ago than this. */
+    acceptedMaxAgeMs: number;
+    /** Restrict pruning to one tenant (ambient-context runs). */
+    tenantId?: string | null;
+    /** Clock override for deterministic tests. */
+    now?: Date;
+}
+/**
+ * Prune settled suggestion rows ONLY (#2051 pin): a dismissed suggestion once
+ * its cool-down has fully elapsed (its suppression job is done), and an
+ * accepted suggestion once it is old. Pending suggestions are NEVER pruned.
+ */
+export declare function pruneFieldPolicySuggestions(db: DatabaseInterface, retention: FieldPolicySuggestionRetention): Promise<{
+    pruned: number;
+}>;
+export interface RunFieldUsageMaintenanceOptions extends Partial<FieldUsageMaintenanceConfig> {
+    db: DatabaseInterface;
+}
+/**
+ * The "aggregation" schedule's work. Ingestion pre-aggregates into period
+ * buckets, so the roll-up job's real job is retention: prune counter buckets
+ * and durable receipts at the shared age cutoff, then settle old suggestion
+ * rows. Max-row trimming leaves recent receipts intact to preserve daily
+ * de-duplication while an ingestion merge is in flight.
+ */
+export declare function runFieldUsageMaintenance(options: RunFieldUsageMaintenanceOptions): Promise<FieldUsageMaintenanceSummary>;
+export interface RunFieldPolicySuggestionGenerationOptions extends Partial<FieldUsageSuggestionConfig> {
+    db: DatabaseInterface;
+    /** Clock override for deterministic tests. */
+    now?: Date;
+}
+/**
+ * The threshold job: evaluate windowed counters per
+ * `(tenantId, objectRef, fieldName)` and create PENDING suggestions with
+ * human-readable evidence.
+ *
+ * - `promote`: at least `minDistinctUsers` distinct users set the field to a
+ *   non-default value in the window AND the org-resolved visibility is not
+ *   already `basic`.
+ * - `default`: at least `minSetCount` TOTAL submissions, a single recorded
+ *   value covers `defaultDominanceRatio` of those TOTAL submissions (not of
+ *   the deviations — see `FieldUsageCounter.submissionCount`), and it differs
+ *   from the org-resolved default. Only histogram-eligible fields
+ *   (low-cardinality, non-sensitive, non-gated) can ever qualify, and a group
+ *   containing a legacy bucket with no recorded total is skipped rather than
+ *   ratioed against the wrong denominator.
+ *
+ * Dedup: a candidate is suppressed while the same
+ * `(tenantId, objectRef, fieldName, kind)` has a PENDING suggestion or a
+ * DISMISSED one still inside its cool-down. Accepted history never blocks —
+ * once accepted, the resolved policy itself stops regeneration (visibility is
+ * basic / the default matches). The pre-check is an optimization only: the
+ * single-active guarantee is STRUCTURAL (`FieldPolicySuggestion.activeKey` in
+ * `conflictColumns`), so overlapping runs upsert onto one row instead of
+ * duplicating.
+ *
+ * Sensitive, read-permission-gated, and transient fields are skipped
+ * entirely: their usage rows are count-only observability data and never
+ * produce suggestions.
+ */
+export declare function runFieldPolicySuggestionGeneration(options: RunFieldPolicySuggestionGenerationOptions): Promise<FieldUsageSuggestionRunSummary>;
+/**
+ * The registered schedule target for the #2051 learning loop (see the module
+ * doc for why it is NOT an smrt-agents `Agent` subclass). Rows of its system
+ * table are never written — the class exists so `AgentSchedule.agentType`
+ * resolves through the `ObjectRegistry` and smrt-jobs can construct it and
+ * invoke the two allowlisted methods.
+ */
+export declare class FieldUsageLearningAgent extends SmrtObject {
+    /**
+     * The smrt-jobs opt-in background allowlist (S5 contract): ONLY these two
+     * methods are reachable from a persisted job/schedule row.
+     */
+    static backgroundEligibleMethods: ReadonlyArray<string>;
+    constructor(options?: SmrtObjectOptions);
+    /** Schedule entry point for {@link runFieldUsageMaintenance}. */
+    runUsageMaintenance(args?: Record<string, unknown>): Promise<FieldUsageMaintenanceSummary>;
+    /** Schedule entry point for {@link runFieldPolicySuggestionGeneration}. */
+    runSuggestionGeneration(args?: Record<string, unknown>): Promise<FieldUsageSuggestionRunSummary>;
+}
+export interface FieldUsageEvidenceInput {
+    kind: FieldPolicySuggestionKind;
+    objectRef: string;
+    fieldName: string;
+    windowStart: string;
+    windowEnd: string;
+    distinctUsers: number;
+    /** True when the distinct-user set overflowed (count is a lower bound). */
+    distinctUsersAtLeast: boolean;
+    /** Submissions that DIFFERED from the resolved default. */
+    setCount: number;
+    /**
+     * TOTAL submissions observed in the window (the dominance denominator).
+     * `undefined` only for legacy buckets that never recorded a total, in which
+     * case the summary states the deviation count alone.
+     */
+    submissionCount?: number;
+    /** The threshold the candidate cleared (documented in the evidence). */
+    threshold: number;
+    topValue?: unknown;
+    topValueShare?: number;
+}
+/**
+ * Human-readable evidence for a suggestion: a `summary` sentence a reviewer
+ * can read as-is, plus the structured numbers behind it.
+ *
+ * The sentence always states BOTH numbers when known — deviations and total
+ * submissions — so a reviewer can see the base rate a dominance percentage was
+ * computed against instead of trusting a bare ratio.
+ */
+export declare function buildFieldUsageEvidence(input: FieldUsageEvidenceInput): Record<string, unknown>;
+//# sourceMappingURL=usage-learning.d.ts.map

package/dist/usage-learning.d.ts.map

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