docs+test: harden treatAsHistorical audit-timeline follow-ups (#3493)

[os-zhuang]

What & why

Follow-up hardening for #3497 (merged), which taught treatAsHistorical to preserve the original audit timeline (#3493). Two loose ends, neither releasing anything:

1. Docs — make the shipped capability discoverable

content/docs/protocol/objectql/state-machine.mdx is the one place treatAsHistorical is documented, but it only covered the FSM-skip half (#3479). One new bullet documents the audit-timeline half that shipped in #3497:

• Under treatAsHistorical, the write context also carries preserveAudit, which makes updated_at / updated_by client-preferred (a supplied historical last-modified survives instead of being stamped now, symmetric with created_at/created_by on insert), and admits a whitelist through the static-readonly write strip — the audit/timestamp family plus author-declared business readonly fields (closed_at, resolved_by, …).
• Platform-managed system columns outside that family (organization_id, tenancy/generated) stay stripped; permissions / RLS / FLS unchanged; opt-in.

2. Test — pin the one untested wire

Each layer of #3497 is tested (audit hook + readonly whitelist through the real engine in plugin.integration.test.ts; the driver's updated_at stamp in sql-driver-timestamp-format.test.ts; the runner wiring in import-runner-historical.test.ts) — but nothing asserted that the engine threads context.preserveAudit into the driver options, the wire that makes the driver's stamp reachable from a real write. Added that assertion in engine.test.ts via the shared buildDriverOptions observable (same pattern as the existing tenantId forwarding tests), plus its opt-in negative.

Notes

• Docs page is hand-written protocol content — no meta.json change (existing page), no generated-doc impact.
• Test-only + docs — releases nothing, so the changeset is intentionally empty (the sanctioned "no version bump" declaration the Check Changeset gate expects).
• The Check PR Size red on an earlier commit was an infra flake — the size-labeler Docker action timed out pulling alpine:3.15 from Docker Hub (fail_if_xl:false, so size never fails it); re-triggered by the test push.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 27, 2026 1:40am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/objectql.

13 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx (via packages/objectql)
• content/docs/deployment/migration-from-objectql.mdx (via @objectstack/objectql)
• content/docs/deployment/vercel.mdx (via @objectstack/objectql)
• content/docs/kernel/services-checklist.mdx (via @objectstack/objectql)
• content/docs/kernel/services.mdx (via @objectstack/objectql)
• content/docs/permissions/authentication.mdx (via @objectstack/objectql)
• content/docs/plugins/index.mdx (via @objectstack/objectql)
• content/docs/plugins/packages.mdx (via @objectstack/objectql)
• content/docs/protocol/kernel/index.mdx (via @objectstack/objectql)
• content/docs/protocol/objectql/state-machine.mdx (via @objectstack/objectql)
• content/docs/releases/implementation-status.mdx (via @objectstack/objectql)
• content/docs/releases/v9.mdx (via @objectstack/objectql)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.