Merge remote-tracking branch 'origin/main' into claude/issue-20802-relation-filter-lowering

Author: claude

.changeset/20513-objectql-runtime-strings-state-the-decision.md

@@ -0,0 +1,35 @@
+---
+'@objectstack/objectql': patch
+---
+
+objectql refusals, log lines and metadata text no longer cite tracker numbers; each states the reason in words
+
+Clause-②: no
+
+Many messages the query engine shows to authors, administrators and operators ended with an
+issue-tracker number where the reason belonged. The number goes, and where the sentence did not
+already say what was decided, it now does:
+
+- Refusals: the bulk update and bulk delete row-scoping refusals now name the seed they are missing
+  (the AST seeded before the middleware chain, which RLS and sharing compose their row-scoping onto,
+  so a bulk write reaches only the rows the caller may edit); the hook-target rebind refusal says
+  why `delete()` stopped honouring a rebind (a handler that silently redirects which row gets
+  deleted is a trap) and names the `dispatchUnscopedMultiWrite` registration the whole-operation
+  dispatch goes to, on update and delete alike. The unknown-option, filter-array,
+  credential-aggregation, HAVING-operator, empty-hook-target, strict read-only and system-write
+  organization refusals lose only the citation, because their sentences already said it.
+- Metadata text: the lifecycle `retention_overrides` setting description and the search companion
+  field description lose their citation.
+- Log lines: the non-atomic cascade warning says a single-datasource cascade is now one
+  transaction; the system-ledger transaction line calls the ledger the one class carved out of the
+  cross-datasource write refusal; the dangling-reference audit summary says findings are reported,
+  never rewritten, because a system-context write is exempt from the write-time reference check;
+  the legacy `apiMethods` warning says the authorable values are the six primitives only, every
+  other operation being derived from them or retired; the two unevaluable-rule warnings say such a
+  rule fails closed and is never skipped. The ADR-0104 value-shape gate lines, the delegated
+  protocol-assembly line and the read-only and runtime-owned strip warnings lose only the citation.
+
+The `findOne` no-predicate refusal keeps its citation for now: `@objectstack/metadata-core`
+carries a byte-identical copy that this package's tests compare against, and both move together.
+
+Text only: no error code, field name, status or behaviour changes.

.changeset/20841-blueprint-nav-label-inherits.md

@@ -0,0 +1,18 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): `BlueprintNavItemSchema.label` says an absent label is inherited at render time, not defaulted by the expander
+
+Clause-②: no
+
+The `label` describe on a blueprint nav item read "defaults to the target label/name". An
+expander or an AI author that follows "defaults" copies the target's label into the entry, and
+the entry then stops following a rename of that target. The runtime nav entry's `label` has
+meant something else since it became optional: absent, the entry inherits the CURRENT label of
+what it opens at render time; present, it renders verbatim. The blueprint describe now says
+exactly that, and tells the author not to copy the target's label in as a default.
+
+Describe text only: the key stays `z.string().optional()`, so the schema accepts and refuses
+the same blueprints. The reference page `content/docs/references/ai/solution-blueprint.mdx`
+is regenerated from it.

content/docs/references/ai/solution-blueprint.mdx

@@ -53,7 +53,7 @@ const result = BlueprintAppSchema.parse(data);
 | :--- | :--- | :--- | :--- |
 | **type** | `Enum<'object' \| 'dashboard'>` | optional (default: `"object"`) | What this nav entry opens |
 | **target** | `string` | ✅ | Object or dashboard machine name to surface (snake_case) |
-| **label** | `string` | optional | Nav entry label (defaults to the target label/name) |
+| **label** | `string` | optional | Nav entry label. Optional: absent ⇒ the entry inherits the CURRENT label of what it opens at render time (a renamed target shows its new name); present ⇒ rendered verbatim, so never copy the target's label in as a default. |
 | **icon** | `string` | optional | Lucide icon name for the nav entry |
 | **viewName** | `string` | optional | For type:"object" only — the `views[].name` this entry opens (e.g. "ticket_status_board"). Omit for the object's default list. SET it whenever this blueprint authors a kanban/calendar/gallery/gantt view the menu should reach: give the object ONE entry per view (a 「工单列表」 entry with no viewName plus a 「工单看板」 entry with viewName:"ticket_status_board"). Without it every entry on the same target opens the SAME default list, and a label/icon saying otherwise is decoration. |
 
@@ -187,7 +187,7 @@ const result = BlueprintAppSchema.parse(data);
 | :--- | :--- | :--- | :--- |
 | **type** | `Enum<'object' \| 'dashboard'>` | optional (default: `"object"`) | What this nav entry opens |
 | **target** | `string` | ✅ | Object or dashboard machine name to surface (snake_case) |
