Merge remote-tracking branch 'origin/main' into claude/issue-22269-print-render-service

Author: claude

.changeset/23543-f2-job-retry-policy-without-attempts-refused.md

@@ -0,0 +1,29 @@
+---
+'@objectstack/spec': minor
+'@objectstack/service-job': patch
+---
+
+feat(spec)!: a job `retryPolicy` block whose `maxRetries` is omitted or 0 is refused, and `retry-policy-converged` leaves the load path
+
+Clause-②: yes (narrowing)
+
+**BREAKING (authoring):** `maxRetries` has defaulted to 0 since 17, so a `job.retryPolicy` block that omits it, or writes 0, buys no retry: the job runs once. Through 17 the loader hid that by writing the pre-17 `maxRetries: 3` and `backoffMultiplier: 2` into such a block with a notice. At 18 the ADR-0087 D2 conversion `retry-policy-converged` is retired from the load path (`retiredAfter: '17.7.0'`), and the job parse refuses the block at `retryPolicy.maxRetries`, at every door that parses an authored job (`defineStack`, `os validate`, `os build`, and `os lint` when the config calls it): "A retry block with no attempts is no retry block: state `maxRetries` ≥ 1, for example 3, or delete the block." The rule is the job's, the same one `flow.errorHandling` applies to `strategy: 'retry'`; the shared `RetryPolicySchema` is unchanged, so a `try_catch` node's `retry` region is judged as before.
+
+Migration:
+
+- `retryPolicy: {}` or `retryPolicy: { backoffMs: 5000 }` → `retryPolicy: { maxRetries: 3, backoffMs: 5000 }` (3 is the count such a block ran with before 17), or delete the block if the job should run once.
+- `retryPolicy: { maxRetries: 0, … }` → delete the block: a job with no `retryPolicy` is a single attempt.
+
+What an author who still writes it sees: `defineStack` throws `STACK_SCHEMA_INVALID` (422) with one issue at `jobs.N.retryPolicy.maxRetries` carrying the prescription above, and `os validate` prints the same issue. Nothing is rewritten silently any more.
+
+Not refused: a block that states `maxRetries` and omits `backoffMultiplier`. It keeps the declared default of 1, a flat delay, where the loader used to write 2. State `backoffMultiplier: 2` to keep the old exponential curve.
+
+Run `os migrate meta --from 16` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand. For such a block the edit writes both pre-17 numbers (`maxRetries: 3`, `backoffMultiplier: 2`). The D3 entry `job-retry-policy-without-attempts-refused` states the decision left to you: keep the written count, or delete the block.
+
+The flow half of the conversion (`retryDelayMs` → `backoffMs` on `flow.errorHandling` and a `try_catch` node's `retry`) needed nothing more: both surfaces already refuse `retryDelayMs` with the rename to `backoffMs`.
+
+Stored metadata needs no edit. Stored-row rehydration, the automation engine's flow rehydration, the metadata save door's flow fallback and the artifact-ingestion door inside its window still replay the conversion, so a job row stored without a count keeps loading with the three retries it ran with.
+
+`@objectstack/service-job`: a comment-only change in `runWithPolicy`, whose `maxRetries` default is now reached only by a caller that builds the options by hand.
+
+<!-- adr-0087: registered job-retry-policy-without-attempts-refused -->

.changeset/23731-activity-changed-fields.md

@@ -0,0 +1,25 @@
+---
+'@objectstack/plugin-audit': minor
+'@objectstack/cli': minor
+---
+
+feat(plugin-audit): `sys_activity` rows carry two writer-stamped read-rule columns, and the withheld-row rule is a predicate over them, with no SYSTEM pre-scan (ADR-0139 E6)
+
+**Run `os migrate activity-changed-fields --apply` at once after upgrading.** After the upgrade, and until it runs, the `sys_activity` rows written before the upgrade carry no stamp and are withheld from every non-system reader: activity feeds, the header bell and record timelines show only the rows written since the upgrade. The door is `os migrate activity-changed-fields`, dry run by default, `--apply` to write, idempotent, and it stamps both columns in one run. Its flags are `os migrate audit-metadata-bodies`'s, one for one (`--database-url`, `--apply`, `--yes`, `--force`, `--json`). The columns arrive with the upgraded deployment's schema sync, which an `--apply` run performs itself; a dry run against a database no upgraded process has opened cannot read them and exits `1`.
+
+Clause-②: yes
+
+`sys_activity` gains two columns, stamped at write time by one derivation (`planActivityStamp`): the CRUD mirror stamps its own rows, and a `sys_activity` before-insert hook stamps every row any other writer inserts (an app's own server action, the seed loader), over whatever value that writer sent.
+
+- `changed_fields` (`tags`) — the key set of the recorded change: for an update, every field its recorded `old` / `new` values name; `[]` for a create, a delete, a note, or an update that touched only `internal` fields. It is served narrowed to the fields the reader is served.
+- `milestone_key` (`text`) — for a fired activity milestone, one sorted, comma-joined key of every field the object's `activityMilestones` declaration watched when it fired; `null` for every other row. It is never served.
+
+The withheld-row rule is now a WHERE over those two columns, one branch per parent object, on `find`, `findOne`, `count` and `aggregate`. It reads no row, so the 2,000-row SYSTEM pre-scan and its window are gone: a broad read of the stream is served every row the caller may read, with a true `total`. What the rule withholds:
+
+- an update row whose `changed_fields` is non-empty and names no field the reader is served (unchanged);
+- a fired milestone row, unless its key equals the key of the object's CURRENT `activityMilestones` declaration and the reader is served every field that declaration watches. **The cost:** a milestone row written under an earlier declaration, or naming a since-removed field, is withheld from every non-exempt reader until retention ages it out (14 days declared; `lifecycle.retention_overrides` may lengthen it);
+- an unstamped row, from every non-system reader: one at rest from before the upgrade until the backfill stamps it, and one the planner cannot judge (a milestone row naming no readable watched-field list), which stays unstamped.
+
+The parent-field query guard covers both columns as it covers `metadata`: a reader withheld any field of the parent is refused a filter, sort, group or aggregate over `changed_fields` or `milestone_key` (`PERMISSION_DENIED` / 403).
+
+`@objectstack/plugin-audit` exports the backfill, `backfillActivityChangedFields` (with `ACTIVITY_BACKFILL_PAGE_SIZE` and its report and engine types), and the planner, `planActivityStamp` (with `ACTIVITY_CHANGED_FIELDS_COLUMN`, `ACTIVITY_MILESTONE_KEY_COLUMN` and `ActivityStamp`). Inside the module (none of it is exported from the package), `computeWithheldUpdateFilter` keeps its name and now builds the predicate, `isWithheldOnlyUpdate` keeps its name as the update half over `changed_fields`, and `isWithheldMilestone` / `isWithheldRow` are gone with the pre-scan they judged for.

.changeset/23756-section-translation-tsdoc.md

@@ -0,0 +1,7 @@
+---
+'@objectstack/spec': patch
+---
+
+Clause-②: no
+
+The published TSDoc now sends a form section's translations to the right key. `FormSectionSchema.name` used to name only `metadataForms.<type>.sections.<name>`, which is the key for a metadata-editing form (`defineForm({ schemaId })`, read by `resolveMetadataFormLabels`). A section of an object-bound form view is keyed at `objects.<object>._sections.<name>`, where `<object>` is the form's own `data.object`, else its view's. The docblock now names both keys and which form each one serves. `TranslationDataSchema._sections` now names the three surfaces that author its key (form-view sections, `record:details` sections, object `fieldGroups`) and its readers (`walkObjectSections`, `collectViewRecord`, `translateView`). `resolveMetadataFormLabels`' docblock no longer says that a section without a `name` keeps its section-level text: such a section is looked up under a slug of its `label`, as the function has always done. These are comment changes only: no key, `.describe()` text or behaviour changes. An object-form translation bundle written from the old docblock under `metadataForms.…` never translated anything. Move its section entries to `objects.<object>._sections.<name>`.

.changeset/23808-type-descriptions-plain.md

@@ -0,0 +1,18 @@
+---
+'@objectstack/spec': patch
+'@objectstack/platform-objects': patch
+---
+
+Clause-②: no
+
+The `description` of four metadata types in `DEFAULT_METADATA_TYPE_REGISTRY`, which Setup shows under the
+type's title, is now one plain sentence for an administrator instead of ADR vocabulary:
+
+- `api`: "A stable HTTP URL that other systems call to run a flow or work with records in the app"
+- `doc`: "A help page written in Markdown that a package ships or you write yourself"
+- `book`: "A table of contents that groups help pages into ordered sections"
+- `capability`: "A permission a package defines; you grant it through permission sets"
+
+The ADR references (ADR-0121, ADR-0046, ADR-0046 §6, ADR-0066 D1) moved to the comments beside the
+registry rows. The generated metadata-forms translations carry the new sentences in en, zh-CN, ja-JP
+and es-ES. No key, type or accept/refuse result changes.

.changeset/23813-minted-session-no-refresh.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/plugin-auth': patch
+---
+
+Clause-②: no
+
+A session minted by `IAuthService.mintPrincipalSession` is no longer refreshed by a read. Before,
+`get-session` (and every endpoint that reads the session) still renewed it on each request: #23772's
+guard held its expiry, but the row's `updatedAt` was rewritten, the session cookie was re-set with a
+7-day `Max-Age`, and `bearer()` answered `set-auth-token`. The console reads that header as a token
+rotation, so a browser carrying a minted cookie stayed on "Opening your console…" and the print
+service could not render under the requesting user. A request that carries a minted session now
+sets better-auth's own per-request skip-refresh switch, on the cookie lane, the bearer lane and
+in-process. The mint's contract, TTL, refusals and revoke are unchanged.

content/docs/automation/jobs.mdx

@@ -385,13 +385,15 @@ Delay before retry *n* is `min(backoffMs * backoffMultiplier^(n-1), maxRetryDela
 optionally jittered. `maxRetries` counts retries **after** the initial attempt and
 is capped at 10.
 
-Two defaults worth knowing before you rely on the block:
+Two rules worth knowing before you rely on the block:
 
-- **`maxRetries` defaults to `0`** — declaring `retryPolicy` without stating a
-  count still means *no retry*. State a count to opt in.
+- **A block must state `maxRetries` ≥ 1.** A `retryPolicy` that omits it or
+  writes `0` would buy no retry, so it is refused at `objectstack validate` with
+  "a retry block with no attempts is no retry block". State a count, or delete
+  the block: a job with no `retryPolicy` runs once.
 - **`backoffMultiplier` defaults to `1`** — a flat delay, not exponential.
 
-Those defaults are why the block is closed: a key it does not declare — `maxRetry`
+The count rule and that default are why the block is closed: a key it does not declare — `maxRetry`
 for `maxRetries`, a `maxDelayMs` borrowed from another retry vocabulary — is
 refused at `objectstack validate` with the declared key it was near, rather than
 dropped and replaced by a default that never retries.

content/docs/deployment/cli.mdx

@@ -1172,6 +1172,7 @@ where the data lives.
 | `os migrate value-shapes` | Scan stored reference and structured-JSON field values against the platform's value contract, and record the deployment's migration flag when clean |
 | `os migrate summary-nulls` | Backfill roll-up `count` / `sum` columns still stored as `NULL` on parent rows created before the insert-time seed. Repairs values; no flag, nothing depends on it having run |
 | `os migrate comment-reactions` | Carry the emoji reactions a 17.x deployment stored in the retired `sys_comment.reactions` column into `sys_comment_reaction` records, list every stored value that does not read, and record the verified run that lets `os migrate apply --allow-destructive` drop the column |
+| `os migrate activity-changed-fields` | Stamp the two read-rule columns (`changed_fields`, `milestone_key`) on the `sys_activity` rows written before they existed. Until it runs, those rows are withheld from every reader but the system, so run it at once after upgrading. No flag; idempotent |
 | `os migrate meta --stored` | Replay the metadata conversion chain over this deployment's `sys_metadata` rows and rewrite the ones still carrying a pre-protocol shape. Hygiene, not a gate — nothing depends on it having run |
 | `os migrate security-catalog-overlays` | List the environment-wide permission-set and position rows (the legacy plurals `permissions` / `positions` included) stored over a name a configured package holds — the rows a v18 cold boot refuses — each with the package that holds its name; `--apply` deletes them, one history tombstone per row. Run it before the first v18 boot, with the flags and environment the deployment boots with: the platform security plugin's sets are held only where `os serve` composes it (an auth secret set, and the `auth` tier on), and the step takes `serve`'s `--preset` and `--dev` with `serve`'s meaning. Adopts nothing; exits 1 while it lists a row |
 | `os migrate duplicates` | Report business identifiers already minted twice across the organization partitions, and the rows blocking the boot-time NULL-safe index tightenings — a read-only inventory as JSON on stdout. Renumbers nothing and writes no row and no schema; run it before the boot-time tenancy repair, which overwrites part of the evidence |
@@ -1411,6 +1412,36 @@ A run that lists an unreadable value or fails a write exits `1`, and so does an
 A database created on v18 never had the column: the run finds nothing, and
 there is no drop to wait for.
 
+#### `os migrate activity-changed-fields`
+
+An activity row is served to a reader only when the platform can judge it for
+that reader: whether the change it records touched a field the reader may see,
+and, for a fired milestone, whether the reader may see every field the
+milestone watches. Since this version that judgement reads two columns the
+platform stamps on every new row, `changed_fields` and `milestone_key`. Rows
+written before the upgrade carry no stamp, and **an unstamped row is withheld
+from every reader but the system**, so until this command runs, activity feeds
+and record timelines show only the rows written since the upgrade.
+
+```bash
+os migrate activity-changed-fields                    # Dry run: counts, writes no rows
+os migrate activity-changed-fields --apply            # Stamp the rows (prompts)
+os migrate activity-changed-fields --apply --yes --json   # CI / scripts
+```
+
+Each row is stamped from its own recorded change, by the rule the platform
+stamps new rows with, and both columns are stamped in one run. **A row that
+cannot be judged stays unstamped**, and stays withheld: a milestone row that
+names no readable list of watched fields. The report counts those rows; they
+age out with the object's retention (14 days unless the deployment lengthens
+it).
+
+**Idempotent**: only unstamped rows are read, so a second run stamps nothing,
+and re-running is how an interrupted run is finished. The columns arrive with
+the upgraded deployment's schema sync, which an `--apply` run performs itself:
+a dry run against a database no upgraded process has opened cannot read them,
+reports the failed read and exits `1`. A failed read or write exits `1`.
+
 #### A database created by this version needs no migration
 
 A deployment whose database the platform **creates from empty** records these