@sparkerp/plugin-sdk 0.1.0

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

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.platform/schema/entity-compliance-config.schema.json",
+  "title": "entity_compliance_config row",
+  "description": "One config row for the generic engine-entity.compliance-sweep job (EntityComplianceSweepJob, Batch 3, 2026-09-10): evaluate a rule-engine boolean expression against every row of source_entity and either flag the offending row (set_field/set_value) or raise a deduped escalation row (escalation_entity). Reuses the platform ExpressionEvaluator (same MVEL evaluator as cross-field validation / Formula fields). Ship via metadata/seed-data/*.json. See ai/patterns/generic-compliance-sweep-job.md.",
+  "type": "object",
+  "required": ["compliance_code", "source_entity", "condition_expr", "active"],
+  "additionalProperties": false,
+  "properties": {
+    "compliance_code": { "type": "string", "description": "Stable identifier / natural key for idempotent seeding." },
+    "source_entity": { "type": "string", "description": "Entity evaluated row-by-row." },
+    "status_field": { "type": "string", "default": "status" },
+    "when_status_in": { "type": "string", "description": "Optional comma-separated status pre-filter." },
+    "filter_field": { "type": "string", "description": "Optional single-column equality pre-filter." },
+    "filter_value": { "type": "string" },
+    "related_count_entity": { "type": "string", "description": "Optional: count child rows of this entity whose related_count_key_field equals the source row's id, and bind the result as `related_count` in the expression context." },
+    "related_count_key_field": { "type": "string", "description": "The FK column on related_count_entity that points back to the source row's id." },
+    "related_count_status_field": { "type": "string", "default": "status" },
+    "related_count_status_in": { "type": "string", "description": "Optional comma-separated status filter for the related count." },
+    "condition_expr": { "type": "string", "description": "MVEL boolean expression evaluated against each row's fields (+ `now`, + `related_count`). Whitelisted functions only (daysBetween, now, etc.). True => apply the outcome." },
+    "set_field": { "type": "string", "description": "Flag outcome: column on the source row to write when the condition is true (idempotent — skipped if already equal to set_value)." },
+    "set_value": { "type": "string", "description": "Flag outcome: value written into set_field." },
+    "escalation_entity": { "type": "string", "description": "Escalation outcome: create one row in this separate entity per violating source row, deduped by escalation_dedupe_field = source id." },
+    "escalation_dedupe_field": { "type": "string", "description": "Column on escalation_entity that holds the source row id (used for dedupe)." },
+    "escalation_timestamp_field": { "type": "string", "description": "Optional column on escalation_entity that receives `now` on create." },
+    "field_map_json": { "type": "object", "description": "Escalation outcome: {targetField: sourceField} — copies source row values into the new escalation row." },
+    "escalation_template_json": { "type": "object", "description": "Escalation outcome: static fields set on every created escalation row." },
+    "seeded_by": { "type": "string" },
+    "active": { "type": "boolean" }
+  }
+}

