@sparkerp/plugin-sdk 0.1.0

package/bundle/schemas/block-instance.schema.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://erp-platform.dev/schemas/block-instance-config.schema.json",
+  "title": "Block instance-config contract v1",
+  "description": "The fragment a Phase 6 form definition or Phase 7 page definition embeds per placed block (W1-04): the block type + the pinned version it was authored against, property values (each a declared value source validated against the type's property surface), and event-to-action-chain wiring. Structured diagnostics on violation: unknown-block-type, unknown-property, property-type-mismatch, invalid-value-source, invalid-binding, version-unsatisfiable.",
+  "type": "object",
+  "$defs": {
+    "boundKey": {
+      "description": "A Phase 4 bound key (state-binding.schema.json shape): scopeKey placeholders ($self/$page/$form/$session/$user) resolve at mount.",
+      "type": "object",
+      "properties": {
+        "scope": { "enum": ["application", "tenant", "user", "session", "page", "form", "block"] },
+        "scopeKey": { "type": "string", "maxLength": 128 },
+        "key": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*$"
+        }
+      },
+      "required": ["scope", "key"],
+      "additionalProperties": false
+    },
+    "propertyValue": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "source": { "const": "static" },
+            "value": {}
+          },
+          "required": ["source", "value"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "source": { "const": "expression" },
+            "expression": { "type": "string", "minLength": 1, "maxLength": 2000 }
+          },
+          "required": ["source", "expression"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "source": { "const": "binding" },
+            "binding": { "$ref": "#/$defs/boundKey" }
+          },
+          "required": ["source", "binding"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "eventWiring": {
+      "description": "An event handler: a Phase 2 action chain executed through executeChain when the block emits the event.",
+      "type": "object",
+      "properties": {
+        "source": { "const": "action-chain" },
+        "actions": {
+          "type": "array",
+          "items": { "type": "object" },
+          "minItems": 1
+        }
+      },
+      "required": ["source", "actions"],
+      "additionalProperties": false
+    }
+  },
+  "properties": {
+    "contractVersion": { "const": 1 },
+    "instanceId": {
+      "description": "The block's instance identity - also its Phase 4 block-scope scopeKey.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "blockType": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+    },
+    "blockVersion": {
+      "description": "The version this instance was authored against (the pin, W1-05).",
+      "type": "string",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$"
+    },
+    "properties": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "additionalProperties": { "$ref": "#/$defs/propertyValue" }
+    },
+    "events": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "additionalProperties": { "$ref": "#/$defs/eventWiring" }
+    },
+    "outputs": {
+      "description": "Optional output redirection: where each output port writes. Defaults to the block's own block-scope entry named after the port.",
+      "type": "object",
+      "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "additionalProperties": { "$ref": "#/$defs/boundKey" }
+    },
+    "children": {
+      "description": "Container-class blocks only: slot name to nested instance configs.",
+      "type": "object",
+      "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "additionalProperties": {
+        "type": "array",
+        "items": { "$ref": "#" }
+      }
+    },
+    "a11yLabelKey": {
+      "description": "W10 (additive, 2026-07-16): the authored label's translation key for this placed instance (a Phase 6 field's labelKey), resolved through the runtime i18n resolver into the node's accessible name; takes precedence over the block definition's labelFrom default.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "name": {
+      "description": "2026-07-18: an author-facing display name (e.g. \"Header block\"), never read at render/runtime — a Studio authoring aid only.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "className": {
+      "description": "2026-07-17: a framework-specific class name applied to the rendered root, the universal escape hatch alongside style.",
+      "type": "string",
+      "maxLength": 512
+    },
+    "style": {
+      "description": "2026-07-17: raw inline style properties applied to the rendered root, the universal escape hatch alongside className.",
+      "type": "object",
+      "additionalProperties": { "type": ["string", "number"] }
+    }
+  },
+  "required": ["contractVersion", "instanceId", "blockType", "blockVersion", "properties"],
+  "additionalProperties": false
+}

