@sparkerp/plugin-sdk 0.1.0

package/bundle/examples/backend/modules/hcm-employee/spk-assembly/metadata/workflow/employee.movement.json

@@ -0,0 +1,44 @@
+{
+  "name": "employee.movement",
+  "description": "Four-stage approval (Manager -> HR -> conditional Finance -> conditional Executive) for an Employee Internal Movement. Finance is only visited when the movement actually changes cost center or business unit (costCenterChanged||businessUnitChanged, computed server-side in MovementService.submit() from which hcm_employee_movement_detail rows exist). Executive is only visited when the movement is high-impact (highImpact = movement_type='composite' with 3+ changed attributes in this v1 — a destination-position-grade-jump variant is deferred, Movement has no position/grade concept the way Promotion does). All three booleans (costCenterChanged/businessUnitChanged/highImpact) are ALWAYS supplied explicitly (never omitted) via extraContext at startInstance time so the condition evaluator never has to treat a missing field as false. hr can go straight to executive (skipping finance) when highImpact is true but neither cost center nor business unit changed; when both are true, the movement visits hr -> finance -> executive in sequence. Empty-match at any stage completes the instance, same rule proven by employee.transfer.json/employee.promotion.json.",
+  "stagesJson": "[\"manager\", \"hr\", \"finance\", \"executive\"]",
+  "tasksJson": "[{\"taskKey\": \"manager-approve\", \"stage\": \"manager\", \"taskType\": \"approval\", \"kind\": \"human\", \"payload\": {\"approvalObject\": \"employee.movement.manager\", \"amount\": 0, \"dueInSeconds\": 259200}}, {\"taskKey\": \"hr-approve\", \"stage\": \"hr\", \"taskType\": \"approval\", \"kind\": \"human\", \"payload\": {\"approvalObject\": \"employee.movement.hr\", \"amount\": 0, \"dueInSeconds\": 259200}}, {\"taskKey\": \"finance-approve\", \"stage\": \"finance\", \"taskType\": \"approval\", \"kind\": \"human\", \"payload\": {\"approvalObject\": \"employee.movement.finance\", \"amount\": 0, \"dueInSeconds\": 259200}}, {\"taskKey\": \"executive-approve\", \"stage\": \"executive\", \"taskType\": \"approval\", \"kind\": \"human\", \"payload\": {\"approvalObject\": \"employee.movement.executive\", \"amount\": 0, \"dueInSeconds\": 259200}}]",
+  "transitionsJson": "[{\"fromStage\": \"manager\", \"toStage\": \"hr\", \"condition\": {\"field\": \"decision\", \"op\": \"eq\", \"value\": \"approved\"}}, {\"fromStage\": \"hr\", \"toStage\": \"finance\", \"condition\": {\"any\": [{\"field\": \"costCenterChanged\", \"op\": \"eq\", \"value\": true}, {\"field\": \"businessUnitChanged\", \"op\": \"eq\", \"value\": true}]}}, {\"fromStage\": \"hr\", \"toStage\": \"executive\", \"condition\": {\"all\": [{\"field\": \"costCenterChanged\", \"op\": \"eq\", \"value\": false}, {\"field\": \"businessUnitChanged\", \"op\": \"eq\", \"value\": false}, {\"field\": \"highImpact\", \"op\": \"eq\", \"value\": true}]}}, {\"fromStage\": \"finance\", \"toStage\": \"executive\", \"condition\": {\"field\": \"highImpact\", \"op\": \"eq\", \"value\": true}}]",
+  "approversJson": "{}",
+  "slasJson": "[]",
+  "escalationsJson": "[]",
+  "notificationsJson": "[]",
+  "metadataJson": "{}",
+  "approvalPermissions": [
+    {
+      "roleCode": "HR_MANAGER",
+      "approvalObject": "employee.movement.manager",
+      "maxAmount": null
+    },
+    {
+      "roleCode": "HR_ADMINISTRATOR",
+      "approvalObject": "employee.movement.manager",
+      "maxAmount": null
+    },
+    {
+      "roleCode": "HR_MANAGER",
+      "approvalObject": "employee.movement.hr",
+      "maxAmount": null
+    },
+    {
+      "roleCode": "HR_ADMINISTRATOR",
+      "approvalObject": "employee.movement.hr",
+      "maxAmount": null
+    },
+    {
+      "roleCode": "HR_ADMINISTRATOR",
+      "approvalObject": "employee.movement.finance",
+      "maxAmount": null
+    },
+    {
+      "roleCode": "HR_ADMINISTRATOR",
+      "approvalObject": "employee.movement.executive",
+      "maxAmount": null
+    }
+  ]
+}

package/bundle/examples/backend/modules/hcm-employee/spk-assembly/metadata/workflow/employee.promotion-acknowledge.json

