Merge remote-tracking branch 'origin/main' into claude/issue-24036-ledger-a

Author: claude

.changeset/22269-print-render-service.md

@@ -0,0 +1,24 @@
+---
+'@objectstack/service-print': minor
+'@objectstack/spec': patch
+'@objectstack/service-storage': minor
+---
+
+feat(service-print): print a record's print page to a PDF in headless Chromium, as the requesting user, and archive it as a file attached to the record
+
+Clause-②: yes (widening)
+
+A new package, `@objectstack/service-print`. `PrintServicePlugin` registers the in-process `print` service (`IPrintService`): `status()` and `printRecordToFile({ app, object, recordId, page, filename? }, context)`. It adds no route, no metadata key and no error code. Compose it explicitly:
+
+```ts
+import { PrintServicePlugin } from '@objectstack/service-print';
+plugins: [new PrintServicePlugin()]
+```
+
+- **One engine, headless Chromium, in one of two placements.** A local executable (`OS_PRINT_CHROMIUM_PATH`, option `chromiumPath`), or a remote browser's DevTools WebSocket endpoint (`OS_PRINT_BROWSER_ENDPOINT`, option `browserEndpoint`). Either one needs `OS_PRINT_CONSOLE_URL` (option `consoleUrl`): the console's URL as that browser reaches it, `/_console` included. Configuring both placements is refused. `playwright-core` is pinned exact on this package only.
+- **Loud at startup.** `start()` probes the engine and logs its placement and Chromium version. An engine that is not configured, is misconfigured or does not answer is reported once, with the setting to fix, and `status()` says why. A remote endpoint is never logged beyond its scheme and host.
+- **As the requesting user.** The page is rendered through a short-lived session minted for the caller's own principal by the auth service (`mintPrincipalSession`), and revoked in a `finally`. There is no system principal.
+- **Refusals first, each with `code` and `status`, before any session is minted or browser started** (an engine that failed its last probe is re-probed only after them all): a caller that is not a human user acting for themselves (`PERMISSION_DENIED` / 403); an engine that is not ready (`SERVICE_UNAVAILABLE` / 503); an unknown page (`RESOURCE_NOT_FOUND` / 404); a page that is not the object's default record page or declares no `print` (`VALIDATION_ERROR` / 400); a record the caller cannot read (`RECORD_NOT_FOUND` / 404); an object without `enable: { files: true }` (`FILES_DISABLED` / 403).
+- **The archive runs as the requesting user.** `@objectstack/service-storage`'s `file-attachments` service gains a caller-scoped face, `ICallerFileAttachmentService` (exported type), on the same slot and the same writer: `assertMayAttach(parentObject, parentId, context)` throws the insert's own refusal without writing (`PERMISSION_DENIED` / 403 when the caller may not create attachments, `ATTACHMENT_PARENT_ACCESS` / 403 when the attach rule refuses), and `attachFileAs(input, context)` writes one `sys_file` owned by the caller and one `sys_attachment` inserted under the caller's context, so every insert gate judges the caller and the row is stamped `uploaded_by` the caller. The print service asks `assertMayAttach` in its files step, before any session is minted or browser started. `attachFileAs` acts only in the caller's own organization: an `organizationId` other than the context's `tenantId` (or `null` when it names none) is refused `PERMISSION_DENIED` / 403. `attachFile` (the system verb) is unchanged.
+
+`@objectstack/spec`'s `llms.txt` counts the new package: the workspace publishes 72 packages.

.changeset/23903-flow-save-reintroduced-retired.md

