nlm-memory 0.19.0 → 0.20.1

package/fixtures/classifier-gold/transcripts/13-research-vector-db-comparison.txt

@@ -0,0 +1,59 @@
+User: For pulsearch I need to pick a vector database. The candidates are pgvector, Qdrant, and Weaviate. We're embedding 2-3 million documents, need sub-100ms p99 search, and I want to avoid managing a separate service if possible. Can you compare them?
+
+Agent: Here's a structured comparison for the pulsearch use case:
+
+pgvector
+- Runs as a Postgres extension, so no separate service if you're already on Postgres
+- At 2-3M vectors, IVFFlat and HNSW indexes both work but require tuning (lists parameter for IVFFlat, ef_construction for HNSW)
+- Sub-100ms p99 is achievable at this scale with HNSW and appropriate connection pool sizing
+- Filtering on metadata is native SQL, which is convenient
+- Writes block on the HNSW index during bulk inserts; need to insert then create index, not the other way around
+
+Qdrant
+- Dedicated vector database, separate service (Docker or cloud)
+- HNSW index is its primary structure, very well tuned; consistently strong benchmark numbers at 1-10M scale
+- Payload filtering is first-class and done before the ANN step, not post-filter, which matters for selective queries
+- REST and gRPC APIs; client libraries for Python, TypeScript, Go
+- Requires running and operating another service
+
+Weaviate
+- Dedicated vector database with a built-in GraphQL query layer
+- More opinionated about data modeling (schemas with classes)
+- Larger operational footprint than Qdrant
+- Better fit when you need hybrid BM25+vector search out of the box
+
+For pulsearch specifically:
+- If Postgres is already in your stack and ops simplicity is the priority, pgvector with HNSW is reasonable at 2-3M documents
+- If you want best-in-class ANN performance and are comfortable running another service, Qdrant is the stronger choice at this scale
+- Weaviate adds complexity without clear benefit unless you need its GraphQL layer
+
+User: We're already running Postgres, but search quality is the top priority. What do you recommend?
+
+Agent: Go with Qdrant. At 2-3M documents with sub-100ms p99 as a hard requirement, Qdrant's HNSW implementation is more predictable than pgvector's, and payload filtering before the ANN step means selective filters don't degrade recall. The operational overhead of one additional Docker container is low.
+
+You can keep Postgres for everything else and run Qdrant alongside it. The pulsearch embedding pipeline writes to both: Postgres for the source record, Qdrant for the vector.
+
+User: Agreed. What collection configuration would you recommend for pulsearch?
+
+Agent: For 2-3M documents with 1536-dim embeddings (if using text-embedding-3-small) or 768-dim (if using a local model):
+
+```python
+client.create_collection(
+    collection_name="pulsearch-docs",
+    vectors_config=VectorParams(
+        size=1536,        # adjust to your embedding dim
+        distance=Distance.COSINE,
+    ),
+    hnsw_config=HnswConfigDiff(
+        m=16,
+        ef_construct=100,
+    ),
+    optimizers_config=OptimizersConfigDiff(
+        indexing_threshold=10_000,  # don't index small batches
+    ),
+)
+```
+
+HNSW m=16 and ef_construct=100 are conservative defaults that hit sub-100ms comfortably at this scale. You can increase ef_construct for higher recall at the cost of slower indexing.
+
+User: Perfect. Let's go with Qdrant.

package/fixtures/classifier-gold/transcripts/14-research-oauth-provider.txt

