Merge origin/main into claude/issue-20493-ja-es-object-labels

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

Author: claude

.changeset/20233-field-export-api-dataset-hook-metadata-migration-guidance-tracker-free.md

@@ -0,0 +1,28 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): `os migrate meta` guidance for the `field-*`, `export-*`, `api-*`, `dataset-*`, `hook-*` and `metadata-*` migration entries states each lesson in words instead of citing tracker numbers
+
+Clause-②: no
+
+The ADR-0087 semantic entries of the `field-*` family (the runtime `field` write door, the
+`maxLength` / `minLength` / `scale` / `precision` refusals, `scale` on a currency field,
+`multiple` on a type that holds one value, and predicates that read through a reference),
+the `export-*` family (the export permission axis, the eight constraint keys retired from
+`ExportFieldMeta` and the retired export-job API family), the `api-*` family (the runtime `api` write door,
+the split API entry and two duration keys renamed with their unit), the `dataset-*` family
+(the aggregate × field-type refusals and the nested-relation list refused at save), the
+`hook-*` family (the retired hook-session `roles` and the two `registerHook` refusals) and
+the `metadata-*` family (the retired customization protocol, the re-partitioned endpoint
+switches, the metadata-manager cache keys and the retired `additionalTypes`) are printed by
+`os migrate meta` as the header, `why:` and `verify:` lines of a manual change. Their text
+sent the reader to issue-tracker, decision-batch and ruling-record numbers — some of which
+no longer resolve, and some in another repository — for what a ruling, measurement or fix
+had decided; it now says what was decided, in the sentence being read. ADR ids are kept.
+
+Text only: no entry id, `from` / `to`, conversion or matching logic changes, and the chain
+rewrites exactly what it rewrote before. One entry's `surface` (the header line of
+`dataset-measure-aggregate-field-type-refused`) drops the two tracker numbers it carried and
+names nothing else differently. The generated migration registry, `spec-changes.json` and
+the protocol upgrade guide carry the same text.

.changeset/20444-empty-operator-engine-arms.md

@@ -0,0 +1,24 @@
+---
+'@objectstack/driver-sql': minor
+'@objectstack/driver-turso': minor
+'@objectstack/driver-memory': minor
+'@objectstack/driver-mongodb': minor
+'@objectstack/formula': minor
+'@objectstack/objectql': minor
+'@objectstack/spec': minor
+---
+
+feat(drivers,formula,objectql): the engine's filter faces answer the staged `$empty` operator (#20444)
+
+Clause-②: yes (widening)
+
+`$empty: true | false` is declared by `@objectstack/spec` (`FieldOperatorsSchema`) with a per-type meaning: a text-like field is empty when it is null or `''`, a multi-value field (multiselect, checkboxes, tags, or a select / radio / lookup / user / file / image with `multiple: true`) when it is null or `[]`, and every other type only when it is null. `$empty: false` is the exact complement. Until now every face in this list refused it (`INVALID_FILTER` / 400), except `matchesFilterCondition`, which answered `false` for every record. **A driver or evaluator called directly now answers it:**
+
+- **By the field's declared type**, through the spec's one expansion (`expandEmptyOperator`): `driver-sql`'s filter compiler (and so `driver-sqlite-wasm` and `driver-turso`'s local transport, which inherit it), `driver-turso`'s remote transport, `driver-memory`'s query path (`find` / `count` / `update` / `delete`) and `driver-mongodb`'s `translateFilter` (its `find`, its aggregate `$match`). The declaration is the one each driver already receives — `initObjects` / `registerObjectMetadata` / `registerExternalObject` on the SQL family, `syncSchema` on the others. On SQL a multi-value field's empty list is tested as stored JSON per dialect (SQLite `json_array_length` behind a `json_valid` guard, PostgreSQL a `jsonb` comparison, MySQL `JSON_LENGTH`), never as an equality comparand.
+- **By value** — null, a missing value, `''` and `[]` are empty (`isEmptyFilterValue`) — on the faces that read no field declaration: `@objectstack/formula`'s `matchesFilterCondition` (the RLS write-side `check`), `driver-memory`'s reference matcher, and `@objectstack/objectql`'s `having` and per-aggregation `filter`. In `having`, a `count` or `sum` holding `0` is not empty.
+
+**Refused, never guessed** (`INVALID_FILTER` / 400): `$empty` on a field whose declaration the driver does not hold (a table built outside its registration, a builtin column such as `id`, a field with no `type`, or `translateFilter` / `RemoteTransport` used standalone without a declaration), a multi-value field on a SQL dialect the driver does not model, and a flag that is not a boolean. `driver-memory`'s analytics (cube) face refuses `$empty` as an operator it cannot compile, as it does `$null`.
+
+New optional API: `translateFilter(where, temporalKind?, valueShape?)` in `@objectstack/driver-mongodb` takes a declared-value-shape resolver (type `ValueShapeResolver`), and `buildAggregationPipeline` a `valueShape` option; `RemoteTransport.setDeclaredValueShapeResolver` in `@objectstack/driver-turso`, which `TursoDriver` wires. `@objectstack/spec`'s shared `FILTER_LOGIC_CASES` table gains seven `$empty` cases: a backend that runs it answers `$empty` or goes red, and its harness must declare the fixture's columns.
+
+`$empty` stays staged: it is not in `FILTER_OPERATORS`, so the engine's front door still refuses it until the flip card adds it, and the view operators `is_empty` / `is_not_empty` still lower to `$null`.