@@ -0,0 +1,32 @@
+---
+'@objectstack/metadata-protocol': minor
+---
+
+feat(metadata-protocol)!: a flow re-save that newly introduces a retired spelling is refused like a new flow's
+
+Clause-②: yes (narrowing)
+
+**BREAKING (API save door), the re-save case:** a flow saved through `saveMetaItem` (`PUT /api/v1/meta/flow/:name`, the runtime dispatcher, and every caller of the protocol) over a stored row is now judged as authored input when its body introduces a spelling retired from the authoring funnel that the stored row does not carry. Adding a node with an old spelling to a legacy flow, or writing one on a node the stored row holds in the canonical spelling, is no longer rewritten and stored: the save meets the flow parse's refusal, `422 INVALID_METADATA`, with an issue located at the key and the same prescription `os validate` and `os build` print, exactly as a new flow's does. Draft and publish mode alike. The whole body is judged that way, so the refusal also lists the retired spellings the stored row already carries; fixing the added one alone is enough to save. Before, a re-save healed every retired spelling in the body, the new one included, and said nothing.
+
+What counts as introduced: a retired conversion that fires on the request at a site where it does not fire on the stored row. A site is the key's path, with each node (and edge) named by its `id` rather than its position, so moving, adding or removing nodes does not change it. The stored rows compared are the row the save overwrites, and for a draft save the active row the draft overlays as well, so Studio's repeated draft saves of a legacy flow keep saving.
+
+Not changed:
+
+- A re-save whose retired spellings the stored row all carries, such as the served legacy body saved back unchanged, keeps replaying the full chain and is healed as before.
+- A new flow with a retired spelling is refused, as it was.
+- The server's own writes of bodies at rest keep the full chain: the stored-metadata migration (`os migrate meta --stored`), a package duplicate and an unmanaged package import.
+- The automation engine's flow rehydration and the read path, which still serves a stored flow verbatim.
+
+Migration, for a client that edits flows through the API: write the spellings below on any node or key you add or change. The legacy spellings already on the stored row may stay until the row is healed.
+
+- `wait` node loose `config.duration` / `config.timerDuration` → `waitEventConfig.timerDuration`; `config.signal` / `config.signalName` → `waitEventConfig.signalName`; `config.eventType` → `waitEventConfig.eventType`. On the block itself, `timeoutMs` → `timerDuration` and `onTimeout` is removed.
+- `connector_action` node loose `config.connectorId` / `config.actionId` / `config.input` → its `connectorConfig` block.
+- CRUD node `config.filters` → `config.filter`; `config.object` → `config.objectName`.
+- `map` and `subflow` node `config.flow` → `config.flowName`.
+- `notify` node `config.to` → `recipients`, `subject` → `title`, `body` → `message`, `url` → `actionUrl`, `source: { object, id }` → `sourceObject` / `sourceId`.
+- `script` node `config.functionName` → `function`, `input` → `inputs`; `actionType` / `template` / `recipients` / `variables` / `script` are removed.
+- `errorHandling.retryDelayMs` and a `try_catch` node's `retry.retryDelayMs` → `backoffMs`; the flow keys `active` / `template`, a node's `outputSchema` and `errorHandling.fallbackNodeId` are removed.
+
+Each refusal names the key to write.
+
+<!-- adr-0087: not-required (already-registered flow-node-crud-filter-alias, flow-node-crud-object-alias, flow-node-notify-config-aliases, flow-node-wait-event-config-lift, flow-node-map-flow-alias, flow-node-subflow-flow-alias, flow-node-connector-config-lift, flow-node-script-config-aliases, flow-inert-keys-removed, flow-node-wait-timeout-keys-removed, flow-node-script-branch-keys-removed, retry-policy-converged) these D2 entries already record every spelling the save door now refuses when a re-save introduces it; this change only stops the door replaying them for a re-save's new authored input, and their own migrations are the ones above -->

.changeset/24007-approval-request-title-label.md

@@ -0,0 +1,12 @@
+---
+'@objectstack/plugin-approvals': patch
+---
+
+Clause-②: no
+
+fix(plugin-approvals): an approval request's record title reads the flow's label, not `flow:NAME`
+
+- **`sys_approval_request.display_title` reads `process_label`.** The title is now the flow's label and the record id (`Discount Sign-off · opp_45`), the same label the request lists show. A row with no label stored falls back to `process_name` (`flow:deal_desk · opp_42`), so the title never reads `null · …`. Every surface that draws the request's title through `nameField` shows it: the record page's heading and breadcrumb, and the request cell of the action history list.
+- **`titleFormat` still names `{process_name}`.** A placeholder template cannot fall back, and `process_label` can be null after the boot fill (a row it could not label, or a failed fill run). A renderer that reads `titleFormat` ahead of `nameField`, such as the global search palette, still shows the machine source.
+
+A patch: one formula on one platform object's computed title. No export, type, accepted value or stored column changes.

.changeset/config.json

@@ -67,6 +67,7 @@
       "@objectstack/service-job",
       "@objectstack/service-knowledge",
       "@objectstack/service-mailbox",
+      "@objectstack/service-print",
       "@objectstack/service-messaging",
       "@objectstack/service-package",
       "@objectstack/service-queue",

.github/workflows/rerun-safety-nightly.yml

@@ -46,6 +46,17 @@
 # Turbo would replay cached results on the second pass and report green without
 # executing anything, which is precisely the wrong answer here. `--force`
 # bypasses the cache so the second pass genuinely re-runs.