@@ -0,0 +1,74 @@
+User: irongate needs customer-facing OAuth 2.0. I'm evaluating Keycloak self-hosted versus Auth0 versus SuperTokens. The main requirements are: LDAP integration for our enterprise customers, self-hosted option, OIDC compliance. What do you think?
+
+Agent: All three support OIDC. The differentiating factor for your requirements is the LDAP integration:
+
+Keycloak
+- Full LDAP and Active Directory federation, built-in and well-documented
+- Self-hosted; runs as a Java service (Quarkus distribution, Docker-friendly)
+- Enterprise-grade: major deployments at scale, active community
+- Admin UI is functional but has a learning curve
+- Free and open source (Apache 2.0)
+
+Auth0
+- LDAP integration via Enterprise Connections, which requires the Business tier ($800+/month for even modest user counts)
+- Managed SaaS; a self-hosted option exists via Auth0 Private Cloud but is expensive and not truly self-hosted
+- Developer experience is excellent; SDKs are polished
+- Cost scales with monthly active users, which gets expensive fast
+
+SuperTokens
+- Self-hosted option available (open source core)
+- No native LDAP integration; enterprise SSO via their Enterprise tier which supports SAML but LDAP is not supported as a user federation source
+- Better for consumer apps; gaps in enterprise identity features
+
+For irongate with the LDAP requirement, Keycloak is the clear choice. It is the only option that covers all three requirements (LDAP federation, self-hosted, OIDC) without additional cost.
+
+User: What's the operational complexity of running Keycloak?
+
+Agent: Moderate. Key considerations:
+
+- Runs as a stateless application backed by Postgres (recommended) or H2 for dev
+- Horizontal scaling works but requires a shared Postgres backend and sticky sessions for the admin console
+- Startup time is 15-30 seconds cold; plan for that in your container orchestration health checks
+- The default Keycloak Docker image needs a few environment variables: KEYCLOAK_ADMIN, KEYCLOAK_ADMIN_PASSWORD, KC_DB_URL, KC_DB_USERNAME, KC_DB_PASSWORD
+- Realm export/import is the standard backup mechanism; automate this
+
+For irongate at this stage (pre-scale), a single Keycloak instance behind your nginx proxy on a dedicated small VM is sufficient. You can add a replica later.
+
+User: Let's go with Keycloak self-hosted backed by Postgres.
+
+Agent: Good choice. I'll draft the Docker Compose configuration for the irongate auth stack.
+
+[Write: docker-compose.auth.yml]
+
+```yaml
+services:
+  keycloak:
+    image: quay.io/keycloak/keycloak:24.0
+    command: start
+    environment:
+      KC_DB: postgres
+      KC_DB_URL: jdbc:postgresql://auth-db:5432/keycloak
+      KC_DB_USERNAME: keycloak
+      KC_DB_PASSWORD: ${KC_DB_PASSWORD}
+      KC_HOSTNAME: auth.irongate.example.com
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
+    depends_on:
+      - auth-db
+    ports:
+      - "8180:8080"
+
+  auth-db:
+    image: postgres:16
+    environment:
+      POSTGRES_DB: keycloak
+      POSTGRES_USER: keycloak
+      POSTGRES_PASSWORD: ${KC_DB_PASSWORD}
+    volumes:
+      - keycloak-pgdata:/var/lib/postgresql/data
+
+volumes:
+  keycloak-pgdata:
+```
+
+User: Perfect. We'll proceed with Keycloak.

package/fixtures/classifier-gold/transcripts/15-writing-api-docs.txt

@@ -0,0 +1,154 @@
+User: I need to write API documentation for cobalt-api. The API has about 12 endpoints. I want to use OpenAPI 3.0 format and host the docs at /api-docs. Can you help me set this up and draft the first few endpoints?
+
+Agent: [Read: src/routes/index.ts]
+
+I can see the route structure. Let me read the auth and resources endpoints to understand the request/response shapes.
+
+[Read: src/routes/auth.ts]
+[Read: src/routes/resources.ts]
+
+Good. I'll draft the OpenAPI 3.0 spec for the auth and resources sections. For hosting at /api-docs, Swagger UI is the standard choice and integrates cleanly with Express.
+
+User: Use Swagger UI. Let's document the auth endpoints first: POST /auth/token and POST /auth/refresh.
+
+Agent: [Write: docs/openapi.yaml]
+
+```yaml
+openapi: "3.0.3"
+info:
+  title: cobalt-api
+  version: "1.0.0"
+  description: REST API for the Cobalt platform
+
+servers:
+  - url: https://api.cobalt.example.com/v1
+    description: Production
+  - url: http://localhost:3000/v1
+    description: Local development
+
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+  schemas:
+    TokenResponse:
+      type: object
+      required: [access_token, refresh_token, expires_in]
+      properties:
+        access_token:
+          type: string
+        refresh_token:
+          type: string
+        expires_in:
+          type: integer
+          description: Seconds until access_token expires
+
+    Error:
+      type: object
+      required: [error, message]
+      properties:
+        error:
+          type: string
+        message:
+          type: string
+
+paths:
+  /auth/token:
+    post:
+      summary: Exchange credentials for tokens
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [email, password]
+              properties:
+                email:
+                  type: string
+                  format: email
+                password:
+                  type: string
+      responses:
+        "200":
+          description: Token pair
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TokenResponse"
+        "401":
+          description: Invalid credentials
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /auth/refresh:
+    post:
+      summary: Exchange a refresh token for a new access token
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [refresh_token]
+              properties:
+                refresh_token:
+                  type: string
+      responses:
+        "200":
+          description: New token pair
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TokenResponse"
+        "401":
+          description: Invalid or expired refresh token
+```
+
+User: Good. Now wire up Swagger UI to serve this at /api-docs.
+
+Agent: [Bash: npm install swagger-ui-express @types/swagger-ui-express yaml -D]
+
+[Read: src/app.ts]
+
+[Edit: src/app.ts]
+
+```typescript
+import swaggerUi from "swagger-ui-express";
+import { readFileSync } from "node:fs";
+import { parse } from "yaml";
+
+const spec = parse(readFileSync("docs/openapi.yaml", "utf-8")) as object;
+app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(spec));
+```
+
+User: Does this need to be behind auth?
+
+Agent: Typically no; API docs are public. But if cobalt-api exposes internal implementation details (internal error codes, admin endpoints), you might want to gate it. For now I'll leave it public and you can add middleware later if needed.
+
+User: Fine as-is. Run the server and confirm /api-docs loads.
+
+Agent: [Bash: npm run dev &]
+
+```
+Server listening on http://localhost:3000
+```
+
+[Bash: curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/api-docs/]
+
+```
+301
+```
+
+[Bash: curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/api-docs]
+
+```
+200
+```
+
+Redirects to trailing slash, returns 200. Swagger UI is serving the spec at /api-docs.

