Merge remote-tracking branch 'origin/main' into claude/issue-18336-retire-walled-legacy-grant-dual-read

Author: claude

.changeset/18118-retire-observability-cel-arms.md

@@ -0,0 +1,123 @@
+---
+'@objectstack/spec': minor
+---
+
+**BREAKING** — retire the CEL predicate arms of `ServiceLevelIndicator.successCriteria`
+and `TraceSamplingConfig.composite[].condition`, the two observability predicates nothing
+ever evaluated.
+
+Both slots were `z.union([<a structured arm>, <the evaluated expression schema>])`. The
+expression arm parsed, normalized a bare string to `{ dialect: 'cel', source }`,
+registered, and was served back — and **nothing anywhere evaluated it**. An identity scan
+over the whole tree finds every hit for `successCriteria`, `ServiceLevelIndicatorSchema`
+and `TraceSamplingConfigSchema` outside `packages/spec/src` to be a generated artefact or
+prose; inside it the only readers are the schemas' own unit tests and the two census tests
+that enumerate expression slots. No service, plugin, runtime or CLI path reads either key.
+So an author — very often an AI reading the generated reference page (ADR-0033) — who
+wrote `successCriteria: 'p95 < 300ms'` got a green parse and no signal, indistinguishable
+from a predicate that ran and answered.
+
+ADR-0049 enforce-or-remove; maintainer ruling 2026-09-18 (director decision batch #160
+item 3, letter A). By the standing criterion that a declared-but-unread capability is kept
+only when mainstream platforms in the domain have it: application platforms do not carry
+SLI success criteria or trace-sampling conditions as authorable application metadata —
+that lives in observability infrastructure (SLO products, OTel sampling policy) and is
+structured there, not a free expression. The `cron-declared-unwired` family was retired
+outright under the same ADR after the same measurement.
+
+## FROM → TO
+
+| you wrote (17.4 and earlier) | write instead |
+| --- | --- |
+| `successCriteria: 'p95 < 300ms'` | `successCriteria: { threshold: 300, operator: 'lt', percentile: 0.95 }` — the structured rule this slot has always carried |
+| `successCriteria: { dialect: 'cel', source: 'p95 < 300ms' }` | the same structured rule; the envelope spelling goes with the bare-string one |
+| `condition: 'record.amount > 10'` on a composite sampling branch | `condition: { service: 'api', attributes: { 'http.route': '/v1/orders' } }` — a structured filter object carrying no `dialect` key |
+| `condition: { dialect: 'cel', source: 'record.amount > 10' }` | the same structured filter; an object carrying `dialect` is refused as an expression attempt |
+
+**The one-line fix:** delete the predicate and write the structured shape the slot already
+carried. A criterion or a sampling rule the structured shape cannot express has no home in
+application metadata at all — it belongs in the SLO product or the OpenTelemetry sampler
+configuration that actually evaluates it. ⛔ Do not translate a predicate into a threshold
+by guessing the number: nothing was evaluating it, so there is no behaviour to preserve and
+a wrong number is worse than an absent one.
+
+## The retirement kit
+
+- **Neither KEY is retired — one ARM of each key's union is.** `successCriteria` and
+  `condition` both survive with their structured arm intact, so `retiredKey()` and an
+  ADR-0087 D2 strip are both the wrong tool: they retire a key. The prescription hangs on
+  the surviving schema's own `error` map, dispatched on `issue.input` — the
+  `HookBodyCapability` / `object.managedBy: 'system'` pattern for a narrowing a key
+  survives.
+- **Where the prescription reaches, measured on zod 4.4.** A schema's `error` map is
+  consulted for the top-level `invalid_type` a NON-OBJECT raises, and not for the child
+  issues a wrong-shaped OBJECT raises. So on `successCriteria` the bare-string spelling
+  carries the prescription and the `{ dialect, source }` envelope is refused by the
+  structured arm's own missing-key issues (`threshold`, `operator`). On `condition` both
+  spellings carry it, because the structured arm is a record whose aborting `dialect`
+  refine sees the object itself. Pinned both ways in the schemas' unit tests, the negative
+  included: a value refused for a reason that is NOT the retirement must not borrow its
+  sentence.
+- **ADR-0087 disposition: a D3 SEMANTIC entry**, `observability-cel-predicates-retired`,
+  not a D2 conversion. A predicate is an intent that no threshold/operator pair or
+  attribute filter records; a mechanical strip would delete what the author meant and leave
+  no trace of which SLI or which sampling branch lost it — and it would not even be lossless
+  in the weak sense, because `successCriteria` is REQUIRED (a strip leaves an SLI that no
+  longer parses) and a composite branch stripped of its `condition` declares no condition at
+  all. That is the one place this retirement parts company with the two precedents it copies
+  its MECHANISM from: `crypto.hash` on `HookBodyCapability` and `managedBy: 'system'` both
+  ALSO registered a D2 conversion, because for each of them a mechanical rewrite existed.
+  Here none does, which is what makes D3 the right disposition rather than merely an
+  available one. The prescriptions therefore carry **no** `os migrate meta` sentence — that
+  sentence is owed only where a conversion covers the surface.
+- **The same-major D3 record is absorbed, per the playbook's 「同 major 记账」.** The
+  `evaluated-expression-slots-source-required` entry landed into this same unpublished step,
+  and it enumerated these two slots among its 36 declaring positions while instructing the
+  upgrader to give a sampling `condition` a dialect and a non-blank `source` — the exact
+  envelope this head now refuses. Both entries first ship together, so the composite of the
+  two changes is the retirement alone: that entry now reads 34 positions, names the two
+  absentees and why, and routes them to this retirement instead of to its own repair.
+- **The surviving accept sets are pinned beside the refusals.** `successCriteria` still
+  takes `{ threshold, operator, percentile? }`; a composite `condition` still takes any
+  filter object carrying no `dialect` key — `{ source: 'x' }` included, because `source`
+  alone is an ordinary filter key and the retirement narrowed the `dialect` door only.
+- **FOUR published JSON Schemas change projection direction**, and it is mechanical rather
+  than chosen: the retired arm held the last `.transform()` in each of these subtrees, so
+  each def now projects in output mode instead of falling back to the input shape. All four
+  lose `x-io: input`, and what each gains differs:
+
+  | published schema | gains |
+  | --- | --- |
+  | `system/MetricsConfig` | `default: []` on `slis`, plus 8 `required` members |
+  | `system/TracingConfig` | `default: {"type":"always_on","rules":[]}` on `sampling`, plus 4 `required` members |
+  | `system/ServiceLevelIndicator` | one `required` member, `enabled` |
+  | `system/TraceSamplingConfig` | one `required` member, `rules` |
+
+  Only the first two carry a `default` move, so only those two are declarable in
+  `DEFAULT_CHANGES_BY_MAJOR` — the nested pair's `required` growth has no ratchet row to
+  live in and is stated here instead. A `required` that lists defaulted keys is this repo's
+  existing output-mode convention, not a new one, and the same-category control
+  `system/CacheConfig` is untouched. The reference pages show the same signature: the nested
+  type cells of both pages lose the `?` from their default-bearing keys. **No runtime default
+  moves** — measured twice, by byte-identity of the untouched `.default(…)` and by parsing a
+  minimal config on the built package.
+
+## What is deliberately NOT in this change
+
+- **The structured arms.** `{ threshold, operator, percentile }` and the sampling filter
+  record are equally unread today. The ruling says so and leaves them to their own card:
+  they carry no dialect and are outside the expression ledger's remit.
+- **`skills/objectstack-formula/SKILL.md`**, which still lists `metrics` / `tracing` under
+  `structured | cel`. The ruling assigns that correction to the skills lane, at tier, and
+  this diff does not touch it.
+- **`packages/spec/src/shared/expression.zod.ts`.** `EvaluatedExpressionInputSchema` is
+  untouched and stays the schema of every remaining evaluated slot; what left is two
+  references to it.
+
+Shipped as `minor` under the repo's launch-window convention, in which `major` is refused
+by `check-changeset-no-major` and breaking-ness is carried by the banner above plus the
+ADR-0087 disposition rather than by the level.
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered observability-cel-predicates-retired -->