docs/protocol-upgrade-guide.md

@@ -4,7 +4,8 @@
  * `os migrate meta` — the guidance it prints for the ADR-0087 semantic entries
  * of the COVERED families (`engine-*`, `ui-*`, `plugin-*`, `driver-*`,
  * `kernel-*`, `system-*`, `datasource-*`, `filter-*`, `action-*`, `data-*`,
- * `element-*`) states each lesson in words and carries no tracker number.
+ * `element-*`, `field-*`, `export-*`, `api-*`, `dataset-*`, `hook-*`,
+ * `metadata-*`) states each lesson in words and carries no tracker number.
  *
  * ## What this pins
  *
@@ -76,6 +77,7 @@ const TRACKER_ID = /#\d{4,5}\b/;
 const COVERED_PREFIXES = [
   'engine-', 'ui-', 'plugin-', 'driver-', 'kernel-', 'system-',
   'datasource-', 'filter-', 'action-', 'data-', 'element-',
+  'field-', 'export-', 'api-', 'dataset-', 'hook-', 'metadata-',
 ];
 
 /**
@@ -89,12 +91,19 @@ const REWRITTEN = [
   'action-descriptor-resume-authority-default-flip',
   'action-engine-facade-find-query-envelope',
   'action-session-roles-to-positions',
+  'api-assembled-entry-split',
+  'api-error-retry-after-unit-in-key',
+  'api-runtime-config-durations-unit-in-key',
+  'api-runtime-create-withdrawn',
   'data-driver-find-stream-retired',
   'data-driver-query-omit-object',
   'data-engine-batch-retired',
   'data-field-changed-event-retired',
   'data-file-value-duration-unit-in-key',
   'data-nosql-query-options-timeout-unit-in-key',
+  'dataset-filter-nested-relation-equality-array-refused-at-save',
+  'dataset-measure-aggregate-field-type-refused',
+  'dataset-measure-selecting-aggregate-field-type-refused',
   'datasource-config-inline-credential-refused',
   'datasource-config-mongo-options-credential-refused',
   'datasource-config-placeholder-refused',
@@ -118,6 +127,16 @@ const REWRITTEN = [
   'engine-find-formula-filter-refused',
   'engine-find-formula-order-by-refused',
   'engine-update-upsert-retired',
+  'export-axis-opt-in',
+  'export-field-meta-constraints-retired',
+  'export-job-family-retired',
+  'field-currency-scale-refused',
+  'field-max-length-malformed-or-misplaced-refused',
+  'field-min-length-malformed-or-misplaced-refused',
+  'field-multiple-non-capable-type-refused',
+  'field-predicate-reference-traversal-refused',
+  'field-runtime-create-withdrawn',
+  'field-scale-precision-integer-refused',
   'filter-between-blank-endpoint-refused',
   'filter-between-field-reference-endpoint-refused',
   'filter-comparand-types-and-widget-nested-slots-refused-at-save',
@@ -129,6 +148,9 @@ const REWRITTEN = [
   'filter-query-face-comparands-refused-at-save',
   'filter-regex-options-retired',
   'filter-text-operator-declared-type-refused',
+  'hook-context-session-roles-retired',
+  'hook-register-empty-object-target-refused',
+  'hook-register-undispatched-lifecycle-event-refused',
   'kernel-compatibility-matrix-estimated-migration-time-unit-in-key',
   'kernel-context-preview-mode-retired',
   'kernel-event-bus-retention-unit-in-key',
@@ -138,6 +160,11 @@ const REWRITTEN = [
   'kernel-plugin-security-durations-unit-in-key',
   'kernel-runtime-config-timeout-unit-in-key',
   'kernel-startup-orchestrator-durations-unit-in-key',
+  'metadata-customization-protocol-retired',
+  'metadata-endpoints-switch-radius-repartitioned',
+  'metadata-manager-config-cache-ttl-unit-in-key',
+  'metadata-manager-config-inert-cache-keys-retired',
+  'metadata-plugin-additional-types-retired',
   'plugin-activation-events-retired',
   'plugin-auto-restart-never-reinitialised',
   'plugin-manifest-contributes-dead-members-retired',

packages/cli/test/migrate-meta-engine-guidance.test.ts

@@ -364,6 +364,13 @@ export const SUPPORTED_FIELD_OPERATORS: ReadonlySet<string> = new Set<string>([
   ...FILTER_OPERATORS,
   '$like',
   '$ilike',
+  // [#20444] The staged emptiness flag, admitted BY HAND for the reason the
+  // `$like` paragraph above gives, and under its ordering rule: both arms land
+  // with this entry — the reference matcher judges the stored value
+  // (`isEmptyFilterValue`, the spec's reading for a face holding no field
+  // declaration) and the live query path the field's DECLARED row
+  // (`expandEmptyOperator`, from the declaration `syncSchema` recorded).
+  '$empty',
 ]);
 
 /** The vocabulary as it appears in a refusal message, in declaration order. */