+#
+# ## Why `--only` (#23880)
+#
+# `--force` applies to every task in the run, and `test` depends on `^build`, so
+# each pass also re-executed the whole build closure -- 69 `build` tasks and
+# `@objectstack/spec#gen:migration-registry` (`turbo run test --dry=json` at
+# 98ba1bf1d2) -- that `Build packages` had just built. `--only` runs the 83 `test`
+# tasks and nothing they depend on; all 69 of those builds are in `pnpm build`'s
+# own plan, and the spec's `test` script regenerates its migration registry
+# itself. It also stops pass 2 from rebuilding `dist/` over whatever pass 1 left
+# there, which is a working-tree state this job exists to see, not to repair.
 name: Rerun Safety
 
 on:
@@ -77,8 +88,36 @@ jobs:
     # in 15 minutes and never at this number. Raising it can therefore hide no
     # hang; all it stops is a slow-but-live run being reported as a failure of
     # the thing under test.
+    #
+    # ⚠️ 170 no longer holds two full passes, and raising it again is not the
+    # fix (#23880). Measured from the job's own step timestamps: pass 1 took 38
+    # minutes on 2026-09-26 (the last green night), 66 on 10-02, and 97-113 on
+    # every night from 10-12 to 10-16, while the queue-tier suite's measured
+    # task time (scripts/test-shard-timings.json) grew from 124 to 194 minutes
+    # between the 09-28 and 10-13 refreshes, the CLI's alone from 733 to 2206
+    # seconds. Not a hang: on 10-16 pass 2 was still printing when the job
+    # timeout cancelled it 67 minutes in. A night finished at all only because
+    # pass 2 stopped at its first failure; one that did not fail was CANCELLED,
+    # with no verdict and a conclusion the red-card filer does not read.
+    #
+    # So each pass now runs under the time the job has LEFT (JOB_TIMEOUT_MINUTES
+    # below, which must equal this number, minus PASS_RESERVE_MINUTES for the
+    # verdict), and a pass that runs out is stopped by `timeout` instead: the
+    # verdict step still runs, reads the pass's 124/137 exit (or a log with no
+    # turbo summary) as INCOMPLETE -- NOT MEASURED, and the job concludes
+    # `failure`, never a silent `cancelled`. That bound decides only WHO reports
+    # a slow night; how two full passes fit again is a capacity decision
+    # recorded on #23880.
     timeout-minutes: 170
+    env:
+      JOB_TIMEOUT_MINUTES: 170
+      # The verdict and the steps after it take seconds; the reserve also covers
+      # `timeout --kill-after=2m`, the grace a pass gets between SIGTERM and SIGKILL.
+      PASS_RESERVE_MINUTES: 5
     steps:
+      - name: Record the job's deadline
+        run: echo "JOB_DEADLINE_EPOCH=$(( $(date +%s) + JOB_TIMEOUT_MINUTES * 60 ))" >> "$GITHUB_ENV"
+
       - name: Checkout repository
         uses: actions/checkout@v7
 
@@ -142,6 +181,17 @@ jobs:
       # comment in ci.yml): grouped log order flushes a task's output only when
       # the task ends, so a solo tail task longer than the budget reads as
       # frozen while healthy. The guard refuses a turbo run without it.
+      #
+      # The time bound (#23880) sits INSIDE the guard, as the command it wraps:
+      # the guard runs that command in its own process group, so `timeout` is
+      # that group's leader and its SIGTERM reaches turbo, which stops its tasks.
+      # Measured locally at 98ba1bf1d2 (guard -> timeout 45s -> turbo over core,
+      # types and formula): exit 124 came back through the guard, and the log
+      # ended at "Shutting down Turborepo tasks..." / "Force killed Turborepo
+      # tasks: @objectstack/core#test" with no `Tasks:` summary. The verdict reads
+      # 124 (or 137, after --kill-after) as a pass that did not finish. Wrapped
+      # the other way round, `timeout` would kill only the guard and leave its
+      # detached group running into the next step.
       - name: Test suite — pass 1
         run: |
           # Bound vitest's INNER worker pool (#11958). A no-op on a runner with
@@ -151,11 +201,23 @@ jobs:
           # vitest's own "use the default" signal. Needs turbo.json's
           # globalPassThroughEnv entry or turbo strips it — see the script header.
           export VITEST_MAX_WORKERS="$(node scripts/vitest-worker-cap.mjs)"
+          budget=$(( (JOB_DEADLINE_EPOCH - $(date +%s)) / 60 - PASS_RESERVE_MINUTES ))
+          echo "Pass 1 may run ${budget} minutes before the job's own timeout would end it."
           status=0