package/bundle/schemas/composite-pack-manifest.schema.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://erp-platform.dev/schemas/plugin-manifest.schema.json",
+  "title": "Plugin/composite-pack manifest contract v1",
+  "description": "The machine-readable contract a plugin or composite pack (Country/Industry Pack, solution template) ships (W1-02...W1-08, ADR 0013): twelve extension points, a dependency graph, a distribution mode (locked vs editable), and the upgrade/data-erasure hook declarations. Cross-references (does a declared function name actually have a supplied implementation, does a dependency resolve) are checked by validatePluginManifest/resolveInstallOrder/PluginRegistry.install against the live registries and the supplied PluginImplementations, not by this schema alone - the same division of labor every earlier phase's schema draws.",
+  "type": "object",
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z_][A-Za-z0-9_.-]*$"
+    },
+    "semver": {
+      "type": "string",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$"
+    },
+    "versionRange": {
+      "description": "Exact \"1.2.3\", caret \"^1.2.0\", tilde \"~1.2.0\", or \"*\" - a deliberately small, closed subset (versionRange.ts), not the full npm range grammar.",
+      "type": "string",
+      "minLength": 1
+    },
+    "dependency": {
+      "type": "object",
+      "properties": {
+        "id": { "$ref": "#/$defs/identifier" },
+        "versionRange": { "$ref": "#/$defs/versionRange" }
+      },
+      "required": ["id", "versionRange"],
+      "additionalProperties": false
+    },
+    "argKind": {
+      "enum": ["Numeric", "MoneyOrNumeric", "String", "Boolean", "Array", "Collection", "DateLike", "Any"]
+    },
+    "actionTypeContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "$ref": "#/$defs/identifier" },
+        "description": { "type": "string", "minLength": 1 }
+      },
+      "required": ["type", "description"],
+      "additionalProperties": false
+    },
+    "functionContribution": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "minArity": { "type": "integer", "minimum": 0 },
+        "maxArity": { "type": "number", "minimum": 0 },
+        "argKinds": { "type": "array", "items": { "$ref": "#/$defs/argKind" } },
+        "returnType": { "type": "string" }
+      },
+      "required": ["name", "description", "minArity", "maxArity", "argKinds", "returnType"],
+      "additionalProperties": false
+    },
+    "idDescription": {
+      "type": "object",
+      "properties": {
+        "id": { "$ref": "#/$defs/identifier" },
+        "description": { "type": "string", "minLength": 1 }
+      },
+      "required": ["id", "description"],
+      "additionalProperties": false
+    },
+    "networkScopedContribution": {
+      "type": "object",
+      "properties": {
+        "id": { "$ref": "#/$defs/identifier" },
+        "description": { "type": "string", "minLength": 1 },
+        "networkScopes": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      },
+      "required": ["id", "description", "networkScopes"],
+      "additionalProperties": false
+    },
+    "scheduledJobContribution": {
+      "type": "object",
+      "properties": {
+        "id": { "$ref": "#/$defs/identifier" },
+        "description": { "type": "string", "minLength": 1 },
+        "schedule": { "type": "string", "minLength": 1 },
+        "networkScopes": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      },
+      "required": ["id", "description", "schedule", "networkScopes"],
+      "additionalProperties": false
+    },
+    "themeContribution": {
+      "type": "object",
+      "properties": {
+        "id": { "$ref": "#/$defs/identifier" },
+        "tokenSetId": { "type": "string", "minLength": 1 }
+      },
+      "required": ["id", "tokenSetId"],
+      "additionalProperties": false
+    },
+    "menuItemContribution": {
+      "type": "object",
+      "properties": {
+        "area": { "type": "string", "minLength": 1 },
+        "group": { "type": "string", "minLength": 1 },
+        "labelKey": { "type": "string", "minLength": 1 },
+        "route": { "type": "string", "minLength": 1 }
+      },
+      "required": ["area", "group", "labelKey", "route"],
+      "additionalProperties": false
+    },
+    "localeBundleContribution": {
+      "type": "object",
+      "properties": {
+        "locale": { "type": "string", "minLength": 1 },
+        "namespace": { "type": "string", "minLength": 1 }
+      },
+      "required": ["locale", "namespace"],
+      "additionalProperties": false
+    },
+    "contributions": {
+      "type": "object",
+      "properties": {
+        "actions": { "type": "array", "items": { "$ref": "#/$defs/actionTypeContribution" } },
+        "blocks": { "type": "array", "items": { "type": "object", "description": "A frozen @erp/block-engine BlockDefinition - validated against the live BlockRegistry at install time." } },
+        "validators": { "type": "array", "items": { "$ref": "#/$defs/idDescription" } },
+        "functions": { "type": "array", "items": { "$ref": "#/$defs/functionContribution" } },
+        "dataSources": { "type": "array", "items": { "$ref": "#/$defs/networkScopedContribution" } },
+        "integrations": { "type": "array", "items": { "$ref": "#/$defs/networkScopedContribution" } },
+        "themes": { "type": "array", "items": { "$ref": "#/$defs/themeContribution" } },
+        "workflowTasks": { "type": "array", "items": { "$ref": "#/$defs/idDescription" } },
+        "menuItems": { "type": "array", "items": { "$ref": "#/$defs/menuItemContribution" } },
+        "scheduledJobs": { "type": "array", "items": { "$ref": "#/$defs/scheduledJobContribution" } },
+        "documentTemplates": { "type": "array", "items": { "$ref": "#/$defs/idDescription" } },
+        "localeBundles": { "type": "array", "items": { "$ref": "#/$defs/localeBundleContribution" } }
+      },
+      "additionalProperties": false
+    }
+  },
+  "properties": {
+    "contractVersion": { "const": 1 },
+    "id": { "$ref": "#/$defs/identifier" },
+    "version": { "$ref": "#/$defs/semver" },
+    "publisher": { "type": "string", "minLength": 1 },
+    "displayNameKey": { "type": "string", "minLength": 1 },
+    "descriptionKey": { "type": "string", "minLength": 1 },
+    "distribution": { "enum": ["locked", "editable"] },
+    "dependencies": { "type": "array", "items": { "$ref": "#/$defs/dependency" } },
+    "contributions": { "$ref": "#/$defs/contributions" },
+    "hasUpgradeMigration": { "type": "boolean" },
+    "hasDataErasureHook": { "type": "boolean" },
+    "frontendBundle": {
+      "description": "2026-09-03, closes the dynamic-frontend-plugin-loading gap (ai/domains/ai-native-developer-platform-gap-analysis.md): a compiled @erp/* frontend bundle a runtime loader fetches from the real, generic engine-file content endpoint (GET /api/v1/files/{fileId}/content) and dynamically import()s, instead of the code shipping inside a host application's own build. Optional and additive - absent on every manifest that predates this field (every real plugin in the fleet today except this pass's own proof plugin), which a frontend loader must treat as a cheap, silent no-op.",
+      "type": "object",
+      "properties": {
+        "fileId": { "type": "string", "minLength": 1, "description": "A real engine-file file id - not a path, not a URL. A loader builds the URL itself against its own baseUrl." },
+        "entrypointExport": { "type": "string", "minLength": 1, "description": "The bundle's exported registration function name a loader calls with its own live BlockRegistry (e.g. \"installRiskScoreCardPlugin\"). Defaults to \"default\" when absent." }
+      },
+      "required": ["fileId"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["contractVersion", "id", "version", "publisher", "displayNameKey", "descriptionKey", "distribution", "contributions"],
+  "additionalProperties": false
+}

package/bundle/schemas/connector-definition.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.internal/schema/connector-definition.schema.json",
+  "title": "ExternalProviderConnectorDefinition",
+  "description": "Authoring shape for one external_provider_definition row (engine-provider-connector, V157) — the generic, domain-agnostic 'call an external HTTP provider per JSON config' capability. Consumed by GenericProviderConnectorExecutor via PUT /api/v1/provider-connectors/definitions/{domain}/{providerKey}. Authored/verified through `erp connector create|validate|list|test` (tools/erp-cli/erp.mjs) — never by hand-editing rows directly.",
+  "type": "object",
+  "required": ["domain", "providerKey", "name", "connectorKind"],
+  "properties": {
+    "domain": { "type": "string", "description": "Consumer namespace, e.g. \"hcm-employee-documents.signature\" — any plugin/feature can register its own domain." },
+    "providerKey": { "type": "string", "description": "Unique per (tenant, domain) — what the consuming entity's provider_name/provider_key column resolves against." },
+    "name": { "type": "string" },
+    "connectorKind": { "type": "string", "enum": ["DIRECT", "HTTP"] },
+    "active": { "type": "boolean" },
+    "isDefault": { "type": "boolean" },
+    "baseUrl": { "type": "string" },
+    "authType": { "type": "string", "enum": ["NONE", "API_KEY_HEADER", "BEARER_TOKEN", "BASIC"] },
+    "authConfig": { "type": "object", "description": "e.g. {headerName, secretRef} — secretRef of shape \"env:VAR_NAME\" resolved from environment at call time, never a literal secret stored here." },
+    "requestPath": { "type": "string" },
+    "httpMethod": { "type": "string", "enum": ["POST", "PUT"] },
+    "requestTemplate": { "type": "object", "description": "JSON object whose string leaves may contain {{fieldName}} tokens substituted at call time." },
+    "responseMapping": { "type": "object", "description": "{providerReferencePath, statusPath, signingUrlPath} dot-paths into the vendor's JSON response." },
+    "statusMapping": { "type": "object", "description": "Vendor status string -> this domain's own internal status vocabulary." },
+    "completionMode": { "type": "string", "enum": ["MANUAL_CONFIRM", "POLL", "WEBHOOK"] },
+    "pollPathTemplate": { "type": "string" },
+    "webhookPath": { "type": "string" },
+    "notes": { "type": "string" },
+    "ownerPlugin": { "type": "string" }
+  }
+}

package/bundle/schemas/data-service-definition.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.internal/schema/data-service-definition.schema.json",
+  "title": "DataServiceDefinitionArtifact",
+  "description": "The real on-disk authoring shape for a Data Service JSON artifact (spk-assembly/metadata/data_service/*.json), backed by com.erp.platform.engine.entity.dataservice.DataServiceSpec (backend/platform-runtime/engine-entity) and executed by DataServiceExecutionController. Confirmed against a live shipped file (hcm-payroll-audit-report.json). `source` is a loose union on the wire — only the field matching source.kind is populated (matches DataServiceSpec.Source's own doc comment about mirroring the frontend's plain-object DataServiceSourceKind union rather than a polymorphic Jackson type).",
+  "type": "object",
+  "required": ["name", "definition"],
+  "properties": {
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "metadata": { "type": "object" },
+    "modules": { "type": "array", "items": { "type": "string" } },
+    "definition": {
+      "type": "object",
+      "required": ["operation", "source"],
+      "properties": {
+        "operation": { "type": "string", "enum": ["get", "count", "search", "composite"], "description": "Also determines the /execute RESPONSE envelope shape a page must bind against — undocumented elsewhere, confirmed against shipped hcm-analytics-reports KPI bindings: operation \"count\" returns `{\"value\": <number>}` (bind as `${api.<callName>.value}` — NOT `.total`, which is only the entity-records LIST pagination envelope's field, unrelated to this endpoint). operation \"get\"/\"search\" return `{\"items\": [...]}` (or `{\"records\": [...]}` for a dataView source — check a shipped example for the exact key before guessing). operation \"composite\" returns `{\"results\": {\"<step.as>\": <that step's own envelope>}}`." },
+        "source": {
+          "type": "object",
+          "properties": {
+            "kind": { "type": "string", "enum": ["provider", "entity", "dataView"] },
+            "providerName": { "type": ["string", "null"] },
+            "entityName": { "type": ["string", "null"] },
+            "dataViewName": { "type": ["string", "null"], "description": "Names a published data-view-definition artifact — see data-view-definition.schema.json." }
+          }
+        },
+        "filters": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "field": { "type": "string" },
+              "operator": { "type": "string" },
+              "value": { "type": "string" },
+              "valueType": { "type": ["string", "null"], "enum": ["string", null], "description": "Opt-in escape hatch telling DataViewQueryExecutor not to numeric-auto-coerce a text id column (e.g. attachment.entity_id). null (default) preserves auto-detect behavior." }
+            }
+          }
+        },
+        "parameters": {
+          "type": "array",
+          "description": "Declares this artifact's own named parameters (referenced in `filters`/`steps` as `${param.<name>}`). NOTE — this only documents the artifact's declared shape, not the caller-side wire shape: a REST call to POST /api/v1/data-services/<name>/execute must nest its argument object one level deeper than a normal entity-records call, as `{\"params\": {\"parameters\": {\"<name>\": \"<value>\"}}}`, NOT `{\"params\": {\"<name>\": \"<value>\"}}`. See ai/patterns/data-service-execute-wiring.md for the full wire-shape writeup and a shipped example.",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "properties": { "name": { "type": "string" }, "type": { "type": "string" } }
+          }
+        },
+        "steps": {
+          "type": "array",
+          "description": "Only for operation \"composite\" — each a fan-out leg naming another published Data Service, executed strictly in declaration order.",
+          "items": {
+            "type": "object",
+            "required": ["as", "service"],
+            "properties": {
+              "as": { "type": "string", "description": "Key this step's result lands under in ExecuteResponse.results." },
+              "service": { "type": "string" },
+              "parameters": { "type": "object", "description": "Values are literals or ${param.<name>} / ${step.<as>.<field>} templates." }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/bundle/schemas/data-view-definition.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.internal/schema/data-view-definition.schema.json",
+  "title": "DataViewDefinitionArtifact",
+  "description": "The real on-disk authoring shape for a Data View JSON artifact (spk-assembly/metadata/data_view/*.json), backed by com.erp.platform.engine.entity.dataview.DataViewSpec (backend/platform-runtime/engine-entity) and executed by DataViewQueryExecutor. Confirmed against a live shipped file (hcm-employee's employee-activity.json). Every table/column reference here is a PLAIN PHYSICAL SQL identifier (never an Entity Designer field name) — see DataViewSpec's own doc comment. Not directly externally-callable: only reachable through a Data Service whose source.kind is \"dataView\" (see data-service-definition.schema.json).",
+  "type": "object",
+  "required": ["name", "definition"],
+  "properties": {
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "metadata": { "type": "object" },
+    "modules": { "type": "array", "items": { "type": "string" } },
+    "definition": {
+      "type": "object",
+      "required": ["source"],
+      "properties": {
+        "source": {
+          "type": "object",
+          "required": ["table", "alias"],
+          "properties": {
+            "table": { "type": "string" },
+            "alias": { "type": "string" },
+            "excludeDeleted": { "type": "boolean" },
+            "schema": { "type": ["string", "null"], "description": "Nullable — defaults to unqualified, resolving through the executing connection's own search_path. A Data View sourced from a plugin-owned schema (e.g. HCM's employee/org_unit/position tables, all in `hcm`) must say so explicitly." }
+          }
+        },
+        "joins": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["table", "alias", "type", "on"],
+            "properties": {
+              "table": { "type": "string" },
+              "alias": { "type": "string" },
+              "type": { "type": "string", "enum": ["LEFT", "INNER"] },
+              "on": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["leftRef", "rightRef"],
+                  "properties": { "leftRef": { "type": "string" }, "rightRef": { "type": "string" } }
+                }
+              },
+              "excludeDeleted": { "type": "boolean" },
+              "schema": { "type": ["string", "null"] }
+            }
+          }
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["ref"],
+            "properties": { "ref": { "type": "string", "description": "\"alias.column\"" }, "outputName": { "type": "string" } }
+          }
+        },
+        "calculatedFields": {
+          "type": "array",
+          "description": "A closed, whitelisted expression AST (com.erp.platform.engine.entity.dataview.CalcExpr) — never a raw SQL/expression string (injection risk). Each item is a { outputName, expression } CalculatedField.",
+          "items": {
+            "type": "object",
+            "required": ["outputName", "expression"],
+            "properties": {
+              "outputName": { "type": "string" },
+              "expression": { "$ref": "#/definitions/calcExpr" }
+            }
+          }
+        },
+        "filter": { "type": ["string", "null"], "description": "A structured JSON predicate tree ({and:[...]}/{or:[...]}/{field,operator,value}) — Studio's PredicateBuilder.tsx grammar, with qualified \"alias.column\" field names. Stored as a JSON string, same as workflow's *Json columns." },
+        "groupBy": { "type": "array", "items": { "type": "string" }, "description": "Each a \"alias.column\" ref. See groupByTruncations for opt-in SQL-level date bucketing of one of these refs." },
+        "groupByTruncations": {
+          "type": "array",
+          "description": "(2026-09-07, date-truncation gap-closing pass) Optional, additive — enables a real SQL date_trunc()-bucketed group-by/select for a time-series \"Trend\" chart (e.g. monthly headcount). Absent/empty reproduces today's exact raw-column behavior. When present, a { ref, unit } entry here causes BOTH the matching groupBy entry AND any fields[] entry with the SAME ref to compile to date_trunc('<unit>', <ref>) instead of the raw column — author the SAME ref string in both places.",
+          "items": {
+            "type": "object",
+            "required": ["ref", "unit"],
+            "properties": {
+              "ref": { "type": "string", "description": "\"alias.column\" — must exactly match a groupBy entry (and, if selected, a fields[].ref) to take effect." },
+              "unit": { "type": "string", "enum": ["day", "week", "month", "quarter", "year"], "description": "Validated server-side against this exact whitelist — never concatenated unchecked (it lands inside a single-quoted SQL string literal)." }
+            }
+          }
+        },
+        "aggregations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["ref", "fn"],
+            "properties": { "ref": { "type": "string" }, "fn": { "type": "string", "enum": ["SUM", "AVG", "COUNT", "MIN", "MAX"] }, "outputName": { "type": "string" } }
+          }
+        },
+        "havingFilter": {
+          "type": ["string", "null"],
+          "description": "(2026-09-07, HAVING gap-closing pass) Optional, additive post-aggregation filter — e.g. a minimum-group-size-5 suppression on a demographic breakdown. Only meaningful when groupBy is non-empty. Stored as a JSON string using the SAME structured predicate grammar as `filter` ({and:[...]}/{or:[...]}/{field,operator,value}), EXCEPT a leaf's \"field\" here MUST name one of this spec's own aggregations[].outputName values (never a raw \"alias.column\" — Postgres cannot reference a SELECT alias inside HAVING, so the executor re-resolves the real FN(ref) expression from the matching aggregation). An outputName with no matching aggregation is rejected. null (every Data View authored before this field existed) adds no HAVING clause — today's exact behavior. Example: {\"field\":\"headcount\",\"operator\":\"gte\",\"value\":5} where aggregations includes {\"ref\":\"e.id\",\"fn\":\"COUNT\",\"outputName\":\"headcount\"}."
+        },
+        "sort": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["ref"],
+            "properties": { "ref": { "type": "string" }, "descending": { "type": "boolean" } }
+          }
+        },
+        "pagination": {
+          "type": "object",
+          "properties": { "defaultPageSize": { "type": "number" }, "maxPageSize": { "type": "number" } }
+        },
+        "permissionKey": { "type": ["string", "null"], "description": "Authored, NOT enforced in v1 — same disclosed ceiling every other Data Service execution has until real platform-wide RBAC/ABAC lands." }
+      }
+    }
+  },
+  "definitions": {
+    "calcExpr": {
+      "type": "object",
+      "description": "com.erp.platform.engine.entity.dataview.CalcExpr — a loose union on the wire; only the properties matching \"op\" are populated.",
+      "required": ["op"],
+      "properties": {
+        "op": { "type": "string", "enum": ["field", "literal", "concat", "coalesce", "add", "sub", "mul", "div", "case", "aggregate", "ratio"] },
+        "fieldRef": { "type": "string", "description": "op==\"field\": an \"alias.column\" ref. Also reused as the aggregated column ref for op==\"aggregate\" (SUM/AVG/MIN/MAX; omit for COUNT(*))." },
+        "literalValue": { "description": "op==\"literal\": string/number/boolean/null — always bind-parameterized." },
+        "args": { "type": "array", "items": { "$ref": "#/definitions/calcExpr" }, "description": "op==\"concat\"|\"coalesce\": 2+ operands." },
+        "left": { "$ref": "#/definitions/calcExpr", "description": "op==\"add\"|\"sub\"|\"mul\"|\"div\"." },
+        "right": { "$ref": "#/definitions/calcExpr" },
+        "whenClauses": {
+          "type": "array",
+          "description": "op==\"case\".",
+          "items": {
+            "type": "object",
+            "required": ["when", "then"],
+            "properties": {
+              "when": { "type": "string", "description": "A structured predicate JSON string — the SAME grammar as DataViewSpec.filter()." },
+              "then": { "$ref": "#/definitions/calcExpr" }
+            }
+          }
+        },
+        "elseExpr": { "$ref": "#/definitions/calcExpr", "description": "op==\"case\", optional ELSE." },
+        "aggFn": {
+          "type": "string",
+          "enum": ["SUM", "AVG", "COUNT", "MIN", "MAX"],
+          "description": "(2026-09-07, ratio gap-closing pass) op==\"aggregate\": compiles to a real SQL aggregate function, valid in a grouped OR ungrouped select list (unlike op==\"field\", which must also appear in groupBy). Combine with \"filter\" for a conditional/filtered aggregate, e.g. count(case when <filter> then 1 end) — the building block a ratio numerator/denominator needs."
+        },
+        "filter": { "type": "string", "description": "op==\"aggregate\": optional structured predicate JSON (same grammar as DataViewSpec.filter()) — CASE WHEN this matches THEN counted/summed ELSE excluded." },
+        "numerator": { "$ref": "#/definitions/calcExpr", "description": "op==\"ratio\": typically an \"aggregate\" expression, but any calcExpr is accepted." },
+        "denominator": { "$ref": "#/definitions/calcExpr", "description": "op==\"ratio\": compiled with a NULLIF(...,0) guard, so a zero denominator yields SQL NULL rather than a divide-by-zero error." },
+        "multiplyBy": { "type": "number", "description": "op==\"ratio\": optional post-division multiplier (e.g. 100 for a percentage). Defaults to 1 (a plain ratio) when absent. Example — attritionRate = { \"op\":\"ratio\", \"numerator\":{\"op\":\"aggregate\",\"aggFn\":\"COUNT\",\"filter\":\"{\\\"field\\\":\\\"r.status\\\",\\\"operator\\\":\\\"eq\\\",\\\"value\\\":\\\"separated\\\"}\"}, \"denominator\":{\"op\":\"aggregate\",\"aggFn\":\"COUNT\"}, \"multiplyBy\":100 }." }
+      }
+    }
+  }
+}

