@@ -0,0 +1,44 @@
+---
+"@objectstack/client": minor
+---
+
+fix(client): the four `packages` READ members declare the stage their door is declared at (#17536)
+
+Clause-②: yes
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface WIDENING, shipped as `minor` under the launch-window convention (`check-changeset-no-major` refuses `major` until GA; breaking-ness is carried by this banner and the ADR-0087 disposition below, never by the level). No runtime behaviour changes, and none is possible here: only a declaration moved, and the values these four methods resolve to are the values they have always resolved to.
+
+`ObjectStackClient.packages.list` / `.get` and their `ScopedEnvironmentClient` twins returned `InstalledPackage` — the AUTHORING manifest stage, imported from `@objectstack/spec/kernel`. Since PR #17517 both read doors have been declared at EITHER stage: `ListInstalledPackagesResponseSchema.packages` is `z.array(InstalledPackageAtEitherStageSchema)` and `GetInstalledPackageResponseSchema.data` is that same schema. ⇒ A response the server is declared able to send was one this SDK's own types said could not arrive.
+
+`packages/spec` is the one contract between producers and consumers, and `packages/client` is a consumer of it, so the consumer's declaration is what moves. All four now declare `InstalledPackageAtEitherStage` from `@objectstack/spec/api`.
+
+**What the union is.** It is a union over the two manifest stages — `InstalledPackageSchema` and `AssembledInstalledPackageSchema` — which differ in exactly one key, `manifest`. Every other member of the row (`id`, `name`, `version`, `status`, `enabled`, `installedAt`, …) is common to both branches and reads exactly as it did, so code that reads only those members needs no change at all.
+
+**Where the RUNTIME and the TYPE disagree, measured at this head.** The runtime schema is the strict half: `InstalledPackageAtEitherStageSchema.safeParse(row)` answers `success: false` for a row whose `manifest` belongs to neither stage — measured on a `{ bogus: 1, objects: 'not-even-an-array' }` manifest and on an empty `{}` one. The published TYPE is NOT that strict: on the assembled branch `manifest` is declared `Record<string, unknown>`, so both of those same rows COMPILE against the declared return type. ⛔ Do not read this widening as a type-level guarantee about `manifest` — the guarantee is the parse's. The type-level tolerance is a known gap, tracked as **#19324**; its root cause is the deliberate `z.ZodType<Record<string, unknown>, …>` annotation at `packages/spec/src/stack.zod.ts:1283` (#14513 — TS7056 and a declaration-chunk ceiling), and it is ⛔ not this change's to fix. It is recorded as a pin in `packages/client/src/return-type-precision.test.ts`, which reddens the day the gap closes.
+
+**What a consumer does, concretely.** A member read off `manifest` on the union arrives as `unknown` (measured: `pkg.manifest.objects` is `unknown`). ⇒ a caller that reaches INTO `manifest` narrows by PARSING the row with a `packages/spec` schema and reading the parse's output:
+
+```ts
+import { AssembledInstalledPackageSchema } from '@objectstack/spec/api';
+import { InstalledPackageSchema } from '@objectstack/spec/kernel';
+
+const row = await client.packages.get(id);
+const parsed = AssembledInstalledPackageSchema.safeParse(row);
+if (parsed.success) {
+  // parsed.data.manifest — the ASSEMBLED stage, object definitions
+} else {
+  const authoring = InstalledPackageSchema.parse(row);
+  // authoring.manifest.objects — the AUTHORING stage, glob strings
+}
+```
+
+⛔ Do NOT narrow with `Array.isArray(pkg.manifest.objects)`, or with any other structural guess. It separates the stages on NEITHER level: at the type level `pkg.manifest` is the same union inside both branches of that `if`, and at runtime BOTH stages' `objects` are arrays — `z.array(z.string())` at the authoring stage against `z.array(ObjectSchema)` at the assembled one. (Measured: a row carrying no `objects` at all parses as either stage, which is the right answer for it — the key such a guess would read is not there.)
+
+In this repository the whole consumer cost is zero sites outside `packages/client` itself: no other workspace package calls either read member.
+
+**The WRITE members did not move** and stay declared at the authoring stage — all four of them: `install`, `enable`, `disable`, `update` still answer `Promise<InstalledPackage>`. `install` answers the row its own request contract produced (`PackageInstallRequestSchema` declares `manifest: ManifestSchema`), and PR #17517 moved the read doors alone. That asymmetry is the measurement, not an oversight, and it is pinned.
+
+The type is reached the same way `InstalledPackage` always was, from `@objectstack/spec` rather than re-exported here: this SDK has never re-exported the package row, and this change does not start.
+
+<!-- adr-0087: not-required (no-migration-prescription) Nothing authorable moves. No metadata key, no authored property, no config field, no accepted request shape and no stored artifact changes spelling or shape: the edit is four declared RETURN TYPES on one SDK class pair plus their docblocks, so `objectstack migrate meta` has nothing to rewrite, `spec-changes.json` has nothing to project and the upgrade guide has no row to gain. The party addressed is a TYPESCRIPT CONSUMER and the delivery channel is the compiler at their own call site — the audience the ADR-0087 ledger explicitly does not serve. The "what a consumer does" paragraph above is a source-code statement about narrowing a union, not a stored-metadata rewrite, which is the distinction #13080 records this refusal cannot make on its own.
+     `type-surface-only` is NOT claimed here, and it is unavailable on the merits rather than on a resolution defect — measured by driving the gate, not assumed. That category was added for a published TYPE-surface NARROWING, and its predicate 4 (`narrowed-from-erased`) reads the base annotation through `isErasedType`, whose line is "the type IS `any` / `unknown`". At the merge base all four members carried a CONCRETE annotation (`Promise<InstalledPackage>`, `Promise<{ packages: InstalledPackage[]; total: number }>`), so nothing moved off an erased type; and this change runs in the opposite direction from the one the category names. The **BREAKING** banner is carried rather than dropped — that erosion is exactly what #13080 was filed about. -->
@@ -0,0 +1,13 @@
+---
+"@objectstack/spec": patch
+---
+
+**ADR-0137 makes field-rule predicate fault semantics part of the contract** (#17778): what SUBMIT and RENDER do when a predicate cannot run.
+
+Clause-②: no
+
+**The predicate fault-semantics contract is recorded, not enforced, by this release.** ADR-0137 states what a field-rule predicate does when it cannot RUN: at SUBMIT a faulting predicate refuses the write and names the field and the rule (D2); at RENDER visibility stays fail-OPEN, so a rule that could not run never hides a control and lets the form write `null` over a column the user never saw (D3); a blank or faulting GATE predicate is diagnosed, never a silent `true` (D4); and the evaluation helper's fallback stays freely specifiable (D5), because fault-to-flag and fault-to-throw both exist only because it is a parameter. Those are consequences CONSUMERS deliver — `packages/spec` carries no business logic — and they land in the ObjectUI half. D1's authoring refusal (an `ast`-only envelope and a blank `source` are refused at authoring) is ruled by decision batch #122 item 2 and ships with the evaluated-slot narrowing that owns it, under that change's own ADR-0087 entry.
+
+**ADR-0089 gains an addendum, not a reopening.** It unified the `visibleWhen` / `visibleOn` / `visibility` family under one name; ADR-0137 owns what that family does when a predicate cannot run, and ADR-0089 itself is unchanged by this release.
+
+**Not carried by this entry: the `cel` / `expression` return-type narrowing to `EvaluatedExpression`.** This card touched that signature too, but main shipped the identical narrowing first, under #18638 (card #15811) — see that release's own changeset for the `EvaluatedExpression` story and the TS2322 it fixes. Restating it here would announce, a second time, a fact this release has already shipped under a different entry.
@@ -0,0 +1,54 @@
+---
+'@objectstack/spec': minor
+---
+
+fix(spec)!: the form-row `scale` is bounded at the renderer ceiling of 100 (#19088)
+
+Clause-②: no (narrowing)
+
+`FormFieldBaseSchema.scale` — the per-field override a form row carries — was declared as
+any non-negative integer with no upper bound. It is the third declaration of `scale` to
+reach the same platform ceiling #18972 bounded on the two in `data/field.zod.ts`: every
+renderer that turns a declared `scale` into fraction digits reaches one of two platform
+primitives, and both refuse above 100. `Number.prototype.toFixed` throws `RangeError:
+toFixed() digits argument must be between 0 and 100`, and `Intl.NumberFormat` throws
+`RangeError: maximumFractionDigits value is out of range.` So a spec-valid declaration was
+unrenderable by any conforming consumer, and its author got no signal at publish time —
+the failure arrived as a render-time crash in someone else's repository. The route from
+this row to that reader, measured in the sibling checkout at the `.objectui-sha` pin
+`53ded82bf7`: plugin-form copies the row's constraint keys onto the runtime field
+(`packages/plugin-form/src/sectionFields.ts:220`, `if (fd.scale != null) base.scale =
+fd.scale;`), and the number cell renderer hands that value straight to `Intl.NumberFormat`
+(`packages/fields/src/index.tsx:661-667`, `maximumFractionDigits: scale ?? 20`). That one
+route carries the premise on its own.
+
+The row now carries that upper bound, and the refusal says **why** — it names both
+primitives, the `RangeError` and the legal maximum — so an author reads a platform limit
+they can verify rather than a cap somebody chose. The bound is the platform's own: at 100
+both primitives are measured to succeed, at 101 both are measured to throw, and a unit
+test re-measures that boundary on every run rather than trusting the literal.
+
+**BREAKING** — a form-row `scale` above 100 that parsed clean before is refused at
+authoring now. This is a deliberate narrowing of a published accepted set, priced as such
+rather than as a tidy-up. The declarations it refuses could only ever have crashed a
+renderer: there is no value above 100 that any conforming consumer can render, which is
+why the bound is the platform's limit and not a policy number.
+
+Unchanged in both directions: `scale: 100` still parses, `scale: 0` still parses, absence
+is still absence, and the malformed-declaration refusals from #8321/#12174 (`scale: -1`,
+`scale: 2.5`) keep their existing codes and their existing wording. `precision` is
+untouched on this row as on the object-field row — it is a total digit count that reaches
+neither primitive, so the renderer-ceiling argument does not carry to it.
+
+The number itself moves into `src/shared/scale-ceiling.ts`, a spec-internal leaf module
+that no package entry re-exports, so no published export moves and `check:api-surface`,
+`check:export-origins` and `check:declaration-map` all stay green. `data/field.zod.ts`
+keeps the module-private copy #18972 minted; a pin asserts the two sites refuse with
+byte-identical text, so the duplication is held equal rather than left to drift, and that
+file can adopt the shared module later as a pure delete-and-import.
+
+Shipped as `minor` under the repo's launch-window convention, in which
+`check-changeset-no-major` refuses `major` and breaking-ness is carried by this banner
+plus the ADR-0087 disposition rather than by the level.
+
+<!-- adr-0087: not-required (no-migration-prescription) no authorable key is renamed, retired or reshaped: `scale` keeps its name, its place on the form row and its type, and what moves is the top of one existing key's accepted numeric range. So `objectstack migrate meta` has nothing to visit — there is no stored spelling to rewrite and no FROM side to map, because the values this now refuses have no correct mechanical replacement: 101 fraction digits is not a precision a renderer can honour at all, and picking the display precision an author actually meant is their judgement, not a transform the ledger can carry. A ledger row would therefore have to invent the very semantics ADR-0078 and PD #12 forbid inventing, and the channel that does reach every affected author is the parse refusal itself, which names both primitives, the `RangeError` and the legal maximum at the moment the declaration is written. Measured on this tree at `7e52288463`: 126 `scale: N` declarations across `*.ts` / `*.tsx` / `*.json` / `*.mdx` / `*.yml` / `*.yaml` as the lit control, of which four read above 100 and all four are refusal fixtures or prose about them (two from #18972's tests, two from this branch's) — zero authored declarations above the ceiling. The instrument's radius is this repository's tracked file contents; the known target outside it is a `sys_metadata` row already stored in a running deployment's database, which no in-repo instrument reaches, and #18972 recorded the same blind spot. The other four categories are closed on facts: `@objectstack/spec` publishes to npm and declares no `private` (not `unpublished`); no ADR-0087 id is minted in this diff (not `registered`) and none pre-dating the base covers it (not `already-registered`); and the surface that moves is a Zod metadata schema, not a runtime-only TS interface and not a type annotation (neither `runtime-interface-only` nor `type-surface-only`). -->
@@ -0,0 +1,31 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): `JobSchema`'s own `@example` no longer opens with `id`, the key retired in 17.0.0 (#19184)
+
+The TSDoc `@example` on `JobSchema` opened with `id: "job_sync_meta"`. `id` was removed in
+17.0.0 (#4667, ADR-0049) and is tombstoned a dozen lines below the block that wrote it, so the
+example the schema publishes was refused **by that schema** on a verbatim copy:
+
+```
+JobSchema.safeParse(<the block as written>)
+  → success: false
+  → unrecognized_keys: ["id"]
+  → "Unrecognized key(s) on this job: `id`. • `job.id` was removed in @objectstack/spec 17.0.0 …"
+```
+
+The same object with the line deleted parses, so the one deleted line is the whole fix. An
+`@example` is read by whoever copies it before they read the key table — an author, and every
+agent writing job metadata from this schema — which is why a key the same file declares dead is
+the one thing it must not open with.
+
+Nothing about what a job may be written as changes here: the accept set, the key table, the
+tombstone and its prescription are all untouched, and the generated authorable-surface and
+JSON-Schema artifacts are byte-identical across the change. What ships is the corrected example
+itself — `src/**/*.zod.ts` is part of this package's published `files`, so the block travels in
+the tarball an upgrading consumer reads.
+
+Scope, stated because the adjacent block invites it: the file's second `@example` (on
+`defineJob`) carries no retired key and is untouched. The package-wide `@example` sweep is its
+own card.
@@ -409,6 +409,28 @@ jobs:
       - name: Raw control-byte guard
         run: pnpm check:nul-bytes
 
+      # Gitlink guard (#17472). Refuses an index entry at mode 160000 — a
+      # SUBMODULE POINTER — that no tracked `.gitmodules` row declares. Placed
+      # beside the control-byte guard because it is its structural sibling: a
+      # whole-index population, a hygiene property of what a CLONE receives, and
+      # a defect whose only native signal is a warning on a command that exits 0.
+      # WHY mode 160000 and why "undeclared" rather than "none at all" are stated
+      # and argued once, in the gate script's header — `scripts/check-gitlink-
+      # declared.mjs`. That header is authoritative and this comment cites it
+      # rather than restating it. The one-line summary, for whoever is reading
+      # this because the step just went red: `git add -A` over a nested git
+      # repository (a linked worktree, a nested clone, a vendored checkout)
+      # stages ONE 160000 entry at exit 0 with only a `warning:` line, and the
+      # commit that follows carries a pointer to an object no clone of this
+      # repository has. A real submodule passes untouched — `git submodule add`
+      # writes the declaration and the pointer in one act — so a hit here is
+      # never a submodule you added on purpose.
+      # ⛔ Not the untracked-signal half: PR #17468 closed that one by ignoring
+      # `.worktrees/`. This step is the STAGE, and it is path-blind on purpose.
+      # Reads the index only, no network, well under a second.
+      - name: Staged gitlinks are declared in .gitmodules
+        run: pnpm check:gitlink-declared
+
       # The first three of these are the shared modules the two `scripts/**`
       # routing gates below DELEGATE their design arguments to (#10608). Both of
       # those gates are
 
@@ -189,7 +189,7 @@ Column footer summary configuration
 | **min** | `number` | optional | Minimum value (for number/currency/percent/slider) |
 | **max** | `number` | optional | Maximum value |
 | **precision** | `integer` | optional | Total digits (non-negative integer; for number/currency) |
-| **scale** | `integer` | optional | Decimal places (non-negative integer) |
+| **scale** | `integer` | optional | Decimal places (integer 0-100). The upper bound is the platform's, not a policy: renderers turn `scale` into fraction digits through `toFixed` and `Intl.NumberFormat`'s `maximumFractionDigits`, both of which throw a RangeError above 100 — so a larger declaration is unrenderable by any conforming consumer. |
 | **multiple** | `boolean` | optional | Allow multiple values (for select/lookup/file/image) |
 | **label** | `string \| Record<string, string>` | optional | Display label override |
 | **placeholder** | `string \| Record<string, string>` | optional | Placeholder text |
@@ -354,7 +354,7 @@ View filter rule
 | **min** | `number` | optional | Minimum value (for number/currency/percent/slider) |
 | **max** | `number` | optional | Maximum value |
 | **precision** | `integer` | optional | Total digits (non-negative integer; for number/currency) |
-| **scale** | `integer` | optional | Decimal places (non-negative integer) |
+| **scale** | `integer` | optional | Decimal places (integer 0-100). The upper bound is the platform's, not a policy: renderers turn `scale` into fraction digits through `toFixed` and `Intl.NumberFormat`'s `maximumFractionDigits`, both of which throw a RangeError above 100 — so a larger declaration is unrenderable by any conforming consumer. |
 | **multiple** | `boolean` | optional | Allow multiple values (for select/lookup/file/image) |
 | **label** | `string \| Record<string, string>` | optional | Display label override |
 | **placeholder** | `string \| Record<string, string>` | optional | Placeholder text |
 
@@ -8,6 +8,16 @@
 
 ---
 
+> **Addendum (2026-09-18, #17778) — what the `*When` family does when it cannot RUN is decided by [ADR-0137](./0137-predicate-fault-semantics-are-contract.md), not here.**
+> This record unified the family under one NAME and is unchanged by that one. ADR-0137 D1 holds a
+> predicate slot to what the engine can actually run — an `ast`-only envelope and a `source` blank
+> after trimming are refused at authoring, which is the field-rule row of the rule decision batch
+> #122 item 2 gave across every evaluated slot; D2 refuses the SUBMIT loudly on a fault, naming the
+> field and the rule; D3 keeps visibility fail-OPEN at RENDER. A reader who arrived here asking what
+> a broken `visibleWhen` does should read that record.
+
+---
+
 ## TL;DR
 
 One concept — *"show this only when the CEL predicate is TRUE"* — is spelled three