Merge origin/main (4d1d9d9) into claude/issue-19133-governed-tiers — the north-star row keeps main's position with its tier; PD #14 keeps the tiered paragraph

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BTeBejoPUvRHN8WdAJC6oF

Author: os-dev

.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/18728-identity-wires-relay-the-spec.md

@@ -0,0 +1,29 @@
+---
+"@objectstack/spec": minor
+"@objectstack/client": minor
+"@objectstack/plugin-auth": minor
+---
+
+The identity read routes now serve what `@objectstack/spec/identity` declares: `metadata` arrives DECODED on every organization route that reads the row back, and `updatedAt` is declared optional on `Organization` / `Member` / `Invitation` — the shape better-auth's own serializer documents (#18728).
+
+Clause-②: yes (widening) — `updatedAt` moves from required to optional on three published schemas, so the set a consumer may hand to `OrganizationSchema` / `MemberSchema` / `InvitationSchema` grows by exactly one shape: the key being absent. Nothing previously admitted is refused, nothing is renamed, and no producer is required to write it. Contract-review tier.
+
+Three published schemas could not parse a served response. `OrganizationSchema` declared `updatedAt` required and `metadata` an object; the four organization read routes (`setActive`, `get`, `delete`, `list`) carried no `updatedAt` at all and served `metadata` as the stored JSON text. `@objectstack/client` had recorded that as three 「not relayed」 notes rather than as a defect, and with zero in-repo consumers nothing went red — the audience was entirely external. Maintainer ruling C (batch #158 item 4) fixed the producer and made the one remaining key conditional on a measurement, which is what decided each half:
+
+- **`metadata` is decoded at the producer, unconditionally** — it is our column. plugin-auth's data adapter decodes `sys_organization.metadata` out of its stored JSON text on its READ verbs, so all four routes serve the object the spec declares, and an unset column is OMITTED rather than sent as `null`. ⛔ The write verbs are deliberately untouched: better-auth's own organization adapter decodes the `create` / `update` echoes itself and discriminates on the value still being a string, so decoding there would fold the create echo's `metadata` to `undefined`. Both directions are pinned.
+- **`updatedAt` aligns to the documented wire** — ruling C's own fallback A, and its two conditions were measured against the installed better-auth 1.7.3 rather than assumed. The routes are better-auth's endpoints mounted through a single catch-all, each answering `ctx.json(...)` with no ObjectStack post-processing; and the vendor's `organization`, `member` and `invitation` models declare no `updatedAt` field, while its adapter factory's output transform iterates the declared fields only, so an undeclared column is dropped before any route sees it. Control, in the same file: the vendor's `team` and `organizationRole` models DO declare `updatedAt`, so the absence is a reading. For `member` and `invitation` there is additionally no column to serve — `sys_member` and `sys_invitation` are `managedBy: 'better-auth'`, the one disposition under which the platform injects no audit family, and neither declares `updated_at` itself.
+- **`@objectstack/client` relays the schemas.** `OrganizationWire` is the spec's `Organization`, `OrganizationMemberWire` is `Member`, and `OrganizationInvitationWire` is `Invitation` with `status` narrowed per route plus the three members the platform adds on top (`teamId` and the two ADR-0105 D8 placement fields, which the non-strict schema strips). The three 「not relayed」 notes are gone.
+- **The negative controls are the point.** "The client relays the spec schemas" and "the client stopped validating" look identical from a green positive test, so every accepted body is paired with a refused one — a required field genuinely missing, `metadata` still arriving as the stored JSON TEXT, and a `createdAt` or `updatedAt` present but not a datetime. `.optional()` widened the accept set by absence ONLY; a value that is there is still held to `z.string().datetime()`.
+
+**Not declared breaking, and the reason is the repo's own criterion** rather than the level being convenient. AGENTS.md binds the breaking class to removing or renaming something an author can write, and to the `(narrowing)` arm of the clause-② pair. Neither holds here: nothing is removed, renamed or retired; the one `packages/spec` edit only widens an accept set; and the `metadata` half is a producer brought into line with a contract this package has published all along — `OrganizationSchema.metadata` has declared an object since it was written, and the client's own comment called the served text 「not relayed」 rather than a shape anyone was promised. No ADR-0087 disposition is claimed because no breaking change is declared: no authored metadata moves, so `objectstack migrate meta` has nothing to visit, `spec-changes.json` has nothing to project and the upgrade guide has no row to gain. These three schemas are not metadata types — not in `DEFAULT_METADATA_TYPE_REGISTRY`, no authorable surface. ⚠️ Stated here rather than assumed silently, because it is the one judgement in this diff that the contract review the `Clause-②: yes` declaration commissions should confirm.
+
+**What a consumer notices**, and where it is delivered: `organization.metadata` was the stored JSON text and is now the decoded object, so a caller that decoded it itself drops that step.
+
+```ts
+// before — the caller decoded what the route sent
+const meta = JSON.parse(org.metadata ?? '{}');
+// after — the producer decoded it; the key is ABSENT when unset
+const meta = org.metadata ?? {};
+```
+
+The channel that reaches that caller is the compiler, on the line that used to work: `JSON.parse` no longer accepts the value. `updatedAt` needs nothing in either direction — it was never on this family's wire, so no caller can have been reading a value, and the declaration now says so out loud instead of promising one.

.changeset/alias-citations-two-roles-sweep.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/spec': patch
+'@objectstack/objectql': patch
+---
+
+Correct six `edit distance cannot reach` citations that are measurably false, and pin the role each alias entry actually plays.
+
+`aliases` has two jobs, not one: filling a gap the distance fallback leaves empty, and overruling a hit the fallback reaches and gets wrong. The lookup is `aliases[aliasProbe(key)] ?? findClosestMatches(key, knownKeys, budget, 1)[0]` — the table is consulted first and wins outright — and the budget is `Math.max(2, Math.floor(key.length / 3))`. A sentence saying distance "cannot reach" the cited case denies the second job, and in three places the cited case is itself an example of it.
+
+- **`latitude` → `lat` is an OVERRULE, not a gap** (`data/field-value.zod.ts`, `data/default-value-shape.ts`, `data/field-value.test.ts`, `data/default-value-shape.test.ts`, objectql `validation/record-validator.ts`). `latitude` is 8 characters, so the budget is 2; `lat` is 5 edits away and out of reach, but the declared `altitude` is exactly 2 — so without the curated entry the bare fallback answers `latitude` → `altitude` and points an author who wrote a GPS latitude at the elevation member. Four docblocks cited this pair as proof that aliases exist only where distance reaches nothing.
+- **`postal_code` → `postalCode` never involved an alias at all** (`data/default-value-shape.ts`). Scoring folds case and separators on both sides, so it is 1 edit against a budget of 3 — the worked example rendered in that docblock is the fallback's own answer, not the `AddressValueSchema` table's.
+- **`uri` → `url` is reachable and agreeing** (`data/driver/turso.zod.ts`). The block was headed "the spellings edit distance cannot reach"; that is true of five of its six rows and false of `uri`, which is 1 edit from `url` against a budget of 2. The row is a pin on an answer the fallback already gets right, not a gap-filler.
+
+Prose plus new pins. No alias is added or removed, no schema, key list, strictness, suggestion or error message changes: `Clause-②: no`. The three roles are now asserted — `longitude` (gap), `latitude` (overrule, with the negative half), `altitud` (a plain typo still riding the fallback) in `data/field-value.test.ts`, and `dsn` (gap) beside `uri` (reachable) in `data/driver/turso.test.ts`.