@@ -0,0 +1,19 @@
+{
+  "name": "employee.promotion-acknowledge",
+  "description": "Single-approval (self-decide) - Employee Acknowledges Promotion Letter. Same self-decide pattern as prejoining.mark-ready/joining.complete: the same actor (the promoted employee) who is being asked to acknowledge is the one whose EMPLOYEE role grants the decide permission - PromotionRestContribution's POST /{id}/acknowledge calls changeRequests.submit(...) then immediately decideHumanTask(...) in the same request.",
+  "stagesJson": "[\"only\"]",
+  "tasksJson": "[{\"taskKey\": \"approve\", \"stage\": \"only\", \"taskType\": \"approval\", \"kind\": \"human\", \"payload\": {\"approvalObject\": \"employee.promotion-acknowledge\", \"amount\": 0, \"dueInSeconds\": 259200}}]",
+  "transitionsJson": "[]",
+  "approversJson": "{}",
+  "slasJson": "[]",
+  "escalationsJson": "[]",
+  "notificationsJson": "[]",
+  "metadataJson": "{}",
+  "approvalPermissions": [
+    {
+      "roleCode": "EMPLOYEE",
+      "approvalObject": "employee.promotion-acknowledge",
+      "maxAmount": null
+    }
+  ]
+}

package/bundle/examples/backend/modules/hcm-employee/spk-assembly/metadata/workflow/employee.resignation.json

@@ -0,0 +1,29 @@
+{
+  "name": "employee.resignation",
+  "description": "Two-stage approval (Manager -> HR) for an Employee Resignation. manager->hr is unconditional (decision approved) - Resignation doesn't have Transfer/Promotion/Movement's finance/IT/executive branching triggers; the spec's own optional Department Head stage is folded into the HR stage (disclosed trim, no distinct Dept-Head role/data exists in this plugin to gate a 3rd stage on). Empty-match at hr completes the instance, same rule proven by employee.transfer.json/employee.movement.json. Send Back reuses the exact same REST-layer convention already built and proven for Movement (sent_back status + POST /{id}/resubmit, not a 3rd engine decision value) - not a real 3-way engine decision.",
+  "stagesJson": "[\"manager\", \"hr\"]",
+  "tasksJson": "[{\"taskKey\": \"manager-approve\", \"stage\": \"manager\", \"taskType\": \"approval\", \"kind\": \"human\", \"payload\": {\"approvalObject\": \"employee.resignation.manager\", \"amount\": 0, \"dueInSeconds\": 259200}}, {\"taskKey\": \"hr-approve\", \"stage\": \"hr\", \"taskType\": \"approval\", \"kind\": \"human\", \"payload\": {\"approvalObject\": \"employee.resignation.hr\", \"amount\": 0, \"dueInSeconds\": 259200}}]",
+  "transitionsJson": "[{\"fromStage\": \"manager\", \"toStage\": \"hr\", \"condition\": {\"field\": \"decision\", \"op\": \"eq\", \"value\": \"approved\"}}]",
+  "approversJson": "{}",
+  "slasJson": "[]",
+  "escalationsJson": "[]",
+  "notificationsJson": "[]",
+  "metadataJson": "{}",
+  "approvalPermissions": [
+    {
+      "roleCode": "HR_MANAGER",
+      "approvalObject": "employee.resignation.manager",
+      "maxAmount": null
+    },
+    {
+      "roleCode": "HR_ADMINISTRATOR",
+      "approvalObject": "employee.resignation.manager",
+      "maxAmount": null
+    },
+    {
+      "roleCode": "HR_ADMINISTRATOR",
+      "approvalObject": "employee.resignation.hr",
+      "maxAmount": null
+    }
+  ]
+}

package/bundle/examples/example-patterns.mjs