package/bundle/schemas/entity-aggregation-config.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.platform/schema/entity-aggregation-config.schema.json",
+  "title": "entity_aggregation_config row",
+  "description": "One config row for the generic engine-entity.aggregation-sweep job (EntityAggregationSweepJob): fold many rows of source_entity into a scalar (or per-group scalar) and upsert the result into target_entity. Ship via metadata/seed-data/*.json. See ai/patterns/generic-aggregation-and-cadence-jobs.md.",
+  "type": "object",
+  "required": ["sweep_code", "source_entity", "aggregation", "target_entity", "target_key_field", "target_value_field", "active"],
+  "additionalProperties": false,
+  "properties": {
+    "sweep_code": { "type": "string", "description": "Stable identifier / natural key for idempotent seeding." },
+    "source_entity": { "type": "string" },
+    "filter_field": { "type": "string", "description": "Optional single-column equality pre-filter." },
+    "filter_value": { "type": "string" },
+    "when_status_in": { "type": "string", "description": "Optional comma-separated status filter." },
+    "status_field": { "type": "string", "default": "status" },
+    "date_field": { "type": "string", "description": "Optional date pre-filter column." },
+    "date_compare_op": { "type": "string", "enum": ["lte", "lt", "gte", "gt"], "default": "lte" },
+    "day_offset": { "type": "integer", "default": 0 },
+    "aggregation": { "type": "string", "enum": ["count", "sum", "avg", "min", "max"] },
+    "agg_field": { "type": "string", "description": "Required for sum/avg/min/max; the numeric column to fold." },
+    "group_by_field": { "type": "string", "description": "Optional; one result bucket per distinct value." },
+    "target_entity": { "type": "string" },
+    "target_key_field": { "type": "string", "description": "Column on target_entity that holds the bucket key (a declared field). Special value \"id\": the bucket key IS a row's own primary key — the fold is written straight back onto target_entity row #<key> (never a create). Use with group_by_field yielding the parent id (e.g. maintenance_id), target_entity = that parent entity, and a blank target_key_prefix — this is the true 'roll child lines up onto the parent record' form (MaintenanceCostSyncJob)." },
+    "target_key_prefix": { "type": "string", "description": "Prepended to the bucket key when writing (so multiple configs can share one summary entity without collisions)." },
+    "result_key": { "type": "string", "description": "Used as the bucket key when group_by_field is blank; defaults to sweep_code." },
+    "target_value_field": { "type": "string" },
+    "target_timestamp_field": { "type": "string", "description": "Optional; now written here on each run." },
+    "target_extra_json": { "type": "object", "description": "Optional static fields set only when a target row is first created." },
+    "seeded_by": { "type": "string" },
+    "active": { "type": "boolean" }
+  }
+}

