suaveplan/openspec/archive/2026-05-19-wire-surreal-import-store/tasks.md

Tasks — wire-surreal-import-store

No retroactive ticks. Each item is checked only after its work is actually complete.

1. Author the spec delta

• 1.1 Draft specs/api-plugin-import/spec.md with ## ADDED Requirements for SurrealImportStore + .surql migration + extended OTel counter pair.
• 1.2 Every ### Requirement: carries **Verified by:** lines pointing at planned tests.

2. Implement SurrealImportStore

• 2.1 Create packages/api/api-plugin-import/src/store/surreal/surreal-import-store.ts implementing ImportStoreAdapter with positional SurQL placeholders.
• 2.2 Create packages/api/api-plugin-import/src/store/surreal/surreal-import-store.types.ts with SurrealImportStoreConfig (Zod-validated) + helper types.
• 2.3 Create packages/api/api-plugin-import/src/store/surreal/surreal-import-store.test.ts — fake-adapter unit tests covering every SurQL emission, parameter ordering, error normalisation, OTel counter increments, and the Job "<id>" not found reject.
• 2.4 Create packages/api/api-plugin-import/src/store/surreal/surreal-import-store.md (≥200 words, all six required sections).
• 2.5 Create packages/api/api-plugin-import/src/store/surreal/index.ts with explicit named re-exports (no export *).

3. Extend the OTel bundle

• 3.1 Add import.store.writes_total{outcome} and import.store.reads_total{outcome} counters to the existing getImportInstruments() bundle.
• 3.2 Update src/otel/instruments.md to document the two new counters.
• 3.3 Update src/otel/instruments.test.ts to assert both new counters appear in the cached bundle.

4. Ship the SurrealDB migration

• 4.1 Create packages/api/api-plugin-import/surql/tables/import_job.surql with the canonical OVERWRITE schema for the import_job table.
• 4.2 Document the path in the package README under a new "SurrealDB store" section.

5. Integration test against real SurrealDB

• 5.1 Create packages/api/api-plugin-import/tests/integration/surreal-import-store.test.ts using SurrealDBFixture — applies .surql, round-trips a record, exercises filter+limit+offset on list, asserts the update-on-missing reject.
• 5.2 Add vitest.integration.config.ts mirroring api-plugin-events's config (hookTimeout 180_000, testTimeout 60_000).

6. Package wiring

• 6.1 Add ./store/surreal/surreal-import-store to package.json#exports.
• 6.2 Add @suaveplan/surrealdb + @suaveplan/testing-integration-surrealdb to dependencies / devDependencies (workspace:^).
• 6.3 Add the public re-exports (SurrealImportStore, SurrealImportStoreConfig) to the package root barrel.

7. Pre-archive gates (all green — non-negotiable)

• 7.1 bunx biome check packages/api/api-plugin-import/src/
• 7.2 bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-import
• 7.3 bunx turbo test:coverage --filter=@suaveplan/api-plugin-import — 100 / 100 / 100 / 100
• 7.4 bun scripts/openspec-conformance.ts @suaveplan/api-plugin-import — 0 errors
• 7.5 bunx turbo build --filter=@suaveplan/api-plugin-import

8. Pre-archive checklist (9 rows)

• 8.1 Banned-pattern scan zero hits in new files.
• 8.2 Barrel-shape scan zero hits in src/store/surreal/index.ts.
• 8.3 Test-runner import scan zero hits (@suaveplan/testing/runner only).
• 8.4 Sibling .md exists for every new .ts (excluding .test.ts, .types.ts, index.ts).
• 8.5 README.md updated with SurrealDB store section.
• 8.6 No bare version pins in package.json (catalog / workspace only).
• 8.7 Subpath export count matches feature module count.
• 8.8 No hardcoded secrets in new files.
• 8.9 Dependent sweep — none impacted (ImportStoreAdapter is the only contract; opt-in by host).

9. Fold + archive

• 9.1 Fold specs/api-plugin-import/spec.md (this change's delta) into openspec/specs/api-plugin-import/spec.md.
• 9.2 mv openspec/changes/wire-surreal-import-store openspec/archive/2026-05-19-wire-surreal-import-store.

10. Commit

• 10.1 Pre-push: git fetch origin genesis && git pull --rebase --autostash origin genesis.
• 10.2 One commit: feat(api-plugin-import): add SurrealImportStore (was excluded in initial migration).
• 10.3 Never --no-verify. Never force-push.