Repository navigation
Commit 3ae0b77
fix(metadata-protocol): a seed reference written blank ('' or whitespace) is no reference, by the engine's isMissing (#24502)
Fixes #24459
Clause-②: no (no published accept set or surface moves: the row was
already written, and only the false "unresolved" report and its
`success: false` go away; owes the seat's `TIER_DEFAULT` review of
record before the queue)
Dispatched under claim 6261694593 (`domain:engine` seat 1, session
`session_01JtSQQ3EWsbNPzyYMug1tXy`); dev session
`session_01KxmveGHL9EpPEGVggMSzDB`.
## What changed
The seed loader decided "this reference has a value" with `undefined` /
`null` only, while the engine's blank rule, `isMissing`
(`@objectstack/core`, `packages/core/src/utils/required-emptiness.ts`),
also calls `''` and whitespace-only strings missing. Every site in
`packages/metadata-protocol/src/seed-loader.ts` that judges a reference
value now asks `isMissing` (imported, not re-spelled):
| Site (symbol) | Before | After |
|---|---|---|
| single reference, `recordRefs` loop (`if (isMissing(fieldValue))
continue;`) | skipped `undefined` / `null` | skips every `isMissing`
value; left **as written** for the engine |
| each element of a `multiple: true` reference, pass 1 | dropped a
`null` / `undefined` hole | drops every `isMissing` hole |
| each element of a deferred value, pass 2 (`resolveDeferredUpdates`) |
same as pass 1 | same rule as pass 1 (the deferred value is the whole
authored array, holes included) |
| `referenceVia` pointer id half | skipped `undefined` / `null` / `''` |
skips every `isMissing` value (whitespace-only joins `''`) |
Other "has a value" sites in the file were read and left alone, on
purpose: `externalIdKey` judges the record's own natural-key components
(not a reference); the organization stamps compare `== null` on
`organization_id`, which is resolved by its own path; `formatAttempted`
is display only. No change to `isMissing`, the engine's required check,
or any error code.
### A blank element inside a multi-valued reference: dropped (decided by
the four axes)
- **Real business need:** measured on `main`, one blank element made the
whole field defer and fail, so the row landed with **none** of its
associations (`books: null` for `['Dune', '', ' ', 'Emma']`). Dropping
the hole lands `[Dune, Emma]`, which is what the author wrote.
- **Long-term soundness:** one hole rule. `null` holes were already
dropped, and `isMissing` is the platform's single definition of "no
value", so blank holes follow the same rule. Leaving the whole value as
written for the engine is not possible, because the other elements are
natural keys that must be resolved first.
- **Guarding against AI-authored metadata errors:** the drop is not a
lenient fallback for off-spec input. A blank element names no row under
the engine's own rule. A key that names a missing row is still reported
loudly, as before (control pin).
- **No scope creep:** no new key, option or error code.
## Measured (real `ObjectQL` + real `SqlDriver` on better-sqlite3,
`SeedLoaderService`, `multiPass: true`)
Seed: `blank_ref_book` (`Dune`, `Emma`) and `blank_ref_loan`
(`loan-real` → `'Dune'`, `loan-empty` → `''`, `loan-whitespace` → `' '`,
`loan-multi` → `books: ['Dune', '', ' ', 'Emma']`). Plus a required
lookup written `''`.
| Reading | `main` (`01fafdee`, before) | this branch (after) |
|---|---|---|
| first load | `success: false`, inserted 6, `errored: 3`: three
`Deferred reference unresolved after pass 2: …book = '' / ' ' / …books =
'' → blank_ref_book.title not found` | `success: true`, inserted 6,
`errored: 0`, no errors |
| replay | `success: false`, skipped 6, `errored: 3` (same three) |
`success: true`, skipped 6, updated 0, `errored: 0` |
| `loan-empty` / `loan-whitespace` `.book` | `null` (the deferral
deleted the key) | `''` / `' '`: left as written; `isMissing` true (see
Acceptance notes) |
| `loan-multi` `.books` | `null`: the whole association was lost |
`[Dune.id, Emma.id]` |
| `loan-real` `.book` (control) | `Dune.id` | `Dune.id` |
| required lookup written `''` | `errored: 2`: `Failed to write … record
#0 (name=loan-required-empty): book is required` **and** `Deferred
reference unresolved after pass 2: …book = '' → …` | `errored: 1`:
`Failed to write … record #0 (name=loan-required-empty): book is
required` only; row not written |
## Pins
-
`packages/runtime/src/seed-blank-reference-real-driver.integration.test.ts`
(new): the table above, on the real driver. It lives in `runtime`
because that package already has the real-driver seed harness and the
`driver-sql` dependency
(`seed-multi-value-lookup-real-driver.integration.test.ts` is its
sibling). `metadata-protocol` has neither. This is outside the claim's
"pins beside it" fence, and the reason is the measurement the dispatch
asked for.
-
`packages/metadata-protocol/src/seed-loader-multi-value-reference.test.ts`
(6 new cases in a new `describe`): single `''` and whitespace skipped
and left as written (not deferred, not dropped); a blank element dropped
in pass 1 (no back-fill `update`); a blank element dropped in pass 2 (a
forward self-reference, so it is proven by the back-fill `update`); a
whitespace pointer skipped like `''`, including the un-addressable
branch, plus a live-pair control; a control showing that a real key
resolves and an unknown key still errors. These cases reuse that file's
already-pinned engine double, so `check:engine-double-contract` needs no
ledger edit. A new file with its own double was tried first, and the
gate reported it.
- Pin sweep: `git grep` for `Deferred reference unresolved` /
`UNRESOLVED` finds no test that pins the old blank behaviour (the only
hits are the loader, `CHANGELOG.md`, and these new pins). Existing `''`
seed values in tests are a field-definition `reference: ''`
(`seed-loader-reference-carrier.test.ts`) and an unrelated ownership
claim (`claim-seed-ownership.test.ts`). No pin needed flipping.
## Ablations (committed fix first, `scripts/ablation-replace.mjs`, trap
restore, restore proven by blob == HEAD and an empty porcelain)
- Unit, per site, `src/` resolution (19-case file): `:1464` single makes
the 2 single-blank cases red; pass-1 element makes the pass-1 element
case red; pass-2 element makes the pass-2 case red; pointer makes the
pointer case red. Each restores to 19/19 green.
- Real driver, `dist/` resolution (`runtime` reads
`@objectstack/metadata-protocol` through `exports`): all three reference
skips set back to `undefined`/`null`, rebuilt, `ablation-dist-preflight`
shows the markers present in `dist/`, and both real-driver cases go
**red**. After restore and rebuild, `--absent` passes and both cases are
green.
- First attempt declared: ablating `:1464` alone was a void reading, in
two ways. (a) The first marker did not reach `dist/`, because the build
re-spells `undefined` as `void 0`; the preflight reported this, so a
string-literal marker was used. (b) With the marker live, the
real-driver file stayed green, because the pass-1 element skip still
drops a scalar `''` (it is wrapped as a one-element list) and the insert
lands NULL. The single-site difference (left as written vs dropped) is
pinned by the unit cases above. The faithful "remove the skip" is all
three sites together, and that run is the red reading above.
## Verification (final head `3e5746dd6`, after `git merge origin/main`
at `ce2e08ee3` and a full `turbo build`, 76/76)
- `pnpm --filter @objectstack/metadata-protocol test`: exit 0, 247 files
passed (3 skipped), 20698 tests passed.
- `pnpm --filter @objectstack/metadata-protocol typecheck`: exit 0.
- `pnpm --filter @objectstack/runtime typecheck`: exit 0
(`check:test-typecheck` OK).
- `pnpm --filter @objectstack/runtime test`: exit 0, 422 files, 6637
tests passed (pre-merge head `f749e65d1`; post-merge, the two
real-driver seed files were re-run: 5/5).
- `pnpm --filter @objectstack/core test:repo`: exit 0, 6 files, 82
tests.
- `node scripts/pm/dispatch-gates.mjs --commands` (no paths, 4 changed
paths vs merge base `ce2e08ee3`): 64 commands, **all exit 0**. `--ran`
reconciliation: 64 derived, 64 run, 0 NOT-MEASURED (a derived zero:
every line carries its exit code). `check:dual-build-cjs-loads` first
exited 3 (PREREQUISITE NOT MET, 39 packages without `dist/`); it was
re-run after the full build and exited 0.
## Acceptance notes
- **What "the field is empty" stores.** The loader leaves a blank single
reference as written, so the engine decides it. The engine's insert door
(`normalizeBlankTypedValues`) deliberately does not null a blank
string-stored value: its doc lists "lookup ids" among the columns where
`''` is a value, and calls what "empty" means there "a separate
question, not answered here". So an optional lookup seeded `''` stores
`''` (and whitespace stores `' '`), exactly as a direct `engine.insert`
of the same payload does. Every reader that asks `isMissing` sees it as
empty, and the required check refuses it. Before this change the
deferral deleted the key, so the row stored NULL. Carrier: none. This
records the engine's own declared open question; it is not filed here.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01KxmveGHL9EpPEGVggMSzDB)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 6b42b6b commit 3ae0b77
4 files changed
Lines changed: 378 additions & 7 deletions
File tree
- .changeset
- packages
- metadata-protocol/src
- runtime/src
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
378 | 378 | | |
379 | 379 | | |
380 | 380 | | |
| 381 | + | |
| 382 | + | |
| 383 | + | |
| 384 | + | |
| 385 | + | |
| 386 | + | |
| 387 | + | |
| 388 | + | |
| 389 | + | |
| 390 | + | |
| 391 | + | |
| 392 | + | |
| 393 | + | |
| 394 | + | |
| 395 | + | |
| 396 | + | |
| 397 | + | |
| 398 | + | |
| 399 | + | |
| 400 | + | |
| 401 | + | |
| 402 | + | |
| 403 | + | |
| 404 | + | |
| 405 | + | |
| 406 | + | |
| 407 | + | |
| 408 | + | |
| 409 | + | |
| 410 | + | |
| 411 | + | |
| 412 | + | |
| 413 | + | |
| 414 | + | |
| 415 | + | |
| 416 | + | |
| 417 | + | |
| 418 | + | |
| 419 | + | |
| 420 | + | |
| 421 | + | |
| 422 | + | |
| 423 | + | |
| 424 | + | |
| 425 | + | |
| 426 | + | |
| 427 | + | |
| 428 | + | |
| 429 | + | |
| 430 | + | |
| 431 | + | |
| 432 | + | |
| 433 | + | |
| 434 | + | |
| 435 | + | |
| 436 | + | |
| 437 | + | |
| 438 | + | |
| 439 | + | |
| 440 | + | |
| 441 | + | |
| 442 | + | |
| 443 | + | |
| 444 | + | |
| 445 | + | |
| 446 | + | |
| 447 | + | |
| 448 | + | |
| 449 | + | |
| 450 | + | |
| 451 | + | |
| 452 | + | |
| 453 | + | |
| 454 | + | |
| 455 | + | |
| 456 | + | |
| 457 | + | |
| 458 | + | |
| 459 | + | |
| 460 | + | |
| 461 | + | |
| 462 | + | |
| 463 | + | |
| 464 | + | |
| 465 | + | |
| 466 | + | |
| 467 | + | |
| 468 | + | |
| 469 | + | |
| 470 | + | |
| 471 | + | |
| 472 | + | |
| 473 | + | |
| 474 | + | |
| 475 | + | |
| 476 | + | |
| 477 | + | |
| 478 | + | |
| 479 | + | |
| 480 | + | |
| 481 | + | |
| 482 | + | |
| 483 | + | |
| 484 | + | |
| 485 | + | |
| 486 | + | |
| 487 | + | |
| 488 | + | |
| 489 | + | |
| 490 | + | |
| 491 | + | |
| 492 | + | |
| 493 | + | |
| 494 | + | |
| 495 | + | |
| 496 | + | |
| 497 | + | |
| 498 | + | |
| 499 | + | |
| 500 | + | |
| 501 | + | |
| 502 | + | |
| 503 | + | |
| 504 | + | |
| 505 | + | |
| 506 | + | |
| 507 | + | |
| 508 | + | |
| 509 | + | |
| 510 | + | |
| 511 | + | |
| 512 | + | |
| 513 | + | |
| 514 | + | |
| 515 | + | |
| 516 | + | |
| 517 | + | |
| 518 | + | |
| 519 | + | |
| 520 | + | |
| 521 | + | |
| 522 | + | |
| 523 | + | |
| 524 | + | |
| 525 | + | |
| 526 | + | |
| 527 | + | |
| 528 | + | |
| 529 | + | |
| 530 | + | |
| 531 | + | |
| 532 | + | |
| 533 | + | |
| 534 | + | |
| 535 | + | |
| 536 | + | |
| 537 | + | |
| 538 | + | |
| 539 | + | |
| 540 | + | |
| 541 | + | |
| 542 | + | |
| 543 | + | |
| 544 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
25 | 25 | | |
26 | 26 | | |
27 | 27 | | |
28 | | - | |
| 28 | + | |
29 | 29 | | |
30 | 30 | | |
31 | 31 | | |
| |||
1403 | 1403 | | |
1404 | 1404 | | |
1405 | 1405 | | |
1406 | | - | |
| 1406 | + | |
| 1407 | + | |
| 1408 | + | |
1407 | 1409 | | |
1408 | 1410 | | |
1409 | 1411 | | |
| |||
1461 | 1463 | | |
1462 | 1464 | | |
1463 | 1465 | | |
1464 | | - | |
| 1466 | + | |
| 1467 | + | |
| 1468 | + | |
| 1469 | + | |
| 1470 | + | |
| 1471 | + | |
| 1472 | + | |
1465 | 1473 | | |
1466 | 1474 | | |
1467 | 1475 | | |
| |||
1533 | 1541 | | |
1534 | 1542 | | |
1535 | 1543 | | |
1536 | | - | |
1537 | | - | |
1538 | | - | |
| 1544 | + | |
| 1545 | + | |
| 1546 | + | |
| 1547 | + | |
1539 | 1548 | | |
1540 | 1549 | | |
1541 | 1550 | | |
| |||
2211 | 2220 | | |
2212 | 2221 | | |
2213 | 2222 | | |
2214 | | - | |
| 2223 | + | |
| 2224 | + | |
| 2225 | + | |
2215 | 2226 | | |
2216 | 2227 | | |
2217 | 2228 | | |
| |||
0 commit comments