Establish and pin how a seed writes history

[os-warren]

Fixes #32

The answer is yes, with a second pass nobody would have guessed. No application-level workaround was needed and none was written.

The answer

{ context: { isSystem: true } } is the sanctioned way to write history — the same leg src/jobs/dispatch.job.ts already uses, and the leg the platform's own seed loader uses (SeedLoaderService.SEED_OPTIONS = { isSystem: true, skipTriggers: true, seedReplay: true }). It exempts a write from the readonly strip.

Column	How you seed it	Measured
completed_at	carried on the insert	✅ works
last_update_at	a second pass in mode: 'update'	✅ works — but an insert can never carry it

The stalled half is the one that would have bitten #7. beforeInsert stamps last_update_at unconditionally, and lifecycle hooks do run on the seed path — skipTriggers suppresses record-change automation, not hooks — so a system insert's value is overwritten with the boot clock. Measured on a real seeded boot: the row seeded with last_update_at: <45 days ago> came back holding boot time. It takes a second seed dataset on the same object in mode: 'update', matched on externalId, carrying only last_update_at; the beforeUpdate leg deliberately does not stamp on an administrative write, so that value lands.

Skip that pass and the "Not moving" view is empty on a freshly seeded demo, with no error anywhere — the seed reports success and the view is simply blank.

A third finding #7 needs

The seed loader resolves duly_task.owner as a natural key against sys_user.name, deferred to a second resolution pass. A bare id string matching no sys_user row does not resolve, and because owner is required: true the whole task row is refused (Owner is required, plus an unresolved-reference error). Measured: without a sys_user dataset seeded first, nothing seeds at all — inserted: 0, errored: 4.

Both directions are pinned

test/seed-history.test.ts runs against a real booted kernel with the declarative seeder actually running (skipSeedData: false), so the seed path itself is under test rather than a hand-made stand-in.

• system-context insert of a done task with a completion instant → succeeds, nothing stripped
• an ordinary caller's identical payload → still refused by completed_at_required_when_done (asserted on code: VALIDATION_FAILED + name: ValidationError + the message, not on a bare toThrow), and nothing is written
• the same refusal with isSystem: false spelled out, so the exemption is pinned to the flag's value and not to the key being absent
• a non-system last_update_at backdate → dropped, with droppedFields asserted as well as the unchanged stored value

Ablations

Both mutations were confirmed on disk before running (grep for the injected and the deleted text), and both were restored by an EXIT INT TERM trap.

Ablation	Predicted	Observed
drop readonly: true from completed_at (src/objects/task.object.ts)	the two refusal tests go red	exactly those 2 failed, 7 passed — the permissive assertions correctly stayed green
drop the mode: 'update' seed pass from the fixture	the stalled assertion goes red	1 failed, 8 passed — expected '2026-09-01T08:09:31.664Z' to be '2026-07-18T08:09:31.478Z'

The second one is the important one: it proves the two-pass shape this PR documents is load-bearing rather than decoration.

Gates

All four green at 4f42406, which is the final commit:

pnpm validate   exit 0   (one expected warning: hierarchy-security provider absent — the documented state of this repo)
pnpm typecheck  exit 0
pnpm test       exit 0   Test Files 15 passed (15) · Tests 428 passed (428)
pnpm build      exit 0   Artifact: dist/objectstack.json (98.8 KB)

pnpm test was re-run after pnpm build with dist/objectstack.json on disk — still 428/428 — confirming the suite's artifactPath guard holds and the tests report on src/, not on the last build.

Files changed

• test/seed-history.test.ts (new)
• AGENTS.md — the answer, next to the product invariants

src/data/ was deliberately not touched. The worked example lives in the test fixture and in AGENTS.md rather than in dulySeeds, because rows added there would boot on every pnpm dev and collide head-on with #7, which owns the real seed. This keeps the file surface to test/ + AGENTS.md. No breach of the declared surface.

Filed out of scope

• finding: the insert-path readonly strip is a protocol-boundary guard only — engine.insert applies none of it, and create_record's onFieldsDropped channel can never fire for a readonly drop objectstack#14147 — the insert-path readonly strip is a protocol-boundary guard only. engine.insert applies none of it (the update-path strip is in the engine and is isSystem-gated), and create_record wires an onFieldsDropped channel that can never fire for a readonly drop on that path. Pinned here as a tripwire written to go red and be deleted when the platform closes it. Not currently reachable in this app — assignment.flow.ts declares runAs: 'system'.
• beforeInsert overwrites a system-supplied last_update_at, so seeding a stalled task takes two passes instead of one #63 — beforeInsert overwrites a system-supplied last_update_at, which is what forces the second pass. The hook can see the context (ctx.session = { isSystem: true }, measured), so a one-line change would collapse it to one pass — but it widens what a system caller may do to the stagnation signal, so it is a triage decision, not a drive-by. src/hooks/ was outside this card's surface.

Generated by Claude Code

---

Generated by Claude Code