package/bundle/schemas/entity-cross-plugin-action-config.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.platform/schema/entity-cross-plugin-action-config.schema.json",
+  "title": "entity_cross_plugin_action_config row",
+  "description": "One config row for the generic engine-entity.cross-plugin-action job (EntityCrossPluginActionJob, Batch 5+6, 2026-09-10): a row of trigger_entity entering a triggering status fans an action out onto every related_entity row keyed back to it - creating a row in create_entity and/or updating the related row itself - deduped so re-runs are safe. trigger_entity may be owned by another plugin (e.g. employee); no cross-plugin HTTP, both are Entity-Engine entities in the same tenant. Ship via metadata/seed-data/*.json. See ai/patterns/generic-cross-plugin-action-job.md.",
+  "type": "object",
+  "required": ["action_code", "trigger_entity", "related_entity", "related_match_field", "active"],
+  "additionalProperties": false,
+  "properties": {
+    "action_code": { "type": "string", "description": "Stable identifier / natural key for idempotent seeding." },
+    "trigger_entity": { "type": "string", "description": "Entity A - the record whose status change triggers the fan-out (often owned by another plugin, e.g. employee)." },
+    "trigger_status_field": { "type": "string", "default": "status" },
+    "trigger_status_in": { "type": "string", "description": "Comma-separated statuses that make a trigger row eligible (e.g. TERMINATED,SEPARATED). Blank = every row." },
+    "trigger_date_field": { "type": "string", "description": "Optional date gate column on the trigger row (e.g. separation_date)." },
+    "trigger_date_compare_op": { "type": "string", "enum": ["lte", "lt", "gte", "gt"], "default": "lte" },
+    "trigger_day_offset": { "type": "integer", "default": 0, "description": "Compare trigger_date_field against now + this many days." },
+    "trigger_key_field": { "type": "string", "default": "id", "description": "Field on the trigger row whose value matches related rows (usually id -> employee id)." },
+    "related_entity": { "type": "string", "description": "Entity B - the rows acted on." },
+    "related_match_field": { "type": "string", "description": "FK column on related_entity that equals the trigger row's key (e.g. employee_id)." },
+    "related_status_field": { "type": "string", "default": "status" },
+    "related_status_in": { "type": "string", "description": "Comma-separated statuses a related row must be in to be acted on (e.g. ALLOCATED,ACKNOWLEDGED,IN_USE)." },
+    "create_entity": { "type": "string", "description": "Create-outcome: entity a row is created in per matched related row (e.g. hcm_asset_return). Omit to only update the related row." },
+    "create_dedupe_field": { "type": "string", "description": "Numeric (long) column on create_entity holding the related row's id - dedupes re-runs. MUST be numeric, not text (EntityRecordService binds numeric-looking filter values as bigint)." },
+    "create_template_json": { "type": "object", "description": "Static fields set on every created row. String values may contain ${date} ${ts} ${uuid} ${relatedId} ${triggerKey} - substituted per created row so a required-unique column (e.g. return_number) never collides." },
+    "create_field_map_json": { "type": "object", "description": "{targetField: relatedField} - copies related row values into the created row." },
+    "related_set_field": { "type": "string", "description": "Update-outcome: column on the related row to write (e.g. status). Idempotent - skipped when already equal to related_set_value." },
+    "related_set_value": { "type": "string", "description": "Value written into related_set_field (e.g. RETURN_PENDING)." },
+    "seeded_by": { "type": "string" },
+    "active": { "type": "boolean" }
+  }
+}

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