.changeset/18550-reference-carrier-residue.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/objectql": minor
+"@objectstack/rest": minor
+"@objectstack/metadata-protocol": minor
+"@objectstack/lint": minor
+"@objectstack/verify": minor
+---
+
+The remaining raw `FieldSchema.reference` readers now **REFUSE** a carrier they cannot read, instead of answering "no target" (#18550). The previous release routed the arbiter (`referenceCarrierOf`) and the lint target readers; these were the measured residue of the same ruling — every reader, not just the arbiter.
+
+`FieldSchema.reference` is `z.string().optional()`, so `ObjectSchema.safeParse` refuses an object- or array-valued carrier at the contract door. These reads are the other door: the one a value reaches only when it never went through parse — a hand-built fixture, a raw `registerObject`, a stored row rehydrated past its schema.
+
+**`@objectstack/objectql`** — both of the delete cascade's carrier reads (`planCascadeAtomicity` and `cascadeDeleteRelations`). This is the one with a measurable runtime consequence, and it is why the level is not `patch`:
+
+```
+before   acct=1 task=1
+delete   RESOLVED true       <- success reported to the caller
+after    acct=0 task=1       <- an ORPHANED master_detail row
+```
+
+An unreadable carrier made the relation invisible to the cascade, so the parent was deleted, the detail row stayed, and the caller was told the delete succeeded — no `restrict` refusal, no `set_null`, nothing logged. It now refuses before any row is touched.
+
+**`@objectstack/rest`** — the public-form lookup picker's field-def fallback. The field def is also hoisted out of the metadata fetch's `catch {}`, so an unreadable carrier is no longer reported as `LOOKUP_TARGET_MISSING`: "no target is declared" and "the declared target cannot be read" want different fixes from whoever owns the metadata.
+
+**`@objectstack/metadata-protocol`** — the seed dependency graph, which also retires an `as string` cast that asserted exactly what its truthiness guard had not checked.
+
+**`@objectstack/lint`** — the four remaining target readers: `masterDetailCount` (`validate-expressions`), the `displayField` consumer edge (`validate-field-consumers`), the field and action-param targets (`validate-object-references`), and `masterOf` (`validate-sharing-rule-enforceability`).
+
+**`@objectstack/verify`** — `relationTarget`, which no longer degrades an unreadable carrier to the generic "has no `reference` target" an object with no relationship metadata at all receives.
+
+`null`, `undefined` and `''` are ABSENCE, not a wrong shape, and still answer `undefined` at every one of these sites — a field is allowed to name no target, and `StrictField` declares `reference` nullable. Each site's absence answer is pinned alongside its refusal.
+
+Upgrading: nothing conformant changes. A non-string `reference` could not be authored, stored or parsed before this release either; what changes is that one now fails loudly at the read instead of being read as an absent target. If a test asserted the old silence, assert the refusal instead.

.changeset/18762-cloud-adr-citation-sweep.md

@@ -0,0 +1,51 @@
+---
+'@objectstack/cloud-connection': patch
+---
+
+docs(cloud-connection): cite the cloud control-plane decisions as `cloud ADR-NNNN` instead of bare numbers that resolve to this repo's own records (#18762)
+
+AGENTS.md Prime Directive 13 is explicit — an ADR "lives in the repository whose
+code it governs", and a cloud decision is cited as `cloud ADR-NNNN`, "never as a
+bare number, which `scripts/check-adr-anchors.mjs` resolves against *this*
+registry (the two number independently)". The rule landed; the stock this
+package already carried was never swept.
+
+Read against this repository's registry, the bare numbers pointed at real but
+unrelated records:
+
+- `ADR-0008` → `docs/adr/0008-metadata-repository-and-change-log.md`, *Metadata
+  Repository, Change Log & Subscription (M0 → M4)* — zero occurrences of
+  "control plane", "cloud-connection" or "Phase 1"/"Phase 2".
+- `ADR-0007` → `docs/adr/0007-settings-manifest-and-kv-store.md`, *Settings —
+  Manifest + K/V Store + Resolver*. The cloud ADR-0007 these lines mean is the
+  one this repo's own ADR-0003 status line already names: the decision that
+  redefined `sys_package_installation` as management-plane desired state and put
+  runtime truth in the `LocalManifestSource` ledger.
+- `ADR-0009` → `docs/adr/0009-execution-pinned-metadata.md`, *Execution-Pinned
+  Metadata* — not the marketplace Setup-navigation ownership decision the lines
+  describe.
+
+That is worse than citing a number nobody has. A dangling id stops a reader; an
+id that resolves lets them believe they read the right page and walk away with
+the wrong decision.
+
+18 citations now carry the `cloud` qualifier, in the spelling this package
+already used elsewhere for the very same numbers — `cloud ADR-0008` in
+`connection-credential-store.ts`, `cloud ADR-0007 step ⑤` in
+`local-manifest-source.ts`, `cloud ADR-0009 P2a` in `marketplace-ui.ts`'s own
+header. All three numbers already carried both spellings inside this one
+package, and `marketplace-ui.ts` carried both inside a single file — qualified in
+its header on line 4, bare on lines 16 and 43.
+
+What actually reaches a consumer of this package:
+
+- The npm `description` field, which is the sentence shown on the package page.
+- `README.md`, including the closing pointer that already said "in the cloud
+  repository" while writing the number bare.
+- The published `.d.ts`, which carries the module and plugin docblocks.
+
+No behaviour moves. No type, export, route, schema or runtime path is touched —
+this is citation spelling and prose only, which is why it ships as a patch rather
+than silently. No ADR record is written or edited. `packages/cloud-connection/CHANGELOG.md`
+is deliberately untouched: it is published history, and a released entry is
+amended in a dedicated docs-only PR, never as a rider on code changes.

.changeset/18978-aggregate-surface-scope.md

@@ -0,0 +1,50 @@
+---
+'@objectstack/spec': minor
+---
+
+fix(spec): `spec-changes.json`'s aggregate export diff declares the release pair it really spans (#18978)
+
+Clause-②: yes (widening) — one new OPTIONAL key on a published artifact (`aggregate.surfaceScope`)
+and one new optional field on `SpecChangesSchema`. Nothing is renamed, retired or reshaped: the
+schema still ACCEPTS a record without it, every existing key keeps its spelling and meaning, and
+`perMajor` and the `release` section are byte-identical. Contract-review tier.
+
+`aggregate.added` / `aggregate.removed` are not registry-derived. A release-time api-surface diff
+fills them by comparing the artifact being published against the previously **published** one, so
+they span **one release** — while the record they sit in is keyed by protocol major (`from: 10,
+to: 17`) and every entry carries only `since: 17` / `removedIn: 17`, with
+`perMajor[16 → 17].added` at `0` beside it. Nothing in the file distinguished one minor's slice
+from the whole major-boundary delta.
+
+Measured on the published `@objectstack/spec@17.4.0` Release asset: `aggregate.added` = **225**,
+`aggregate.removed` = **51**, every entry `since`/`removedIn` = 17 — and set-identical to a
+recomputed `17.3.0 → 17.4.0` diff of the two tarballs' own `api-surface/` snapshots. It was the
+minor's delta wearing a major's label.
+
+**What ships now.** A record whose export arrays are non-empty carries the version pair they were
+diffed between:
+
+```bash
+jq '.aggregate | {from, to, surfaceScope, added: (.added | length), removed: (.removed | length)}' \
+  node_modules/@objectstack/spec/spec-changes.json
+```
+
+- `surfaceScope: { fromVersion, toVersion }` present ⇒ `added`/`removed` span exactly that
+  published-version pair. ⛔ They are **not** the `from` → `to` major delta, and never were.
+- `surfaceScope` absent ⇒ the record carries no export diff at all and `added`/`removed` are
+  empty. ⛔ Read that as "this record does not say", never as "nothing was added between `from`
+  and `to`" — the same rule the `release` section already states for itself.
+- `from` / `to` still answer the major-boundary question for `converted` / `migrated`, which are
+  registry-derived and unaffected.
+
+**Refused at the producer and at the publish gate, in both directions.** The generator reads the
+previous version off the previous artifact's own `package.json`, omits the arrays loudly when it
+cannot read one, and refuses outright to write a non-empty unlabelled array.
+`scripts/check-release-spec-changes.mjs` — which until now checked the `release` section and not
+the aggregate — recomputes the aggregate's claim from the two tarballs and refuses an absent,
+mislabelled or untrue scope. Its self-test roster grows from 15 batteries to 23.
+
+**Nothing previously honest moved.** The committed registry-only projection and every `perMajor`
+record carry no new key at all; the committed `spec-changes.json` changes on its `$comment` line
+and nowhere else. The published schema is deliberately not narrowed — every manifest published so
+far carries an unscoped diff and must keep parsing.