Merge remote-tracking branch 'origin/main' into claude/issue-17052-insert-failure-log-level

Author: claude

.changeset/adr-0112-envelope-refusal-declaration.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): the ADR-0112 error envelope gains a producer-side `refusal` declaration, so a deliberate 5xx refusal can keep its caller-authored `message` (#16335)
+
+`ApiErrorSchema` and `EnhancedApiErrorSchema` declare one new optional key, **`refusal: true`** — the producer's declaration that the 5xx it named is a deliberate REFUSAL whose `message` is authored for the caller, so the boundary keeps that message verbatim instead of withholding it. Director ruling, decision batch #58 (2026-09-06, option C): the refusal/fault distinction is a producer-side declaration on the published envelope — not a status heuristic and not a second allow-list.
+
+The three cases are now documented side by side on the envelope's TSDoc:
+
+- **undeclared 5xx** (no `status` on the throw) — unchanged: the leak heuristic decides per message.
+- **declared fault** (`status >= 500` + `code`, nothing declared here) — unchanged, and still the DEFAULT: `message` is withheld from the body and logged for the operator.
+- **declared refusal** (`status >= 500` + `code` + `refusal: true`) — new: `message` is kept verbatim, bounded exactly as a 4xx message is.
+
+Purely additive: a producer that says nothing here gets exactly the previous behaviour. `true` is the only value — `refusal: false` fails parse instead of becoming a third state consumers would have to interpret. `userMessage` is orthogonal (end-user text; it never replaces `message`) and may ride the same envelope; the TSDoc reconciles this flag with the recorded reason `userMessage` is a text-carrying field rather than "a boolean beside `message`".
+
+This is the spec half. The relay half — the three withhold arms reading the declaration (two in `@objectstack/rest`: `declaredServerFaultAnswer`, and `resolveErrorResponse`'s own 5xx passthrough arm, which the `/references` door reaches; one at `@objectstack/runtime`'s dispatcher exit, `errorResponseBase`, which `objectstack serve` mounts and which never consults the first), plus retiring the route-local patch from PR #16143 on `/meta/:type/:name/references` — is #16146 for the REST pair and its sub-issue #17153 for the runtime exit; until they land, a declared refusal is still withheld at the wire.

.changeset/artifact-granted-permissions-load-binding.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/runtime': minor
+---
+
+Bind an environment artifact's install-time GRANTED permission set to the packages that artifact materializes.
+
+`EnvironmentArtifactSchema.grantedPermissions` — the consented `{ services, hooks, network, fs }` set the control plane compiles onto the artifact at install-consent time (ADR-0025 §3.5 step 2 / F4) — now reaches `PluginPermissionEnforcer.registerGrantedPermissions` at materialize time, one call per consent record, keyed by the plugin manifest `id`. `AppPlugin.init()` performs the binding, so it happens on every path that turns an artifact into a kernel plugin without either caller changing a line, and the enforcer holding the result is readable as `AppPlugin.permissionEnforcer` (with `AppPlugin.grantBinding` recording what bound).
+
+Absent, `{}` and a consented entry stay three distinct states. An artifact carrying no `grantedPermissions` key allocates no enforcer and registers nothing, so a package with no consent record loads exactly as it did; a per-plugin `{}` is a consent record that consented to nothing and registers a bag that denies every service, hook, host and path. A consent record naming a package the artifact does not carry is reported at `warn` rather than passing in silence.
+
+Fixed alongside, because without it the binding was unreachable: the `{ schemaVersion, metadata }` envelope unwrap in `loadArtifactBundle` handed the kernel `metadata` alone and dropped every key standing beside it, so an envelope artifact reached the kernel with `grantedPermissions` stripped. The loss was silent and indistinguishable from the legitimate absent reading. The unwrap now carries the key across when the envelope declares it, `{}` included, and never invents one.
+
+New exports from `@objectstack/runtime`: `registerArtifactGrantedPermissions`, `resolveArtifactGrantBinding`, `carriedPackageIds`, `ArtifactGrantBinding`.
+
+This is the registration half. Access-time enforcement runs through `SecurePluginContext`, which no production path constructs; that seam is ADR-0025 install-flow work and is unchanged here.

.changeset/client-get-session-envelope-and-refresh-read.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/client": patch
+---
+
+fix(client): `auth.me` / `auth.refreshToken` deliver the `SessionResponse` envelope they declare, and `refreshToken` reads the token the route actually serves (#16760)
+
+Both methods annotate their return as `SessionResponse` — ObjectStack's REST
+`{ success, data }` envelope — for `GET /api/v1/auth/get-session`. better-auth
+owns those bytes and answers **bare**. Measured against a real `AuthManager`
+(better-auth 1.7.2, organization plugin) over a real driver:
+
+```
+GET /api/v1/auth/get-session  (signed in) -> 200 {"user":{…},"session":{…,"token":"…"}}
+GET /api/v1/auth/get-session  (anonymous) -> 200 null
+```
+
+So `(await client.auth.me()).data.user` type-checked and was `undefined` at
+runtime, while `.user` — the real payload — did not type-check. The annotation
+pointed every caller at the wrong key.
+
+## What changed
+
+- The bare answer is now lifted into the declared envelope, the same lift
+  `auth.login` has always carried for `/sign-in/email`. `SessionResponse` is
+  **unchanged** and so is each method's published return annotation: the fix is
+  in what the methods produce, not in what they promise.
+- The lift fills `success` as well as `data`. `SessionResponseSchema` is
+  `BaseResponseSchema.extend(…)` and that base declares `success` as a required
+  boolean, so a body carrying `data` alone still would not parse as the declared
+  type.
+- The raw `.user` / `.session` keys are **kept** alongside `data`. They are what
+  callers were pushed onto while the declared shape was unreachable; dropping
+  them would trade one silent breakage for another.
+- `auth.refreshToken` now reads `data.session.token`. It used to read
+  `data.data?.token` — a field this route does not produce at any nesting, so
+  the method returned successfully having captured nothing. A bearer-mode client
+  calling it to refresh kept whatever credential it already had, silently.
+
+## The read was not a consequence of the envelope
+
+Worth stating because the reverse is the natural assumption: enveloping the body
+does **not** put a token at `data.token`, because the route serves no top-level
+`token` to lift. The only credential in the body is `session.token`, and that is
+now the read. Fixing the shape alone would have left `refreshToken` exactly as
+inert as it was.
+
+## FROM → TO
+
+| you wrote | write instead |
+|:--|:--|
+| `(await client.auth.me()).user` | still works — kept deliberately |
+| `(await client.auth.me()).data.user` | now populated (was `undefined`) |
+| `(await client.auth.refreshToken(t)).data.token` | `.data.session.token` |
+
+`refreshToken` stores the **unsigned** session token, which is the spelling
+`/get-session` serves; `bearer()` accepts it and the signed
+`token.signature` form interchangeably, so a client that held the signed form
+stays signed in across the call.
+
+Two answers stay outside the declared type and are **not** addressed here: the
+anonymous `null`, which would need the published return annotation to widen, and
+`SessionUser.image`, declared `z.string().optional()` against a route that
+serves `null` (#17235). The sibling `auth.login` / `auth.register`, which
+normalize into `data` but set no `success`, are #17234.

.changeset/dashboard-item-level-property-names.md

@@ -0,0 +1,59 @@
+---
+"@objectstack/spec": minor
+"@objectstack/rest": patch
+"@objectstack/platform-objects": patch
+---
+
+feat(spec): a metadata-form repeater's row properties have a name — `DashboardHeaderAction` fields carry a JSON Schema `title`, and `resolveMetadataFormSchemaTitles` overlays a bundle's `metadataForms.<type>.fields.<path>.label` onto a derived JSON Schema (#16458)
+
+## What was wrong
+
+The Studio property panel renders `dashboard.header.actions[]` as a table whose
+column headers read `items.properties[k].title ?? k` from the JSON Schema
+derived by `z.toJSONSchema(DashboardSchema)`. None of the four item fields
+(`label`, `actionUrl`, `actionType`, `icon`) carried a `title`, so the fallback
+arm ran for every locale, English included, and the maker saw machine keys.
+Nothing could localise them either: the only channel, `resolveMetadataFormLabels`,
+decorates the `FormFieldSpec` tree, which the table never reads. And the platform
+catalogs carried `dashboard.fields.header` alone — `dashboard.form.ts` declared
+no children under the composite, so `os i18n extract` emitted no
+`header.showTitle` / `header.showDescription` / `header.actions` key and the
+console shipped a private overlay for exactly those three.
+
+## What changed
+
+- **`@objectstack/spec`** — `DashboardHeaderActionSchema`'s four fields author
+  `.meta({ title })` (`Label`, `Action URL`, `Action Type`, `Icon`), so the
+  derived JSON Schema names each column. New export
+  `resolveMetadataFormSchemaTitles(schema, type, bundle, opts)` in
+  `@objectstack/spec/system`: every `metadataForms.<type>.fields.<path>.label`
+  at any locale of the chain becomes the `title` of the node the path addresses,
+  stepping through an array's `items` so a repeater ROW property is addressed
+  as `<repeater>.<property>` (`header.actions.label`) — the same path the
+  extractor emits. Pure; returns the input object itself when nothing applies.
+  `dashboardForm` enumerates the `header` composite's children
+  (`showTitle`, `showDescription`, `actions` with its four row properties) with
+  labels equal to the schema titles, pinned equal in `dashboard.test.ts`.
+  The mechanism is written down in `content/docs/protocol/kernel/i18n-standard.mdx`
+  → "Metadata authoring forms".
+- **`@objectstack/rest`** — `GET /api/v1/meta` localises each entry's derived
+  `schema` beside its `form`, through that overlay.
+- **`@objectstack/platform-objects`** — the four generated `metadata-forms`
+  catalogs carry the seven new `dashboard.fields` keys, translated in `zh-CN`,
+  `ja-JP` and `es-ES`.
+
+Additive: no key removed, no accept set changed, no parsed output moved.
+
+`DashboardSchema.columns` deliberately still declares no `.default(12)`, and
+the reason is stronger than the one #16458 assumed. The card reasoned that the
+renderer already falls back to 12, which would make `.default(12)`
+behaviour-preserving. Measured at objectui `origin/main`
+(`packages/plugin-dashboard/src/DashboardRenderer.tsx`), it does not: a
+`columns`-less dashboard is INFERRED from the widget spans — `maxSpan > 4`
+yields 12 and everything else yields **4** — and the next line switches the
+whole layout on that value (`hasExplicitColumns = schema.columns != null ||
+inferredColumns !== 4`, positioned grid vs responsive auto-flow). Declaring the
+default would therefore both retire the inference and flip every auto-flow
+dashboard into the positioned grid. A default that silently materialises a key
+is expensive to take back, so the round stopped at the declared condition and
+left the key alone; see #16458.

.changeset/generate-migration-emits-declared-unique-index.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os generate migration` emits the field-level unique index the driver creates (#16317)
+
+## What was wrong
+
+Both migration formats emitted the table and none of the object's declared
+uniqueness. Measured on live PostgreSQL 16.13 — one object driven through all
+three producers into three schemas, `pg_indexes` read back per schema:
+
+```ts
+{ name: 'probe', fields: { keyed_unique: { type: 'text', unique: true, maxLength: 100 } } }
+```
+
+| producer | before | after |
+|:--|:--|:--|
+| `driver-sql` via `initObjects` | `probe_pkey`, `uniq_probe_keyed_unique` | unchanged |
+| `--format sql` | `probe_pkey` | `probe_pkey`, **`uniq_probe_keyed_unique`** |
+| `--format ts` | `probe_pkey` | `probe_pkey`, **`uniq_probe_keyed_unique`** |
+
+Two rows with the same `keyed_unique` value were refused by the platform's table
+(`23505 ... violates unique constraint "uniq_probe_keyed_unique"`) and accepted
+by both generated ones, with nothing reporting it: a scaffold that creates the
+table for an object silently dropped a uniqueness guarantee the object declares.
+After the change the duplicate is refused by all three, each naming the same
+constraint.
+
+The key set was not missing — it was already computed here to size the keyed
+text family's columns; only the index it implies was never emitted.
+
+## What it does now
+
+- **`--format sql`** emits an inline `CONSTRAINT "<name>" UNIQUE (<columns>)`.
+  That is what knex's `table.unique(columns, { indexName })` — the driver's own
+  call — compiles to on PostgreSQL, so a generated table and a platform-created
+  one agree in `pg_constraint` as well as in `pg_indexes`; and it stays inside
+  the statement's `IF NOT EXISTS`, which a following `ALTER TABLE ... ADD
+  CONSTRAINT` has no spelling for.
+- **`--format ts`** emits that knex call itself, `indexName` included — which is
+  what makes the driver recognise the constraint as already present on its first
+  boot against a generated table, instead of adding a second one under its own
+  name and then reporting the generated one as an orphan to drop.
+- Names come from a transcription of `driver-sql`'s `buildIndexName`, pinned
+  against the driver's own export (a CLI production module may not statically
+  value-import a driver package).
+
+## What it deliberately still does not emit — and now says so
+
+Both formats print a `NOT EMITTED:` line naming the index, its key parts and the
+reason, instead of dropping it silently:
+
+- the **organization-scoped composite** (`unique: true` / `'organization'` on an
+  object with an organization column), whose key part is
+  `COALESCE(<organization column>, '__global__')`. Emitting the bare composite
+  instead would be worse than emitting nothing: under SQL's NULL-distinct
+  `UNIQUE` it constrains no row that has no organization, which on a
+  single-tenant deployment is every row.
+- an index over a column no field materialises (a virtual `formula` field) —
+  the same skip the driver performs, where the driver logs a warning.
+
+Object-level `indexes[]` remains unemitted by both formats; it is normalized by
+a different driver-side rule and is not covered by this change.

.changeset/generator-declared-column-default.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): a generated migration carries the column DEFAULT `driver-sql` puts on the same field (#16294)
+
+## What was wrong
+
+Neither `os generate migration` format read a field's `defaultValue`, so a table
+created from a generated migration had no column DEFAULT where the platform's
+own table has one. A row inserted out of band — by a database client, a seed
+script, anything that does not go through the engine — got NULL where the
+declared value belonged.
+
+Driven on live PostgreSQL 16.13: one object, three schemas, one producer each
+(`driver-sql` through `initObjects`, `--format sql` through `db.raw`,
+`--format ts` by importing the emitted module and calling `up(db)`), with
+`information_schema.columns` read back per schema.
+
+```
+field                driver                          sqlgen               verdict
+f_default            null=YES default='hello'::text  null=YES default=-   DIVERGED
+f_default_required   null=YES default='hello'::text  null=YES default=-   DIVERGED
+```
+
+After: `diverged: 0 of 6` on the card's probe, and 22 of 23 on a wider one
+covering every `defaultValue` shape.
+
+## What changed
+
+Both formats now render one shared verdict, taken from
+`SqlDriver.applyDeclaredColumnDefault` — the single place a `defaultValue`
+becomes DDL on the platform side:
+
+- a **literal** is emitted, quoted the way knex binds it (`DEFAULT '42'`, not
+  `DEFAULT 42` — PostgreSQL keeps those two textually apart forever in
+  `column_default`, and the driver's column carries the quoted form);
+- **`'NOW()'`** becomes the driver's own translation, which is type-branched:
+  `CURRENT_TIMESTAMP` on a timestamp column, and a UTC-pinned expression on
+  `date` / `time`, because a bare `CURRENT_TIMESTAMP` resolves those in the
+  server's timezone;
+- **any other runtime token** (`current_user`), an **Expression envelope** and
+  an **option-level `default: true`** emit nothing, each because the driver
+  emits nothing — the engine owns those, and a column DEFAULT would override a
+  decision it makes deliberately;
+- a **`multiple: true`** field gets neither, because `createColumn` returns
+  before both questions.
+
+No authorable key, export or accepted-input set changes: `defaultValue` was
+already declared, already parsed and already honoured by the driver. The
+generators simply now read it.