@@ -0,0 +1,94 @@
+/**
+ * The curated, named-SHAPE example catalog shared by `erp examples patterns`
+ * (tools/erp-cli/erp.mjs) and the MCP server's `erp_examples_patterns` tool
+ * (tools/erp-mcp-server/index.mjs) — a single source of truth so a developer
+ * driving purely through the CLI and one driving purely through an MCP
+ * client see the identical catalog, never two copies that can drift. Pure
+ * data, no side effects, safe to import from either entrypoint (unlike
+ * importing erp.mjs itself, which runs its own CLI main() at import time).
+ */
+export const EXAMPLE_PATTERNS = {
+  workflow: [
+    {
+      name: "single-stage-self-decide",
+      description: "One actor both requests and immediately decides — models what would otherwise be a bare permission-gated direct action as a real, auditable, later-upgradable workflow instance. stagesJson: [\"only\"], transitionsJson: [] (no transitions needed, the one task's own decision ends the instance), approvalPermissions has exactly the role(s) that would have held the old direct-action permission. Caller: submit() then immediately decideHumanTask() in the same request.",
+      file: "backend/modules/hcm-employee/spk-assembly/metadata/workflow/employee.promotion-acknowledge.json",
+    },
+    {
+      name: "multi-stage-linear",
+      description: "A fixed sequence of real approvers, no branching. stagesJson: [\"manager\", \"hr\"], one transition (manager->hr) gated on {field:\"decision\",op:\"eq\",value:\"approved\"}, no transition out of the last stage — reaching it with no match completes the instance.",
+      file: "backend/modules/hcm-employee/spk-assembly/metadata/workflow/employee.resignation.json",
+    },
+    {
+      name: "multi-stage-conditional-branching",
+      description: "Stage routing depends on server-computed booleans passed via extraContext at startInstance (never omitted, so the condition evaluator never treats a missing field as false). transitionsJson conditions use {field,op,value} or {any:[...]}/{all:[...]} composition; a stage can be skipped entirely (hr->finance only if costCenterChanged||businessUnitChanged; hr->executive directly if neither changed but highImpact did). Empty-match at any stage completes the instance.",
+      file: "backend/modules/hcm-employee/spk-assembly/metadata/workflow/employee.movement.json",
+    },
+  ],
+  page: [
+    {
+      name: "related-record-lookup-field",
+      description: "2026-09-03, real gap found and fixed (a module built entirely by AI agents shipped every foreign-key field — employee_id, course_id, provider_id, etc. — as a bare text/number input the user had to type a raw numeric id into, module-wide, because this pattern was undiscoverable). ANY page field whose value is another entity's id must be a `core.lookup` block (or `core.select`/`core.autocomplete` for a small, static or already-loaded option set), never a plain text/number input. `core.lookup`'s properties: `value` (binding to the field), `recordType` (documentation-only label, e.g. \"Employee\"), `optionsSourceKey` (the REAL routing key — the `name` of a published Data Service artifact, spk-assembly/metadata/data_service/*.json, that this lookup calls server-side with a `search` parameter and expects back `{value,label}` rows). `committed` event fires with `event.new` = the picked record's id. If the target entity doesn't already have a search-shaped Data Service, author one first (`erp examples search employee-search --kind data-service` and `--kind data-view` show the real recipe: a `dataView` source + a `contains` filter on `${param.search}` + one required `search` parameter) — never skip straight to a text input because no Data Service exists yet.",
+      file: "backend/modules/hcm-employee/spk-assembly/metadata/page/promotions.json",
+    },
+    {
+      name: "resolved-reference-grid-column",
+      description: "2026-09-03, real gap found and fixed (a JSON-first module's grids showed a raw FK id — employee_id — in a `core.grid` column even though the SAME page's create dialog already used `core.lookup` for that field; the grid has no field-level lookup concept, only a `name`/`type`/`headerKey`/`renderAs` column spec). Do NOT bind a grid column or a detail-view value to a raw *_id field — check the entity's own field metadata first (`erp schema pull entity-definition` -> `properties.fields.items.properties.flags`'s own description covers this) for `flags.reference.entityType`; if present, GET .../records/query and GET .../records/{id} already return a sibling `<fieldName>_label` key (e.g. `employee_id` -> `employee_id_label`) with zero extra code — bind the column/value to that key instead. If the field ISN'T marked yet: set `\"flags\":\"{\\\"reference\\\":{\\\"entityType\\\":\\\"Employee\\\"}}\"` on it via `PUT /api/v1/entities/{id}/fields/{fieldId}` (entityType must be a REGISTERED provider — \"Employee\" is the only one shipped today) and the `_label` key appears automatically on the next read, batched once per page load, never per row.",
+      file: "backend/modules/hcm-compensation/spk-assembly/metadata/page/salary-planning.json",
+    },
+  ],
+  jobs: [
+    {
+      name: "n-days-before-reminder-sweep",
+      description: "2026-09-10. A 'remind me N days before <date>' background job needs ZERO Java — it is one entity_status_date_sweep_config row (engine-entity.status-date-sweep) with `day_offset` set. e.g. {entity_name:'hcm_asset', when_status_in:'AVAILABLE,ASSIGNED,IN_USE', date_field:'warranty_expiry_date', compare_op:'lte', day_offset:30, set_field:'warranty_alert_30d', set_status_to:'true', active:true} fires when warranty_expiry_date <= now+30d. Use a distinct flag field per window (30d/14d/7d) so windows are independently queryable and the reminder never touches the lifecycle `status` enum. Ship the rows via metadata/seed-data/*.json so they travel with the plugin. Schema: `erp_get_schema entity-status-date-sweep-config`. Doc: ai/patterns/generic-entity-status-date-sweep.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-sweep-configs.json",
+    },
+    {
+      name: "cross-row-aggregation-into-summary-entity",
+      description: "2026-09-10. A 'reconcile/roll-up count or total across many rows and store the result' job = one entity_aggregation_config row (engine-entity.aggregation-sweep), no Java. e.g. count hcm_asset grouped by status into a summary entity: {sweep_code:'asset-inventory-reconciliation', source_entity:'hcm_asset', aggregation:'count', group_by_field:'status', target_entity:'hcm_asset_reconciliation', target_key_field:'metric_key', target_key_prefix:'asset_status:', target_value_field:'metric_value', target_timestamp_field:'last_reconciled_at', active:true}. aggregation is count|sum|avg|min|max (last four over agg_field). Use target_key_prefix so several configs can share one summary entity. Schema: `erp_get_schema entity-aggregation-config`. Doc: ai/patterns/generic-aggregation-and-cadence-jobs.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-aggregation-configs.json",
+    },
+    {
+      name: "scheduled-record-generation-cadence",
+      description: "2026-09-10. A 'create new records on a schedule' job = one entity_cadence_config row (engine-entity.cadence-generator), no Java. STANDALONE (one row per tick): {cadence_code:'asset-audit-schedule', target_entity:'hcm_asset_audit', interval_days:90, dedupe_target_field:'cadence_marker', template_json:{audit_number:'AUDIT-${date}-${ts}', audit_name:'Scheduled Audit ${date}', status:'DRAFT'}}. SOURCE-DRIVEN (one row per due source row): add source_entity + source_date_field + due_within_days + field_map_json + dedupe_target_field=<a column holding the source id>. template_json string values support ${date} ${ts} ${uuid} ${sourceId}. Schema: `erp_get_schema entity-cadence-config`.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-cadence-configs.json",
+    },
+    {
+      name: "condition-based-compliance-flagging",
+      description: "2026-09-10 (Batch 3). A 'detect rows that violate a policy/compliance condition and flag them, or escalate them' job = one entity_compliance_config row (engine-entity.compliance-sweep), no Java. It evaluates a rule-engine boolean expression (the SAME platform ExpressionEvaluator cross-field validation and Formula fields use — whitelisted funcs only: daysBetween, now, etc.; no ternary/`in`/`^`) against each source row, with the row's own fields + `now` + optional `related_count` in scope. FLAG outcome: {compliance_code:'asset-assignment-compliance', source_entity:'hcm_asset', when_status_in:'ASSIGNED,IN_USE', condition_expr:'custody_acknowledged != true', set_field:'compliance_flag', set_value:'NON_COMPLIANT', active:true} (idempotent — skipped when the field already equals set_value). RELATED-COUNT (cross-record, e.g. license over-allocation): add related_count_entity + related_count_key_field (FK back to source id) + related_count_status_in, then use `related_count` in condition_expr (e.g. 'related_count > entitlement_quantity'). ESCALATION outcome (raise a row in a separate entity, deduped by source id): set escalation_entity + escalation_dedupe_field + field_map_json + escalation_template_json instead of set_field. Ship via metadata/seed-data/*.json + an AFTER_CREATE {type:EXECUTE_SERVICE, service:ensureEntityComplianceSweepJobRegistered} rule on entity_compliance_config. Schema: `erp_get_schema entity-compliance-config`. Doc: ai/patterns/generic-compliance-sweep-job.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-compliance-configs.json",
+    },
+    {
+      name: "target-key-field-id-rollup",
+      description: "2026-09-10 (Batch 5+6). To roll child line-items UP onto their own parent record (the true MaintenanceCostSyncJob shape — write synced_cost onto hcm_asset_maintenance keyed by its OWN id, not into a summary entity), set target_key_field:'id' on an entity_aggregation_config row: {sweep_code:'maintenance-cost-rollup', source_entity:'hcm_asset_maintenance_cost', aggregation:'sum', agg_field:'total_cost', group_by_field:'maintenance_id', target_entity:'hcm_asset_maintenance', target_key_field:'id', target_value_field:'synced_cost', target_timestamp_field:'cost_synced_at', active:true}. The bucket key (from group_by_field) IS the parent row's primary key; the fold is written straight onto that row (never a create). Leave target_key_prefix blank. Schema: `erp_get_schema entity-aggregation-config`. Doc: ai/patterns/generic-aggregation-and-cadence-jobs.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-aggregation-configs.json",
+    },
+    {
+      name: "cross-plugin-offboarding-fanout",
+      description: "2026-09-10 (Batch 5+6). 'When an employee is separated, auto-create asset return requests / license reclamation rows for everything they hold' = one entity_cross_plugin_action_config row (engine-entity.cross-plugin-action), no Java, no cross-plugin HTTP. {action_code:'asset-separation-return', trigger_entity:'employee', trigger_status_field:'employment_status', trigger_status_in:'TERMINATED,SEPARATED', trigger_key_field:'id', related_entity:'hcm_asset_allocation', related_match_field:'employee_id', related_status_in:'ALLOCATED,ACKNOWLEDGED,IN_USE', create_entity:'hcm_asset_return', create_dedupe_field:'allocation_id' (MUST be a numeric/long column), create_template_json:{status:'REQUESTED', reason:'EMPLOYEE_SEPARATION'}, create_field_map_json:{asset_id:'asset_id', employee_id:'employee_id'}, related_set_field:'status', related_set_value:'RETURN_PENDING', active:true}. The trigger entity can be owned by any plugin. Idempotent via the dedupe field. Schema: `erp_get_schema entity-cross-plugin-action-config`. Doc: ai/patterns/generic-cross-plugin-action-job.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-cross-plugin-configs.json",
+    },
+    {
+      name: "per-row-document-artifact-generation",
+      description: "2026-09-10 (Batch 5+6). 'Generate an audit report / certificate document per completed record and stash the file' = one entity_document_generator_config row (engine-entity.document-generator), no Java. {document_code:'asset-audit-report', source_entity:'hcm_asset_audit', when_status_in:'COMPLETED', target_file_field:'report_file_ref_id' (a TEXT column — its non-blank state IS the dedupe marker), format:'json', cabinet_id:<a real DMS cabinet id>, child_entity:'hcm_asset_audit_item', child_match_field:'audit_id', file_name_template:'asset-audit-${id}-${date}.json', active:true}. LIMITATION: the platform print-template render path (engine-print-export PlaywrightPdfRenderer) only renders synthetic sample data via the Studio app — it can't be driven headless against a real record — so this job emits a structured-data artifact (json/csv), not a rendered PDF; template_ref is reserved for when real-record binding ships. Schema: `erp_get_schema entity-document-generator-config`. Doc: ai/patterns/generic-document-generator-job.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-document-configs.json",
+    },
+    {
+      name: "heuristic-predictive-maintenance",
+      description: "2026-09-10 (Batch 5). PredictiveMaintenanceJob with NO ML: there is no tabular AI-inference seam (engine-ai-provider is text-gen/embedding only), so predictive-maintenance risk is scored as a DETERMINISTIC HEURISTIC config of the existing generic primitives — an entity_aggregation_config counting recent maintenance events per asset (target_key_field:'id' onto hcm_asset.recent_maintenance_count) plus an entity_compliance_config flagging hcm_asset.maintenance_risk='HIGH' when condition_expr combines real signals already in the data (recent_maintenance_count >= 3, or age past X% of expected_life_months, or open_maintenance_count >= 2). A real model plugs in later via the AiModelProvider seam with an entity_prediction_config, config-shape-compatible. Doc: ai/patterns/generic-compliance-sweep-job.md + the Batch 5 note in hcm-assets IMPLEMENTATION-GAPS.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-predictive-configs.json",
+    },
+    {
+      name: "install-lifecycle-data-seeding",
+      description: "2026-09-10. To make Entity-Engine data rows (especially rows in the SHARED platform config entities entity_status_date_sweep_config / entity_aggregation_config / entity_cadence_config / workflow_reminder_config) travel with the .spk instead of a manual per-tenant POST: add metadata/seed-data/<name>.json = {entity, keyFields:[...natural key...], source:'<pluginId>', rows:[...]}. PluginDataSeedInstaller upserts these on every install/upgrade/auto-provision, idempotently by keyFields (matched row updated only if a value changed, else inserted — never duplicated). Also ship metadata/entities/*.json for any entity/column the rows need, and metadata/rules/*.json AFTER_CREATE {type:EXECUTE_SERVICE, service:ensure<Job>Registered} to auto-register the job on first row. Schema: `erp_get_schema plugin-seed-data`. Doc: ai/patterns/plugin-install-data-seeding.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-sweep-configs.json",
+    },
+  ],
+  entities: [
+    {
+      name: "reference-display-label-field",
+      description: "2026-09-03. Any entity field whose value is another entity's real record id (a `long`-typed FK, e.g. `employee_id`) should carry `\"flags\":\"{\\\"reference\\\":{\\\"entityType\\\":\\\"Employee\\\"}}\"` in its field definition — this is the ONE line that turns on automatic id->display-name resolution platform-wide, no Java, no hand-written join. Once set, both the generic grid query (`GET .../records/query`) and single-record read (`GET .../records/{id}`) automatically add a `\"<fieldName>_label\"` key to every row/record where the id resolves (batched: one resolve call per distinct reference-flagged field per page load, never per row) — see `resolved-reference-grid-column` under `--kind page` for the consuming side. `entityType` must be a REGISTERED provider (a plugin that exposes its own `batch-names` endpoint) — \"Employee\" (backed by hcm-employee) is the only one shipped today; an unregistered entityType just produces no `_label` key, never an error.",
+      file: "backend/modules/hcm-compensation/spk-assembly/metadata/entities/hcm_salary_planning_entry.json",
+    },
+  ],
+};

