@sparkerp/plugin-sdk 0.1.0

package/bundle/schemas/plugin-manifest.schema.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.internal/schema/spk-plugin-manifest.schema.json",
+  "title": "SpkPluginManifest",
+  "description": "The real, actual shape of a hot-loadable PF4J .spk business-application plugin's own spk-assembly/plugin.json — id/name/version/permissions/roles/dependencies, confirmed against every already-shipped module (hcm-performance, hcm-organization, hcm-learning, ~30 more). Added 2026-09-03 — the pre-existing 'plugin-manifest' schema-registry entry (frontend/packages/plugin-sdk/schema/plugin-manifest.schema.json, now separately registered as 'composite-pack-manifest') is a genuinely DIFFERENT, newer contract (contractVersion/publisher/distribution/12 extension-point 'contributions') for a different artifact type (a composite pack / Country-or-Industry-Pack / Code-Plugin-style TS manifest) — validating any real shipped .spk plugin.json against it always FAILed (confirmed live against hcm-performance's own plugin.json, found while building hcm-learning's Course Catalog batch), even though erp_list_schemas' own 'plugin-manifest' description ('plugin.json's own manifest contract (id/version/permissions/roles/dependencies)') describes THIS shape, not that one. This schema is the fix: 'plugin-manifest' now points here.",
+  "type": "object",
+  "required": ["id", "name", "version"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "name": { "type": "string" },
+    "version": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$" },
+    "type": { "type": "string" },
+    "vendor": { "type": "string" },
+    "license": { "type": "string" },
+    "licenseTier": { "type": "string" },
+    "category": { "type": "string" },
+    "erpVersion": { "type": "string" },
+    "minErpVersion": { "type": "string" },
+    "maxErpVersion": { "type": "string" },
+    "mainClass": { "type": ["string", "null"], "description": "Fully-qualified PF4J plugin main class. Optional (null/absent) for a pure-JSON plugin that ships zero Java classes -- the platform loads it via the built-in JsonOnlyPlugin entry point." },
+    "schemaName": { "type": "string", "description": "App-owned Postgres schema this plugin's Entity-Engine tables route to — see feedback-entity-engine-tables-must-route-to-app-schema." },
+    "scope": { "type": "string", "enum": ["global", "tenant"], "default": "global", "description": "Tenant-Safe Plugin & Extension Architecture spec §54. 'global' (default, every manifest that predates this field): a shared plugin installable by any tenant. 'tenant': a private single-tenant L5 extension — MUST also set tenantId, and if it carries Java code (mainClass, or type java-extension/code-plugin) it MUST declare runtimeModes: ['service'] — the shared runtime refuses to load it (ExtensionInstallValidator, spec §11/§28.10/§74)." },
+    "tenantId": { "type": "string", "description": "Spec §54 — the owning tenant of a scope:'tenant' plugin. Required iff scope=='tenant'; must match the tenant the plugin is installed into. Absent for a global plugin." },
+    "erpApiVersion": { "type": "string", "description": "Spec §25 — the ERP extension-API contract version this plugin targets (e.g. '5.0'), distinct from erpVersion/minErpVersion (platform build versions). Optional; informational in E1." },
+    "supportedApplications": { "type": "array", "items": { "type": "string" }, "description": "Spec §25 — applications this extension supports, e.g. ['HCM']. Optional; empty/absent means unconstrained." },
+    "dependencies": { "type": "array", "items": { "type": "string" } },
+    "optionalDependencies": { "type": "array", "items": { "type": "string" } },
+    "permissions": { "type": "array", "items": { "type": "string" }, "description": "Legacy flat permission-key catalogue; real installs read roles[].permissionKeys instead (PluginRoleInstaller) — commonly left empty on modules whose roles[] is populated." },
+    "owner": { "type": "string" },
+    "editable": { "type": "boolean" },
+    "extendable": { "type": "boolean" },
+    "capabilitiesProvided": { "type": "array", "items": { "type": "string" } },
+    "capabilitiesRequired": { "type": "array", "items": { "type": "string" } },
+    "featureFlags": { "type": "array", "items": { "type": "string" } },
+    "configSchemaJson": { "type": ["object", "string", "null"] },
+    "frontendBundle": {
+      "type": "object",
+      "description": "Optional — dynamic frontend-plugin-loading (ai/patterns/code-plugin-sdk.md). Absent on every plugin.json that predates it.",
+      "required": ["fileId"],
+      "properties": {
+        "fileId": { "type": "string" },
+        "entrypointExport": { "type": "string" }
+      }
+    },
+    "roles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "code", "permissionKeys"],
+        "properties": {
+          "name": { "type": "string" },
+          "code": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" },
+          "description": { "type": "string" },
+          "permissionKeys": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "runtimeModes": {
+      "type": "array",
+      "items": { "type": "string", "enum": ["embedded", "service"] },
+      "description": "Added 2026-09-03 (real gap — this field is genuinely load-bearing on every shipped plugin.json today, e.g. hcm-learning's own [\"embedded\"], but was entirely absent from this schema until now, so erp_get_schema/erp schema pull misrepresented the real manifest shape). Which Plugin Runtime modes this plugin can run under: 'embedded' (loaded in-process via PF4J, the only behavior every pre-existing manifest declares) and/or 'service' (its own standalone Spring Boot process, routed to over HTTP — see PluginManifest#runtimeModes' own Javadoc in engine-plugin-api). Defaults to ['embedded'] when absent. Declaring 'service' here does not itself switch anything — the actual mode is chosen per-plugin via Studio's Plugin Runtime toggle (erp_core.application.deployment_type)."
+    },
+    "serviceRuntime": {
+      "type": ["string", "null"],
+      "enum": ["java", "python", "nodejs", null],
+      "description": "Added 2026-09-14 (Polyglot Plugin Runtime initiative, PluginManifest#serviceRuntime's own Javadoc in engine-plugin-api). Which language a Service-mode plugin's own process is implemented in. Only meaningful when runtimeModes contains 'service' — an embedded-only plugin is always Java (nothing else can load into the JVM), and installing a manifest that sets this to 'python'/'nodejs' without declaring 'service' in runtimeModes fails install (PluginCodeLifecycle#validateServiceRuntime). null/absent defaults to 'java' — every manifest that predates this field keeps its exact current behavior. Real, proven implementations exist for all three values: hello-plugin-service (java), hello-plugin-service-python (python), hello-plugin-service-node (nodejs) — see 'Build a Service-mode plugin in Python or Node.js' for the SDK and full build/deploy path for each."
+    },
+    "serviceFramework": {
+      "type": ["string", "null"],
+      "enum": ["spring-boot", "fastapi", "express", null],
+      "description": "Added 2026-09-14, same initiative as serviceRuntime — purely informational (shown as a read-only chip in Studio's Plugin Runtime panel; not validated against serviceRuntime today, so keep them consistent yourself: spring-boot pairs with java, fastapi with python, express with nodejs). null/absent defaults to 'spring-boot'."
+    },
+    "serviceDeployment": {
+      "type": ["object", "null"],
+      "description": "Added 2026-09-03 (same real-gap fix as runtimeModes). Recommended deployment/runtime defaults for this plugin when run in 'service' mode (PluginManifest.PluginServiceDeploymentSpec in engine-plugin-api). null (the default for almost every manifest) means Studio seeds an empty config the admin fills in the first time they switch this plugin to Service mode. Only healthPath/timeoutMs/heartbeatIntervalSeconds actually drive runtime behavior today (health checks, proxy call timeout) — docker/kubernetes/cloud are real, persisted, Studio-editable data for a future Deployment Manager, not wired to any live provisioning API.",
+      "properties": {
+        "process": {
+          "type": ["object", "null"],
+          "description": "Local/Windows-process deployment — the mode this platform actually runs and tests today.",
+          "properties": {
+            "port": { "type": ["integer", "null"] },
+            "startupCommand": { "type": ["string", "null"] },
+            "workingDirectory": { "type": ["string", "null"] },
+            "env": { "type": ["object", "null"], "additionalProperties": { "type": "string" } }
+          }
+        },
+        "docker": {
+          "type": ["object", "null"],
+          "description": "Container image parameters — real data, not acted on by this codebase (no Docker Engine API calls).",
+          "properties": {
+            "image": { "type": ["string", "null"] },
+            "containerPort": { "type": ["integer", "null"] },
+            "env": { "type": ["object", "null"], "additionalProperties": { "type": "string" } },
+            "resources": { "$ref": "#/definitions/resourceLimits" }
+          }
+        },
+        "kubernetes": {
+          "type": ["object", "null"],
+          "description": "Kubernetes Deployment/Service parameters — real data, not acted on by this codebase (no Kubernetes API calls; manifests under deploy/kubernetes/ are applied by hand via kubectl).",
+          "properties": {
+            "namespace": { "type": ["string", "null"] },
+            "replicas": { "type": ["integer", "null"] },
+            "serviceName": { "type": ["string", "null"] },
+            "image": { "type": ["string", "null"] },
+            "imagePullPolicy": { "type": ["string", "null"] },
+            "resources": { "$ref": "#/definitions/resourceLimits" },
+            "livenessProbePath": { "type": ["string", "null"] },
+            "readinessProbePath": { "type": ["string", "null"] },
+            "env": { "type": ["object", "null"], "additionalProperties": { "type": "string" } },
+            "secretRefs": { "type": ["array", "null"], "items": { "type": "string" } }
+          }
+        },
+        "cloud": {
+          "type": ["object", "null"],
+          "description": "Informational only — which cloud (if any) this deployment targets, and its region. Not read by any provisioning code in this codebase.",
+          "properties": {
+            "provider": { "type": ["string", "null"] },
+            "region": { "type": ["string", "null"] }
+          }
+        },
+        "healthPath": { "type": ["string", "null"], "description": "Path (relative to service_url) this plugin's health check calls. Defaults to '/actuator/health' when absent." },
+        "timeoutMs": { "type": ["integer", "null"], "description": "Outbound proxy call timeout in milliseconds. Defaults to 5000 when absent." },
+        "heartbeatIntervalSeconds": { "type": ["integer", "null"], "description": "Expected self-registration heartbeat cadence, used only to size ApplicationServiceRegistry's staleness TTL (3x this value). Defaults to 10 when absent." }
+      }
+    }
+  },
+  "definitions": {
+    "resourceLimits": {
+      "type": ["object", "null"],
+      "description": "CPU/memory requests+limits, Kubernetes resource-quantity string convention (e.g. '500m', '512Mi').",
+      "properties": {
+        "requestsCpu": { "type": ["string", "null"] },
+        "requestsMemory": { "type": ["string", "null"] },
+        "limitsCpu": { "type": ["string", "null"] },
+        "limitsMemory": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/bundle/schemas/plugin-seed-data.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.platform/schema/plugin-seed-data.schema.json",
+  "title": "Plugin install-lifecycle seed-data file (metadata/seed-data/*.json)",
+  "description": "Declares Entity-Engine data rows a plugin seeds on install/upgrade/auto-provision, idempotently (upsert by keyFields), for the installing tenant. Applied by PluginDataSeedInstaller. Generalizes plugin.json roles[] to arbitrary entity data - notably the shared platform config entities entity_status_date_sweep_config / entity_aggregation_config / entity_cadence_config / workflow_reminder_config. See ai/patterns/plugin-install-data-seeding.md.",
+  "type": "object",
+  "required": ["entity", "keyFields", "rows"],
+  "additionalProperties": false,
+  "properties": {
+    "entity": { "type": "string", "description": "Entity Engine entity name the rows belong to. Must already exist (ship it in metadata/entities/ if the plugin owns it)." },
+    "keyFields": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "The natural-key fields that uniquely identify a row. On re-install, a row matching all keyFields is updated (only if a non-key value changed); otherwise inserted. Never produces duplicates."
+    },
+    "source": { "type": "string", "description": "The plugin id. Stamped into a seeded_by field when the entity has one." },
+    "rows": {
+      "type": "array",
+      "items": { "type": "object" },
+      "description": "The rows to upsert. Each is a plain field map for the entity - no tenant id (the installer supplies it)."
+    }
+  }
+}

package/bundle/schemas/print-template-definition.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.internal/schema/print-template-definition.schema.json",
+  "title": "PrintTemplateDefinitionArtifact",
+  "$comment": "CLOSED 2026-09-03 (mcp-12), same as report-definition.schema.json: a real Print Template is now shipped — backend/modules/hcm-organization/spk-assembly/metadata/print_template/organization-tag-label.json, a minimal single-entity Badge-sized label (name/code/QR-code) over the real `organization_tag` entity. Installed live via the same hcm-organization plugin upgrade (1.0.91->1.0.92) that shipped the sibling Report above — confirmed via `GET /api/v1/authoring/print-templates` returning a real, owned, published row (id 1), and via a real authenticated Playwright session opening Studio's Print Template Designer (Data source/Fields correctly resolved, category 'Labels', zero Problems) and its own live Preview tab (real band rendering: bold name, code caption, an actually-rendered QR code image, real Export PDF/Word/Excel buttons present). `erp schema validate` passes against this real file. Derived directly from frontend/packages/print-engine/src/types.ts's PrintTemplateDefinition/PrintBand/PrintElement (imports ReportBandKind/ReportGroupLevel/ReportSortLevel from @erp/report-engine, respected here via $ref). The synthetic print-template-definition.example.json in this same directory is kept as a secondary fixture.",
+  "description": "Print Template Designer's content model — Report's band/element sibling, diverging in three ways: a physical mm-based page, data binding up to one level of parent+children, and free-form merge-tag prose text. Element `content.kind` is a large discriminated union (see the TS source); this schema constrains the common/required fields and leaves `properties`/kind-specific fields as an open object rather than re-deriving all ~10 content kinds field-by-field.",
+  "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": ["contractVersion", "templateCategory", "page", "bands"],
+      "properties": {
+        "contractVersion": { "type": "number", "enum": [1] },
+        "templateCategory": {
+          "type": "string",
+          "enum": ["Payslip", "Invoice", "Tax Invoice", "Purchase Order", "Sales Order", "Quotation", "Delivery Challan", "Goods Receipt Note", "Purchase Requisition", "Expense Voucher", "Payment Voucher", "Receipt", "Credit Note", "Debit Note", "Employee ID Card", "Visitor ID Card", "Offer Letter", "Appointment Letter", "Confirmation Letter", "Promotion Letter", "Transfer Letter", "Experience Letter", "Relieving Letter", "Salary Revision Letter", "Warning Letter", "Termination Letter", "Employment Contract", "Joining Kit", "Leave Approval Letter", "Attendance Certificate", "Training Certificate", "Performance Letter", "Asset Handover Form", "Exit Clearance Form", "Certificates", "Labels", "Barcode Labels", "QR Code Labels", "Custom Document"]
+        },
+        "dataSource": {
+          "type": ["object", "null"],
+          "properties": {
+            "kind": { "type": "string", "enum": ["entity", "entity-with-children"] },
+            "entityId": { "type": "number" },
+            "entityName": { "type": "string" },
+            "fields": { "type": "array", "items": { "type": "string" } },
+            "parent": { "type": "object" },
+            "children": { "type": "array" }
+          }
+        },
+        "page": {
+          "type": "object",
+          "required": ["sizePreset", "widthMm", "heightMm", "orientation", "marginsMm", "bleedMm"],
+          "properties": {
+            "sizePreset": { "type": "string", "enum": ["A4", "A5", "Letter", "Legal", "Thermal-58mm", "Thermal-80mm", "ID-Card", "Badge", "Custom"] },
+            "widthMm": { "type": "number" },
+            "heightMm": { "type": "number" },
+            "orientation": { "type": "string", "enum": ["portrait", "landscape"] },
+            "marginsMm": { "type": "object", "properties": { "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" } } },
+            "bleedMm": { "type": "object", "properties": { "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" } } }
+          }
+        },
+        "groupLevels": { "type": "array", "description": "ReportGroupLevel[] — same shape as report-definition.schema.json's groupLevels items." },
+        "sortLevels": { "type": "array", "description": "ReportSortLevel[] — same shape as report-definition.schema.json's sortLevels items." },
+        "bands": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "kind", "heightPx", "elements"],
+            "properties": {
+              "id": { "type": "string" },
+              "kind": { "type": "string", "enum": ["report-header", "report-footer", "page-header", "page-footer", "group-header", "group-footer", "detail"] },
+              "groupLevelId": { "type": "string" },
+              "name": { "type": "string" },
+              "heightPx": { "type": "number" },
+              "visible": { "type": "boolean" },
+              "elements": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["id", "position", "content"],
+                  "properties": {
+                    "id": { "type": "string" },
+                    "position": { "type": "object", "required": ["x", "y", "width", "height"] },
+                    "content": {
+                      "type": "object",
+                      "required": ["kind"],
+                      "properties": {
+                        "kind": { "type": "string", "enum": ["literal", "block", "field", "merge-text", "formula", "table", "repeating-section", "barcode"] }
+                      },
+                      "description": "Open per-kind fields (type/properties/fieldName/template/expression/columns/elements/format/valueTemplate/...) — see PrintElementContent's discriminated union in the TS source; not re-derived field-by-field here."
+                    },
+                    "locked": { "type": "boolean" },
+                    "style": { "type": "object" },
+                    "visibility": { "type": "object" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "variables": { "type": "array" },
+        "locale": { "type": "string", "description": "BCP-47 tag, e.g. \"ar\"/\"en\". Absent means \"en\"/LTR." }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.internal/schema/provider-definition.schema.json",
+  "title": "ProviderDefinitionArtifact",
+  "description": "The real on-disk authoring shape for a Data Provider JSON artifact (spk-assembly/metadata/provider/*.json), served by ProviderAuthoringController (backend/platform-runtime/engine-form) — a thin JsonArtifactAuthoringController subclass, same wrapper every artifact type of this family uses. `definition` matches frontend/apps/studio/src/ProviderDesigner.tsx's ProviderDefinitionForm exactly (confirmed against a live shipped file, crm-leads-provider.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": ["kind", "connectionRef", "basePath", "supports"],
+      "properties": {
+        "kind": { "type": "string", "enum": ["rest", "mock", "graphql", "offline", "ai", "connector"] },
+        "connectionRef": { "type": "string", "description": "\"self\" for this platform's own backend; otherwise a named external connection." },
+        "basePath": { "type": "string" },
+        "supports": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["search", "get", "create", "update", "patch", "delete", "export", "import", "bulkUpdate"] }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,96 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.internal/schema/report-definition.schema.json",
+  "title": "ReportDefinitionArtifact",
+  "$comment": "CLOSED 2026-09-03 (mcp-12): a real Report is now shipped — backend/modules/hcm-organization/spk-assembly/metadata/report/organization-tag-list.json, a minimal listing report over the real `organization_tag` Entity Engine entity (id 1). Installed live via `erp-organization`'s real plugin upgrade path (spark package + POST /api/v1/authoring/plugins/hcm-organization/upload, 1.0.91->1.0.92) — confirmed via `GET /api/v1/authoring/reports` returning a real, owned, published row (id 1, ownerPlugin hcm-organization), and via a real authenticated Playwright session opening Studio's Report Designer for it (Data source/Fields/Sort order all correctly resolved, zero Problems) and its own live Preview tab (real band rendering: title, column headers, 5 synthetic detail rows). `erp schema validate` passes against this real file. This schema is derived directly from frontend/packages/report-engine/src/types.ts's ReportDefinition/ReportBand/ReportElement and from ReportAuthoringController/BiReportAuthoringController's shared JsonArtifactAuthoringController wrapper convention — now validated against a genuinely real, installed artifact, not only the synthetic report-definition.example.json in this same directory (still kept as a secondary fixture).",
+  "description": "A report's band/element content model — bands are a vertical stack of fixed-height Report/Page Header/Footer, Group Header/Footer, and Detail sections that repeat once per data group/row.",
+  "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": ["contractVersion", "dataSource", "groupLevels", "sortLevels", "bands"],
+      "properties": {
+        "contractVersion": { "type": "number", "enum": [1] },
+        "dataSource": {
+          "type": ["object", "null"],
+          "properties": {
+            "kind": { "type": "string", "enum": ["entity"] },
+            "entityId": { "type": "number" },
+            "entityName": { "type": "string" },
+            "fields": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "groupLevels": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "field", "sortDirection"],
+            "properties": { "id": { "type": "string" }, "field": { "type": "string" }, "sortDirection": { "type": "string", "enum": ["asc", "desc"] } }
+          }
+        },
+        "sortLevels": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["field", "direction"],
+            "properties": { "field": { "type": "string" }, "direction": { "type": "string", "enum": ["asc", "desc"] } }
+          }
+        },
+        "bands": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "kind", "heightPx", "elements"],
+            "properties": {
+              "id": { "type": "string" },
+              "kind": { "type": "string", "enum": ["report-header", "report-footer", "page-header", "page-footer", "group-header", "group-footer", "detail"] },
+              "groupLevelId": { "type": "string", "description": "Required for group-header/group-footer bands." },
+              "name": { "type": "string" },
+              "heightPx": { "type": "number" },
+              "visible": { "type": "boolean" },
+              "elements": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["id", "position", "content"],
+                  "properties": {
+                    "id": { "type": "string" },
+                    "position": {
+                      "type": "object",
+                      "required": ["x", "y", "width", "height"],
+                      "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "zIndex": { "type": "number" } }
+                    },
+                    "content": {
+                      "type": "object",
+                      "required": ["kind"],
+                      "properties": {
+                        "kind": { "type": "string", "enum": ["literal", "block", "field"] },
+                        "type": { "type": "string", "enum": ["text", "image", "shape", "line", "page-number", "date"] },
+                        "properties": { "type": "object" },
+                        "blockType": { "type": "string" },
+                        "fieldName": { "type": "string" },
+                        "format": { "type": "string" }
+                      }
+                    },
+                    "locked": { "type": "boolean" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "pageSize": { "type": "string", "enum": ["A4", "Letter", "Legal"] },
+        "orientation": { "type": "string", "enum": ["portrait", "landscape"] },
+        "margins": {
+          "type": "object",
+          "properties": { "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" } }
+        }
+      }
+    }
+  }
+}

