@sparkerp/plugin-sdk 0.1.0 → 1.0.0

package/bundle/docs/guides/extend-a-shipped-application.md

@@ -0,0 +1,132 @@
+---
+title: Extend a shipped application (e.g. HCM)
+audience: tenant
+---
+
+# Extend a shipped application
+
+This page answers a question the other guides don't: *"HCM (or CRM, or any
+other shipped application) already has the screen I want — how do I add to
+it without forking the product?"* It uses HCM as the worked example because
+it's the largest shipped application, but the pattern is identical for every
+other one.
+
+## What you're doing
+
+There are exactly three ways to extend a shipped application. Picking the
+wrong one is the most common mistake — start here.
+
+| You want to... | Use | Why |
+|---|---|---|
+| Add a field to an existing screen (e.g. a new column on the Employee form) | **Custom Fields** (no code) — see [Document Settings, Custom Fields, Custom Forms & Numbering Sequences](../applications/hcm/settings-extensibility.md) | It's a tenant admin setting, not a development task. No plugin needed. |
+| Add a new screen, report, KPI, or workflow that *reads* existing data (e.g. a dashboard of employees whose certifications expire soon) | **A companion plugin** that reads the shipped module's entities through a **Data Service / Data View** (read-only) | This is what the rest of this page walks through. |
+| Add a new approval step or business rule triggered by an existing entity changing | **A workflow or business rule** attached via metadata to the existing entity | See [Add an approval workflow](./add-an-approval-workflow.md) and [Add business rules and expressions](./add-business-rules.md) — no Java, and no edit to the shipped plugin. |
+
+What you must **never** do: edit `hcm-employee`'s (or any shipped plugin's)
+own Java source or its metadata files. Those are the platform's, upgraded
+independently of your tenant, and per
+[[feedback-avoid-frequent-core-code-changes]] only a real, confirmed bug
+justifies touching another module's code — a feature request never does.
+Every legitimate extension in the table above is additive: a new plugin, a
+new metadata file, a new rule. Nothing you write ever modifies a file that
+ships with `hcm-employee`, `hcm-leave`, or any other application module.
+
+## The complete example
+
+A companion plugin, `hcm-cert-tracker`, that adds one new read-only page to
+HCM: **Employees by Department** — a KPI built entirely from data that
+already lives in the shipped `hcm-employee` module's own database table,
+without touching that module at all.
+
+`spk-assembly/metadata/data_view/employees-by-department-view.json`:
+
+```json
+{
+  "name": "hcm-cert-tracker-employees-by-department-view",
+  "description": "Read-only view over hcm-employee's own `employee` table — active headcount grouped by department. This plugin never writes to this table.",
+  "definition": {
+    "source": { "table": "employee", "alias": "e", "excludeDeleted": false, "schema": "hcm" },
+    "joins": [
+      { "table": "org_unit", "alias": "dept", "type": "INNER", "on": [{ "leftRef": "e.department_id", "rightRef": "dept.id" }], "excludeDeleted": false, "schema": "hcm" }
+    ],
+    "fields": [{ "ref": "dept.name", "outputName": "label" }],
+    "calculatedFields": [],
+    "filter": "{\"and\":[{\"field\":\"e.employment_status\",\"operator\":\"eq\",\"value\":\"active\"}]}",
+    "groupBy": ["dept.name"],
+    "aggregations": [{ "ref": "e.id", "fn": "COUNT", "outputName": "value" }],
+    "sort": [{ "ref": "dept.name", "descending": false }],
+    "pagination": { "defaultPageSize": 50, "maxPageSize": 100 },
+    "permissionKey": null
+  },
+  "metadata": {},
+  "modules": ["hcm-cert-tracker-dashboard"]
+}
+```
+
+`spk-assembly/metadata/data_service/employees-by-department.json`:
+
+```json
+{
+  "name": "hcm-cert-tracker-employees-by-department",
+  "operation": "search",
+  "source": { "kind": "dataView", "ref": "hcm-cert-tracker-employees-by-department-view" }
+}
+```
+
+The page then binds a `core.donut-chart` (or `core.list`) block to
+`POST /api/v1/data-services/hcm-cert-tracker-employees-by-department/execute`
+— the exact same `callApi` → `setValue` → binding pattern in
+[Wire a page's data](./wire-a-pages-data.md).
+
+## Line by line
+
+- **`source.schema: "hcm"`** — every HCM module's tables live in the shared
+  `hcm` Postgres schema, not a per-plugin schema. Get this from the shipped
+  module's own real, already-installed `data_view` files (as done here,
+  copied from `hcm-employee`'s own
+  `department-headcount-distribution-view.json`) — never guess it, and never
+  trust a plugin's `plugin.json` `schemaName` field, which can be stale (see
+  [[feedback-entity-engine-tables-must-route-to-app-schema]]).
+- **`source.table: "employee"`** — the real table name. Reverse-engineer real
+  table/column names the same way: read an existing, shipped `data_view`
+  JSON from the module you're extending. Every shipped HCM module's
+  `metadata/data_view/` directory is real, readable reference material for
+  exactly this purpose.
+- **This view is read-only** — a `dataView`/`dataService` pair can only
+  `search`/`get`/`count`; there is no write path through this mechanism.
+  Writing to another module's table is not supported and not safe — if you
+  need to change HCM data, do it through HCM's own real forms/APIs, not by
+  reaching into its schema.
+- **`modules: ["hcm-cert-tracker-dashboard"]`** — scopes this data service to
+  your own plugin's page, not to `hcm-employee`'s.
+
+## How to verify it worked
+
+1. `erp plugin build && erp plugin publish --env dev`
+2. `curl -X POST $BASE/api/v1/data-services/hcm-cert-tracker-employees-by-department/execute -H "Authorization: Bearer $TOKEN"` and confirm it returns real `{label, value}` rows matching your tenant's actual employee/department data — spot-check one row against the HCM Employee Directory screen itself.
+3. Confirm `hcm-employee`'s own files are untouched: `git status` inside `backend/modules/hcm-employee` should show nothing.
+
+## Common mistakes
+
+- **Editing the shipped module instead of reading it.** If you find yourself
+  opening `hcm-employee`'s source to add a field or endpoint, stop — that's
+  Custom Fields or a companion plugin, not a source edit.
+- **Guessing the schema name.** Always confirm it from a real, already-shipped
+  `data_view` file in the module you're reading from.
+- **Building a bespoke REST controller instead of a Data Service.** See
+  [[feedback-prefer-dataview-over-bespoke-rest-for-reads]] — if you're
+  reading rows, a `dataView`/`dataService` pair is almost always the right
+  tool, not a hand-written `@RestController`.
+- **Forgetting `TenantContext`.** If any part of your companion plugin adds a
+  `NO_AUTH` endpoint that touches this data outside the normal
+  tenant-request path, it must wrap the call in
+  `TenantContext.set()`/`finally clear()` — see
+  [[feedback-no-auth-endpoints-need-manual-tenant-context]].
+
+## What to read next
+
+- [Add a data provider, data view, or data service](./add-a-data-provider.md) — the full reference for what this guide's worked example used.
+- [Build a page](./build-a-page.md) and [Wire a page's data](./wire-a-pages-data.md) — to add the screen this data feeds.
+- [Add a KPI or aggregation](./add-a-kpi.md) — for the KPI-card version of this same pattern.
+- [Add an approval workflow](./add-an-approval-workflow.md) — for the "add a workflow step to an existing entity" extension path.
+- [Add your own app-owned roles & permissions](./add-app-owned-roles-and-permissions.md) — the correct pattern if your companion plugin needs its own admin role, instead of widening a shipped module's access checks.

package/bundle/docs/guides/index.md

@@ -39,6 +39,8 @@ Every code sample is a real file under
 
 - [Add business rules and expressions](./add-business-rules.md)
 - [Add an approval workflow](./add-an-approval-workflow.md)
+- [Add your own app-owned roles & permissions](./add-app-owned-roles-and-permissions.md)
+- [Extend a shipped application (e.g. HCM)](./extend-a-shipped-application.md)
 
 ## Scheduled jobs (no Java)
 

package/bundle/docs/reference/entity-aggregation-config.md

@@ -27,7 +27,7 @@ Pull the full JSON Schema: `erp schema pull entity-aggregation-config`  ·&
 | `agg_field` | string |  | Required for sum/avg/min/max; the numeric column to fold. |
 | `group_by_field` | string |  | Optional; one result bucket per distinct value. |
 | `target_entity` | string | yes |  |
-| `target_key_field` | string | yes | Column on target_entity that holds the bucket key (a declared field). Special value "id": the bucket key IS a row's own primary key — the fold is written straight back onto target_entity row #<key> (never a create). Use with group_by_field yielding the parent id (e.g. maintenance_id), target_entity = that parent entity, and a blank target_key_prefix — this is the true 'roll child lines up onto the parent record' form (MaintenanceCostSyncJob). |
+| `target_key_field` | string | yes | Column on target_entity that holds the bucket key (a declared field). Special value "id": the bucket key IS a row's own primary key — the fold is written straight back onto target_entity row #&lt;key&gt; (never a create). Use with group_by_field yielding the parent id (e.g. maintenance_id), target_entity = that parent entity, and a blank target_key_prefix — this is the true 'roll child lines up onto the parent record' form (MaintenanceCostSyncJob). |
 | `target_key_prefix` | string |  | Prepended to the bucket key when writing (so multiple configs can share one summary entity without collisions). |
 | `result_key` | string |  | Used as the bucket key when group_by_field is blank; defaults to sweep_code. |
 | `target_value_field` | string | yes |  |

package/bundle/docs/reference/entity-document-generator-config.md

@@ -24,7 +24,7 @@ Pull the full JSON Schema: `erp schema pull entity-document-generator-config` &n
 | `format` | string |  | one of: `json`, `csv` |
 | `cabinet_id` | integer |  | DMS cabinet id (engine-file) the artifact is stored in. Give this OR cabinet_name. |
 | `cabinet_name` | string |  | 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` | string |  | Generated file name. Supports ${id} ${date} ${ts} ${uuid} and ${field:<name>}. Default: <document_code>-${id}-${date}.<ext>. |
+| `file_name_template` | string |  | Generated file name. Supports ${id} ${date} ${ts} ${uuid} and ${field:&lt;name&gt;}. Default: &lt;document_code&gt;-${id}-${date}.&lt;ext&gt;. |
 | `include_fields` | string |  | Comma-separated source fields to include in the artifact. Blank = all fields. |
 | `child_entity` | string |  | Optional child entity whose rows (matched by child_match_field == source id) are embedded (json) alongside the record. |
 | `child_match_field` | string |  | FK column on child_entity pointing at the source row's id. |

package/bundle/docs/tutorial/01-create-the-plugin.md

@@ -8,12 +8,18 @@ audience: tenant
 ## Scaffold
 
 ```bash
-erp plugin create example-plugin --name "Office Equipment" --type business-app
+erp plugin create example-plugin --name "Office Equipment" --type business-application
 ```
 
 > The folder is `example-plugin/` to match this docs tree. The plugin **id** we
 > use is `office-equipment` — set below. (In real life pick one name and use it
 > for both.)
+>
+> The `--type` value is written into `plugin.json` verbatim, with no
+> validation against what the rest of the platform actually uses — pass
+> `business-application` exactly (not `business-app` or anything else), since
+> that's the real convention every shipped plugin (`hcm-foundation`,
+> `crm-foundation`, ...) uses.
 
 You get `example-plugin/spk-assembly/` with empty `metadata/*` folders and a
 `plugin.json` with `"mainClass": null`.

package/bundle/docs/tutorial/07-return-due-reminder-job.md

@@ -78,12 +78,35 @@ numbers) before the write, so a config targeting a `boolean`/`integer`/`numeric`
 `set_field` is fully supported. An earlier draft of this tutorial hit a SQL type
 error doing exactly that — that platform bug is fixed.
 
-## 3. The job registers itself
+## 3. Ship the rule that registers the job
+
+Unlike this doc's own first draft claimed, **the platform does not ship this
+rule for you** — every plugin using a shared sweep-style entity
+(`entity_status_date_sweep_config`, `entity_aggregation_config`,
+`entity_compliance_config`, ...) ships its own copy of the one small
+`AFTER_CREATE` rule that registers the corresponding job, the same way
+`hcm-assets` ships its own `entity_aggregation_config_register.json` /
+`entity_compliance_config_register.json`. Skip this file and your config rows
+sit in the table forever with no job ever scheduled to read them — confirmed
+live (2026-09-22): a tenant with pre-existing `entity_status_date_sweep_config`
+rows from another plugin still had no `engine-entity.status-date-sweep` job at
+all until this rule shipped.
+
+`spk-assembly/metadata/rules/entity_status_date_sweep_config_register.json`
+([real file](./example-plugin/spk-assembly/metadata/rules/entity_status_date_sweep_config_register.json)):
 
-The platform ships an `AFTER_CREATE` rule on `entity_status_date_sweep_config`
-that calls `ensureEntityStatusDateSweepJobRegistered`. So the first row you seed
-auto-registers the job for your tenant — **you ship no register rule for this
-job** (unlike the aggregation/cadence/compliance jobs).
+```json
+{
+  "entityType": "entity_status_date_sweep_config",
+  "name": "ensure_status_date_sweep_job_registered",
+  "description": "Register the generic EntityStatusDateSweepJob for this tenant on first config row.",
+  "triggerEvent": "AFTER_CREATE",
+  "conditions": null,
+  "actions": "[{\"type\": \"EXECUTE_SERVICE\", \"service\": \"ensureEntityStatusDateSweepJobRegistered\"}]",
+  "priority": 10,
+  "active": true
+}
+```
 
 ## Verify
 

package/bundle/docs/tutorial/08-menus-i18n-publish.md

@@ -44,7 +44,7 @@ erp plugin test     example-plugin/spk-assembly
 ```
 
 ```
-validated 3 page(s) — clean
+OK — 3 page(s) valid
 
 Plugin Tests
 ────────────────────────────────────────
@@ -65,24 +65,24 @@ node developer-docs/examples/test-examples.mjs
 ## Build
 
 ```bash
-erp plugin build example-plugin/spk-assembly -o example-plugin/office-equipment-1.0.0.spk
+erp plugin build example-plugin/spk-assembly -o example-plugin/office-equipment-1.0.4.spk
 ```
 
 ```
 validated 3 page(s) — clean
-packaged 33 files -> example-plugin/office-equipment-1.0.0.spk (231986 bytes)
+packaged 32 files -> example-plugin/office-equipment-1.0.4.spk (230832 bytes)
 sha256: ...
 ```
 
 ## Publish
 
 ```bash
-erp plugin publish example-plugin/office-equipment-1.0.0.spk --tenant 2
+erp plugin publish example-plugin/office-equipment-1.0.4.spk --tenant 2
 ```
 
 ```
 installed:
-{"pluginId":"office-equipment","version":"1.0.0","state":"installed","pf4jState":"STARTED", ...}
+{"pluginId":"office-equipment","version":"1.0.4","state":"installed","pf4jState":"STARTED", ...}
 ```
 
 ## Confirm it's all live

package/bundle/manifest.json

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

package/bundle/schemas/page.schema.json

@@ -285,6 +285,19 @@
     "isSessionExpiredPage": { "type": "boolean" },
     "isAccessDeniedPage": { "type": "boolean" },
     "devicePersistence": { "type": "array", "items": { "$ref": "#/$defs/devicePersistenceRule" } },
+    "events": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "hook": { "const": "onLoad" },
+          "actions": { "type": "array", "items": { "type": "object" }, "description": "Frozen @erp/action-engine ActionDefinition[] - validated against the live ActionRegistry at mount time, same as a block item's own events." }
+        },
+        "required": ["hook", "actions"],
+        "additionalProperties": false
+      },
+      "description": "Page-level lifecycle hooks - today only \"onLoad\", fired once after the page mounts."
+    },
     "modules": { "type": "array", "items": { "type": "string" }, "description": "App-module ids this page belongs to (e.g. \"hcm-foundation-home\") - TenantPageHost's per-module page listing only surfaces a page if it's present here. Load-bearing in practice for any page reached via the app sidenav/module shell, even on pages authored before this was documented." }
   },
   "required": ["contractVersion", "id", "version", "publisher", "title", "rows", "route", "designer"],

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

@@ -42,6 +42,19 @@
         "entrypointExport": { "type": "string" }
       }
     },
+    "publicApis": {
+      "type": "array",
+      "description": "Added 2026-09-16 (direct user instruction: \"ideally during plugin installation - plugin should tell what are the apis are what is their behaviour\"). Gateway-public API endpoints this plugin declares — installed into the real, admin-editable gateway_public_read_path table at install/upgrade time (PluginPublicApiInstaller in engine-plugin) instead of a human hand-authoring a platform migration or a gateway Java-source change. Absent/empty (every manifest that predates this field, and the overwhelming majority of plugins going forward) means this plugin declares no public APIs — its whole surface stays tenant/session-gated, same as before this field existed.",
+      "items": {
+        "type": "object",
+        "required": ["pathPattern"],
+        "properties": {
+          "pathPattern": { "type": "string", "description": "Ant-style path, e.g. \"/api/v1/my-plugin/webhook\"." },
+          "category": { "type": "string", "enum": ["PUBLIC_READ", "NO_AUTH"], "default": "PUBLIC_READ", "description": "PUBLIC_READ (GET/HEAD only, gateway injects the platform tenant's own id, never trusted from the client) or NO_AUTH (any verb, no tenant context injected at all — genuinely unauthenticated). Defaults to PUBLIC_READ, the narrower/safer of the two, when absent." },
+          "description": { "type": "string", "description": "Why this endpoint must be reachable before a tenant/session exists — shown to a platform admin reviewing what a plugin is asking to expose." }
+        }
+      }
+    },
     "roles": {
       "type": "array",
       "items": {

package/bundle/validators/block-engine.mjs

@@ -3384,6 +3384,25 @@ function endsWith(args) {
   const [s, suffix] = args;
   return rvBool(str(s).endsWith(str(suffix)));
 }
+function displayString(v) {
+  switch (v.type) {
+    case "String":
+      return v.value;
+    case "Integer":
+      return v.value.toString();
+    case "Decimal":
+      return v.value.toString();
+    case "Boolean":
+      return String(v.value);
+    case "Null":
+      return "";
+    default:
+      throw new EvaluationError(`concat() does not support ${v.type} operands`);
+  }
+}
+function concatFn(args) {
+  return rvString(args.map(displayString).join(""));
+}
 function registerStringFunctions(registry, version) {
   registry.register(version, "upper", upper);
   registry.register(version, "lower", lower);
@@ -3392,6 +3411,7 @@ function registerStringFunctions(registry, version) {
   registry.register(version, "substring", substring);
   registry.register(version, "startsWith", startsWith);
   registry.register(version, "endsWith", endsWith);
+  registry.register(version, "concat", concatFn);
 }
 function contains(args) {
   const [collection, needle] = args;
@@ -3438,12 +3458,19 @@ function size(args) {
 function isEmpty(args) {
   return rvBool(sizeOf(args[0]) === 0);
 }
+function pluck(args) {
+  const [arr, key] = args;
+  if (arr.type !== "Array") throw new EvaluationError(`pluck() expects an Array as its first argument, got ${arr.type}`);
+  if (key.type !== "String") throw new EvaluationError("pluck() expects a String field name as its second argument");
+  return rvArray(arr.value.map((row) => row.type === "Object" ? row.value[key.value] ?? RV_NULL : RV_NULL));
+}
 function registerCollectionFunctions(registry, version) {
   registry.register(version, "contains", contains);
   registry.register(version, "first", first);
   registry.register(version, "last", last);
   registry.register(version, "size", size);
   registry.register(version, "isEmpty", isEmpty);
+  registry.register(version, "pluck", pluck);
 }
 function ifImpl(args) {
   const [cond, thenValue, elseValue] = args;
@@ -3516,12 +3543,14 @@ var FUNCTION_CATALOG = [
   c({ name: "substring", minArity: 2, maxArity: 3, argKinds: ["String", "Numeric", "Numeric"], returnType: "String", category: "String", description: "Part of a string from a 0-based start position, optionally limited to a length." }),
   c({ name: "startsWith", minArity: 2, maxArity: 2, argKinds: ["String", "String"], returnType: "Boolean", category: "String", description: "True when the string begins with the given prefix." }),
   c({ name: "endsWith", minArity: 2, maxArity: 2, argKinds: ["String", "String"], returnType: "Boolean", category: "String", description: "True when the string ends with the given suffix." }),
+  c({ name: "concat", minArity: 2, maxArity: Infinity, argKinds: ["Any"], returnType: "String", category: "String", description: `Joins 2+ values' display text into one string, e.g. concat("Total: ", page.count).` }),
   // Collection
   c({ name: "contains", minArity: 2, maxArity: 2, argKinds: ["Collection", "Any"], returnType: "Boolean", category: "Collection", description: "True when a list, string, or object contains the given element/substring/key." }),
   c({ name: "first", minArity: 1, maxArity: 1, argKinds: ["Array"], returnType: "Any", category: "Collection", description: "The first element of a list." }),
   c({ name: "last", minArity: 1, maxArity: 1, argKinds: ["Array"], returnType: "Any", category: "Collection", description: "The last element of a list." }),
   c({ name: "size", minArity: 1, maxArity: 1, argKinds: ["Collection"], returnType: "Integer", category: "Collection", description: "Number of elements in a list, characters in a string, or keys in an object." }),
   c({ name: "isEmpty", minArity: 1, maxArity: 1, argKinds: ["Collection"], returnType: "Boolean", category: "Collection", description: "True when a list, string, or object has no elements." }),
+  c({ name: "pluck", minArity: 2, maxArity: 2, argKinds: ["Array", "String"], returnType: "Array", category: "Collection", description: `pluck(rows, "fieldName") \u2014 a new list of that field's value from each object in the list, e.g. turning [{date, value}, ...] into [value, value, ...].` }),
   // Utility
   c({ name: "if", minArity: 3, maxArity: 3, argKinds: ["Boolean", "Any", "Any"], returnType: "Any", category: "Utility", description: "if(condition, thenValue, elseValue) \u2014 returns one of two values based on a condition." }),
   c({ name: "coalesce", minArity: 1, maxArity: Infinity, argKinds: ["Any"], returnType: "Any", category: "Utility", description: "The first argument that is not null." }),
@@ -4744,9 +4773,9 @@ function resolvePath(scopes, rawPath) {
   return value;
 }
 function resolveString(scopes, text) {
-  const pluck = PLUCK_TEMPLATE.exec(text);
-  if (pluck) {
-    const [, path, field] = pluck;
+  const pluck2 = PLUCK_TEMPLATE.exec(text);
+  if (pluck2) {
+    const [, path, field] = pluck2;
     const resolved = runtimeValueToJs(resolvePath(scopes, path));
     if (!Array.isArray(resolved)) {
       throw new ActionError("unresolved-variable", `'${path}|pluck:${field}' requires an array at '${path}'`);
@@ -11057,6 +11086,26 @@ ${failedSteps}` : "")
     });
     if (faulted && this.phase === "ready") this.present();
   }
+  /**
+   * A real, previously-undiscovered gap (2026-09-22, found live authoring the HCM Permissions
+   * "Create Permission" dialog): a `core.text-input` (or any other inputClass block) whose page
+   * JSON only ever sets `properties.value.binding` — the "obviously two-way" way EVERY such field
+   * in this codebase's own already-shipped pages is authored (`hcm-users.json`'s Create User
+   * dialog included) — never actually wrote a keystroke back to that bound page-scope key. `commit`
+   * → `writeOutput` only ever consulted `config.outputs[name]`, a SEPARATE, explicit redirect
+   * nothing in this codebase's own page-authoring convention ever sets; absent that, every write
+   * landed in a `{scope:"block", scopeKey:this.instanceId}` bucket no page action chain can ever
+   * read — the DOM still showed the typed characters (via `RevealableTextField`'s own local echo
+   * state), so this was invisible in every purely-visual check, only surfacing when a create
+   * dialog's Submit button's `${page.createX}` params were inspected against the REAL network
+   * payload, which showed every field empty. Fixed by falling back to the SAME resolved binding
+   * target `resolveProperties()` already computed for the identically-named PROPERTY's own read
+   * side (`this.boundProps`) when no explicit `config.outputs[name]` redirect exists — making a
+   * `source:"binding"` property's own binding genuinely two-way by default, matching what every
+   * page author already (reasonably) assumed it meant. An explicit `config.outputs[name]` still
+   * wins unchanged (e.g. `core.file-upload`'s own redirect to a different scope/key than its
+   * `value` property reads from); this only fills in the previously-silent gap.
+   */
   async writeOutput(name, value) {
     const port = (this.type.definition.outputs ?? []).find((o) => o.name === name);
     if (!port) {
@@ -11064,7 +11113,7 @@ ${failedSteps}` : "")
       return;
     }
     const redirect = this.config.outputs?.[name];
-    const target = redirect ? resolveBoundKey(redirect, this.bindingContext()) : { scope: "block", scopeKey: this.instanceId, key: name };
+    const target = redirect ? resolveBoundKey(redirect, this.bindingContext()) : this.boundProps.get(name) ?? { scope: "block", scopeKey: this.instanceId, key: name };
     await this.ctx.state.set(target, value);
   }
   /* ---------------- error isolation & standard states (W2-04) ---------------- */
@@ -12884,6 +12933,47 @@ var imageDefinition = definition({
       type: "string",
       sources: ["static"],
       designer: { group: "content", editor: "text", labelKey: "core.image.property.height" }
+    },
+    {
+      // 2026-09-17 (page-builder "Customize" panel parity) — a clip-path-class
+      // shape, the same fixed vocabulary a real page-builder's own "Shape"
+      // picker offers (never an arbitrary path — that stays a `style`
+      // escape-hatch concern).
+      name: "shape",
+      type: "string",
+      sources: ["static"],
+      default: "none",
+      constraints: { options: [{ value: "none", labelKey: "core.image.shape.none" }, { value: "circle", labelKey: "core.image.shape.circle" }, { value: "rounded", labelKey: "core.image.shape.rounded" }] },
+      designer: { group: "content", editor: "select", labelKey: "core.image.property.shape" }
+    },
+    {
+      /** A native browser tooltip (HTML `title` attribute) — distinct from `alt` (accessibility text, always present) and from a rich hover-card (out of scope here, a real different feature). */
+      name: "tooltip",
+      type: "string",
+      sources: ["static"],
+      designer: { group: "content", editor: "text", labelKey: "core.image.property.tooltip" }
+    },
+    {
+      /** A raw CSS `transform` value, e.g. "rotate(4deg)" — same "text travels as data" posture as `PageTheme.customCss`, never `dangerouslySetInnerHTML`, just an inline style value. */
+      name: "transform",
+      type: "string",
+      sources: ["static"],
+      designer: { group: "content", editor: "text", labelKey: "core.image.property.transform" }
+    },
+    {
+      name: "filter",
+      type: "string",
+      sources: ["static"],
+      default: "none",
+      constraints: {
+        options: [
+          { value: "none", labelKey: "core.image.filter.none" },
+          { value: "grayscale", labelKey: "core.image.filter.grayscale" },
+          { value: "sepia", labelKey: "core.image.filter.sepia" },
+          { value: "blur", labelKey: "core.image.filter.blur" }
+        ]
+      },
+      designer: { group: "content", editor: "select", labelKey: "core.image.property.filter" }
     }
   ],
   events: [],
@@ -12905,7 +12995,11 @@ var imageLogic = {
         src: String(io.props["src"] ?? ""),
         alt: io.props["alt"] !== void 0 ? String(io.props["alt"]) : "",
         width: io.props["width"] !== void 0 ? String(io.props["width"]) : void 0,
-        height: io.props["height"] !== void 0 ? String(io.props["height"]) : void 0
+        height: io.props["height"] !== void 0 ? String(io.props["height"]) : void 0,
+        shape: io.props["shape"] !== void 0 ? String(io.props["shape"]) : void 0,
+        tooltip: io.props["tooltip"] !== void 0 ? String(io.props["tooltip"]) : void 0,
+        transform: io.props["transform"] !== void 0 ? String(io.props["transform"]) : void 0,
+        filter: io.props["filter"] !== void 0 ? String(io.props["filter"]) : void 0
       }
     });
   }
@@ -16275,6 +16369,31 @@ var gridDefinition = definition({
       designer: { group: "data", editor: "binding", labelKey: "core.grid.property.refreshTrigger" }
     }
   ],
+  // 2026-09-23 — these are the block's own internal state (written via
+  // `io.setOwnState` in this file's `query()`/handlers, read back into
+  // `node.props` for the adapter), not authored properties: a page author
+  // never sets them, but a plugin/theme developer inspecting `core.grid`
+  // via `erp blocks list --type core.grid` had no way to discover they
+  // exist at all — the empty-grid production bug this session traced back
+  // to exactly this state (rows/total both came from the same query
+  // response, one reached the render, the other didn't) took a live
+  // Playwright session plus a source read to pin down, when this list
+  // alone would have shown the full internal-state surface immediately.
+  outputs: [
+    { name: "rows", type: "json" },
+    { name: "total", type: "number" },
+    { name: "pageIndex", type: "number" },
+    { name: "sort", type: "json" },
+    { name: "filter", type: "json" },
+    { name: "groups", type: "json" },
+    { name: "aggregates", type: "json" },
+    { name: "expandedGroups", type: "json" },
+    { name: "error", type: "string" },
+    { name: "circuitOpen", type: "boolean" },
+    { name: "selectedIds", type: "json" },
+    { name: "density", type: "string" },
+    { name: "groupBy", type: "string" }
+  ],
   events: [
     { name: "selectionChanged", catalogType: "GridSelectionChanged" },
     { name: "rowClicked", catalogType: "GridRowClicked" },
@@ -17182,6 +17301,30 @@ var fileUploadDefinition = definition({
       type: "string",
       sources: ["static", "expression"],
       designer: { group: "data", editor: "text", labelKey: "core.file-upload.property.cabinetId" }
+    },
+    {
+      // 2026-09-21 (HCM Users spec gap-closing pass) — every pre-existing
+      // page never sets this (undefined === "dms"), so it's a zero-risk
+      // addition: `"dms"` keeps today's exact behavior (a real DMS cabinet
+      // upload via the injected `FileUploadSource`, `value` becomes real
+      // `UploadedFileRef`s). `"raw"` skips the DMS upload entirely — `value`
+      // becomes the picked file's own `{filename, contentType, dataUrl}`
+      // straight from the browser's file picker, with no `id`/`url` (nothing
+      // was uploaded anywhere) — meant to feed a `callApi` action's
+      // `multipart: true` body (see that handler's own doc comment), the
+      // real fix for the disclosed "core.file-upload cannot emit raw bytes
+      // into a callApi body" gap (`ai/patterns/import.md`).
+      name: "mode",
+      type: "string",
+      sources: ["static"],
+      default: "dms",
+      constraints: {
+        options: [
+          { value: "dms", labelKey: "core.file-upload.mode.dms" },
+          { value: "raw", labelKey: "core.file-upload.mode.raw" }
+        ]
+      },
+      designer: { group: "behavior", editor: "select", labelKey: "core.file-upload.property.mode" }
     }
   ],
   outputs: [{ name: "value", type: "json" }],
@@ -17194,15 +17337,23 @@ var fileUploadDefinition = definition({
     category: "input",
     propertyGroups: [
       { id: "data", titleKey: "core.designer.group.data" },
-      { id: "content", titleKey: "core.designer.group.content" }
+      { id: "content", titleKey: "core.designer.group.content" },
+      { id: "behavior", titleKey: "core.designer.group.behavior" }
     ],
     allowedTargets: ["page", "form", "container", "dashboard"],
     preview: { kind: "field" }
   }
 });
+var rawFileIdCounter = 0;
+function nextRawFileId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+  rawFileIdCounter += 1;
+  return `raw-file-${Date.now()}-${rawFileIdCounter}`;
+}
 function createFileUploadLogic(uploadSource) {
   return {
     render(io) {
+      const mode = io.props["mode"] === "raw" ? "raw" : "dms";
       const files = Array.isArray(io.props["value"]) ? io.props["value"] : [];
       const accept = typeof io.props["accept"] === "string" ? io.props["accept"] : void 0;
       const multiple = io.props["multiple"] !== false;
@@ -17211,8 +17362,17 @@ function createFileUploadLogic(uploadSource) {
         props: { value: files, accept, multiple },
         handlers: {
           upload: async (payload) => {
-            if (!uploadSource) return;
             const incoming = payload ?? [];
+            if (mode === "raw") {
+              await io.runLoading(async () => {
+                const picked = incoming.map((f) => ({ id: nextRawFileId(), ...f }));
+                const next = [...files, ...picked];
+                await io.writeOutput("value", next);
+                await io.emit("committed", { field: "value", old: files, new: next });
+              });
+              return;
+            }
+            if (!uploadSource) return;
             await io.runLoading(async () => {
               const uploaded = [];
               for (const f of incoming) uploaded.push(await uploadSource.upload(f, cabinetId));