@@ -611,6 +618,42 @@ export function nonBooleanNullComparandError(field: string, value: unknown, path
   );
 }
 
+/**
+ * [#20444] A non-boolean `$empty` comparand. The leading sentence is
+ * `driver-sql`'s `nonBooleanEmptyComparandError`, verbatim — one condition,
+ * one wording (#5240).
+ */
+export function nonBooleanEmptyComparandError(field: string, value: unknown, path: string): Error {
+  return unsupportedFilterError(
+    `Operator "$empty" on field "${field}" requires a boolean comparand (true or false). ` +
+      `Received ${describeFilterOperand(value)} (${safeShapePreview(value)}) at ${path}. ` +
+      `@objectstack/spec FieldOperatorsSchema declares $empty as a boolean: true asks for the ` +
+      `empty rows, false for their exact complement.`,
+  );
+}
+
+/**
+ * [#20444] `$empty` on the live query path, aimed at a field this driver holds
+ * no declaration for — an object never passed through `syncSchema`, a field
+ * its schema does not name, or one declared with no `type`.
+ *
+ * What counts as empty is the field's DECLARED row of the ruled table, and the
+ * live path reads it from the declaration rather than from a value, so without
+ * one there is no answer to give: refused, never guessed. The reference matcher
+ * (`memory-matcher.ts`) is the face that holds NO declarations at all, and it
+ * judges the stored value instead — the spec's reading for such a face.
+ */
+export function undeclaredEmptyOperatorFieldError(field: string, path: string): Error {
+  return unsupportedFilterError(
+    `Operator "$empty" on field "${field}" at ${path} targets a field whose declaration this ` +
+      `driver does not hold (no declared type — the object's schema was never synced, or does not ` +
+      `declare the field). What counts as empty is the field's DECLARED row of the ruled table — ` +
+      `null or '' for a text-like type, null or [] for a multi-value field, null only for every ` +
+      `other type — so the operator is refused rather than guessed. Declare the field, or use ` +
+      `"$null" for "has no value".`,
+  );
+}
+
 /**
  * [#5702] A RETIRED filter operator in a field constraint.
  *
@@ -895,6 +938,13 @@ function assertFieldConstraintShape(
     if (op === '$null' && typeof spec[op] !== 'boolean') {
       throw nonBooleanNullComparandError(field, spec[op], `${path}.$null`);
     }
+    // [#20444] `$empty`'s comparand is a boolean by the same declaration
+    // (`FieldOperatorsSchema`), refused on this walk for the same reason: both
+    // faces of this package evaluate `true` / `false` exhaustively, so a third
+    // value would land on whichever side each arm happens to default to.
+    if (op === '$empty' && typeof spec[op] !== 'boolean') {
+      throw nonBooleanEmptyComparandError(field, spec[op], `${path}.$empty`);
+    }
     // [#16810] An ARRAY comparand on a single-value comparison — the operator
     // spelling of the implicit-equality position refused at the top of this
     // function, and the same cell `@objectstack/spec`'s comparand door leaves