package/bundle/schemas/rule.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://erp-platform.dev/schema/rule-definition/v1",
+  "title": "Rule definition (contract version 1)",
+  "description": "The frozen canonical Rule JSON (Phase 3 W1-03, ADR 0008). A rule binds an event pattern to a Phase 2 action chain through the seven match dimensions and the enforced priority bands (1=Security, 5=Validation, 10=Business, 100=Notification). 'actions' entries are full Action definitions validated against the frozen Action schema (../../action-engine/schema/action-definition.schema.json); this schema constrains only their identity shape to keep the two artifacts independently versionable.",
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable marketplace-facing name (Phase 21 §4c)."
+    },
+    "description": { "type": "string" },
+    "event": {
+      "type": "string",
+      "pattern": "^([A-Za-z*][A-Za-z0-9_-]*|\\*\\*)(\\.([A-Za-z0-9_*-]+|\\*\\*))*$",
+      "description": "Dotted event-name pattern: '*' matches one segment, trailing '**' matches any remainder."
+    },
+    "priority": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "One of the band values 1/5/10/100 unless priorityOverride is true. Bands confer timing and veto rights (ADR 0008 §4): security(1) and validation(5) run synchronously pre-commit and can veto; business(10) sync; notification(100) async post-commit."
+    },
+    "priorityOverride": {
+      "type": "boolean",
+      "description": "Explicit opt-out of the band constraint. Deliberate, visible, audited."
+    },
+    "enabled": { "type": "boolean", "default": true },
+    "scope": {
+      "type": "object",
+      "description": "Match dimensions beyond event name and tenant. Unset means any.",
+      "properties": {
+        "block": { "type": "string" },
+        "form": { "type": "string" },
+        "page": { "type": "string" },
+        "workflow": { "type": "string" },
+        "role": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "watchedFields": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Fire only when one of these data fields changed between data.old and data.new (ADR 0008 §2). Fires when old/new are absent (creation)."
+    },
+    "condition": {
+      "type": "string",
+      "description": "Phase 1 expression over ${event.*} plus the ambient scopes. Boolean true fires; false/Null skips; non-Boolean/unresolvable is a distinct observable skip."
+    },
+    "suppressSelfTrigger": {
+      "type": "boolean",
+      "description": "Don't re-fire from events this rule's own actions caused (ADR 0008 §5)."
+    },
+    "actions": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Phase 2 action chain(s), executed by the Action Engine with its frozen retry/timeout/error semantics.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "type": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$" },
+          "name": { "type": "string", "minLength": 1 }
+        },
+        "required": ["id", "type", "name"]
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Marketplace-publishable shape (Phase 21 §4c): version required at publish time.",
+      "properties": {
+        "version": { "type": "string" },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "author": { "type": "string" },
+        "publisher": { "type": "string" }
+      }
+    }
+  },
+  "required": ["id", "name", "event", "priority", "actions"],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://erp.internal/schema/workflow-definition.schema.json",
+  "title": "WorkflowDefinitionArtifact",
+  "description": "The REAL on-disk authoring shape for a workflow-definition JSON artifact (spk-assembly/metadata/workflow/*.json) — confirmed 2026-09-02 against live shipped files (crm-leads' lead.merge.json, hcm-employee's employee.transfer.json), not derived from the WorkflowDefinition Java record's field names alone. The Java record's own *Json columns (stagesJson/tasksJson/transitionsJson/approversJson/slasJson/escalationsJson/notificationsJson/metadataJson) are each persisted as a raw JSON string — so the artifact authors them as JSON-encoded STRINGS, not nested objects, except approvalPermissions which is a real top-level array. This schema types each *Json property as a string (its own inner shape is documented in the nested $comment/examples below since JSON Schema can't directly constrain 'this string, when parsed, matches...'). See ai/workflows/README.md's 'Domain module integration recipe'.",
+  "type": "object",
+  "required": ["name", "stagesJson", "tasksJson", "transitionsJson"],
+  "properties": {
+    "name": { "type": "string", "description": "Unique per tenant; a domain module's REST layer starts instances by this exact name, e.g. \"employee.transfer\"." },
+    "description": { "type": "string" },
+    "stagesJson": {
+      "type": "string",
+      "$comment": "Parses to a string[] of ordered stage codes, e.g. [\"manager\",\"hr\",\"finance\",\"it\"]. A single-actor self-decide flow uses [\"only\"]. Example literal value: \"[\\\"manager\\\",\\\"hr\\\"]\""
+    },
+    "tasksJson": {
+      "type": "string",
+      "$comment": "Parses to an array of {taskKey, stage, taskType, kind, payload:{approvalObject, amount, dueInSeconds}}. taskType/kind are typically \"approval\"/\"human\". approvalObject is the string approvalPermissions entries reference."
+    },
+    "transitionsJson": {
+      "type": "string",
+      "$comment": "Parses to an array of {fromStage, toStage, condition}. condition is a composable {all:[...]}/{any:[...]}/{not:...} tree or a single {field, op, value} leaf, evaluated against the instance's context (which always includes \"decision\": \"approved\"|\"rejected\" from the just-decided stage, plus whatever extraContext the submitter supplied at startInstance). A stage with no matching outgoing transition completes the instance. Example: \"[{\\\"fromStage\\\":\\\"manager\\\",\\\"toStage\\\":\\\"hr\\\",\\\"condition\\\":{\\\"field\\\":\\\"decision\\\",\\\"op\\\":\\\"eq\\\",\\\"value\\\":\\\"approved\\\"}}]\""
+    },
+    "approversJson": { "type": "string", "default": "{}", "$comment": "Legacy/reserved — real shipped workflows leave this \"{}\" and use the top-level approvalPermissions array instead." },
+    "slasJson": { "type": "string", "default": "[]" },
+    "escalationsJson": { "type": "string", "default": "[]" },
+    "notificationsJson": { "type": "string", "default": "[]" },
+    "metadataJson": { "type": "string", "default": "{}" },
+    "approvalPermissions": {
+      "type": "array",
+      "description": "Which role (by its stable role.code, never a mutable display name) may decide which named approvalObject task.",
+      "items": {
+        "type": "object",
+        "required": ["roleCode", "approvalObject"],
+        "properties": {
+          "roleCode": { "type": "string" },
+          "approvalObject": { "type": "string", "description": "Matches a tasksJson entry's payload.approvalObject." },
+          "maxAmount": { "type": ["number", "null"], "description": "Optional approval-limit gate; null for a plain non-amount-gated approval." }
+        }
+      }
+    }
+  }
+}