fix(platform-objects): 超预算后台 seed 期间不再空库自证 —— 一次启动不再跑两套契约 (#4795) (#6147)

* fix(platform-objects): defer ADR-0104 attestation while this boot's seed is in flight

#4769 moved the fresh-datastore attestation off `kernel:ready` onto
`app:seeded` — the settle point for this boot's own data — keeping
`kernel:ready` as the backstop for kernels that never seed. The remaining
window is that the two hooks can arrive in EITHER order: when AppPlugin's
inline seed overruns `OS_INLINE_SEED_BUDGET_MS` it continues in the
background, so `kernel:ready` lands first and the backstop certified the
store mid-seed, flipping the value-shape gates to strict while the same
seed run was still writing. One boot, two contracts.

Measured on a showcase cold boot at `OS_INLINE_SEED_BUDGET_MS=1`:
attestation at +0.470s, seed settled at +3.617s — a 3.147s window.

Both hooks now ask whether this boot's seed has settled before certifying
anything, `app:seeded` included: a multi-app bundle fires it once per app,
so the first one is not the boot's settle point.

The signal is a published `seed-settlement` contract rather than a sniff of
the runtime's internal `seed-datasets` service. That array's presence says a
seed source EXISTS; it can never say whether it has SETTLED, and the gap
between those two facts is the whole window. The runtime declares each seed
source before choosing what to do with it and settles it when the write is
actually done.

Posture for multi-tenant and `skipSeedData` (ruled 2026-08-06, #4795): both
register seed datasets and deliberately do not write them at boot, so
`app:seeded` never fires and the tally stays pending. They do not
self-certify at boot and wait for `os migrate … --apply` to record the flag
on a real scan — which falls out of the same predicate rather than needing a
branch of its own.

objectql carries a comment-only change: the background-seed ordering is no
longer a scenario #4769's revocation mechanism has to catch, since it is now
closed at the source. It stays live for the `os dev` hot-reload seeder, a
runtime marketplace install, and the lax env-var escapes.

Fixes #4795

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019Q7oc7ASjh8yxyS3Yz78We

* chore(spec): regenerate api-surface after merging main

The merge driver defers generated artifacts rather than text-merging them
(AGENTS.md §11); this is the regeneration from the merged tree. Restores
main's `DriverQuery` entry alongside this branch's seed-settlement exports.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019Q7oc7ASjh8yxyS3Yz78We

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: baozhoutao

.changeset/defer-adr0104-attestation-while-seed-in-flight.md

@@ -0,0 +1,18 @@
+---
+'@objectstack/platform-objects': patch
+'@objectstack/runtime': patch
+'@objectstack/objectql': patch
+'@objectstack/spec': patch
+---
+
+fix(platform-objects): 超预算后台 seed 期间不再空库自证 —— 一次启动不再跑两套契约
+
+#4769 已把 ADR-0104 的空库自证从 `kernel:ready` 挪到 `app:seeded`(本次启动自身数据的结算点),但保留 `kernel:ready` 作为「从不 seed 的内核」的兜底。剩下的窗口是这两个钩子**到达顺序可以颠倒**:`AppPlugin` 的 inline seed 超出软预算(`OS_INLINE_SEED_BUDGET_MS`,默认 8s)后转入后台,于是 `kernel:ready` 先到、兜底自证在 seed 仍在写的时候签发证书并把闸门翻到 strict——同一次 seed 运行的后半段撞上前半段从未见过的契约。showcase 冷启(`OS_INLINE_SEED_BUDGET_MS=1`)实测:自证发生在 +0.470s,seed 结算在 +3.617s,窗口 3.147s。
+
+现在两个钩子都先问一句「本次启动自己的 seed 落定了吗」,任一处报告仍有未结算的 seed 源就不签发。`app:seeded` 同样受这道检查约束——多 config app 的 bundle 会每个 app 触发一次,第一次并不是本次启动的结算点。
+
+新增 `seed-settlement` 契约(`@objectstack/spec/contracts`)承载这个信号,而不是让 platform-objects 去嗅 runtime 内部的 `seed-datasets` 服务:那个数组的存在只能说明「seed 源存在」,永远说明不了「已经落定」,而这两件事之间的差正是本 bug 的整个窗口。runtime 在选择分支之前先声明 seed 源,并在写入真正结束的同一刻结算它。
+
+**multi-tenant 与 `skipSeedData` 的 ADR-0104 姿态(2026-08-06 裁定,#4795)**:这两种部署会注册 seed 数据但在启动时并不写入(前者按 org 在 `sys_organization` insert 时重放,后者是 `os migrate` 的只读规划启动,#3917),`app:seeded` 永不触发。它们的姿态是**启动时不自证,等 `os migrate … --apply` 在真实扫描的证据上落笔**——由同一个判据自然得出,不需要单独分支。这是答案而不是缺口:在启动那一刻断言一次尚未发生的 per-org 重放不含违规值,正是 #4769 的同一个错误、只是引信更长;而停在 warn-first 是可恢复的方向,随时可由 `os migrate value-shapes --apply` / `os migrate files-to-references --apply` 关闭。
+
+`@objectstack/objectql` 侧只更新了 #4769 撤销机制的注释:「后台 seed 收尾晚于签发」不再是它要兜的场景(已在源头关闭),它对 `os dev` 热重载 seeder、运行期 marketplace 安装以及 lax 开关仍然有效。

packages/objectql/src/engine.ts

@@ -3952,10 +3952,20 @@ export class ObjectQL implements IObjectQLEngine {
    * order — the certificate is already in the ledger and the contradicting
    * value lands afterwards, which is reachable whenever the deployment is
    * still lenient at that moment (`OS_ALLOW_LAX_MEDIA_VALUES` /
-   * `OS_ALLOW_LAX_VALUE_SHAPES`, or a seed that finishes in the background
-   * after its budget). Without this the ledger would keep asserting a fact the
-   * store contradicts, and the NEXT boot would enforce it against exactly the
-   * data this one wrote.
+   * `OS_ALLOW_LAX_VALUE_SHAPES`) or whenever a writer runs after the
+   * attestation point at all — the `os dev` hot-reload seeder and a runtime
+   * marketplace install both seed on a store this boot created. Without this
+   * the ledger would keep asserting a fact the store contradicts, and the NEXT
+   * boot would enforce it against exactly the data this one wrote.
+   *
+   * The boot's own inline seed used to head that list, via the background
+   * continuation of a run that overran `OS_INLINE_SEED_BUDGET_MS` — the
+   * attestation's `kernel:ready` backstop fired mid-seed and the tail landed
+   * against the certificate it had just issued. #4795 closed that ordering at
+   * the source: the attestation now defers while the `seed-settlement` contract
+   * reports a source outstanding, so the inline seed can no longer contradict
+   * a certificate this boot issued. This stays the safety net rather than the
+   * first line of defence for it.
    *
    * Deliberately narrow:
    *

packages/platform-objects/src/plugin.test.ts

@@ -263,4 +263,170 @@ describe('PlatformObjectsPlugin: fresh-datastore attestation (#3438, ADR-0104)',
       expect(engine.rows.map((r: any) => r.id)).toEqual(['adr-0104-value-shapes']);
     });
   });
