iranti-control-plane 0.4.0

package/migrations/001_create_staff_events.sql

@@ -0,0 +1,65 @@
+-- Migration: 001_create_staff_events
+-- Spec ref: CP-T001 §3 (Option 1 schema)
+-- Creates the staff_events table for the Iranti Control Plane event stream.
+--
+-- The `event_id` column name matches CP-T001 spec (not generic `id`).
+-- CHECK constraints on staff_component and level enforce data integrity.
+-- All INSERT statements from application code use parameterized queries only.
+
+CREATE TABLE IF NOT EXISTS staff_events (
+  -- Primary key: UUID generated by DB
+  event_id        UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+
+  -- Timestamp: when the event occurred (NOT NULL — every event must have a timestamp)
+  timestamp       TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  -- Staff component: which subsystem emitted this event
+  -- Constrained to the 4 known components for data integrity
+  staff_component VARCHAR(32) NOT NULL
+    CHECK (staff_component IN ('Librarian', 'Attendant', 'Archivist', 'Resolutionist')),
+
+  -- Action type: what happened within the component
+  action_type     VARCHAR(64) NOT NULL,
+
+  -- The agent whose operation triggered this event
+  agent_id        TEXT,       -- Nullable: may be unknown for adapter-inferred events
+
+  -- The source surface (mcp, api, cli, etc.)
+  source          TEXT,
+
+  -- Entity targeting fields (all nullable — not all events target an entity)
+  entity_type     TEXT,
+  entity_id       TEXT,
+  key             TEXT,
+
+  -- Human-readable note from the triggering operation
+  reason          TEXT,
+
+  -- Event level: audit (always on) or debug (configurable)
+  level           VARCHAR(16) NOT NULL DEFAULT 'audit'
+    CHECK (level IN ('audit', 'debug')),
+
+  -- Component-specific supplementary data (schema varies by actionType)
+  metadata        JSONB
+);
+
+-- Index 1: Primary query pattern — time-ordered event stream
+-- Supports: SELECT * FROM staff_events ORDER BY timestamp DESC
+-- Supports: SELECT * FROM staff_events WHERE timestamp > :cursor ORDER BY timestamp ASC
+CREATE INDEX IF NOT EXISTS idx_staff_events_timestamp ON staff_events (timestamp DESC);
+
+-- Index 2: Filter by Staff component
+-- Supports: WHERE staff_component = 'Librarian'
+CREATE INDEX IF NOT EXISTS idx_staff_events_component ON staff_events (staff_component);
+
+-- Index 3: Filter by entity (compound — covers both type+id and type-only queries)
+-- Supports: WHERE entity_type = 'ticket' AND entity_id = 'cp_t001'
+-- Supports: WHERE entity_type = 'ticket'
+CREATE INDEX IF NOT EXISTS idx_staff_events_entity ON staff_events (entity_type, entity_id);
+
+-- Index 4: Filter by level (most queries filter to level='audit')
+CREATE INDEX IF NOT EXISTS idx_staff_events_level ON staff_events (level);
+
+-- Index 5: Filter by agent
+-- Supports: WHERE agent_id = 'product_manager'
+CREATE INDEX IF NOT EXISTS idx_staff_events_agent ON staff_events (agent_id);

package/migrations/002_create_archive_flags.sql

