# 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.