package/fixtures/classifier-gold/transcripts/16-meeting-sprint-planning.txt

@@ -0,0 +1,69 @@
+User: I need to capture the notes from our sprint planning meeting for orbitflow. Here's what we covered:
+
+Attendees: product, backend, frontend squads
+
+Sprint 5 goals we discussed:
+- Webhook retry feature (backend priority, carries over from sprint 4 incomplete)
+- Analytics dashboard (frontend wanted this but product deprioritized it)
+- Rate limiting on the ingest API (security team flagged it last week)
+- Mobile push notifications (new request, everyone agreed too large for this sprint)
+
+Capacity: backend has 3 devs, one on PTO mid-sprint. Frontend has 2 devs full capacity.
+
+Decisions made:
+- Webhook retry moves to sprint 5 as the top backend priority
+- Analytics dashboard deferred to sprint 6
+- Rate limiting assigned to backend as secondary item
+- Mobile push notifications deferred to sprint 6 backlog
+
+Sprint 5 end date: July 18.
+
+Can you format these into clean sprint notes?
+
+Agent: Here are the sprint 5 planning notes for orbitflow:
+
+---
+
+Sprint 5 Planning Notes
+orbitflow | Sprint 5 | Ends July 18
+
+Attendees: Product, Backend squad (3 devs, one PTO mid-sprint), Frontend squad (2 devs)
+
+Committed Items
+
+Backend (primary)
+- Webhook retry with exponential backoff [carries over from sprint 4]
+
+Backend (secondary)
+- Rate limiting on ingest API [security flag from last week]
+
+Deferred
+
+- Analytics dashboard: pushed to sprint 6 [frontend request, deprioritized by product]
+- Mobile push notifications: pushed to sprint 6 backlog [scope too large for current capacity]
+
+Capacity Notes
+
+Backend is constrained mid-sprint due to PTO; webhook retry is the single priority. Rate limiting is secondary and may slip if webhook retry runs long.
+
+---
+
+User: Looks good. Can you also add a risks section?
+
+Agent: Updated with risks:
+
+---
+
+Risks
+
+1. Backend PTO mid-sprint reduces capacity by roughly 33% for one week. If webhook retry is not at code review by day 6, rate limiting will slip to sprint 6.
+2. Rate limiting scope is not fully defined. The security team flagged the need but did not specify limits or key type. Backend needs a brief sync with security before starting implementation.
+3. Analytics dashboard deferral may resurface as a blocker if frontend has no other committed work. Confirm frontend squad has sufficient sprint 5 items.
+
+---
+
+User: Perfect. Save this to docs/sprints/sprint-5-planning.md.
+
+Agent: [Write: docs/sprints/sprint-5-planning.md]
+
+Saved. The sprint 5 notes are in docs/sprints/sprint-5-planning.md with attendees, committed items, deferrals, capacity notes, and risks.