+
+  /**
+   * #4795 — `app:seeded` and `kernel:ready` can arrive in EITHER order.
+   *
+   * When the inline seed overruns `OS_INLINE_SEED_BUDGET_MS` the runtime hands
+   * it to the background, so `kernel:ready` lands first and the #4769 backstop
+   * fired mid-seed: it certified the store, flipped the gates to strict, and
+   * the tail of the same seed run met a contract its head never saw — one
+   * boot, two contracts. Measured on a showcase cold boot at
+   * `OS_INLINE_SEED_BUDGET_MS=1`: attestation +0.470s, seed settled +3.617s.
+   *
+   * The fix asks the published `seed-settlement` contract instead of guessing
+   * from the runtime's internal `seed-datasets` array — see the contract's own
+   * TSDoc for why an array's presence cannot answer this.
+   */
+  describe('defers while this boot own seed is still landing (#4795)', () => {
+    /** Fake `seed-settlement` service over mutable state a test can advance. */
+    function seedSettlementFake(state: {
+      inFlight?: number;
+      suppressed?: Array<'multi-tenant-replay' | 'skip-seed-data'>;
+    }) {
+      return {
+        snapshot: () => ({
+          pending: (state.inFlight ?? 0) + (state.suppressed?.length ?? 0),
+          inFlight: state.inFlight ?? 0,
+          suppressed: [...(state.suppressed ?? [])],
+        }),
+      };
+    }
+
+    async function bootWithSeed(engine: unknown, state: Parameters<typeof seedSettlementFake>[0]) {
+      const plugin = new PlatformObjectsPlugin();
+      const ctx = makeCtx();
+      ctx.registerService('objectql', engine);
+      ctx.registerService('seed-settlement', seedSettlementFake(state));
+      await plugin.init(ctx);
+      await plugin.start(ctx);
+      return ctx;
+    }
+
+    /**
+     * The nail for this issue: at `kernel:ready` the background seed is still
+     * writing, so nothing may be certified yet — and once it settles, the
+     * certificate lands normally. One contract for the whole seed run.
+     */
+    it('kernel:ready writes no attestation while a seed source is still in flight', async () => {
+      const engine = engineWith(true);
+      const state = { inFlight: 1 };
+
+      const ctx = await bootWithSeed(engine, state);
+      await ctx._flushReady();
+
+      expect(engine.rows).toHaveLength(0);
+
+      // The background seed finishes and the runtime emits `app:seeded`.
+      state.inFlight = 0;
+      await ctx._flush('app:seeded');
+
+      expect(engine.rows.map((r: any) => r.id).sort()).toEqual([
+        'adr-0104-file-references',
+        'adr-0104-value-shapes',
+      ]);
+    });
+
+    /**
+     * `app:seeded` fires once per config app, so the FIRST one is not the
+     * settle point for the boot. Guarding only `kernel:ready` would move the
+     * same split-contract window onto multi-app bundles.
+     */
+    it('an app:seeded from one config app does not certify while another is still writing', async () => {
+      const engine = engineWith(true);
+      const state = { inFlight: 2 };
+
+      const ctx = await bootWithSeed(engine, state);
+
+      state.inFlight = 1; // app A settled; app B still writing
+      await ctx._flush('app:seeded');
+      expect(engine.rows).toHaveLength(0);
+
+      state.inFlight = 0; // app B settled
+      await ctx._flush('app:seeded');
+      expect(engine.rows).toHaveLength(2);
+    });
+
+    /**
+     * The #4795 ruling (2026-08-06), pinned: a deployment whose seed never runs
+     * at boot does not self-certify — it waits for `os migrate`. Falls out of
+     * the same predicate rather than needing a branch of its own.
+     */
+    it.each([
+      ['multi-tenant', 'multi-tenant-replay' as const],
+      ['skipSeedData', 'skip-seed-data' as const],
+    ])('%s: attests nothing at boot, without erroring', async (_label, reason) => {
+      const engine = engineWith(true);
+
+      const ctx = await bootWithSeed(engine, { suppressed: [reason] });
+      await expect(ctx._flushReady()).resolves.toBeUndefined();
+
+      expect(engine.rows).toHaveLength(0);
+    });
+
+    it('says why it stood down, and names the command that closes the gate', async () => {
+      const engine = engineWith(true);
+
+      const ctx = await bootWithSeed(engine, { suppressed: ['multi-tenant-replay'] });
+      await ctx._flushReady();
+
+      const said = ctx._logs.info.join('\n');
+      expect(said).toContain('multi-tenant-replay');
+      expect(said).toContain('os migrate value-shapes --apply');
+      // A posture that is correct by design must not spend the level that
+      // means "something you trusted did not persist" (AGENTS.md).
+      expect(ctx._logs.warn.join('\n')).not.toContain('not attesting');
+    });
+
+    it('an in-flight deferral says it will be picked up on app:seeded', async () => {
+      const engine = engineWith(true);
+
+      const ctx = await bootWithSeed(engine, { inFlight: 1 });
+      await ctx._flushReady();
+
+      expect(ctx._logs.info.join('\n')).toContain('app:seeded');
+    });
+
+    /**
+     * Regression guard for the two paths this change must leave untouched:
+     * a seed that fits inside its budget (settled before `kernel:ready`), and
+     * a kernel with no seed pipeline at all — the backstop #4769 kept for
+     * exactly that case, which is the same moment as before for it.
+     */
+    it('a settled seed attests at kernel:ready exactly as before', async () => {
+      const engine = engineWith(true);
+
+      const ctx = await bootWithSeed(engine, { inFlight: 0 });
+      await ctx._flushReady();
+
+      expect(engine.rows.map((r: any) => r.id).sort()).toEqual([
+        'adr-0104-file-references',
+        'adr-0104-value-shapes',
+      ]);
+    });
+
+    it('a kernel with no seed pipeline still attests on the kernel:ready backstop', async () => {
+      const engine = engineWith(true);
+      const plugin = new PlatformObjectsPlugin();
+      const ctx = makeCtx();
+      ctx.registerService('objectql', engine); // no `seed-settlement` service
+      await plugin.init(ctx);
+      await plugin.start(ctx);
+
+      await ctx._flushReady();
+
+      expect(engine.rows).toHaveLength(2);
+    });
+
+    /**
+     * A store that was FOUND was never going to be attested, so announcing a
+     * deferral over it would explain a decision nobody was making.
+     */
+    it('says nothing about deferral on a store that already existed', async () => {
+      const ctx = await bootWithSeed(engineWith(false), { inFlight: 1 });
+      await ctx._flushReady();
+
+      expect(ctx._logs.info.join('\n')).not.toContain('attestation deferred');
+    });
+  });
 });