@@ -0,0 +1,46 @@
+-- Migration: 002_create_archive_flags
+-- Spec ref: CP-T049 (Archivist Decision Transparency)
+--
+-- Flag storage decision (OQ-1):
+--   A separate `archive_flags` table was chosen over a JSONB column on the archive
+--   row for the following reasons:
+--
+--   1. The archive table is an upstream Iranti schema — altering it with an ALTER TABLE
+--      risks colliding with upstream migrations and makes the control plane's concerns
+--      bleed into Iranti's core schema.
+--
+--   2. A relational table gives us a proper FK with CASCADE DELETE, so flags are
+--      automatically cleaned up if the archive row is ever garbage-collected by Iranti.
+--      The ticket risk assessment specifically called this out as a mitigation concern.
+--
+--   3. It is easier to query "all flagged facts" with a JOIN than to scan JSONB columns
+--      across the entire archive table.
+--
+--   4. Flags are a control-plane-owned concept; keeping them in a control-plane-owned
+--      table keeps the schema responsibility clean.
+
+CREATE TABLE IF NOT EXISTS archive_flags (
+  -- Primary key
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+
+  -- The archive row this flag refers to. Stored as TEXT because the archive table's
+  -- id column type may vary (bigint, uuid, or other) — we store it as a string reference
+  -- and do NOT add a FK constraint so we don't depend on the archive table's PK type.
+  -- If a FK is desired after confirming the archive id type, add it with CASCADE DELETE.
+  archive_id      TEXT NOT NULL,
+
+  -- Operator note — why they are flagging this fact
+  note            TEXT,
+
+  -- When the flag was created
+  flagged_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  -- Which operator/agent created the flag (from session context; nullable)
+  created_by      TEXT
+);
+
+-- Index: look up flags by archive_id (primary access pattern)
+CREATE INDEX IF NOT EXISTS idx_archive_flags_archive_id ON archive_flags (archive_id);
+
+-- Only one active flag per archive row (operators can edit the note by clearing and re-flagging)
+CREATE UNIQUE INDEX IF NOT EXISTS idx_archive_flags_unique_per_row ON archive_flags (archive_id);

package/migrations/003_staff_events_metrics_index.sql

@@ -0,0 +1,16 @@
+-- Migration: 003_staff_events_metrics_index
+-- Spec ref: CP-T060 (Metrics Dashboard — Backend)
+--
+-- Adds a compound index on staff_events (timestamp, agent_id, action_type) to
+-- support the aggregate GROUP BY queries used by the metrics endpoints.
+--
+-- The existing idx_staff_events_timestamp covers time-ordered streaming (timestamp DESC).
+-- This compound index covers the metrics query pattern:
+--   WHERE timestamp > $period_start AND action_type = ANY($types)
+--   GROUP BY DATE(timestamp), agent_id
+--
+-- Using BRIN would not help here because we need per-agent selectivity.
+-- A B-tree compound index is appropriate for this query shape.
+
+CREATE INDEX IF NOT EXISTS idx_staff_events_metrics
+  ON staff_events (timestamp, agent_id, action_type);

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "iranti-control-plane",
+  "version": "0.4.0",
+  "description": "Operator control plane for Iranti - local-first agent memory management",
+  "bin": {
+    "iranti-cp": "bin/iranti-cp.js"
+  },
+  "files": [
+    "bin/",
+    "dist/server/bundle.cjs",
+    "public/control-plane/",
+    "migrations/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "dev:server": "node scripts/dev-server.mjs",
+    "dev:client": "cd src/client && npm run dev",
+    "dev": "node scripts/dev.mjs",
+    "dev:reset": "node scripts/dev-reset.mjs",
+    "build:client": "cd src/client && npm run build",
+    "build:server": "cd src/server && npm run build",
+    "build": "npm run build:client && npm run build:server && npm run package:bundle",
+    "prepack": "npm run build",
+    "start": "cd src/server && npm start",
+    "migrate": ".\\src\\server\\node_modules\\.bin\\tsx src/server/migrations/runner.ts",
+    "setup": "node scripts/setup-wizard.js",
+    "dev-setup": "npm install --prefix src/server && npm install --prefix src/client",
+    "package:bundle": "node scripts/package/bundle.mjs",
+    "package:windows": "node scripts/package/archive/build-windows.mjs",
+    "package:macos": "node scripts/package/archive/build-macos.mjs",
+    "package:linux": "node scripts/package/archive/build-linux.mjs",
+    "package:all": "npm run package:bundle && npm run package:windows && npm run package:macos && npm run package:linux"
+  },
+  "devDependencies": {
+    "@clack/prompts": "^1.1.0",
+    "concurrently": "^8.2.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nfemmanuel/iranti-control-plane.git"
+  },
+  "homepage": "https://github.com/nfemmanuel/iranti-control-plane#readme",
+  "bugs": {
+    "url": "https://github.com/nfemmanuel/iranti-control-plane/issues"
+  },
+  "keywords": [
+    "iranti",
+    "control-plane",
+    "agent-memory",
+    "operator-dashboard",
+    "mcp",
+    "claude-code",
+    "codex"
+  ],
+  "author": "NF",
+  "license": "AGPL-3.0-or-later"
+}