package/fixtures/classifier-gold/transcripts/17-trivial-list-files.txt

@@ -0,0 +1,14 @@
+User: What files are in the src/ directory?
+
+Agent: [Bash: ls src/]
+
+```
+app.ts
+config.ts
+index.ts
+routes.ts
+```
+
+Four files: app.ts, config.ts, index.ts, and routes.ts.
+
+User: Thanks.

package/fixtures/classifier-gold/transcripts/18-trivial-version-check.txt

@@ -0,0 +1,21 @@
+User: What version of Node.js is installed?
+
+Agent: [Bash: node --version]
+
+```
+v22.4.0
+```
+
+Node.js v22.4.0.
+
+User: And npm?
+
+Agent: [Bash: npm --version]
+
+```
+10.8.1
+```
+
+npm 10.8.1.
+
+User: Good, that's what I needed.

package/fixtures/classifier-gold/transcripts/19-trivial-syntax-help.txt

@@ -0,0 +1,29 @@
+User: How do I iterate over an array in TypeScript and get both the index and the value?
+
+Agent: Use `Array.prototype.entries()` with a `for...of` loop:
+
+```typescript
+const items = ["a", "b", "c"];
+for (const [index, value] of items.entries()) {
+  console.log(index, value);
+}
+```
+
+Output:
+```
+0 a
+1 b
+2 c
+```
+
+Alternatively, `forEach` with two parameters:
+
+```typescript
+items.forEach((value, index) => {
+  console.log(index, value);
+});
+```
+
+The `for...of` with `.entries()` is generally preferred in modern TypeScript because it works with `break` and `continue`, which `forEach` does not.
+
+User: Got it, thanks.

package/fixtures/classifier-gold/transcripts/20-trivial-read-package-json.txt

@@ -0,0 +1,41 @@
+User: Read the package.json and tell me what dependencies are listed.
+
+Agent: [Read: package.json]
+
+```json
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "express": "^4.18.2",
+    "pg": "^8.11.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  }
+}
+```
+
+Dependencies:
+- express ^4.18.2
+- pg ^8.11.0
+
+Dev dependencies:
+- typescript ^5.3.3
+- vitest ^1.2.0
+
+User: Are they installed?
+
+Agent: [Bash: ls node_modules | grep -E "^(express|pg|typescript|vitest)$"]
+
+```
+express
+pg
+typescript
+vitest
+```
+
+All four are installed in node_modules.
+
+User: Perfect, thanks.

package/migrations/000_initial_schema.sql