packages/platform-objects/src/plugin.ts

@@ -6,7 +6,13 @@ import { SysMigration } from './system/sys-migration.object.js';
 import { SysMigrationJournal } from './system/sys-migration-journal.object.js';
 import { SysSecret } from './system/sys-secret.object.js';
 import { attestFreshDatastore } from './system/migration-flag.js';
-import type { II18nService, IObjectQLEngine } from '@objectstack/spec/contracts';
+import type {
+  II18nService,
+  IObjectQLEngine,
+  ISeedSettlementService,
+  SeedSettlementSnapshot,
+} from '@objectstack/spec/contracts';
+import { SEED_SETTLEMENT_SERVICE } from '@objectstack/spec/contracts';
 
 
 /**
@@ -48,7 +54,10 @@ import type { II18nService, IObjectQLEngine } from '@objectstack/spec/contracts'
  *    seed), whichever services are composed. Not before: emptiness settles
  *    a claim about CONTENT, and a boot that certifies itself and then seeds
  *    rows contradicting the certificate leaves every later boot enforcing
- *    it against data this one wrote (#4769).
+ *    it against data this one wrote (#4769). The `kernel:ready` fallback
+ *    additionally asks the `seed-settlement` contract whether a seed is
+ *    still in flight, so an over-budget background seed is waited out
+ *    rather than certified over (#4795).
  *  - **Translation bundles** — `SetupAppTranslations` (the static Setup
  *    App + sys_* dashboards) and `MetadataFormsTranslations`
  *    (`metadataForms.*` for object/field/agent/flow/view configuration
@@ -116,7 +125,26 @@ export class PlatformObjectsPlugin {
     // (above; #4243 — moved here with the registration from
     // service-storage). A store that was found rather than created attests
     // nothing and keeps producing evidence by scan.
-    const attest = async () => {
+    // #4795 — "has this boot's own seed finished landing?", asked through the
+    // published `seed-settlement` contract rather than by sniffing the
+    // runtime's internal `seed-datasets` service. That array's presence says a
+    // seed source EXISTS; it can never say whether it has SETTLED, and the gap
+    // between those two facts IS the bug. An absent service means no seed
+    // pipeline registered on this kernel — a fact by `kernel:ready`, since
+    // every source is declared in Phase 2 `start()`.
+    const readSeedSettlement = (): SeedSettlementSnapshot | undefined => {
+      try {
+        const svc = ctx.getService?.(SEED_SETTLEMENT_SERVICE) as
+          | ISeedSettlementService
+          | undefined;
+        if (!svc || typeof svc.snapshot !== 'function') return undefined;
+        return svc.snapshot();
+      } catch {
+        return undefined;
+      }
+    };
+
+    const attest = async (phase: 'app:seeded' | 'kernel:ready') => {
       let engine: IObjectQLEngine | undefined;
       try {
         engine = ctx.getService?.('objectql');
@@ -126,6 +154,15 @@ export class PlatformObjectsPlugin {
       if (!engine || typeof engine.wasDatastoreCreatedFromEmpty !== 'function') return;
       try {
         if (engine.wasDatastoreCreatedFromEmpty()) {
+          // Asked AFTER the created-from-empty check on purpose: a store that
+          // was found rather than created attests nothing either way, and
+          // announcing a deferral there would be noise about a decision that
+          // was never going to be made.
+          const seed = readSeedSettlement();
+          if (seed && seed.pending > 0) {
+            if (phase === 'kernel:ready') reportDeferral(ctx, seed);
+            return;
+          }
           await attestFreshDatastore(engine, { logger: ctx.logger });
           // The engine memoizes the flag read on first use; this write
           // may already have raced it on a fast boot.
@@ -151,8 +188,20 @@ export class PlatformObjectsPlugin {
     // (it is the same moment as before for those). Both land in the same
     // idempotent call: the first one to find an id unattested and
     // uncontradicted writes it, the other finds the row and skips.
-    ctx?.hook?.('app:seeded', attest);
-    ctx?.hook?.('kernel:ready', attest);
+    //
+    // #4795 — subscribing to both is necessary but not sufficient, because the
+    // two can arrive in EITHER order. When the inline seed overruns its budget
+    // the runtime hands it to the background and `kernel:ready` arrives first,
+    // so the backstop fired mid-seed: it certified the store, flipped the gates
+    // to strict, and the tail of the same seed run met a contract its head had
+    // never seen — one boot, two contracts. Measured on a showcase cold boot at
+    // `OS_INLINE_SEED_BUDGET_MS=1`: attestation +0.470s, seed settled +3.617s.
+    // Neither hook may certify while the pipeline reports work outstanding, so
+    // the settlement check lives inside `attest` and guards both — `app:seeded`
+    // included, since a bundle with several config apps fires it once per app
+    // and the first one is not the last.
+    ctx?.hook?.('app:seeded', () => attest('app:seeded'));
+    ctx?.hook?.('kernel:ready', () => attest('kernel:ready'));
 
     ctx?.hook?.('kernel:ready', async () => {
       let i18n: II18nService | undefined;
@@ -194,6 +243,62 @@ export class PlatformObjectsPlugin {
   }
 }
 
+/**
+ * Say, once, why `kernel:ready` did not attest — and what closes the gate.
+ *
+ * ## The ADR-0104 posture for deployments that never settle a boot seed (#4795)
+ *
+ * Two shapes register seed datasets and deliberately do not run them at boot,
+ * so `app:seeded` never fires and the tally stays pending for the life of the
+ * process: **multi-tenant** (seeds replay per organization on
+ * `sys_organization` insert) and **`skipSeedData`** (an `os migrate` planning
+ * boot that must not write to the target database at all, #3917).
+ *
+ * Their posture is **do not self-certify at boot; wait for `os migrate`** —
+ * ruled 2026-08-06 and recorded on #4795. It is not a gap this check leaves
+ * behind, it is the answer:
+ *
+ *  - the fresh-datastore attestation infers "created empty, therefore no
+ *    legacy value can exist". On a multi-tenant deployment the rows that
+ *    inference is about have not been written yet — they land org by org,
+ *    later. Certifying at startup that a replay which has not happened holds
+ *    no violating value is exactly #4769's error with a longer fuse;
+ *  - a `skipSeedData` boot writes nothing, so it observes nothing, so it has
+ *    no evidence to certify from;
+ *  - standing down is the *recoverable* direction. The deployment stays
+ *    warn-first — true, and closable at any time by `os migrate value-shapes
+ *    --apply` / `os migrate files-to-references --apply`, which record the flag
+ *    on a real scan of what the store actually holds. The opposite error is not
+ *    recoverable in the same way: a certificate issued over rows nobody looked
+ *    at is enforced by every later boot against data it never examined.
+ *
+ * Logged at `info`, not `warn`. This is a functional posture, not a durability
+ * degradation: nothing claims to have persisted and failed, and the gate that
+ * stays open is the lenient one. A `warn` on every boot of every multi-tenant
+ * deployment for behaviour that is correct by design is precisely what trains
+ * operators to skim the level that matters (AGENTS.md, degradation log levels).
+ */
+function reportDeferral(ctx: any, seed: SeedSettlementSnapshot): void {
+  if (seed.suppressed.length > 0) {
+    const reasons = [...new Set(seed.suppressed)].join(', ');
+    ctx?.logger?.info?.(
+      `[platform-objects] not attesting this fresh datastore at boot: seed data is registered but ` +
+        `this boot does not write it (${reasons}). Multi-tenant deployments replay seeds per org on ` +
+        `sys_organization insert, and a skipSeedData boot writes nothing at all — so nothing observed ` +
+        `now could prove or disprove the claim. The deployment stays warn-first until ` +
+        `\`os migrate value-shapes --apply\` / \`os migrate files-to-references --apply\` records the ` +
+        `flag on a real scan (ADR-0104, #4795).`,
+    );
+    return;
+  }
+  ctx?.logger?.info?.(
+    `[platform-objects] fresh-datastore attestation deferred at kernel:ready: ${seed.inFlight} seed ` +
+      `source(s) still writing (an inline seed overran OS_INLINE_SEED_BUDGET_MS and continues in the ` +
+      `background). Attesting now would flip this boot to strict half-way through its own seed run. ` +
+      `It runs on \`app:seeded\` once the seed settles (ADR-0104, #4795).`,
+  );
+}
+
 /** Convenience factory mirroring the rest of the plugin ecosystem. */
 export function createPlatformObjectsPlugin(): PlatformObjectsPlugin {
   return new PlatformObjectsPlugin();