-          node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/rerun-pass1.log" --stall-minutes 15 -- \
-            pnpm turbo run test --concurrency=4 --force --log-order=stream || status=$?
+          if [ "$budget" -lt 1 ]; then
+            : > "$RUNNER_TEMP/rerun-pass1.log"
+            status=124
+          else
+            node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/rerun-pass1.log" --stall-minutes 15 -- \
+              timeout --kill-after=2m "${budget}m" \
+              pnpm turbo run test --only --concurrency=4 --force --log-order=stream || status=$?
+          fi
           echo "PASS1_EXIT=$status" >> "$GITHUB_ENV"
-          if [ "$status" -ne 0 ]; then
+          if [ "$status" -eq 124 ] || [ "$status" -eq 137 ]; then
+            echo "::warning::Pass 1 ran out of the job's time (exit $status) before it finished."
+            echo "::warning::That is a capacity reading, not a suite reading; the verdict step"
+            echo "::warning::reports it as INCOMPLETE and will fail this job."
+          elif [ "$status" -ne 0 ]; then
             echo "::warning::Pass 1 exited $status — the suite is red on main. Recorded as the"
             echo "::warning::BASELINE and NOT failed here: pass 2 runs anyway so the rerun"
             echo "::warning::property still gets measured tonight. The verdict step owns the"
@@ -197,9 +259,18 @@ jobs:
           # vitest's own "use the default" signal. Needs turbo.json's
           # globalPassThroughEnv entry or turbo strips it — see the script header.
           export VITEST_MAX_WORKERS="$(node scripts/vitest-worker-cap.mjs)"
+          # Whatever pass 1 left of the job's time; see pass 1 for the bound.
+          budget=$(( (JOB_DEADLINE_EPOCH - $(date +%s)) / 60 - PASS_RESERVE_MINUTES ))
+          echo "Pass 2 may run ${budget} minutes before the job's own timeout would end it."
           status=0
-          node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/rerun-pass2.log" --stall-minutes 15 -- \
-            pnpm turbo run test --concurrency=4 --force --log-order=stream || status=$?
+          if [ "$budget" -lt 1 ]; then
+            : > "$RUNNER_TEMP/rerun-pass2.log"
+            status=124
+          else
+            node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/rerun-pass2.log" --stall-minutes 15 -- \
+              timeout --kill-after=2m "${budget}m" \
+              pnpm turbo run test --only --concurrency=4 --force --log-order=stream || status=$?
+          fi
           echo "PASS2_EXIT=$status" >> "$GITHUB_ENV"
 
       # ⭐ THE VERDICT, and the job's exit status (#18590).

.github/workflows/scheduled-full-run-card.yml

@@ -72,7 +72,14 @@ on:
   workflow_run:
     # Byte-exact workflow NAMES (the `name:` at the top of each file), not
     # paths. Quoted because `Lint & Type Check` starts a YAML alias unquoted.
-    workflows: ['CI', 'Lint & Type Check']
+    #
+    # `Rerun Safety` (rerun-safety-nightly.yml, #23880) runs once a night, and
+    # its scheduled runs from 2026-09-17 to 10-16 concluded `success` once in
+    # thirty nights with no filer at all. It gets its own card by the same
+    # identity rule, in its own cadence's words: every name listed here must
+    # have an entry in `CARD_CADENCES` (scripts/ci/scheduled-full-run.mjs),
+    # which refuses a name it does not hold rather than default one.
+    workflows: ['CI', 'Lint & Type Check', 'Rerun Safety']
     types: [completed]
 
 permissions: {}

content/docs/deployment/environment-variables.mdx

@@ -59,6 +59,18 @@ read at startup unless noted otherwise. Boolean variables accept `true` / `false
 
 ---
 
+## Printing
+
+Read by `@objectstack/service-print` when `PrintServicePlugin` is composed; see [Print Pages](/docs/ui/print-pages). Configure **one** placement plus the console URL; a plugin option of the same purpose wins over its variable.
+
+| Variable | Type | Default | Description |
+|:---|:---|:---|:---|
+| `OS_PRINT_CHROMIUM_PATH` | path | — | **Local placement**: a Chromium executable on this host, launched per print (plugin option `chromiumPath`). |
+| `OS_PRINT_BROWSER_ENDPOINT` | url | — | **Remote placement**: a browser's DevTools WebSocket endpoint, connected per print (option `browserEndpoint`). The minted session cookie travels in its frames, so use `wss://` off this host and `ws://` only on loopback. Never logged beyond its scheme and host. Setting it together with `OS_PRINT_CHROMIUM_PATH` is refused. |
+| `OS_PRINT_CONSOLE_URL` | url | — | The console URL that browser loads, `/_console` included (option `consoleUrl`). A URL carrying credentials (`user:password@`) is refused: the browser signs in with the requesting user's own session. |
+
+---
+
 ## Secrets & Clustering
 
 | Variable | Type | Default | Description |