package/bundle/manifest.json

@@ -0,0 +1,14 @@
+{
+  "bundleVersion": "2026-09-14.1",
+  "platformVersion": "0.0.0",
+  "generatedAt": "2026-09-14T13:48:11.809Z",
+  "generatedBy": "erp bundle build (tools/erp-cli/erp.mjs bundleBuildCommand)",
+  "schemaCount": 27,
+  "docCount": 90,
+  "exampleFileCount": 14,
+  "blockCount": 124,
+  "catalogGeneratedAt": "2026-09-14T13:48:11.094Z",
+  "catalogEngineCount": 43,
+  "catalogContractUnitCount": 74,
+  "sdkMode": "packaged"
+}

package/bundle/schemas/action.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://erp-platform.dev/schemas/action-definition/v1",
+  "title": "Action Definition",
+  "description": "The frozen Phase 2 Action contract (contract version 1). Shared verbatim between the TypeScript Action Engine and the Java ActionHandler side; Phase 9's workflow tasks invoke definitions conforming to exactly this schema. Published definitions are immutable — changes create a new version (SAP clean-core rule). See low-code-docs/adr/0007-action-execution-semantics.md for the semantics decisions behind retry/error/async/idempotency fields.",
+  "$ref": "#/$defs/actionDefinition",
+  "$defs": {
+    "actionDefinition": {
+      "type": "object",
+      "required": ["id", "type", "name"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Unique identifier (stringified integer row id for persisted definitions — table ids are incremental integers; any unique string for inline chain children)."
+        },
+        "type": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$",
+          "description": "Action handler key resolved against the Action Registry (callApi, setValue, showField, validate, navigate, executePlugin, ...)."
+        },
+        "name": { "type": "string", "minLength": 1, "description": "Friendly display name." },
+        "description": { "type": "string" },
+        "enabled": { "type": "boolean", "default": true, "description": "Runtime enable/disable. A disabled action is skipped, not failed." },
+        "order": { "type": "integer", "default": 0, "description": "Execution sequence among siblings (ascending)." },
+        "timeout": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum execution time in milliseconds. On expiry the in-flight work is actually cancelled (AbortSignal), not orphaned, and the failure is classified retryable with code 'timeout'."
+        },
+        "retry": {
+          "description": "Retry policy (ADR 0007 §1). A bare integer n is legacy shorthand for { maxAttempts: n+1, strategy: 'fixed', intervalMs: 1000 }. Only errors classified retryable (timeout, network, HTTP 408/429/5xx) consume extra attempts — logical/validation failures are never retried.",
+          "oneOf": [{ "type": "integer", "minimum": 0 }, { "$ref": "#/$defs/retryPolicy" }]
+        },
+        "async": {
+          "type": "boolean",
+          "default": false,
+          "description": "ADR 0007 §5: an async action does not block its next sibling; its output is visible only to its own onSuccess/onFailure chains; the enclosing chain execution still awaits all async branches before reporting completion (structured concurrency)."
+        },
+        "condition": {
+          "type": "string",
+          "description": "Phase 1 expression evaluated against the resolved scope chain before execution; false or Null skips the action (skipped, not failed)."
+        },
+        "config": {
+          "type": "object",
+          "description": "Handler-specific configuration. String values support ${...} variable resolution — a PLAIN DOTTED PATH LOOKUP ONLY (e.g. ${page.foo}, ${api.bar.baz}) against the resolved scope chain (page/event/output-of-prior-action, referenced by its own `output` name). It does NOT support: arithmetic/operators (${page.count+1} resolves the literal string \"count+1\" as a variable name and faults with 'Unresolved variable' — found live authoring hcm-communications; to get a value that reliably changes between calls, reuse a field a preceding callApi step already recomputed, e.g. a just-refreshed KPI count, not an increment expression); a 'system' scope (${system.date}/${system.now} are NOT resolvable anywhere, in config OR input — same live fault; there is no current-server-time binding available to a page action chain today). A whole-value expression (config value is exactly \"${expr}\", nothing else) preserves the resolved value's real type (number/boolean/null); embedding it inside a longer string always stringifies. MUST NOT contain inline secrets — outbound calls reference a named tenant-scoped connection via connectionRef (ADR 0007 §3); publish-time validation rejects secret-shaped keys with literal values.",
+          "properties": {
+            "connectionRef": {
+              "type": "string",
+              "description": "Name of a tenant-scoped connection (URL + credentials) resolved at execution time. The reference is stored; the credential never is. Full connector configuration is Phase 17."
+            }
+          },
+          "additionalProperties": true
+        },
+        "input": { "type": "object", "description": "Runtime parameter mapping, ${...}-resolvable like config.", "additionalProperties": true },
+        "output": {
+          "type": "string",
+          "description": "Name under which the handler result is stored in the api scope — retrievable as ${api.<name>} (or bare ${<name>}) by subsequent chain steps."
+        },
+        "onSuccess": { "type": "array", "items": { "$ref": "#/$defs/actionDefinition" }, "description": "Child actions executed after success, ordered by 'order'." },
+        "onFailure": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/actionDefinition" },
+          "description": "Child actions executed after final failure (retries exhausted). The ${error.*} scope (message, code, actionId, attempt, retryable — ADR 0007 §2) is resolvable inside this chain."
+        },
+        "onError": { "$ref": "#/$defs/errorStrategy" },
+        "compensation": {
+          "$ref": "#/$defs/actionDefinition",
+          "description": "ADR 0007 §4: the compensating action executed when onError is 'compensate'. Required at publish time if onError is 'compensate'."
+        },
+        "metadata": {
+          "type": "object",
+          "properties": {
+            "version": { "type": "string", "description": "Semantic version of this definition (informational; the persistence layer's integer version is authoritative)." },
+            "tags": { "type": "array", "items": { "type": "string" } },
+            "createdBy": { "type": "string" }
+          },
+          "additionalProperties": true
+        }
+      }
+    },
+    "retryPolicy": {
+      "type": "object",
+      "required": ["maxAttempts"],
+      "additionalProperties": false,
+      "properties": {
+        "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Total attempts including the first. 1 = no retry." },
+        "strategy": { "type": "string", "enum": ["fixed", "exponential"], "default": "fixed" },
+        "intervalMs": { "type": "integer", "minimum": 0, "default": 1000, "description": "Delay before the first retry; exponential doubles it per attempt." },
+        "maxIntervalMs": { "type": "integer", "minimum": 0, "description": "Cap on the exponential backoff interval." }
+      }
+    },
+    "errorStrategy": {
+      "type": "string",
+      "enum": ["continue", "stop", "retry", "compensate", "rollback", "ignore", "custom"],
+      "default": "stop",
+      "description": "Disposition after final failure (ADR 0007 §4): continue = next sibling runs, chain reports the failure; stop = chain halts (default); retry = explicit alias for the retry policy then stop; compensate = execute 'compensation' then stop; rollback = restore the chain-start scope snapshot then stop; ignore = failure swallowed, chain continues clean; custom = execute config.errorHandler (a registered handler type) then stop."
+    }
+  }
+}

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

