Initial Commit

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

@@ -0,0 +1,69 @@
+# 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.