@@ -40,7 +40,7 @@ CREATE TABLE IF NOT EXISTS entities (
   canonical           TEXT PRIMARY KEY,           -- preferred spelling — also the primary key
   type                TEXT NOT NULL,              -- 'candidate' until labeled. Built-in labels: project | tool | contact | service | concept. Custom labels are user-defined via the UI / `nle-daemon action label` and have no CHECK constraint.
   status              TEXT NOT NULL CHECK(status IN ('active','dormant','retired','rejected','candidate')),
-  source              TEXT,                       -- e.g. 'property:.claude/properties/polysignal.yaml', 'auto-detected', 'user-registered'
+  source              TEXT,                       -- e.g. 'property:.claude/properties/beacon.yaml', 'auto-detected', 'user-registered'
   notes               TEXT,                       -- freeform user notes
   first_seen_session  TEXT REFERENCES sessions(id),
   last_seen_session   TEXT REFERENCES sessions(id),

package/migrations/024_backfill_exemplar_repo_basename.sql

@@ -0,0 +1,32 @@
+-- Migration 024: backfill code_exemplars.repo to logical basenames.
+--
+-- The pre-#330 session-capture path (captureExemplarsFromSession) stamped the
+-- absolute projectDir into the repo column, leaking a host filesystem path
+-- (/Users/.../<name>) into the local store — meaningless on a client install
+-- and a privacy concern (per-install scoping, synthesis item 4). The #330
+-- producer (nlm code-signal) and the now-fixed session-capture path both
+-- record the logical basename instead.
+--
+-- This strips any directory prefix from existing absolute-path repos in place,
+-- generically (no hardcoded host path), via a recursive CTE that peels off
+-- each segment up to and including the next '/' until none remains. Idempotent:
+-- once every repo is a basename, `repo LIKE '/%'` matches nothing and re-running
+-- is a no-op. Fresh installs have no leaked rows, so this is a no-op there too.
+--
+-- The primary key id (sha256 of install_scope|repo|code_hash|outcome) is NOT
+-- recomputed — SQLite cannot sha256 in pure SQL. The stale id is harmless: it
+-- stays a valid unique key and keeps its embedding link. The only consequence
+-- is that re-capturing the exact same legacy commit via the basename path would
+-- compute a fresh id and insert a duplicate rather than dedup-skip — a rare
+-- edge (requires a full re-ingest of old sessions) and never wrong data.
+
+WITH RECURSIVE basename(id, rest) AS (
+  SELECT id, repo FROM code_exemplars WHERE repo LIKE '/%'
+  UNION ALL
+  SELECT id, substr(rest, instr(rest, '/') + 1) FROM basename WHERE instr(rest, '/') > 0
+)
+UPDATE code_exemplars
+SET repo = (SELECT rest FROM basename WHERE basename.id = code_exemplars.id AND instr(basename.rest, '/') = 0)
+WHERE repo LIKE '/%';
+
+INSERT OR IGNORE INTO schema_migrations (version, name) VALUES (24, '024_backfill_exemplar_repo_basename');

package/migrations/025_workstreams.sql

@@ -0,0 +1,30 @@
+-- migrations/025_workstreams.sql
+-- Workstream abstraction (#367) Plan A: a persistent container a session binds
+-- to at end-of-session. See docs/superpowers/specs/2026-06-24-workstream-abstraction-design.md.
+
+CREATE TABLE IF NOT EXISTS workstreams (
+  id              TEXT PRIMARY KEY,           -- ws_<uuid>
+  label           TEXT NOT NULL,
+  status          TEXT NOT NULL DEFAULT 'active' CHECK(status IN ('active','merged','retired')),
+  merged_into     TEXT REFERENCES workstreams(id),
+  created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at      TEXT NOT NULL DEFAULT (datetime('now')),
+  last_session_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS workstream_entities (
+  workstream_id    TEXT NOT NULL REFERENCES workstreams(id) ON DELETE CASCADE,
+  entity_canonical TEXT NOT NULL REFERENCES entities(canonical),
+  session_count    INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (workstream_id, entity_canonical)
+);
+
+CREATE INDEX IF NOT EXISTS idx_workstream_entities_entity ON workstream_entities(entity_canonical);
+
+ALTER TABLE sessions ADD COLUMN workstream_id TEXT REFERENCES workstreams(id);
+ALTER TABLE sessions ADD COLUMN binding_source TEXT;
+ALTER TABLE sessions ADD COLUMN binding_confidence REAL;
+
+CREATE INDEX IF NOT EXISTS idx_sessions_workstream ON sessions(workstream_id);
+
+INSERT OR IGNORE INTO schema_migrations (version, name) VALUES (25, 'workstreams');

package/migrations/026_embedding_config.sql

@@ -0,0 +1,12 @@
+-- Records which embedder produced the stored vectors, per lane.
+-- lane 'prose' covers session chunks and fact embeddings (same embedder);
+-- lane 'code' covers code exemplar embeddings.
+-- Absence of a row means pre-tracking corpus: reconcile treats the running
+-- embedder as canonical and records it.
+CREATE TABLE IF NOT EXISTS embedding_config (
+  lane       TEXT PRIMARY KEY CHECK (lane IN ('prose', 'code')),
+  provider   TEXT NOT NULL,
+  model      TEXT NOT NULL,
+  dim        INTEGER NOT NULL,
+  updated_at TEXT NOT NULL
+);

package/migrations/027_drop_legacy_session_embeddings.sql

@@ -0,0 +1,7 @@
+-- Migration 027: drop the legacy session_embeddings virtual table.
+-- Migration 003 created it; migration 009 superseded it with the chunk + max-pool index.
+
+DROP TABLE IF EXISTS session_embeddings;
+
+INSERT OR IGNORE INTO schema_migrations (version, name)
+  VALUES (27, '027_drop_legacy_session_embeddings');

package/migrations/028_classifier_provenance.sql

@@ -0,0 +1,5 @@
+-- Which classifier produced this session's classification. NULL = classified
+-- before provenance tracking; nlm reprocess treats NULL as eligible.
+ALTER TABLE sessions ADD COLUMN classifier_provider TEXT;
+ALTER TABLE sessions ADD COLUMN classifier_model TEXT;
+ALTER TABLE sessions ADD COLUMN classifier_confidence REAL;

package/migrations/pg/001_initial.sql

@@ -26,6 +26,9 @@ CREATE TABLE IF NOT EXISTS sessions (
   transcript_length    BIGINT,
   created_at           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   updated_at           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  workstream_id        TEXT,
+  binding_source       TEXT,
+  binding_confidence   DOUBLE PRECISION,
   fts_vector           TSVECTOR GENERATED ALWAYS AS (
     setweight(to_tsvector('english', coalesce(label, '')), 'A') ||
     setweight(to_tsvector('english', coalesce(summary, '')), 'B') ||
@@ -255,3 +258,34 @@ CREATE TABLE IF NOT EXISTS code_exemplar_embeddings (
 CREATE INDEX IF NOT EXISTS code_exemplar_embeddings_idx
   ON code_exemplar_embeddings USING ivfflat (embedding vector_l2_ops)
   WITH (lists = 100);
+
+-- ── Workstreams (mirror of SQLite migration 025) ─────────────────────────────
+CREATE TABLE IF NOT EXISTS workstreams (
+  id              TEXT PRIMARY KEY,
+  label           TEXT NOT NULL,
+  status          TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','merged','retired')),
+  merged_into     TEXT REFERENCES workstreams(id),
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  last_session_at TIMESTAMPTZ
+);
+
+CREATE TABLE IF NOT EXISTS workstream_entities (
+  workstream_id    TEXT NOT NULL REFERENCES workstreams(id) ON DELETE CASCADE,
+  entity_canonical TEXT NOT NULL REFERENCES entities(canonical),
+  session_count    INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (workstream_id, entity_canonical)
+);
+
+CREATE INDEX IF NOT EXISTS idx_workstream_entities_entity ON workstream_entities(entity_canonical);
+
+-- FK from sessions.workstream_id to workstreams (deferred so workstreams exists first)
+DO $$
+BEGIN
+  ALTER TABLE sessions
+    ADD CONSTRAINT fk_sessions_workstream
+    FOREIGN KEY (workstream_id) REFERENCES workstreams(id);
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+CREATE INDEX IF NOT EXISTS idx_sessions_workstream ON sessions(workstream_id);

package/migrations/pg/019_split_replaces.sql

@@ -1,9 +1,10 @@
 -- PG parity for SQLite migration 019: split the mechanical `replaces` relation
 -- out of `supersedes`.
 --
--- One-shot repair, applied manually by an operator against a PG canonical store
--- (PgStorage.init only runs 001_initial.sql; there is no version-gated runner on
--- the PG side). Mirrors migrations/019_split_replaces.sql.
+-- Idempotent: safe to re-apply on a database that already has this shape.
+-- DROP CONSTRAINT IF EXISTS removes any existing named constraint before the
+-- DO-block re-adds it, so duplicate_object is never raised in practice;
+-- the EXCEPTION clause is defensive for parity with the 001 pattern.
 --
 -- Widens the CHECK constraints on sessions.status and session_edges.kind to
 -- admit 'replaced' / 'replaces', then reclassifies existing mechanical edges:
@@ -13,12 +14,20 @@
 BEGIN;
 
 ALTER TABLE sessions DROP CONSTRAINT IF EXISTS sessions_status_check;
-ALTER TABLE sessions ADD CONSTRAINT sessions_status_check
-  CHECK (status IN ('active', 'closed', 'superseded', 'replaced'));
+DO $$
+BEGIN
+  ALTER TABLE sessions ADD CONSTRAINT sessions_status_check
+    CHECK (status IN ('active', 'closed', 'superseded', 'replaced'));
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
 
 ALTER TABLE session_edges DROP CONSTRAINT IF EXISTS session_edges_kind_check;
-ALTER TABLE session_edges ADD CONSTRAINT session_edges_kind_check
-  CHECK (kind IN ('supersedes', 'replaces', 'continues'));
+DO $$
+BEGIN
+  ALTER TABLE session_edges ADD CONSTRAINT session_edges_kind_check
+    CHECK (kind IN ('supersedes', 'replaces', 'continues'));
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
 
 UPDATE session_edges e SET kind = 'replaces'
 WHERE e.kind = 'supersedes'