{ "schemaVersion": 1, "sensitiveFieldsExcluded": true, "generatedAt": "1970-01-01T00:00:00.000Z", "packageName": "@happyvertical/smrt-fields", "packageVersion": "0.57.20", "sourceManifestPath": "dist/manifest.json", "agentDocPath": "AGENTS.md", "sourceHashes": { "manifest": "656f4a372b299d318734153b2c654be70c8e9ba8fd86c501826e6c25a30aa945", "packageJson": "1fa65902121c9c70d9152906a7c3a1a2dd0d6f6dd7ccfac8b7ed1c0230727067", "agents": "ae4bf7b69ae3b28a7900b590dd21b53ea0dfc5fd6778f858ceac97dfd8654187" }, "exports": [ ".", "./manifest", "./manifest.json", "./playground", "./svelte" ], "dependencies": { "@happyvertical/smrt-core": "workspace:*", "@happyvertical/smrt-tenancy": "workspace:*", "@happyvertical/smrt-ui": "workspace:*", "@happyvertical/smrt-users": "workspace:*", "@happyvertical/sql": "catalog:", "@happyvertical/smrt-cli": "workspace:*", "@happyvertical/smrt-scanner": "workspace:*", "@happyvertical/smrt-vitest": "workspace:*", "@sveltejs/package": "^2.5.8", "@sveltejs/vite-plugin-svelte": "^7.3.0", "@testing-library/svelte": "^5.4.2", "@types/node": "24.13.6", "svelte": "^5.57.0", "svelte-check": "^4.7.6", "typescript": "6.0.3", "vite": "8.1.6", "vitest": "4.1.10" }, "smrtDependencies": [ "@happyvertical/smrt-cli", "@happyvertical/smrt-core", "@happyvertical/smrt-scanner", "@happyvertical/smrt-tenancy", "@happyvertical/smrt-ui", "@happyvertical/smrt-users", "@happyvertical/smrt-vitest" ], "sdkDependencies": [ "@happyvertical/sql" ], "tags": [ "cross-package", "field-policy", "form-defaults", "multi-tenant", "smrt", "visibility" ], "risks": [ "cross-package-refs:4", "sensitive-fields-excluded" ], "objects": [ { "name": "FieldUsageLearningAgent", "qualifiedName": "@happyvertical/smrt-fields:FieldUsageLearningAgent", "collection": "fieldusagelearningagents", "description": "The registered schedule target for the #2051 learning loop (see the module doc for why it is NOT an smrt-agents Agent subclass).", "tableName": "_smrt_field_usage_learning_agents", "packageName": "@happyvertical/smrt-fields", "extends": "SmrtObject", "fields": [], "relationships": [], "methods": [ "runSuggestionGeneration", "runUsageMaintenance" ], "methodSignatures": [ { "name": "runSuggestionGeneration", "async": true, "params": [ "args?: Record" ], "returns": "Promise" }, { "name": "runUsageMaintenance", "async": true, "params": [ "args?: Record" ], "returns": "Promise" } ], "surfaces": [], "withheldSurfaces": [ { "kind": "api", "operation": "runSuggestionGeneration", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldUsageLearningAgent" }, { "kind": "api", "operation": "runUsageMaintenance", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldUsageLearningAgent" } ], "relationshipFeatures": [ "uuidColumns" ], "tags": [], "risks": [] }, { "name": "FieldPolicyCollection", "qualifiedName": "@happyvertical/smrt-fields:FieldPolicyCollection", "collection": "fieldpolicies", "tableName": "_smrt_field_policies", "packageName": "@happyvertical/smrt-fields", "extends": "SmrtCollection", "fields": [], "relationships": [], "methods": [ "getAppRows", "getEditorState", "getTenantRows", "getUserRows", "policyAudit", "resolveBatch" ], "methodSignatures": [ { "name": "getAppRows", "async": true, "params": [ "objectRef: string" ], "returns": "Promise>" }, { "name": "getEditorState", "async": true, "params": [ "options?: object" ], "returns": "Promise" }, { "name": "getTenantRows", "async": true, "params": [ "objectRef: string", "tenantIds: string[]" ], "returns": "Promise>>" }, { "name": "getUserRows", "async": true, "params": [ "objectRef: string", "userId: string" ], "returns": "Promise>" }, { "name": "policyAudit", "async": true, "params": [ "options?: object" ], "returns": "Promise" }, { "name": "resolveBatch", "async": true, "params": [ "options?: object" ], "returns": "Promise" } ], "conflictColumns": [ "object_ref", "field_name", "scope_type", "scope_key" ], "surfaces": [ { "kind": "api", "name": "fieldpolicies.policyAudit", "operation": "policyAudit", "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection", "path": "/fieldpolicies/policy-audit", "method": "POST" }, { "kind": "api", "name": "fieldpolicies.resolveBatch", "operation": "resolveBatch", "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection", "path": "/fieldpolicies/resolve", "method": "POST" }, { "kind": "api", "name": "fieldpolicies.getEditorState", "operation": "getEditorState", "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection", "path": "/fieldpolicies/editor-state", "method": "POST" } ], "withheldSurfaces": [ { "kind": "api", "operation": "getAppRows", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection" }, { "kind": "api", "operation": "getTenantRows", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection" }, { "kind": "api", "operation": "getUserRows", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection" } ], "relationshipFeatures": [ "uuidColumns" ], "tags": [], "risks": [] }, { "name": "FieldPolicySuggestionCollection", "qualifiedName": "@happyvertical/smrt-fields:FieldPolicySuggestionCollection", "collection": "fieldpolicysuggestions", "description": "Collection surface for FieldPolicySuggestion plus the three manage-gated actions the gear badge / control-panel queue consume (#2051; UI integration is #2050-follow-up territory — this is the minimal…", "tableName": "_smrt_field_policy_suggestions", "packageName": "@happyvertical/smrt-fields", "extends": "SmrtCollection", "fields": [], "relationships": [], "methods": [ "acceptSuggestion", "dismissSuggestion", "pendingSuggestions" ], "methodSignatures": [ { "name": "acceptSuggestion", "async": true, "params": [ "options?: object" ], "returns": "Promise" }, { "name": "dismissSuggestion", "async": true, "params": [ "options?: object" ], "returns": "Promise" }, { "name": "pendingSuggestions", "async": true, "params": [ "options?: object" ], "returns": "Promise" } ], "conflictColumns": [ "object_ref", "field_name", "tenant_id", "kind", "active_key" ], "surfaces": [ { "kind": "api", "name": "fieldpolicysuggestions.pendingSuggestions", "operation": "pendingSuggestions", "objectName": "@happyvertical/smrt-fields:FieldPolicySuggestionCollection", "path": "/fieldpolicysuggestions/pending", "method": "POST" }, { "kind": "api", "name": "fieldpolicysuggestions.acceptSuggestion", "operation": "acceptSuggestion", "objectName": "@happyvertical/smrt-fields:FieldPolicySuggestionCollection", "path": "/fieldpolicysuggestions/accept", "method": "POST" }, { "kind": "api", "name": "fieldpolicysuggestions.dismissSuggestion", "operation": "dismissSuggestion", "objectName": "@happyvertical/smrt-fields:FieldPolicySuggestionCollection", "path": "/fieldpolicysuggestions/dismiss", "method": "POST" } ], "relationshipFeatures": [ "uuidColumns" ], "tags": [], "risks": [] }, { "name": "FieldUsageCounterCollection", "qualifiedName": "@happyvertical/smrt-fields:FieldUsageCounterCollection", "collection": "fieldusagecounters", "description": "Collection surface for FieldUsageCounter plus the batched usage ingestion action (#2051).", "tableName": "_smrt_field_usage_counters", "packageName": "@happyvertical/smrt-fields", "extends": "SmrtCollection", "fields": [], "relationships": [], "methods": [ "listWindow", "reportUsage" ], "methodSignatures": [ { "name": "listWindow", "async": true, "params": [ "options: object" ], "returns": "Promise" }, { "name": "reportUsage", "async": true, "params": [ "options?: object" ], "returns": "Promise" } ], "conflictColumns": [ "object_ref", "field_name", "tenant_id", "period" ], "surfaces": [ { "kind": "api", "name": "fieldusagecounters.reportUsage", "operation": "reportUsage", "objectName": "@happyvertical/smrt-fields:FieldUsageCounterCollection", "path": "/fieldusagecounters/report", "method": "POST" } ], "withheldSurfaces": [ { "kind": "api", "operation": "listWindow", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldUsageCounterCollection" } ], "relationshipFeatures": [ "uuidColumns" ], "tags": [], "risks": [] }, { "name": "FieldUsageReportReceiptCollection", "qualifiedName": "@happyvertical/smrt-fields:FieldUsageReportReceiptCollection", "collection": "fieldusagereportreceipts", "description": "Internal only — this table has no generated surface.", "tableName": "_smrt_field_usage_report_receipts", "packageName": "@happyvertical/smrt-fields", "extends": "SmrtCollection", "fields": [], "relationships": [], "methods": [ "claim" ], "methodSignatures": [ { "name": "claim", "async": true, "params": [ "options: object" ], "returns": "Promise" } ], "conflictColumns": [ "tenant_id", "user_id", "object_ref", "field_name", "period" ], "surfaces": [], "withheldSurfaces": [ { "kind": "api", "operation": "claim", "code": "api-disabled", "reason": "api is disabled", "objectName": "@happyvertical/smrt-fields:FieldUsageReportReceiptCollection" } ], "relationshipFeatures": [ "uuidColumns" ], "tags": [], "risks": [] }, { "name": "FieldPolicy", "qualifiedName": "@happyvertical/smrt-fields:FieldPolicy", "displayLabelField": "label", "collection": "fieldpolicies", "tableName": "_smrt_field_policies", "packageName": "@happyvertical/smrt-fields", "extends": "SmrtObject", "fields": [ { "name": "objectRef", "type": "text", "required": true, "columnType": "TEXT", "default": "" }, { "name": "fieldName", "type": "text", "required": true, "columnType": "TEXT", "default": "" }, { "name": "scopeType", "type": "text", "required": true, "columnType": "TEXT", "default": "app" }, { "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", "description": "The value a new record starts with for this field." }, { "name": "visibility", "type": "text", "required": false, "columnType": "TEXT", "description": "Whether the field is always shown, tucked under advanced, or hidden." }, { "name": "help", "type": "text", "required": false, "columnType": "TEXT", "description": "The hint shown beside the field on the form." }, { "name": "label", "type": "text", "required": false, "columnType": "TEXT", "description": "The name people see for the field on forms." }, { "name": "displayOrder", "type": "integer", "required": false, "columnType": "INTEGER", "description": "Where the field appears on the form; lower numbers come first." }, { "name": "locked", "type": "boolean", "required": false, "columnType": "BOOLEAN", "description": "Stops individual people from changing this field for themselves." }, { "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" ], "methodSignatures": [ { "name": "delete", "async": true, "returns": "Promise" }, { "name": "getDefaultValue", "returns": "unknown" }, { "name": "save", "async": true, "returns": "Promise" }, { "name": "setDefaultValue", "params": [ "value: unknown" ], "returns": "void" } ], "conflictColumns": [ "object_ref", "field_name", "scope_type", "scope_key" ], "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" } ], "withheldSurfaces": [ { "kind": "api", "operation": "getDefaultValue", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldPolicy" }, { "kind": "api", "operation": "save", "code": "lifecycle-method", "reason": "`save` is a framework lifecycle method, not a distinct operation", "objectName": "@happyvertical/smrt-fields:FieldPolicy" }, { "kind": "api", "operation": "setDefaultValue", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldPolicy" } ], "relationshipFeatures": [ "crossPackageRef", "uuidColumns" ], "tags": [], "risks": [] }, { "name": "FieldPolicySuggestion", "qualifiedName": "@happyvertical/smrt-fields:FieldPolicySuggestion", "collection": "fieldpolicysuggestions", "tableName": "_smrt_field_policy_suggestions", "packageName": "@happyvertical/smrt-fields", "extends": "SmrtObject", "fields": [ { "name": "objectRef", "type": "text", "required": true, "columnType": "TEXT", "default": "" }, { "name": "fieldName", "type": "text", "required": true, "columnType": "TEXT", "default": "" }, { "name": "tenantId", "type": "text", "required": true, "columnType": "UUID" }, { "name": "kind", "type": "text", "required": true, "columnType": "TEXT", "default": "promote" }, { "name": "proposedValue", "type": "text", "required": false, "columnType": "TEXT" }, { "name": "evidence", "type": "text", "required": false, "columnType": "TEXT" }, { "name": "status", "type": "text", "required": true, "columnType": "TEXT", "default": "pending" }, { "name": "activeKey", "type": "text", "required": true, "columnType": "TEXT" }, { "name": "cooldownUntil", "type": "datetime", "required": false, "columnType": "TIMESTAMP" }, { "name": "decidedBy", "type": "crossPackageRef", "required": false, "related": "@happyvertical/smrt-users:User", "columnType": "UUID" }, { "name": "decidedAt", "type": "datetime", "required": false, "columnType": "TIMESTAMP" } ], "relationships": [ { "name": "decidedBy", "type": "crossPackageRef", "required": false, "related": "@happyvertical/smrt-users:User", "columnType": "UUID" } ], "methods": [ "delete", "getEvidence", "getProposedValue", "save", "setEvidence", "toSuggestionData" ], "methodSignatures": [ { "name": "delete", "async": true, "returns": "Promise" }, { "name": "getEvidence", "returns": "Record" }, { "name": "getProposedValue", "returns": "unknown" }, { "name": "save", "async": true, "returns": "Promise" }, { "name": "setEvidence", "params": [ "evidence: Record" ], "returns": "void" }, { "name": "toSuggestionData", "returns": "FieldPolicySuggestionData" } ], "conflictColumns": [ "object_ref", "field_name", "tenant_id", "kind", "active_key" ], "surfaces": [], "withheldSurfaces": [ { "kind": "api", "operation": "getEvidence", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldPolicySuggestion" }, { "kind": "api", "operation": "getProposedValue", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldPolicySuggestion" }, { "kind": "api", "operation": "save", "code": "lifecycle-method", "reason": "`save` is a framework lifecycle method, not a distinct operation", "objectName": "@happyvertical/smrt-fields:FieldPolicySuggestion" }, { "kind": "api", "operation": "setEvidence", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldPolicySuggestion" }, { "kind": "api", "operation": "toSuggestionData", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldPolicySuggestion" } ], "relationshipFeatures": [ "crossPackageRef", "uuidColumns" ], "tags": [], "risks": [] }, { "name": "FieldUsageCounter", "qualifiedName": "@happyvertical/smrt-fields:FieldUsageCounter", "collection": "fieldusagecounters", "tableName": "_smrt_field_usage_counters", "packageName": "@happyvertical/smrt-fields", "extends": "SmrtObject", "fields": [ { "name": "objectRef", "type": "text", "required": true, "columnType": "TEXT", "default": "" }, { "name": "fieldName", "type": "text", "required": true, "columnType": "TEXT", "default": "" }, { "name": "tenantId", "type": "text", "required": true, "columnType": "UUID" }, { "name": "period", "type": "text", "required": true, "columnType": "TEXT", "default": "" }, { "name": "submissionCount", "type": "integer", "required": false, "columnType": "INTEGER" }, { "name": "setCount", "type": "integer", "required": false, "columnType": "INTEGER" }, { "name": "distinctUserCount", "type": "integer", "required": false, "columnType": "INTEGER" }, { "name": "distinctUserIds", "type": "text", "required": false, "columnType": "TEXT" }, { "name": "distinctUsersOverflowed", "type": "boolean", "required": false, "columnType": "BOOLEAN" }, { "name": "valueHistogram", "type": "text", "required": false, "columnType": "TEXT" }, { "name": "valueHistogramOverflowed", "type": "boolean", "required": false, "columnType": "BOOLEAN" } ], "relationships": [], "methods": [ "addDistinctUser", "delete", "getDistinctUserIds", "getValueHistogram", "isLegacyBucket", "recordHistogramSample", "save" ], "methodSignatures": [ { "name": "addDistinctUser", "params": [ "userId: string" ], "returns": "void" }, { "name": "delete", "async": true, "returns": "Promise" }, { "name": "getDistinctUserIds", "returns": "string[]" }, { "name": "getValueHistogram", "returns": "Record" }, { "name": "isLegacyBucket", "returns": "boolean" }, { "name": "recordHistogramSample", "params": [ "key: string" ], "returns": "void" }, { "name": "save", "async": true, "returns": "Promise" } ], "conflictColumns": [ "object_ref", "field_name", "tenant_id", "period" ], "surfaces": [], "withheldSurfaces": [ { "kind": "api", "operation": "addDistinctUser", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldUsageCounter" }, { "kind": "api", "operation": "getDistinctUserIds", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldUsageCounter" }, { "kind": "api", "operation": "getValueHistogram", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldUsageCounter" }, { "kind": "api", "operation": "isLegacyBucket", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldUsageCounter" }, { "kind": "api", "operation": "recordHistogramSample", "code": "not-included", "reason": "not listed in api.include", "objectName": "@happyvertical/smrt-fields:FieldUsageCounter" }, { "kind": "api", "operation": "save", "code": "lifecycle-method", "reason": "`save` is a framework lifecycle method, not a distinct operation", "objectName": "@happyvertical/smrt-fields:FieldUsageCounter" } ], "relationshipFeatures": [ "uuidColumns" ], "tags": [], "risks": [] }, { "name": "FieldUsageReportReceipt", "qualifiedName": "@happyvertical/smrt-fields:FieldUsageReportReceipt", "collection": "fieldusagereportreceipts", "description": "Durable daily receipt for one member's contribution to one field.", "tableName": "_smrt_field_usage_report_receipts", "packageName": "@happyvertical/smrt-fields", "extends": "SmrtObject", "fields": [ { "name": "tenantId", "type": "text", "required": true, "columnType": "UUID" }, { "name": "userId", "type": "crossPackageRef", "required": false, "related": "@happyvertical/smrt-users:User", "columnType": "UUID" }, { "name": "objectRef", "type": "text", "required": true, "columnType": "TEXT", "default": "" }, { "name": "fieldName", "type": "text", "required": true, "columnType": "TEXT", "default": "" }, { "name": "period", "type": "text", "required": true, "columnType": "TEXT", "default": "" } ], "relationships": [ { "name": "userId", "type": "crossPackageRef", "required": false, "related": "@happyvertical/smrt-users:User", "columnType": "UUID" } ], "methods": [], "conflictColumns": [ "tenant_id", "user_id", "object_ref", "field_name", "period" ], "surfaces": [], "relationshipFeatures": [ "crossPackageRef", "uuidColumns" ], "tags": [], "risks": [] } ], "surfaces": [ { "kind": "api", "name": "fieldpolicies.policyAudit", "operation": "policyAudit", "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection", "path": "/fieldpolicies/policy-audit", "method": "POST" }, { "kind": "api", "name": "fieldpolicies.resolveBatch", "operation": "resolveBatch", "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection", "path": "/fieldpolicies/resolve", "method": "POST" }, { "kind": "api", "name": "fieldpolicies.getEditorState", "operation": "getEditorState", "objectName": "@happyvertical/smrt-fields:FieldPolicyCollection", "path": "/fieldpolicies/editor-state", "method": "POST" }, { "kind": "api", "name": "fieldpolicysuggestions.pendingSuggestions", "operation": "pendingSuggestions", "objectName": "@happyvertical/smrt-fields:FieldPolicySuggestionCollection", "path": "/fieldpolicysuggestions/pending", "method": "POST" }, { "kind": "api", "name": "fieldpolicysuggestions.acceptSuggestion", "operation": "acceptSuggestion", "objectName": "@happyvertical/smrt-fields:FieldPolicySuggestionCollection", "path": "/fieldpolicysuggestions/accept", "method": "POST" }, { "kind": "api", "name": "fieldpolicysuggestions.dismissSuggestion", "operation": "dismissSuggestion", "objectName": "@happyvertical/smrt-fields:FieldPolicySuggestionCollection", "path": "/fieldpolicysuggestions/dismiss", "method": "POST" }, { "kind": "api", "name": "fieldusagecounters.reportUsage", "operation": "reportUsage", "objectName": "@happyvertical/smrt-fields:FieldUsageCounterCollection", "path": "/fieldusagecounters/report", "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": 4, "junctionCollections": 0, "hierarchicalObjects": 0, "polymorphicAssociations": 0, "uuidColumns": 25 }, "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 //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 uses `@happyvertical/smrt-users`' `TenantCollection`; an injected loader\n may return no provider (or no chain for a tenant), which falls back to a\n flat single-tenant chain. `smrt-users` itself is a required Fields runtime\n dependency for policy authorization, not an optional hierarchy dependency.\n 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 persisted row is excluded\n from projected lower-layer resolution, so clearing the row's only default\n while demoting a required field is rejected before mutation; that projected\n lookup bypasses the shared cache. The resolver-side safety net remains\n authoritative when a different row is later deleted.\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. `fields.policy.manage`\n authorizes app/tenant policy mutations; `fields.policy.personalize` authorizes\n only the caller's user tier (default-seeded for built-in roles). With NO ambient\n identity at all (tenancy ALS never entered), policy writes/deletes fail closed;\n trusted system and super-admin contexts retain their explicit bypasses.\n Context-LESS *reads* stay allowed because `resolveFieldPolicy` is a trusted\n server-side API. `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## Svelte generated forms (#2049)\n\n- `ObjectForm` accepts direct generated `fields` plus a resolved `policy` for\n SSR and explicit hosts, or accepts only `objectRef` beneath an\n `ObjectFormSourceProvider`. `ObjectFormSourceRegistry` is per app and maps\n canonical refs to generated web collection definitions before calling the\n generated `resolveBatch` custom action. It uses structural types only: this\n package must never import `smrt-web`.\n- Generated custom-action clients resolve `Promise`; validate their\n `policies[objectRef]` response at the registry boundary and fail closed on a\n missing/mismatched definition or policy. The component renders an accessible\n loading state and alert rather than a partial form.\n- Browser manifest types are `text`, `integer`, `decimal`, `boolean`,\n `datetime`, `json`, `foreignKey`, and `crossPackageRef`; there is no `select`\n wire type. Apps use the per-app `FieldInputRegistry.registerField` seam for\n select-like widgets. Reference fields intentionally default to identifier\n inputs unless an app supplies a chooser.\n- `policyToVisibleColumnIds(policy, columns)` feeds smrt-ui `DataTable`'s\n `visibleColumnIds`; it filters policy-hidden mapped fields and restricted\n (`sensitive`/`secret` or `readable: false`) columns, preserves unrestricted\n unmapped computed/action columns, and cannot reveal a static `column.hidden`\n column. Pass `authorizedColumnIds` only when the host explicitly authorizes a\n restricted column; `readable: true` alone does not override sensitivity.\n- `policyToDataSurfaceDescriptor(policy, descriptor)` is the corresponding\n mounted DataSurface adapter. It carries effective labels, help text, order,\n visibility, readable/capability state, and operator/query allowlists into\n discovery metadata while retaining unrestricted computed, row-key, selection,\n and action columns. Static or resolved-policy-hidden structural columns are\n omitted from discovery (the row key remains only as a non-readable identity\n column), and actions that explicitly depend on hidden columns are removed.\n Sensitive/secret and `readable: false` columns also fail closed when omitted\n from the resolved policy; a host must pass `authorizedColumnIds` explicitly\n to expose a restricted descriptor column, and authorization sets the\n effective `readable` metadata to `true` so capabilities and query allowlists\n cannot contradict it.\n- **Two-tier context contract.** `PolicyField` alone reads the context with\n `tryGetFieldPolicyContext()`, because outside a Provider it still has the\n caller's children to render verbatim (incremental adoption). The\n provider-only compositions — `ModeSwitch`, `AdvancedFields`, `FormHelp` —\n read it with the throwing `getFieldPolicyContext()`: their whole output is\n derived from the resolved policy, so degrading would render an empty or\n absent control instead of surfacing the missing Provider. Do not convert one\n of them to the non-throwing accessor in isolation (#2272).\n- **One provider per form.** `FieldPolicyProvider` renders only\n `{@render children?.()}`, so a host wanting `FormHelp` in a page header\n extends the SAME provider over the header rather than hoisting the component\n out. It must not add a second: each provider constructs its own\n `FieldPolicyModeStore` and `setContext` shadows for the subtree, so a\n `FormHelp` above a nested provider stops tracking the `ModeSwitch` inside it.\n `ObjectForm` builds its own provider, so never wrap it in another; its\n `actions` snippet renders INSIDE that provider (context resolves at the render\n site), which is the only way to reach `FormHelp` through it — below the\n fields, since there is no header seam (#2289).\n\n## Defaults control panel (#2050)\n\n- `buildFieldPolicySettingsCatalog()` is the server-side, URL/GET-driven\n catalog builder. It structurally targets `SettingsCatalog`, but this package\n must not import `smrt-svelte`; hosts inject `SettingsCatalog` into\n `FieldPolicyControlPanel` and retain their own route and transport adapters.\n- `policyAudit` is the only routed organization roll-up. It requires\n `fields.policy.manage`, returns only the caller tenant's editable rows and\n read-only app summaries, and represents other users strictly as per-field\n counts. It resolves only requested page refs; never pre-resolve the catalog.\n- Display code/app/org values by replaying the explained resolver layers, not\n by independently calculating precedence. Reset and drift prune are ordinary\n model deletes, so existing scope/permission validation remains authoritative.\n The panel asks for an explicit confirmation before either destructive action;\n SSR hosts can inject that confirmation decision instead of relying on\n `window.confirm`.\n- `fieldPolicyControlPanelNavItem()` is a structural AdminShell tenant-nav\n seam. It never imports `smrt-svelte` or `smrt-web`; the host supplies the\n returned entry and must enforce its real route permission server-side.\n\n## Recipe: `fields.form-customization` (#3719)\n\n`src/recipes.ts` declares `FormCustomizationRecipe`\n(help: `src/form-customization.recipe.md`), emitted in `manifest.json` and\n`smrt-knowledge.json` `recipes`. Contract: [core recipes](../core/agents/recipes.md).\n\n- Models: the four policy/learning tables. No `nav`, deliberately: the tables\n have no generated read surface, so the one management UI is the declared\n `settings-panel` surface `@happyvertical/smrt-fields/svelte#FieldPolicyControlPanel`.\n That component is not zero-prop: the host still injects `SettingsCatalog`,\n the adapter, and loads `buildFieldPolicySettingsCatalog()` data server-side.\n- `runtime = 'server'` is the truthful value while #3618 is open: the root\n entry (resolver, `usage-schedules`) statically imports core's node-only\n `import-workspace-module`. The `/svelte` components are browser-safe because\n they render an already-resolved policy. Flip to `'both'` only when #3618 lands\n and a browser build of the root entry is proven.\n- No `demoSeed` (no fixture exists) and no `playground` surface: the playground\n export is a registry object, not a component. Help field references must\n point at `FieldPolicy` fields that carry `@field({ description })`.\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", "recipes": [ { "id": "fields.form-customization", "className": "FormCustomizationRecipe", "label": "Form customization", "summary": "Choose what your forms ask for: defaults, labels, hints and which fields are shown.", "synonyms": [ "form defaults", "field defaults", "customize forms", "hide fields", "field visibility", "field labels" ], "models": [ "@happyvertical/smrt-fields:FieldPolicy", "@happyvertical/smrt-fields:FieldPolicySuggestion", "@happyvertical/smrt-fields:FieldUsageCounter", "@happyvertical/smrt-fields:FieldUsageReportReceipt" ], "nav": [], "requires": [], "help": { "markdown": "## Overview\n\nForm customization lets you decide what the forms in your app ask for. For any\nfield you can change the name people see, the hint beside it, the value a new\nrecord starts with, where it sits on the form, and whether it is always shown,\ntucked under \"advanced\", or hidden. You can also lock a field so that people\ncannot change it for themselves.\n\nChanges layer. The app starts with sensible settings, your organization can\nchange them for everyone in it, and each person can then adjust their own view\nunless you locked the field. Resetting a field removes your change and brings\nback whatever sits underneath.\n\n## Tasks\n\n### Change what a field is called\n\n1. Open **Form defaults** from your settings and find the form you want.\n2. Choose the field and type a new **{field:label}**.\n3. Save. The new name appears on the form.\n\n### Give people a hint\n\n1. Choose the field in **Form defaults**.\n2. Write the **{field:help}**, one short sentence that says what to enter.\n3. Save. The hint now shows beside the field.\n\n### Pre-fill a value\n\n1. Choose the field in **Form defaults**.\n2. Enter the **{field:defaultValue}** a new record should start with.\n3. Save. People can still type over it unless the field is locked.\n\n### Tidy a long form\n\n1. Choose a field that most people never need.\n2. Set its **{field:visibility}** to advanced to tuck it away, or to hidden to\n remove it.\n3. Save. A field that must always be filled in stays shown unless it also has a\n default value.\n\n### Put fields in a better order\n\n1. Choose a field.\n2. Set its **{field:displayOrder}**. Lower numbers come first.\n3. Save, then check the form.\n\n### Keep everyone on the same setting\n\n1. Choose the field in **Form defaults**.\n2. Turn on **{field:locked}**.\n3. Save. People can no longer change that field for themselves.\n\n### Undo a change\n\nChoose **Reset** on a field to remove your change. Settings from the layers\nbelow, such as the app's own, come back. Resetting asks you to confirm first.\n\n### Review suggestions\n\nWhen enough people fill in the same value, or keep opening the same advanced\nfield, the app suggests a change. Open the suggestions list in **Form defaults**\nand accept or dismiss each one. Nothing changes until you accept.\n", "fieldRefs": [ "defaultValue", "displayOrder", "help", "label", "locked", "visibility" ] }, "surfaces": [ { "kind": "settings-panel", "export": "@happyvertical/smrt-fields/svelte#FieldPolicyControlPanel", "label": "Form defaults" } ], "runtime": "server", "demo": { "mode": "server", "reasons": [ "The recipe declares runtime \"server\".", "Needs a server because its package does not build for a browser: imports core utils/import-workspace-module (node:url, node:fs, node:path); and its package depends on @happyvertical/smrt-profiles, @happyvertical/smrt-tenancy, @happyvertical/smrt-users, which do not build for a browser (#3617, #3618, #3624, #3626)." ] } } ], "browser": { "status": "server-only", "issues": [ "#3617", "#3618", "#3624", "#3626" ], "reason": "imports core utils/import-workspace-module (node:url, node:fs, node:path)", "via": [ "@happyvertical/smrt-profiles", "@happyvertical/smrt-tenancy", "@happyvertical/smrt-users" ] } }