@@ -0,0 +1,222 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://erp-platform.dev/schemas/block-definition.schema.json",
+  "title": "Block definition contract v1",
+  "description": "The machine-readable contract a block type ships (W1-03) - the artifact every platform studied has (PCF manifest, LWC js-meta.xml, Mendix widget XML, ServiceNow now-ui.json). Phase 6/7 definitions embed instance configs against it, Phase 10's palette and property panel render from it, Phase 8 plugins extend it, Phase 16's AI authors against it, Phase 21 publishes it. Identity carries the marketplace shape (type + semver + publisher) from day one.",
+  "type": "object",
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    },
+    "i18nKey": {
+      "description": "A translation-resolver key. Designer-facing and user-facing text is always a key, never a literal string (W5-03).",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "propertyType": {
+      "enum": ["string", "number", "boolean", "date", "json"]
+    },
+    "valueSourceKind": {
+      "description": "The four ways anything in this platform computes a value (W1-02): a literal, a Phase 1 expression, a Phase 4 state binding, or a Phase 2 action chain (event handlers only).",
+      "enum": ["static", "expression", "binding", "action-chain"]
+    },
+    "selectOption": {
+      "type": "object",
+      "properties": {
+        "value": {},
+        "labelKey": { "$ref": "#/$defs/i18nKey" }
+      },
+      "required": ["value", "labelKey"],
+      "additionalProperties": false
+    },
+    "propertySpec": {
+      "type": "object",
+      "properties": {
+        "name": { "$ref": "#/$defs/identifier" },
+        "type": { "$ref": "#/$defs/propertyType" },
+        "description": { "type": "string", "maxLength": 500 },
+        "required": { "type": "boolean", "default": false },
+        "default": {},
+        "sources": {
+          "description": "Which value sources an instance config may use for this property. Event handlers are declared under events, so action-chain never appears here.",
+          "type": "array",
+          "items": { "enum": ["static", "expression", "binding"] },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "constraints": {
+          "type": "object",
+          "properties": {
+            "min": { "type": "number" },
+            "max": { "type": "number" },
+            "precision": { "type": "integer", "minimum": 0, "maximum": 20 },
+            "maxLength": { "type": "integer", "minimum": 1 },
+            "pattern": { "type": "string", "maxLength": 500 },
+            "options": { "type": "array", "items": { "$ref": "#/$defs/selectOption" } }
+          },
+          "additionalProperties": false
+        },
+        "designer": {
+          "description": "Per-property designer metadata: which panel group it renders in and with which editor (LWC targetConfigs / Mendix propertyGroups precedent).",
+          "type": "object",
+          "properties": {
+            "group": { "$ref": "#/$defs/identifier" },
+            "editor": { "enum": ["text", "number", "switch", "select", "date", "expression", "binding", "json"] },
+            "labelKey": { "$ref": "#/$defs/i18nKey" }
+          },
+          "required": ["group", "editor", "labelKey"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["name", "type", "sources", "designer"],
+      "additionalProperties": false
+    },
+    "portSpec": {
+      "description": "An input or output port: named, typed data the block consumes/produces through the state engine.",
+      "type": "object",
+      "properties": {
+        "name": { "$ref": "#/$defs/identifier" },
+        "type": { "$ref": "#/$defs/propertyType" },
+        "description": { "type": "string", "maxLength": 500 }
+      },
+      "required": ["name", "type"],
+      "additionalProperties": false
+    },
+    "eventSpec": {
+      "description": "An emitted event. catalogType MUST name a Phase 3 event-catalog entry (past-tense, registered, never ad hoc - the ServiceNow catalogued-actions lesson).",
+      "type": "object",
+      "properties": {
+        "name": { "$ref": "#/$defs/identifier" },
+        "catalogType": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "description": { "type": "string", "maxLength": 500 }
+      },
+      "required": ["name", "catalogType"],
+      "additionalProperties": false
+    }
+  },
+  "properties": {
+    "contractVersion": { "const": 1 },
+    "type": {
+      "description": "Globally unique block-type id, dot-namespaced (e.g. core.text-input, acme-hr.org-chart).",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+    },
+    "version": {
+      "description": "Semver. Instances pin the version they were authored against; minor/patch upgrades apply automatically, major upgrades require an explicit migration (W1-05).",
+      "type": "string",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$"
+    },
+    "publisher": {
+      "description": "The Phase 21 marketplace publisher id.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "inputClass": {
+      "description": "True for input-class blocks: the block inherits the validation-message surface (invalid state + message slot + aria-invalid/aria-describedby) from the base contract, which Phase 6's validation pipeline populates (round 2).",
+      "type": "boolean",
+      "default": false
+    },
+    "properties": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/propertySpec" }
+    },
+    "inputs": { "type": "array", "items": { "$ref": "#/$defs/portSpec" } },
+    "outputs": { "type": "array", "items": { "$ref": "#/$defs/portSpec" } },
+    "events": { "type": "array", "items": { "$ref": "#/$defs/eventSpec" } },
+    "permissions": {
+      "description": "Which permission hook points the block honors (W2-05). Enforcement lands in Phase 11; the hooks are in the render path from day one.",
+      "type": "object",
+      "properties": {
+        "visible": { "type": "boolean" },
+        "enabled": { "type": "boolean" },
+        "masked": { "type": "boolean" }
+      },
+      "required": ["visible", "enabled", "masked"],
+      "additionalProperties": false
+    },
+    "a11y": {
+      "type": "object",
+      "properties": {
+        "role": { "type": "string", "minLength": 1, "maxLength": 64 },
+        "labelFrom": {
+          "description": "Where the accessible label comes from: property:<name> or i18n:<key>.",
+          "type": "string",
+          "pattern": "^(property|i18n):.+$"
+        }
+      },
+      "required": ["role", "labelFrom"],
+      "additionalProperties": false
+    },
+    "designer": {
+      "description": "Block-level designer metadata: what Phase 10's palette and property panel render for a block they have never seen (gap audit).",
+      "type": "object",
+      "properties": {
+        "displayNameKey": { "$ref": "#/$defs/i18nKey" },
+        "descriptionKey": { "$ref": "#/$defs/i18nKey" },
+        "icon": { "type": "string", "minLength": 1, "maxLength": 64 },
+        "category": { "enum": ["input", "display", "layout", "data", "action"] },
+        "propertyGroups": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": { "$ref": "#/$defs/identifier" },
+              "titleKey": { "$ref": "#/$defs/i18nKey" }
+            },
+            "required": ["id", "titleKey"],
+            "additionalProperties": false
+          }
+        },
+        "allowedTargets": {
+          "description": "Where an instance of this block may be placed (LWC targets precedent).",
+          "type": "array",
+          "items": { "enum": ["page", "form", "container", "dashboard", "report"] },
+          "minItems": 1
+        },
+        "preview": {
+          "description": "Design-mode preview descriptor (Mendix editorPreview precedent) - rendered by the builder without mounting the real block.",
+          "type": "object",
+          "properties": {
+            "kind": { "enum": ["field", "text", "button", "box", "table"] },
+            "sampleKey": { "$ref": "#/$defs/i18nKey" }
+          },
+          "required": ["kind"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["displayNameKey", "descriptionKey", "icon", "category", "propertyGroups", "allowedTargets", "preview"],
+      "additionalProperties": false
+    },
+    "slots": {
+      "description": "Container-class blocks only: named child slots and what they may contain.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "$ref": "#/$defs/identifier" },
+          "allowedCategories": {
+            "type": "array",
+            "items": { "enum": ["input", "display", "layout", "data", "action"] },
+            "minItems": 1
+          }
+        },
+        "required": ["name", "allowedCategories"],
+        "additionalProperties": false
+      }
+    },
+    "composition": {
+      "description": "2026-07-18: present only on tenant-authored composite Block definitions (Studio's Block Designer) - the block's own fixed internal content, an array of frozen @erp/block-engine BlockInstanceConfig, validated against the live BlockRegistry at mount time exactly like a page item's or a container's own children. undefined for every core/plugin block.",
+      "type": "array",
+      "items": { "type": "object" }
+    }
+  },
+  "required": ["contractVersion", "type", "version", "publisher", "properties", "events", "permissions", "a11y", "designer"],
+  "additionalProperties": false
+}