-| **label** | `string` | optional | Nav entry label (defaults to the target label/name) |
+| **label** | `string` | optional | Nav entry label. Optional: absent ⇒ the entry inherits the CURRENT label of what it opens at render time (a renamed target shows its new name); present ⇒ rendered verbatim, so never copy the target's label in as a default. |
 | **icon** | `string` | optional | Lucide icon name for the nav entry |
 | **viewName** | `string` | optional | For type:"object" only — the `views[].name` this entry opens (e.g. "ticket_status_board"). Omit for the object's default list. SET it whenever this blueprint authors a kanban/calendar/gallery/gantt view the menu should reach: give the object ONE entry per view (a 「工单列表」 entry with no viewName plus a 「工单看板」 entry with viewName:"ticket_status_board"). Without it every entry on the same target opens the SAME default list, and a label/icon saying otherwise is decoration. |
 

packages/objectql/src/engine-dropped-fields-primary-key.test.ts

@@ -315,7 +315,7 @@ describe('#6437 — the refusal message is composed from `drops`, not from the c
       `API-boundary caller, isSystem included. A value DERIVED by a beforeUpdate hook is ` +
       `not a caller write and is never stripped — that is the sanctioned write path for a ` +
       `conditionally-locked derived field). To let the strip happen and merely observe it, drop ` +
-      `strictReadonlyWrites and pass options.onFieldsDropped instead (#3407).`,
+      `strictReadonlyWrites and pass options.onFieldsDropped instead.`,
     );
   });
 

packages/objectql/src/engine.ts

@@ -781,7 +781,7 @@ function rejectUnknownEngineOptions(
   throw new Error(
     `${operation}('${object}') does not recognise option${unknown.length > 1 ? 's' : ''} ` +
     `${details.join('; ')}. The engine executes none of ${unknown.length > 1 ? 'them' : 'it'}, ` +
-    `so the call would succeed with the option silently ignored (#4371). ` +
+    `so the call would succeed with the option silently ignored. ` +
     `Legal keys for ${operation}: ${[...legal].sort().join(', ')}.`,
   );
 }
@@ -1089,7 +1089,7 @@ function lowerWhereFilterArray<T extends object | undefined>(
       `${JSON.stringify(where)}. A filter array is a comparison [field, operator, value], ` +
       `a logical node ["and"|"or", ...conditions], or a list of those — it is INPUT-ONLY ` +
       `sugar (spec 'FilterArray'), lowered to a FilterCondition here before any driver sees ` +
-      `it (#5158). This value cannot be lowered, and an unapplied filter would have returned ` +
+      `it. This value cannot be lowered, and an unapplied filter would have returned ` +
       `the UNFILTERED result set. Recognised operators: ` +
       `${[...VALID_AST_OPERATORS].sort().join(', ')}. Infix joins ([condA, "or", condB]) are ` +
       `NOT one of the shapes — write the prefix form ["or", condA, condB].`,
@@ -1112,7 +1112,7 @@ function lowerWhereFilterArray<T extends object | undefined>(
     throw new Error(
       `${operation}('${object}'): filter array ${JSON.stringify(where)} passed isFilterAST() ` +
       `but parseFilterAST() lowered it to nothing. Refusing rather than running the query ` +
-      `unfiltered (#5158).`,
+      `unfiltered.`,
     );
   }
   // [#5869] Door 2's half of the same check USED to be a second
@@ -9688,7 +9688,7 @@ export class ObjectQL implements IObjectQLEngine {
       FILE_REFERENCES_MIGRATION_ID,
       '[value-shape] this deployment has verified the file-as-reference migration — ' +
         'media value shapes are enforced and released field files may be collected ' +
-        '(ADR-0104 / #3617)',
+        '(ADR-0104)',
     );
   }
 
@@ -9736,7 +9736,7 @@ export class ObjectQL implements IObjectQLEngine {
       'valueShapesMigrationVerified',
       VALUE_SHAPES_MIGRATION_ID,
       '[value-shape] this deployment has verified the value-shape scan — reference and ' +
-        'structured-JSON value shapes are enforced (ADR-0104 / #3438)',
+        'structured-JSON value shapes are enforced (ADR-0104)',
     );
   }
 