@@ -0,0 +1,126 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.internal/schema/entity-definition.schema.json",
+  "title": "EntityDefinition",
+  "description": "One tenant-authored entity (table) definition understood by engine-entity's EntityDdlGenerator. Mirrors the Java record com.erp.platform.engine.entity.EntityDefinition plus its child EntityFieldDefinition/EntityRelationshipDefinition rows. See ai/patterns/entity-engine-real-module.md for the authoring recipe. Two real, distinct on-the-wire shapes exist and both validate here (FIXED 2026-09-03 — the schema previously modeled ONLY shape A, so `erp schema validate --schema entity-definition` FAILED on every already-shipped spk-assembly/metadata/entities/*.json file in this repo, a real, previously-undisclosed bug found live authoring hcm-learning's Course Catalog batch): (A) the flat POST /api/v1/entities request body (fields added separately via POST .../fields) — entity properties top-level, no `fields` array required; (B) the packaged install-time artifact PluginEntityInstaller actually reads from spk-assembly/metadata/entities/*.json — a `{\"entity\": {...same entity properties...}, \"fields\": [...]}` wrapper, fields inline. dataType is accepted case-insensitively (both the UPPERCASE enum below and the lowercase spelling — e.g. \"text\"/\"TEXT\" — every real shipped file on disk actually uses, confirmed live).",
+  "oneOf": [
+    { "$ref": "#/definitions/flatEntity" },
+    {
+      "type": "object",
+      "required": ["entity", "fields"],
+      "properties": {
+        "entity": { "$ref": "#/definitions/entityProps" },
+        "fields": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/field" } },
+        "relationships": { "type": "array", "items": { "$ref": "#/definitions/relationship" } }
+      }
+    }
+  ],
+  "definitions": {
+    "entityProps": {
+      "type": "object",
+      "required": ["name", "label"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*$",
+          "description": "Logical entity name; becomes the physical table name unless tableName is set."
+        },
+        "tableName": { "type": "string", "description": "Physical table name override; defaults to name." },
+        "label": { "type": "string", "description": "entity_definition.label is a jsonb column (server-side `cast(? as jsonb)`) — this string must itself BE valid JSON, e.g. an i18n object \"{\\\"en\\\":\\\"Announcement\\\"}\", not a bare display string like \"Announcement\" (that fails install with 'invalid input syntax for type json'; found live authoring hcm-communications). Same requirement applies to flatEntity.label and field.label below." },
+        "description": { "type": "string" },
+        "category": { "type": "string" },
+        "icon": { "type": "string" },
+        "color": { "type": "string" },
+        "cacheable": { "type": "boolean", "default": false },
+        "fullTextSearch": { "type": "boolean", "default": false },
+        "softDeleteEnabled": { "type": "boolean", "default": false },
+        "status": { "type": "string", "enum": ["DRAFT", "PUBLISHED", "DEPRECATED"], "default": "DRAFT" },
+        "pkStrategy": { "type": "string", "enum": ["IDENTITY", "SEQUENCE", "identity", "sequence"], "default": "IDENTITY" },
+        "pkSequenceName": { "type": "string" },
+        "schemaName": { "type": "string", "description": "App-owned Postgres schema this entity's table routes to — see feedback-entity-engine-tables-must-route-to-app-schema." },
+        "designerMetadata": { "type": "string" }
+      }
+    },
+    "flatEntity": {
+      "type": "object",
+      "required": ["name", "label", "fields"],
+      "properties": {
+        "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
+        "tableName": { "type": "string" },
+        "label": { "type": "string", "description": "See entityProps.label above — same jsonb-encoding requirement (this flatEntity shape is normally the live POST-body path, where the server may accept a plain string; the packaged spk-assembly artifact path does not)." },
+        "description": { "type": "string" },
+        "category": { "type": "string" },
+        "icon": { "type": "string" },
+        "color": { "type": "string" },
+        "cacheable": { "type": "boolean", "default": false },
+        "fullTextSearch": { "type": "boolean", "default": false },
+        "softDeleteEnabled": { "type": "boolean", "default": false },
+        "status": { "type": "string", "enum": ["DRAFT", "PUBLISHED", "DEPRECATED"], "default": "DRAFT" },
+        "pkStrategy": { "type": "string", "enum": ["IDENTITY", "SEQUENCE"], "default": "IDENTITY" },
+        "pkSequenceName": { "type": "string" },
+        "schemaName": { "type": "string" },
+        "fields": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/field" } },
+        "relationships": { "type": "array", "items": { "$ref": "#/definitions/relationship" } }
+      }
+    },
+    "field": {
+      "type": "object",
+      "required": ["fieldName", "label", "dataType"],
+      "properties": {
+        "fieldName": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
+        "label": { "type": "string", "description": "entity_field_definition.label is a jsonb column too — pass a JSON-encoded string, e.g. \"\\\"Code\\\"\" (a JSON string literal, with escaped quotes) not a bare \"Code\". See entityProps.label above for the same requirement and the real install error it throws when violated." },
+        "description": { "type": "string" },
+        "dataType": {
+          "type": "string",
+          "enum": [
+            "TEXT", "NUMBER", "INTEGER", "BOOLEAN", "DATE", "DATETIME", "JSON", "REFERENCE", "FORMULA", "ENUM",
+            "text", "number", "integer", "long", "decimal", "currency", "boolean", "date", "datetime", "json", "reference", "formula", "enum", "string", "email", "file", "image", "uuid", "binary", "time"
+          ],
+          "description": "The real EntityDataType Java enum (STRING/TEXT/INTEGER/LONG/DECIMAL/CURRENCY/BOOLEAN/DATE/DATETIME/TIME/JSON/ENUM/EMAIL/FILE/IMAGE/UUID/BINARY) accepts its value case-insensitively at install time; every real shipped spk-assembly/metadata/entities/*.json file on disk today spells it lowercase."
+        },
+        "typeParams": {
+          "description": "Type-specific config — either a JSON object, or (as every real shipped file on disk actually authors it) that same object pre-serialized as a JSON string, e.g. \"{\\\"length\\\": 50}\" / \"{\\\"enumValues\\\": [\\\"A\\\",\\\"B\\\"]}\".",
+          "oneOf": [{ "type": "object" }, { "type": "string" }]
+        },
+        "nullable": { "type": "boolean", "default": true },
+        "required": { "type": "boolean", "default": false },
+        "defaultValue": { "type": "string" },
+        "displayOrder": { "type": "integer" },
+        "isPrimaryKey": { "type": "boolean", "default": false },
+        "isUnique": { "type": "boolean", "default": false },
+        "isIndexed": { "type": "boolean", "default": false },
+        "isReadOnly": { "type": "boolean", "default": false },
+        "isHidden": { "type": "boolean", "default": false },
+        "isDisplayField": { "type": "boolean", "default": false },
+        "flags": {
+          "type": "object",
+          "description": "e.g. { \"formula\": \"<mvel expression>\" } — a formula field gets no physical column, computed on read. ALSO (added 2026-09-03): { \"reference\": { \"entityType\": \"Employee\" } } on a foreign-key-shaped field (e.g. employee_id) turns on automatic id->display-name resolution — no Java, no per-page join. Once set (via this file or PUT /api/v1/entities/{id}/fields/{fieldId}), BOTH GET .../records/query (the grid endpoint) and GET .../records/{id} (single-record read) automatically add a sibling \"<fieldName>_label\" key to every row/record where that id resolves (e.g. employee_id:1, employee_id_label:\"Aria Chen\") — bind a grid column or detail-view field to \"<fieldName>_label\" instead of the raw id. Batched: one resolve call per distinct reference-flagged field per page load, never per row. entityType must be a REGISTERED provider — \"Employee\" is the only one today (backed by hcm-employee's own batch-names endpoint via engine-entity's ReferenceResolutionService); an unregistered entityType simply produces no \"_label\" key, never an error. See erp examples search \"employee_id_label\" for a real shipped instance (hcm-compensation's hcm_salary_planning_entry/hcm_salary_review/hcm_merit_increase entities + their page grid columns/detail bindings)."
+        },
+        "roleRules": {
+          "type": "array",
+          "description": "Mirrors @erp/form-engine's FieldRoleRule[].",
+          "items": {
+            "type": "object",
+            "required": ["role"],
+            "properties": {
+              "role": { "type": "string" },
+              "required": { "type": "boolean" },
+              "readOnly": { "type": "boolean" },
+              "hidden": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    },
+    "relationship": {
+      "type": "object",
+      "required": ["name", "type", "targetEntity"],
+      "properties": {
+        "name": { "type": "string" },
+        "type": { "type": "string", "enum": ["ONE_TO_MANY", "MANY_TO_ONE", "MANY_TO_MANY"] },
+        "targetEntity": { "type": "string" },
+        "foreignKeyField": { "type": "string" }
+      }
+    }
+  }
+}

package/bundle/schemas/entity-document-generator-config.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.platform/schema/entity-document-generator-config.schema.json",
+  "title": "entity_document_generator_config row",
+  "description": "One config row for the generic engine-entity.document-generator job (EntityDocumentGeneratorJob, Batch 5+6, 2026-09-10): generate a document artifact per eligible source_entity row via the platform FileService, store it in a DMS cabinet, and stamp the file id onto target_file_field. Deduped by 'target field already populated'. NOTE: the platform print-template render path (engine-print-export PlaywrightPdfRenderer) cannot be driven headless against a real business record - it only renders synthetic sample data via the Studio app - so this job emits a structured-data artifact (json/csv). template_ref is reserved for when real-record print binding ships. Ship via metadata/seed-data/*.json. See ai/patterns/generic-document-generator-job.md.",
+  "type": "object",
+  "required": ["document_code", "source_entity", "target_file_field", "active"],
+  "additionalProperties": false,
+  "properties": {
+    "document_code": { "type": "string", "description": "Stable identifier / natural key for idempotent seeding." },
+    "source_entity": { "type": "string", "description": "Entity whose rows get a document." },
+    "status_field": { "type": "string", "default": "status" },
+    "when_status_in": { "type": "string", "description": "Comma-separated statuses a row must be in to be eligible (e.g. COMPLETED for an audit report). Blank = every row." },
+    "filter_field": { "type": "string", "description": "Optional single-column equality pre-filter." },
+    "filter_value": { "type": "string" },
+    "target_file_field": { "type": "string", "description": "Text column on the source row that receives the generated file id. Its non-blank state IS the dedupe marker." },
+    "format": { "type": "string", "enum": ["json", "csv"], "default": "json" },
+    "cabinet_id": { "type": "integer", "description": "DMS cabinet id (engine-file) the artifact is stored in. Give this OR cabinet_name." },
+    "cabinet_name": { "type": "string", "description": "Portable alternative to cabinet_id: the job resolves a cabinet by this name for the tenant, creating it if absent. Preferred for seed-data rows (no hardcoded id)." },
+    "file_name_template": { "type": "string", "description": "Generated file name. Supports ${id} ${date} ${ts} ${uuid} and ${field:<name>}. Default: <document_code>-${id}-${date}.<ext>." },
+    "include_fields": { "type": "string", "description": "Comma-separated source fields to include in the artifact. Blank = all fields." },
+    "child_entity": { "type": "string", "description": "Optional child entity whose rows (matched by child_match_field == source id) are embedded (json) alongside the record." },
+    "child_match_field": { "type": "string", "description": "FK column on child_entity pointing at the source row's id." },
+    "template_ref": { "type": "string", "description": "Reserved: a print-template id, for the future render_mode:template branch. Not used today (see description)." },
+    "regenerate": { "type": "boolean", "default": false, "description": "When true, regenerate even if target_file_field is already populated." },
+    "seeded_by": { "type": "string" },
+    "active": { "type": "boolean" }
+  }
+}

package/bundle/schemas/entity-rule-definition.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.internal/schema/entity-rule-definition.schema.json",
+  "title": "EntityRuleDefinition",
+  "description": "One declarative entity-lifecycle rule, generic across any engine-entity-designed entity. Mirrors com.erp.platform.engine.rule.EntityRuleDefinition. NOT the same as the older Studio 'Business Rule' tier (event-name + single-expression) — see that record's own Javadoc. See ai/patterns/business-rule-engine.md.",
+  "type": "object",
+  "required": ["entityType", "name", "triggerEvent", "conditions", "actions"],
+  "properties": {
+    "entityType": { "type": "string", "description": "The EntityDefinition.name this rule fires against." },
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "triggerEvent": {
+      "type": "string",
+      "enum": ["BEFORE_CREATE", "AFTER_CREATE", "BEFORE_UPDATE", "AFTER_UPDATE", "BEFORE_DELETE", "AFTER_DELETE"]
+    },
+    "priority": { "type": "integer", "default": 0, "description": "Lower runs first when multiple rules match the same trigger." },
+    "active": { "type": "boolean", "default": true },
+    "conditions": { "$ref": "#/definitions/condition" },
+    "actions": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/action" }
+    }
+  },
+  "definitions": {
+    "condition": {
+      "description": "A composable all/any/not condition tree evaluated against the entity record's fields, or a single leaf comparison.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "all": { "type": "array", "items": { "$ref": "#/definitions/condition" } }
+          },
+          "required": ["all"]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "any": { "type": "array", "items": { "$ref": "#/definitions/condition" } }
+          },
+          "required": ["any"]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "not": { "$ref": "#/definitions/condition" }
+          },
+          "required": ["not"]
+        },
+        {
+          "type": "object",
+          "required": ["field", "op"],
+          "properties": {
+            "field": { "type": "string" },
+            "op": { "type": "string", "enum": ["eq", "neq", "gt", "gte", "lt", "lte", "contains", "in", "is_null", "is_not_null"], "description": "Mirrors EntityRuleConditionEvaluator exactly (see ai/patterns/business-rule-engine.md). is_null/is_not_null take no `value`." },
+            "value": { "description": "Required for all ops except is_null/is_not_null." }
+          }
+        }
+      ]
+    },
+    "action": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": { "type": "string", "enum": ["REJECT", "SET_VALUE", "EXECUTE_SERVICE", "START_WORKFLOW"] },
+        "message": { "type": "string", "description": "REJECT only — the error surfaced to the caller." },
+        "field": { "type": "string", "description": "SET_VALUE only — target field name." },
+        "value": { "description": "SET_VALUE only — literal or expression result to assign." },
+        "handlerName": { "type": "string", "description": "EXECUTE_SERVICE only — a registered ActionHandler bean name." },
+        "params": { "type": "object", "description": "EXECUTE_SERVICE/START_WORKFLOW only — extra args passed to the handler/workflow." },
+        "workflowName": { "type": "string", "description": "START_WORKFLOW only." }
+      }
+    }
+  }
+}