package/bundle/schemas/entity-cadence-config.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.platform/schema/entity-cadence-config.schema.json",
+  "title": "entity_cadence_config row",
+  "description": "One config row for the generic engine-entity.cadence-generator job (EntityCadenceGeneratorJob): create new target_entity rows on a cadence, either one-per-due-source-row or one standalone row from a template. Ship via metadata/seed-data/*.json. See ai/patterns/generic-aggregation-and-cadence-jobs.md.",
+  "type": "object",
+  "required": ["cadence_code", "target_entity", "interval_days", "active"],
+  "additionalProperties": false,
+  "properties": {
+    "cadence_code": { "type": "string", "description": "Stable identifier / natural key for idempotent seeding." },
+    "target_entity": { "type": "string" },
+    "interval_days": { "type": "integer", "description": "Minimum days between generations; the job stamps last_generated_at on its own config row after each run." },
+    "last_generated_at": { "type": "string", "description": "Managed by the job; leave unset in seed files." },
+    "template_json": { "type": "object", "description": "Static field values for each created row. String values may use ${date} ${ts} ${uuid} ${sourceId} placeholders." },
+    "source_entity": { "type": "string", "description": "Set for source-driven generation (one target row per due source row); leave blank for a standalone single-row generator." },
+    "source_filter_field": { "type": "string" },
+    "source_filter_value": { "type": "string" },
+    "source_status_field": { "type": "string", "default": "status" },
+    "source_status_in": { "type": "string" },
+    "source_date_field": { "type": "string", "description": "Only source rows whose date_field <= now + due_within_days are generated from." },
+    "due_within_days": { "type": "integer", "default": 0 },
+    "field_map_json": { "type": "object", "description": "{ targetField: sourceField } - copies values from each source row." },
+    "dedupe_target_field": { "type": "string", "description": "Target column holding the source row id (source-driven) or the cadence marker (standalone) - the idempotency key." },
+    "seeded_by": { "type": "string" },
+    "active": { "type": "boolean" }
+  }
+}