@@ -10039,7 +10039,7 @@ export class ObjectQL implements IObjectQLEngine {
             'no byte is deleted on evidence this deployment has contradicted. Fix the data and run ' +
             '`os migrate ' +
             (migrationId === FILE_REFERENCES_MIGRATION_ID ? 'files-to-references' : 'value-shapes') +
-            ' --apply` to clear it (ADR-0104 / #4797).',
+            ' --apply` to clear it (ADR-0104).',
         );
       })
       .catch((err: any) => {
@@ -10050,7 +10050,7 @@ export class ObjectQL implements IObjectQLEngine {
           `[value-shape] could not record the observed deviation for '${migrationId}' ` +
             `(${err?.message ?? err}) — the ledger still authorises irreversible collection while ` +
             'this deployment holds a value its own contract rejects; run the migration to ' +
-            're-derive the gate (#4797)',
+            're-derive the gate',
         );
       });
   }
@@ -10141,7 +10141,7 @@ export class ObjectQL implements IObjectQLEngine {
             `(${tally?.first.object}.${tally?.first.field}: ${tally?.first.detail}). ` +
             'The gate is closed again — fix the data, then run `os migrate ' +
             (migrationId === FILE_REFERENCES_MIGRATION_ID ? 'files-to-references' : 'value-shapes') +
-            ' --apply` to re-earn it (ADR-0104 / #4769).',
+            ' --apply` to re-earn it (ADR-0104).',
         );
       })
       .catch((err: any) => {
@@ -10150,7 +10150,7 @@ export class ObjectQL implements IObjectQLEngine {
         this.logger.warn(
           `[value-shape] could not revoke the creation attestation for '${migrationId}' ` +
             `(${err?.message ?? err}) — the ledger still claims this deployment is verified ` +
-            'while its data contradicts that; run the migration to re-derive it (#4769)',
+            'while its data contradicts that; run the migration to re-derive it',
         );
       });
   }