package/bundle/schemas/entity-status-date-sweep-config.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.platform/schema/entity-status-date-sweep-config.schema.json",
+  "title": "entity_status_date_sweep_config row",
+  "description": "One config row for the generic engine-entity.status-date-sweep job (EntityStatusDateSweepJob). Ship these via metadata/seed-data/*.json (see plugin-seed-data.schema.json). See ai/patterns/generic-entity-status-date-sweep.md.",
+  "type": "object",
+  "required": ["entity_name", "when_status_in", "date_field", "set_status_to", "active"],
+  "additionalProperties": false,
+  "properties": {
+    "entity_name": { "type": "string", "description": "Entity Engine entity to sweep, e.g. hcm_asset." },
+    "status_field": { "type": "string", "default": "status", "description": "Column holding the gating status." },
+    "when_status_in": { "type": "string", "description": "Comma-separated statuses a row must currently be in to be eligible." },
+    "date_field": { "type": "string", "description": "Date/datetime column compared against now (+day_offset)." },
+    "compare_op": { "type": "string", "enum": ["lte", "lt", "gte", "gt"], "default": "lte" },
+    "day_offset": { "type": "integer", "default": 0, "description": "Compare date_field against now + day_offset days (negative shifts earlier). Enables N-days-before reminders. Added 2026-09." },
+    "set_field": { "type": "string", "description": "Field to WRITE when a row matches; defaults to status_field. Use a distinct flag field (e.g. warranty_alert_30d) so a reminder never corrupts the lifecycle enum." },
+    "set_status_to": { "type": "string", "description": "Value written into set_field on match (e.g. \"true\" for a boolean flag, or a new status enum value)." },
+    "seeded_by": { "type": "string", "description": "Provenance stamp (the plugin id). Set automatically by PluginDataSeedInstaller from the seed file's \"source\"." },
+    "active": { "type": "boolean" }
+  }
+}

