feat: add guarded legacy knowledge adoption

[andrei-hasna]

Refs hasna/todos bug 18b2bc16-b698-40b0-a4a8-844b3e1f6578.

Summary

• add bounded exact stored binding-state readback for full Knowledge IDs
• add version + raw-content-SHA CAS adoption of legacy rows with immutable FCAME-1 receipts
• add deterministic replay and receipt-scoped conditional rollback without content/version/history mutation
• preserve ordinary SQLite, hosted PostgreSQL/API, guarded writer, versioning, and CLI behavior
• bump @hasna/knowledge to 0.2.99 and rebuild committed artifacts

Verification

• affected guarded-writer/serve at the frozen head: 34 pass, 0 fail
• cross-tenant direct POST + SDK negative control: 1 pass, 0 fail; both return detail-free 404 and preserve the foreign row
• claim/receipt raw-SQL negative control: unrelated receipt refused, planned receipt accepted once, later rewrite refused
• migration append control: 118 prior statements byte-for-byte identical; 1 replacement-function statement appended
• bun run build
• bun run verify:generated: 6 bundles byte-identical
• bun test tests/package-release.test.ts: 6 pass, 0 fail
• bun run contracts:conformance
• bunx contracts no-cloud-scan .
• node scripts/validate-public-package.mjs
• staged gitleaks scan: 0 findings

Review scope

The exact candidate head is f26133e (tree fafc0eb3eea73c901b5ba2d0d5c6b240b67ecb3b). Formal adversarial review is coordinated against the linked OSS + hosted-wrapper release candidate after both heads are frozen.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[andrei-hasna]

[REVIEW] NO_GO — #80 @ 8c028e7 — lens: correctness+isolation+wiring, reviewer codewith-sol-reviewer (1 of 1)

P0 — None found.

P1 — src/serve.ts (bindingState and executeAdoption): any authenticated tenant with knowledge:read/knowledge:write can take ownership of any tenant-NULL legacy row. Existing ordinary list/get visibility includes every row whose authority_classification IS NULL, while the new binding-state query exposes such a row to every requested tenant and returns the exact version/content hash. executeAdoption then treats existing.tenant_id == null as valid for the caller and rewrites it to that caller's tenant. Thus tenant A can enumerate a legacy row, obtain all CAS inputs, bind it to tenant A, and make it unavailable to other tenants. The cross-tenant test covers an already-bound row, not this reachable tenant-NULL transition. Adoption needs an operator/ownership authorization boundary or a tenant-neutral migration authority that ordinary tenant keys cannot invoke.

P1 — src/serve.ts (knowledgeOpenApi): GuardedAdoptionEnvelope declares all request fields required and sets additionalProperties: false, but defines no properties. The published schema therefore rejects every non-empty adoption envelope, so spec-driven validation/code generation cannot legally call the new endpoint. GuardedAdoptionReceipt also omits the returned binding property required by the SDK rollback path. The added test only asserts that path keys exist and cannot detect this wiring failure.

P2 — None recorded.

P3 — None recorded.

Could not verify: I did not rerun the exact-head test matrix or apply the migration to a production-equivalent PostgreSQL instance. I reviewed the supplied exact-head diff and current base contracts read-only; no repository or merge state was changed.

[andrei-hasna]

[REVIEW] GO — #80 @ f26133e — lens: correctness+security+gates, reviewer Phaedon (1 of 1)

Reviewed the exact candidate against freshly fetched base origin/main at 8566f10b1dfe4b8186fc109f11150d8707392497.

What I read:

• git log --oneline origin/main..HEAD and git diff origin/main...HEAD --stat.
• The full diff for all 20 changed files, including the guarded-adoption contract and writer, HTTP validation and routes, PostgreSQL transaction/migrations/triggers, public exports and generated bundles/declarations, test fixtures and regression suites, README, changelog, and package metadata.
• Surrounding source for the authentication/tenant boundary, binding-state lookup, deterministic claim and planned-receipt binding, compare-and-swap checks, immutable receipts, reconciliation, and receipt-scoped rollback.

Commands and exact results:

• bun install — exit 0; 156 packages installed. Setup only, not the test result.
• bun run test — exit 0; 451 pass, 2 skip, 0 fail, 3547 expect() calls; 453 tests across 49 files in 161.33s.
• Typecheck — not run because package.json declares no typecheck script.
• No separate build command was included in the supplied repository gate set, so I did not invent one.

Adversarial checks covered the reachable cross-tenant and legacy-row paths: cross-tenant and absent targets share the same detail-free 404 surface; stale version/content hashes and wrong bindings have zero effects; direct content-mutating and stale claims are rejected; claim receipt binding is single-use and restricted to the planned receipt; accepted adoption preserves content, timestamps, version, and history; rollback is current-receipt- and compare-and-swap-scoped; lost POST responses reconcile without duplicate effects; TEXT and UUID tenant schemas plus the pre-adoption ledger upgrade pass.

Blocking P0/P1 findings: none.

Non-blocking follow-ups: none.

Verdict: GO. The exact declared test gate is green and the reviewed candidate has no concrete, currently reachable, in-scope P0/P1 defect.