@@ -10226,15 +10226,15 @@ export class ObjectQL implements IObjectQLEngine {
           '[value-shape] media values are checked but NOT enforced here, and released files are ' +
             'never collected — this deployment has not verified its file migration. Run ' +
             '`os migrate files-to-references` (dry run) to see what it would do, then `--apply` ' +
-            'to close the gate (ADR-0104 / #3617).',
+            'to close the gate (ADR-0104).',
         );
       }
       if (covered && !(await this.readMigrationFlagVerified(VALUE_SHAPES_MIGRATION_ID)).verified) {
         this.logger.info(
           '[value-shape] reference and structured-JSON values are checked but NOT enforced here — ' +
             'this deployment has not verified its value-shape scan. Run `os migrate value-shapes` ' +
             '(dry run) to see what it would report, then `--apply` to close the gate ' +
-            '(ADR-0104 / #3438).',
+            '(ADR-0104).',
         );
       }
     } catch {
@@ -14191,7 +14191,9 @@ export class ObjectQL implements IObjectQLEngine {
            if (!ast) {
                throw new Error(
                  `[Security] Refusing bulk update on '${object}': row-scoping AST was not seeded ` +
-                   `(the predicate branch was reached without the #2982 seed).`,
+                   `(the predicate branch was reached without the AST seeded before the middleware ` +
+                   `chain — the one RLS and sharing compose their row-scoping onto, so that a bulk ` +
+                   `write reaches only the rows this caller may edit).`,
                );
            }
            // [#9974] The unscoped-multi shape check, BEFORE the matched-row
@@ -15373,7 +15375,8 @@ export class ObjectQL implements IObjectQLEngine {
       `Cascade delete of '${object}' cannot run as one unit of work: the cascade reaches an object routed ` +
         `to a datasource other than the default one ('${this.defaultDriver ?? '<none>'}'), and a transaction ` +
         "covers one driver's connection only (ADR-0119 D1 — no two-phase commit). The cascade therefore runs " +
-        'UNWRAPPED, exactly as it did before #7413: if a later dependent refuses the delete, the rows already ' +
+        'UNWRAPPED, as every cascade did before a single-datasource cascade was made one transaction: if a ' +
+        'later dependent refuses the delete, the rows already ' +
         'removed stay removed while the call rejects. Route the cascading objects to one datasource to get the ' +
         'atomic path. Reported once per object per engine instance.',
       { object, defaultDatasource: this.defaultDriver ?? undefined },
@@ -16511,7 +16514,9 @@ export class ObjectQL implements IObjectQLEngine {
         if (!ast) {
           throw new Error(
             `[Security] Refusing bulk delete on '${object}': row-scoping AST was not seeded ` +
-              `(the predicate branch was reached without the #2982 seed).`,
+              `(the predicate branch was reached without the AST seeded before the middleware ` +
+              `chain — the one RLS and sharing compose their row-scoping onto, so that a bulk ` +
+              `write reaches only the rows this caller may edit).`,
           );
         }
         // [#9719] The unscoped-multi shape check, BEFORE the matched-row read:
@@ -16835,7 +16840,7 @@ export class ObjectQL implements IObjectQLEngine {
           + 'secret/password fields are masked on read and `internal: true` fields are omitted '
           + 'outright, so the value never leaves the engine on the generic data path; aggregating '
           + 'them (group-by, min/max, array_agg, …) would surface it. '
-          + 'Refusing (fail-closed) — see ADR-0100 / #3171 / #7922.',
+          + 'Refusing (fail-closed) — see ADR-0100.',
       );
     }
   }
@@ -17599,7 +17604,8 @@ export class ObjectQL implements IObjectQLEngine {
     this.logger.debug(
       `${operation} of '${objectName}' inside transaction() is routed to datasource '${target}' while the ` +
         `transaction is open on '${scope.datasource}' — executing it OUTSIDE the transaction, on its own ` +
-        'connection (ADR-0057 §3.6 system ledger, carved out by #5351). It commits independently and will ' +
+        'connection (ADR-0057 §3.6 system ledger — the one class carved out of the cross-datasource write ' +
+        'refusal). It commits independently and will ' +
         'SURVIVE a rollback of this transaction: an audit/telemetry/event row may describe a write that was ' +
         'undone. That is the decided direction of error for an append-only ledger — an extra reconcilable ' +
         'row beats a missing row for a write that did commit. Said once per transaction per datasource.',

packages/objectql/src/having-filter.ts

@@ -325,7 +325,7 @@ function unknownOperator(
   return invalidFilterError(
     `Unsupported operator '${op}' in \`${clause.root}\`. ${clause.semantics} and supports: ${supported}. `
     + `An unknown operator is refused rather than ignored — ignoring it would silently `
-    + `return unfiltered aggregates (#4286, ADR-0078).`,
+    + `return unfiltered aggregates (ADR-0078).`,
   );
 }
 

packages/objectql/src/hook-binder.ts

@@ -205,7 +205,7 @@ export function bindHooksToEngine(
         result.skipped += 1;
         const reason =
           'hook target names no object — an empty `object` is refused rather than widened to '
-          + "the wildcard '*' (#4001). Name the object(s), or write `object: '*'` if firing on "
+          + "the wildcard '*'. Name the object(s), or write `object: '*'` if firing on "
           + 'every object is the intent.';
         result.errors.push({ hook: hook.name, reason });
         if (opts.strict) {

packages/objectql/src/hook-target-rebind-errors.ts

@@ -167,18 +167,20 @@ function buildMessage(info: {
       ? cleared
         ? ` The capability this used to have is RETIRED: clearing 'input.id' in a '${event}' handler ` +
           `converted a by-id write into a PREDICATE write over the caller's 'where'. Since ADR-0058 ` +
-          `Addendum II (#5574 / #5846) the dispatch ladder is resolved BEFORE the before phase — the ` +
+          `Addendum II the dispatch ladder is resolved BEFORE the before phase — the ` +
           `predicate path has to read its matched rows first, to build one context per row — so there ` +
           `is no ladder left to re-enter.`
         : ` The capability this used to have is RETIRED: rebinding 'input.id' in a '${event}' handler ` +
           `moved the write to another row. The engine now resolves the target BEFORE the before phase ` +
           `and computes the whole write against it — the pre-image, the 'readonlyWhen' locks, the ` +
           `validation rules — so a by-id target is immutable once a handler runs, on BOTH verbs. ` +
-          `'delete()' honoured a rebind until #6752 by re-resolving the new target; that is retired ` +
-          `too, so one rule now covers both.`
+          `'delete()' used to honour a rebind by re-resolving the new target; that is retired ` +
+          `too, because a handler that silently redirects which row gets deleted is a trap — so ` +
+          `one rule now covers both.`
       : path === 'unscoped-multi'
         ? ` This is the whole-operation dispatch an UNSCOPED predicate write delivers to a declared ` +
-          `shape guard (#9719, both write verbs since #9974): its 'id' is present-but-undefined ON ` +
+          `shape guard (one registered with 'dispatchUnscopedMultiWrite', on update and delete ` +
+          `alike): its 'id' is present-but-undefined ON ` +
           `PURPOSE — there is no target row — and the dispatch ladder was resolved before any handler ` +
           `ran, so binding 'input.id' here retargets nothing. It is refused rather than ignored, ` +
           `because a silent no-op is the failure this contract exists to abolish.`