package/bundle/schemas/form.schema.json

@@ -0,0 +1,281 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://erp-platform.dev/schemas/form-definition.schema.json",
+  "title": "Form definition contract v1",
+  "description": "The machine-readable contract a form ships (W1-03) - Fields/Sections/Tabs/Layout/Validations/Rules/Events/Permissions, freezing the gap-audit additions: a child-table field kind for repeatable rows (gap 1), computed/formula fields (gap 6), section/tab-level rule targets (gap 3), a cascading-options rule output (gap 4), an async validation kind (gap 5), and a lifecycle-hook catalog (gap 2). Cross-references (sectionId/tabId/field-name existence, rollup targets) are checked by validateFormDefinition, not by this schema alone - the same division of labor as block-definition.schema.json. Permissions reuse the Phase 5 block-instance-config.schema.json shape verbatim (gap 8), never a new model.",
+  "type": "object",
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    },
+    "i18nKey": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "permissionSurface": {
+      "description": "The Phase 5 W2-05 visible/enabled/masked hook, reused verbatim (gap 8) - never a new permission model.",
+      "type": "object",
+      "properties": {
+        "visible": { "type": "boolean" },
+        "enabled": { "type": "boolean" },
+        "masked": { "type": "boolean" }
+      },
+      "required": ["visible", "enabled", "masked"],
+      "additionalProperties": false
+    },
+    "boundKey": {
+      "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
+    },
+    "fieldValue": {
+      "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 }
+      ]
+    },
+    "selectOption": {
+      "type": "object",
+      "properties": { "value": {}, "labelKey": { "$ref": "#/$defs/i18nKey" } },
+      "required": ["value", "labelKey"],
+      "additionalProperties": false
+    },
+    "fieldConstraints": {
+      "type": "object",
+      "properties": {
+        "min": { "type": "number" },
+        "max": { "type": "number" },
+        "maxLength": { "type": "integer", "minimum": 1 },
+        "pattern": { "type": "string", "maxLength": 500 },
+        "options": { "type": "array", "items": { "$ref": "#/$defs/selectOption" } },
+        "currencyCode": { "description": "ISO 4217 code a currency field formats with (taxonomy v2, 2026-07-16) - presentation only.", "type": "string", "pattern": "^[A-Z]{3}$" }
+      },
+      "additionalProperties": false
+    },
+    "fieldDesigner": {
+      "type": "object",
+      "properties": {
+        "group": { "$ref": "#/$defs/identifier" },
+        "icon": { "type": "string", "maxLength": 64 },
+        "helpTextKey": { "$ref": "#/$defs/i18nKey" }
+      },
+      "required": ["group"],
+      "additionalProperties": false
+    },
+    "computedSpec": {
+      "type": "object",
+      "properties": { "expression": { "type": "string", "minLength": 1, "maxLength": 2000 } },
+      "required": ["expression"],
+      "additionalProperties": false
+    },
+    "fetchFromBinding": {
+      "type": "object",
+      "properties": {
+        "sourceBinding": { "$ref": "#/$defs/boundKey" },
+        "fieldMap": { "type": "object", "additionalProperties": { "type": "string" } }
+      },
+      "required": ["sourceBinding", "fieldMap"],
+      "additionalProperties": false
+    },
+    "rollupBinding": {
+      "type": "object",
+      "properties": {
+        "targetField": { "$ref": "#/$defs/identifier" },
+        "expression": { "type": "string", "minLength": 1, "maxLength": 2000 }
+      },
+      "required": ["targetField", "expression"],
+      "additionalProperties": false
+    },
+    "childTableSpec": {
+      "type": "object",
+      "properties": {
+        "rowFields": { "type": "array", "items": { "$ref": "#/$defs/fieldSpec" }, "minItems": 1 },
+        "rowValidations": { "type": "array", "items": { "$ref": "#/$defs/validationSpec" } },
+        "minRows": { "type": "integer", "minimum": 0 },
+        "maxRows": { "type": "integer", "minimum": 1 },
+        "rowPermissions": { "$ref": "#/$defs/permissionSurface" },
+        "fetchFrom": { "$ref": "#/$defs/fetchFromBinding" },
+        "rollup": { "$ref": "#/$defs/rollupBinding" }
+      },
+      "required": ["rowFields", "rowPermissions"],
+      "additionalProperties": false
+    },
+    "fieldSpec": {
+      "type": "object",
+      "properties": {
+        "name": { "$ref": "#/$defs/identifier" },
+        "kind": { "enum": ["text", "number", "date", "time", "datetime", "select", "radio", "multi-select", "checkbox", "currency", "computed", "child-table"] },
+        "labelKey": { "$ref": "#/$defs/i18nKey" },
+        "required": { "type": "boolean" },
+        "translatable": { "type": "boolean" },
+        "blockType": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "value": { "$ref": "#/$defs/fieldValue" },
+        "constraints": { "$ref": "#/$defs/fieldConstraints" },
+        "sectionId": { "$ref": "#/$defs/identifier" },
+        "tabId": { "$ref": "#/$defs/identifier" },
+        "colSpan": { "description": "How many of the owning section's columns this field spans (multi-column layout, 2026-07-16 audit).", "type": "integer", "minimum": 1, "maximum": 4 },
+        "designer": { "$ref": "#/$defs/fieldDesigner" },
+        "computed": { "$ref": "#/$defs/computedSpec" },
+        "childTable": { "$ref": "#/$defs/childTableSpec" },
+        "permissions": { "$ref": "#/$defs/permissionSurface" },
+        "style": { "description": "React CSSProperties-shaped style bag (2026-07-24), the same shape @erp/block-engine's own BlockInstanceConfig.style already uses.", "type": "object", "additionalProperties": { "type": ["string", "number"] } },
+        "className": { "type": "string" }
+      },
+      "required": ["name", "kind", "labelKey"],
+      "additionalProperties": false
+    },
+    "sectionSpec": {
+      "type": "object",
+      "properties": {
+        "id": { "$ref": "#/$defs/identifier" },
+        "titleKey": { "$ref": "#/$defs/i18nKey" },
+        "fields": { "type": "array", "items": { "$ref": "#/$defs/identifier" } },
+        "columns": { "description": "Multi-column layout (2026-07-16 audit, additive): fields lay out across this many columns; absent = single column; collapses to one column at xs (mobile-first).", "type": "integer", "minimum": 1, "maximum": 4 }
+      },
+      "required": ["id", "titleKey", "fields"],
+      "additionalProperties": false
+    },
+    "tabSpec": {
+      "type": "object",
+      "properties": {
+        "id": { "$ref": "#/$defs/identifier" },
+        "titleKey": { "$ref": "#/$defs/i18nKey" },
+        "sectionIds": { "type": "array", "items": { "$ref": "#/$defs/identifier" } }
+      },
+      "required": ["id", "titleKey", "sectionIds"],
+      "additionalProperties": false
+    },
+    "actionDefinition": {
+      "description": "A Phase 2 action definition - opaque here (action-engine's own schema is the contract), just structurally present.",
+      "type": "object"
+    },
+    "validationSpec": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "scope": { "enum": ["field", "cross-field", "form"] },
+        "field": { "$ref": "#/$defs/identifier" },
+        "fields": { "type": "array", "items": { "$ref": "#/$defs/identifier" } },
+        "trigger": { "enum": ["onChange", "onBlur", "beforeSave"] },
+        "kind": { "enum": ["expression", "async"] },
+        "expression": { "type": "string", "maxLength": 2000 },
+        "actionChain": { "type": "array", "items": { "$ref": "#/$defs/actionDefinition" } },
+        "messageKey": { "$ref": "#/$defs/i18nKey" }
+      },
+      "required": ["id", "scope", "trigger", "kind", "messageKey"],
+      "additionalProperties": false
+    },
+    "ruleBindingSpec": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "trigger": { "$ref": "#/$defs/identifier" },
+        "targetKind": { "enum": ["field", "section", "tab"] },
+        "targetId": { "$ref": "#/$defs/identifier" },
+        "output": { "enum": ["visibility", "required", "readonly", "options"] },
+        "condition": { "type": "string", "minLength": 1, "maxLength": 2000 },
+        "resetOnChange": { "type": "boolean" }
+      },
+      "required": ["id", "trigger", "targetKind", "targetId", "output", "condition"],
+      "additionalProperties": false
+    },
+    "formEventBinding": {
+      "type": "object",
+      "properties": {
+        "hook": { "enum": ["onLoad", "beforeSave", "afterSave", "onCancel"] },
+        "actions": { "type": "array", "items": { "$ref": "#/$defs/actionDefinition" }, "minItems": 1 }
+      },
+      "required": ["hook", "actions"],
+      "additionalProperties": false
+    },
+    "canvasPosition": {
+      "description": "Freeform placement envelope (2026-07-24, mirrors @erp/block-engine's own canvas position shape) - authored data, not derived from flow layout.",
+      "type": "object",
+      "properties": {
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "width": { "type": "number" },
+        "height": { "type": "number" },
+        "zIndex": { "type": "number" },
+        "hidden": { "type": "boolean" }
+      },
+      "required": ["x", "y", "width", "height"],
+      "additionalProperties": false
+    },
+    "canvasPlacement": {
+      "description": "One freeform-placed field in a form's own `canvas` (2026-07-24, the same 'Free canvas' mode @erp/block-engine and @erp/page-engine already have) - `field` names an entry already declared in `fields`, a placement layer, not a duplicate content tree.",
+      "type": "object",
+      "properties": {
+        "id": { "$ref": "#/$defs/identifier" },
+        "field": { "$ref": "#/$defs/identifier" },
+        "position": { "$ref": "#/$defs/canvasPosition" },
+        "locked": { "type": "boolean" }
+      },
+      "required": ["id", "field", "position"],
+      "additionalProperties": false
+    }
+  },
+  "properties": {
+    "contractVersion": { "const": 1 },
+    "id": {
+      "description": "Dot-namespaced form id, e.g. hr.employee-lookup.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+    },
+    "version": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$" },
+    "publisher": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "fields": { "type": "array", "items": { "$ref": "#/$defs/fieldSpec" } },
+    "sections": { "type": "array", "items": { "$ref": "#/$defs/sectionSpec" } },
+    "tabs": { "type": "array", "items": { "$ref": "#/$defs/tabSpec" } },
+    "layout": {
+      "type": "object",
+      "properties": { "order": { "type": "array", "items": { "$ref": "#/$defs/identifier" } } },
+      "required": ["order"],
+      "additionalProperties": false
+    },
+    "canvas": { "type": "array", "items": { "$ref": "#/$defs/canvasPlacement" } },
+    "validations": { "type": "array", "items": { "$ref": "#/$defs/validationSpec" } },
+    "rules": { "type": "array", "items": { "$ref": "#/$defs/ruleBindingSpec" } },
+    "events": { "type": "array", "items": { "$ref": "#/$defs/formEventBinding" } },
+    "permissions": { "$ref": "#/$defs/permissionSurface" },
+    "designer": {
+      "type": "object",
+      "properties": {
+        "displayNameKey": { "$ref": "#/$defs/i18nKey" },
+        "descriptionKey": { "$ref": "#/$defs/i18nKey" },
+        "icon": { "type": "string", "minLength": 1, "maxLength": 64 },
+        "propertyGroups": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": { "id": { "$ref": "#/$defs/identifier" }, "titleKey": { "$ref": "#/$defs/i18nKey" } },
+            "required": ["id", "titleKey"],
+            "additionalProperties": false
+          }
+        },
+        "preview": {
+          "type": "object",
+          "properties": { "kind": { "const": "form" }, "sampleKey": { "$ref": "#/$defs/i18nKey" } },
+          "required": ["kind"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["displayNameKey", "descriptionKey", "icon", "propertyGroups", "preview"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["contractVersion", "id", "version", "publisher", "fields", "sections", "tabs", "layout", "validations", "rules", "events", "permissions", "designer"],
+  "additionalProperties": false
+}