@oscharko-dev/keiko-server 0.2.0

package/dist/store/schema.d.ts

@@ -0,0 +1,4 @@
+import type { DatabaseSync } from "node:sqlite";
+export declare const SCHEMA_VERSION = 5;
+export declare function runMigrations(db: DatabaseSync): void;
+//# sourceMappingURL=schema.d.ts.map

package/dist/store/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/store/schema.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,cAAc,IAAI,CAAC;AAqNhC,wBAAgB,aAAa,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAepD"}

package/dist/store/schema.js

@@ -0,0 +1,220 @@
+// ADR-0013 D5 — Schema v1 + migration runner via PRAGMA user_version. Forward-only, idempotent,
+// transactional. Each migration is a `.sql` string of one or more CREATE/ALTER statements; the
+// runner applies migrations whose 1-based index > current user_version.
+export const SCHEMA_VERSION = 5;
+const V1_SQL = `
+CREATE TABLE projects (
+  path TEXT NOT NULL PRIMARY KEY,
+  name TEXT NOT NULL,
+  favorite INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL,
+  last_opened_at INTEGER NOT NULL
+) STRICT;
+
+CREATE TABLE chats (
+  id TEXT NOT NULL PRIMARY KEY,
+  project_path TEXT NOT NULL REFERENCES projects(path) ON DELETE CASCADE,
+  title TEXT NOT NULL,
+  selected_model TEXT NOT NULL,
+  branch_label TEXT,
+  status TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+) STRICT;
+
+CREATE TABLE chat_messages (
+  id TEXT NOT NULL PRIMARY KEY,
+  chat_id TEXT NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
+  role TEXT NOT NULL,
+  content TEXT NOT NULL,
+  timestamp INTEGER NOT NULL,
+  run_id TEXT,
+  workflow_id TEXT,
+  workflow_status TEXT,
+  short_result TEXT
+) STRICT;
+
+CREATE INDEX idx_chats_project_path ON chats(project_path);
+CREATE INDEX idx_messages_chat_id ON chat_messages(chat_id);
+CREATE INDEX idx_messages_chat_ts ON chat_messages(chat_id, timestamp);
+`;
+// V2 (issue #66) adds an additive `task_type` column to chat_messages so the chat can label
+// non-workflow task runs (verify, explain-plan) without overloading workflow_id. STRICT tables
+// require an explicit type for ALTER ... ADD COLUMN; existing rows materialise NULL.
+const V2_SQL = `
+ALTER TABLE chat_messages ADD COLUMN task_type TEXT;
+`;
+// V3 (issue #184) adds two additive columns to `chats` so a chat can carry its connected
+// Files-window scope across reloads. `connected_scope_paths` keeps its legacy column name but
+// stores the JSON scope payload ({ kind, relativePaths }); PR #254 legacy rows that stored only a
+// JSON path array decode as files scopes. `connected_scope_at` stores epoch ms. Both NULL for
+// pre-binding rows; patching either column to NULL clears the binding. The combination round-trips
+// into the wire-type ChatConnectedScope at the store boundary.
+const V3_SQL = `
+ALTER TABLE chats ADD COLUMN connected_scope_paths TEXT;
+ALTER TABLE chats ADD COLUMN connected_scope_at INTEGER;
+`;
+// V4 (issue #200) adds additive local-knowledge scope state to chats. The JSON payload stores
+// either { kind: "capsule", capsuleId, connectedAtMs } or { kind: "capsule-set", capsuleSetId,
+// connectedAtMs }. NULL means no local-knowledge scope is selected for the chat.
+const V4_SQL = `
+ALTER TABLE chats ADD COLUMN local_knowledge_scope_json TEXT;
+`;
+// V5 (issue #539, epic #532) — relationship engine tables. STRICT mode. The schema follows
+// docs/relationship-engine/storage.md §3.1 (relationships, lifecycle history) and
+// docs/relationship-engine/audit-events.md §5.5 (relationship_audit_entries sibling table).
+// No FOREIGN KEY from relationships → projects: endpoint liveness is resolved at the API edge
+// through the RelationshipEndpointResolver port (storage.md §2.2). Indexes serve the bounded
+// query patterns from api-contract.md §4.3; partial unique indexes enforce 1:1 cardinality at
+// the DB layer as a second barrier alongside the validator (storage.md §3.3, §4.1).
+const V5_SQL = `
+CREATE TABLE relationships (
+  id                  TEXT NOT NULL PRIMARY KEY,
+  schema_version      TEXT NOT NULL,
+  workspace_scope_id  TEXT NOT NULL,
+  scope_kind          TEXT NOT NULL,
+  scope_coordinate    TEXT NOT NULL,
+  type                TEXT NOT NULL,
+  source_kind         TEXT NOT NULL,
+  source_id           TEXT NOT NULL,
+  target_kind         TEXT NOT NULL,
+  target_id           TEXT NOT NULL,
+  lifecycle           TEXT NOT NULL,
+  created_at          INTEGER NOT NULL,
+  updated_at          INTEGER NOT NULL,
+  etag                TEXT NOT NULL,
+  confidence          REAL,
+  summary             TEXT,
+  CHECK (
+    schema_version IN ('1')
+    AND type IN (
+      'reads-context','proposes-patch','uses-tool','starts-workflow',
+      'produces-evidence','references-document','depends-on'
+    )
+    AND lifecycle IN (
+      'draft','active','archived','superseded','revoked','blocked','stale'
+    )
+    AND scope_kind IN ('user','workspace','project','workflow','global')
+    AND source_kind IN (
+      'memory','capsule','capsule-set','workflow-run','evidence-run',
+      'workspace-path','chat','tool','patch-proposal',
+      'agent','connector','data-source','skill','mcp-tool'
+    )
+    AND target_kind IN (
+      'memory','capsule','capsule-set','workflow-run','evidence-run',
+      'workspace-path','chat','tool','patch-proposal',
+      'agent','connector','data-source','skill','mcp-tool'
+    )
+    AND created_at >= 0
+    AND updated_at >= created_at
+    AND (confidence IS NULL OR (confidence >= 0.0 AND confidence <= 1.0))
+    AND (summary IS NULL OR length(summary) <= 240)
+  )
+) STRICT;
+
+CREATE INDEX idx_relationships_source
+  ON relationships(workspace_scope_id, source_kind, source_id);
+CREATE INDEX idx_relationships_target
+  ON relationships(workspace_scope_id, target_kind, target_id);
+CREATE INDEX idx_relationships_type
+  ON relationships(workspace_scope_id, type, lifecycle);
+CREATE INDEX idx_relationships_lifecycle
+  ON relationships(workspace_scope_id, lifecycle, updated_at);
+
+CREATE UNIQUE INDEX uniq_relationships_produces_evidence_source
+  ON relationships(workspace_scope_id, source_kind, source_id)
+  WHERE type = 'produces-evidence' AND lifecycle IN ('draft','active','archived');
+
+CREATE UNIQUE INDEX uniq_relationships_starts_workflow_target
+  ON relationships(workspace_scope_id, target_kind, target_id)
+  WHERE type = 'starts-workflow' AND lifecycle IN ('draft','active','archived');
+
+CREATE TABLE relationship_lifecycle_history (
+  id              TEXT NOT NULL PRIMARY KEY,
+  relationship_id TEXT NOT NULL REFERENCES relationships(id) ON DELETE CASCADE,
+  from_state      TEXT NOT NULL,
+  to_state        TEXT NOT NULL,
+  occurred_at     INTEGER NOT NULL,
+  summary         TEXT,
+  CHECK (
+    from_state IN ('draft','active','archived','superseded','revoked','blocked','stale')
+    AND to_state IN ('draft','active','archived','superseded','revoked','blocked','stale')
+    AND occurred_at >= 0
+    AND (summary IS NULL OR length(summary) <= 240)
+  )
+) STRICT;
+
+CREATE INDEX idx_relationship_lifecycle_relationship
+  ON relationship_lifecycle_history(relationship_id, occurred_at);
+
+CREATE TABLE relationship_audit_entries (
+  event_id                       TEXT NOT NULL PRIMARY KEY,
+  relationship_audit_schema_ver  TEXT NOT NULL,
+  workspace_id                   TEXT NOT NULL,
+  sequence                       INTEGER NOT NULL,
+  occurred_at                    INTEGER NOT NULL,
+  kind                           TEXT NOT NULL,
+  relationship_id                TEXT,
+  actor_surface                  TEXT NOT NULL,
+  redacted_actor_id              TEXT NOT NULL,
+  redaction_state                TEXT NOT NULL,
+  summary                        TEXT NOT NULL,
+  payload_json                   TEXT NOT NULL,
+  CHECK (
+    relationship_audit_schema_ver IN ('1')
+    AND kind IN (
+      'relationship.created','relationship.updated','relationship.deleted',
+      'relationship.reconnected','relationship.validation-denied',
+      'relationship.policy-denied','relationship.activity-transitioned',
+      'relationship.impact-analysis-bounded','relationship.health-finding'
+    )
+    AND actor_surface IN ('chat','inspector','workflow','health-check','system')
+    AND redaction_state IN ('redacted-on-write','redacted-on-write-and-persist')
+    AND sequence >= 0
+    AND occurred_at >= 0
+    AND length(summary) <= 240
+  )
+) STRICT;
+
+CREATE UNIQUE INDEX uniq_relationship_audit_workspace_sequence
+  ON relationship_audit_entries(workspace_id, sequence);
+CREATE INDEX idx_relationship_audit_workspace_occurred_at
+  ON relationship_audit_entries(workspace_id, occurred_at);
+CREATE INDEX idx_relationship_audit_relationship
+  ON relationship_audit_entries(workspace_id, relationship_id, occurred_at)
+  WHERE relationship_id IS NOT NULL;
+`;
+const MIGRATIONS = [
+    { version: 1, sql: V1_SQL },
+    { version: 2, sql: V2_SQL },
+    { version: 3, sql: V3_SQL },
+    { version: 4, sql: V4_SQL },
+    { version: 5, sql: V5_SQL },
+];
+function currentUserVersion(db) {
+    const row = db.prepare("PRAGMA user_version").get();
+    return typeof row?.user_version === "number" ? row.user_version : 0;
+}
+function setUserVersion(db, v) {
+    // user_version cannot be parameterized; v is a server-controlled integer constant from MIGRATIONS.
+    db.exec(`PRAGMA user_version = ${String(v)}`);
+}
+// Applies pending migrations inside a single transaction. Throws (and rolls back) on any failure.
+export function runMigrations(db) {
+    const start = currentUserVersion(db);
+    const pending = MIGRATIONS.filter((m) => m.version > start);
+    if (pending.length === 0)
+        return;
+    db.exec("BEGIN");
+    try {
+        for (const m of pending) {
+            db.exec(m.sql);
+            setUserVersion(db, m.version);
+        }
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}

package/dist/store/types.d.ts

@@ -0,0 +1,29 @@
+import type { Project, Chat, ChatConnectedScope, ChatLocalKnowledgeScope, ChatRole, WorkflowStatus, ChatMessage, CreateChatOptions, UpdateProjectPatch, UpdateChatPatch, NewChatMessage, UpdateChatMessagePatch } from "@oscharko-dev/keiko-contracts/bff-wire";
+export type { Project, Chat, ChatConnectedScope, ChatLocalKnowledgeScope, ChatRole, WorkflowStatus, ChatMessage, CreateChatOptions, UpdateProjectPatch, UpdateChatPatch, NewChatMessage, UpdateChatMessagePatch, };
+export interface UiStore {
+    readonly listProjects: () => readonly Project[];
+    readonly createProject: (path: string, name?: string) => Project;
+    readonly updateProject: (path: string, patch: UpdateProjectPatch) => Project;
+    readonly deleteProject: (path: string) => void;
+    readonly listChats: (projectPath: string, limit?: number) => readonly Chat[];
+    readonly findChatById: (id: string) => Chat | undefined;
+    readonly createChat: (projectPath: string, title: string, selectedModel: string, opts?: CreateChatOptions) => Chat;
+    readonly updateChat: (id: string, patch: UpdateChatPatch, options?: UpdateChatOptions) => Chat;
+    readonly deleteChat: (id: string) => void;
+    readonly listMessages: (chatId: string, limit?: number) => readonly ChatMessage[];
+    readonly findMessageById: (id: string) => ChatMessage | undefined;
+    readonly createMessage: (msg: NewChatMessage) => ChatMessage;
+    readonly createMessages: (messages: readonly NewChatMessage[]) => readonly ChatMessage[];
+    readonly updateMessage: (id: string, patch: UpdateChatMessagePatch) => ChatMessage;
+    readonly close: () => void;
+}
+export interface UpdateChatOptions {
+    readonly maxConnectedSources?: number;
+    readonly maxLocalKnowledgeSources?: number;
+}
+export interface UiStoreFactoryOptions {
+    readonly now?: () => number;
+    readonly newId?: () => string;
+    readonly redactString?: (input: string) => string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/store/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/store/types.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,OAAO,EACP,IAAI,EACJ,kBAAkB,EAClB,uBAAuB,EACvB,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,sBAAsB,EACvB,MAAM,wCAAwC,CAAC;AAChD,YAAY,EACV,OAAO,EACP,IAAI,EACJ,kBAAkB,EAClB,uBAAuB,EACvB,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,sBAAsB,GACvB,CAAC;AAEF,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,SAAS,OAAO,EAAE,CAAC;IAChD,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IACjE,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IAC7E,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAE/C,QAAQ,CAAC,SAAS,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,SAAS,IAAI,EAAE,CAAC;IAC7E,QAAQ,CAAC,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,UAAU,EAAE,CACnB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,iBAAiB,KACrB,IAAI,CAAC;IACV,QAAQ,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC/F,QAAQ,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAE1C,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,SAAS,WAAW,EAAE,CAAC;IAClF,QAAQ,CAAC,eAAe,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC;IAClE,QAAQ,CAAC,aAAa,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,WAAW,CAAC;IAC7D,QAAQ,CAAC,cAAc,EAAE,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,KAAK,SAAS,WAAW,EAAE,CAAC;IACzF,QAAQ,CAAC,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,KAAK,WAAW,CAAC;IAEnF,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;CAC5C;AAID,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CACnD"}

package/dist/store/types.js

@@ -0,0 +1,8 @@
+// ADR-0013 D4 — UiStore port and entity types. The port is the seam for testing; the concrete
+// `createNodeUiStore` adapter and the `createInMemoryUiStore` test adapter both implement it.
+//
+// Re-export shim: wire-safe entity types live in @oscharko-dev/keiko-contracts (issue #158).
+// WorkflowStatus and ChatMessage are imported from the bff-wire subpath because those names
+// collide with unit-test-events.ts and gateway.ts in the main contracts index.
+// verbatimModuleSyntax is on: type-only names use `export type`.
+export {};

package/dist/store/validation.d.ts

@@ -0,0 +1,7 @@
+export interface ValidateProjectPathOptions {
+    readonly mustExist: boolean;
+}
+export type PathShape = "posix-absolute" | "windows-drive" | "windows-unc" | "windows-device" | "relative";
+export declare function classifyPathShape(input: string): PathShape;
+export declare function validateProjectPath(input: string, options: ValidateProjectPathOptions): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/store/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/store/validation.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,SAAS,GACjB,gBAAgB,GAChB,eAAe,GACf,aAAa,GACb,gBAAgB,GAChB,UAAU,CAAC;AAIf,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAM1D;AAiFD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,GAAG,MAAM,CAK9F"}

package/dist/store/validation.js

@@ -0,0 +1,117 @@
+// ADR-0013 D6 — Path validation policy (fail-closed). Structural rules in one place; no path reaches
+// the database without passing every check. Normalized absolute form is the only thing that returns.
+//
+// Issue #174 — cross-platform project roots. Native Windows drive paths (e.g. `C:\Users\Example`)
+// are accepted as local project roots. Unsafe Windows shapes — UNC (`\\server\share`), device
+// (`\\?\` / `\\.\`), traversal segments, null bytes, and remote URL forms — remain rejected.
+// Shape classification is host-independent so unit tests pin every branch on any host OS.
+import { isAbsolute, normalize, resolve as resolvePath, win32 as winPath } from "node:path";
+import { statSync } from "node:fs";
+import { invalidPath, pathNotDirectory, pathNotFound } from "./errors.js";
+const MAX_PATH_LEN = 4096;
+// scheme prefix per RFC 3986: ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) "://"
+const REMOTE_URL_PREFIX_RE = /^[a-zA-Z][a-zA-Z0-9+\-.]*:\/\//;
+const WINDOWS_DRIVE_RE = /^[a-zA-Z]:[\\/]/;
+// Device-namespace prefixes: `\\?\`, `\\.\`, `//?/`, `//./`. Reserved for raw device or extended
+// length paths and never used for normal project roots.
+const WINDOWS_DEVICE_PREFIX_RE = /^[\\/]{2}[?.][\\/]/;
+// UNC (Universal Naming Convention) prefix: `\\<host>\<share>` or `//<host>/<share>`. The first
+// character after the two separators is part of the host name and must not start a device prefix.
+const WINDOWS_UNC_PREFIX_RE = /^[\\/]{2}[^\\/?.]/;
+const TRAVERSAL_SEGMENT_RE = /(^|[\\/])\.\.(?:[\\/]|$)/;
+// Pure, host-independent classifier. Inspects only the input string so the same call returns the
+// same shape on Linux, macOS, and Windows hosts.
+export function classifyPathShape(input) {
+    if (WINDOWS_DEVICE_PREFIX_RE.test(input))
+        return "windows-device";
+    if (WINDOWS_UNC_PREFIX_RE.test(input))
+        return "windows-unc";
+    if (WINDOWS_DRIVE_RE.test(input))
+        return "windows-drive";
+    if (input.startsWith("/"))
+        return "posix-absolute";
+    return "relative";
+}
+function rejectUnsafeShape(input, stage) {
+    const shape = classifyPathShape(input);
+    if (shape === "windows-unc") {
+        throw invalidPath(stage === "input"
+            ? "Windows UNC paths are not supported."
+            : "Windows UNC paths are not supported after normalization.");
+    }
+    if (shape === "windows-device") {
+        throw invalidPath(stage === "input"
+            ? "Windows device paths are not supported."
+            : "Windows device paths are not supported after normalization.");
+    }
+}
+function rejectTraversal(input) {
+    if (TRAVERSAL_SEGMENT_RE.test(input)) {
+        throw invalidPath("Path contains a traversal segment.");
+    }
+}
+function rejectStructural(input) {
+    if (input.length === 0)
+        throw invalidPath("Path is empty.");
+    if (input.length > MAX_PATH_LEN)
+        throw invalidPath("Path too long.");
+    if (input.includes("\0"))
+        throw invalidPath("Path contains a null byte.");
+    const shape = classifyPathShape(input);
+    // Windows drive paths with redundant forward slashes (for example `C://Users/Example`) match the
+    // scheme-prefix regex even though they are valid local paths. Classify the shape first and skip
+    // the remote-URL check for Windows drive shapes; other shapes still fail closed on `http://`,
+    // `ssh://`, `file://`, and similar URL forms.
+    if (shape !== "windows-drive" && REMOTE_URL_PREFIX_RE.test(input)) {
+        throw invalidPath("Remote URL forms are not allowed.");
+    }
+    rejectUnsafeShape(input, "input");
+    rejectTraversal(input);
+    if (shape === "relative")
+        throw invalidPath("Path must be absolute.");
+    return shape;
+}
+function normalizeForShape(input, shape) {
+    // Use the Windows path namespace for Windows drive paths so backslash separators and drive
+    // letters normalize correctly on any host OS. POSIX-absolute paths use the OS-native namespace,
+    // which on POSIX hosts is identical to `path.posix`.
+    if (shape === "windows-drive") {
+        const normalized = winPath.normalize(input);
+        if (!winPath.isAbsolute(normalized)) {
+            throw invalidPath("Path must be absolute after normalization.");
+        }
+        rejectUnsafeShape(normalized, "normalized");
+        rejectTraversal(normalized);
+        return normalized;
+    }
+    const normalized = normalize(input);
+    const resolved = resolvePath(normalized);
+    if (!isAbsolute(resolved)) {
+        throw invalidPath("Path must be absolute after normalization.");
+    }
+    rejectUnsafeShape(resolved, "normalized");
+    rejectTraversal(resolved);
+    return resolved;
+}
+function statAsDirectory(resolved) {
+    let s;
+    try {
+        s = statSync(resolved);
+    }
+    catch {
+        throw pathNotFound();
+    }
+    if (!s.isDirectory())
+        throw pathNotDirectory();
+}
+// Validates and normalizes a project path. Returns the canonical absolute path on success; throws a
+// typed UiStoreError otherwise. When `mustExist` is false, the stat-as-directory step is skipped
+// (PATCH/DELETE callers identify a project by its previously normalized path; the directory may
+// have been deleted/moved since registration — that is reflected via derived availability).
+export function validateProjectPath(input, options) {
+    const shape = rejectStructural(input);
+    const resolved = normalizeForShape(input, shape);
+    if (options.mustExist)
+        statAsDirectory(resolved);
+    return resolved;
+}

package/dist/store-handlers.d.ts

@@ -0,0 +1,17 @@
+import type { RouteContext, RouteResult } from "./routes.js";
+import type { UiHandlerDeps } from "./deps.js";
+declare function notFoundResult(message: string): RouteResult;
+export declare function handleListProjects(_ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleCreateProject(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleUpdateProject(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleDeleteProject(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleListChats(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleCreateChat(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleUpdateChat(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleDeleteChat(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleListMessages(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleCreateMessage(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleCreateRunSummaryPair(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleUpdateMessage(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export { notFoundResult };
+//# sourceMappingURL=store-handlers.d.ts.map

package/dist/store-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-handlers.d.ts","sourceRoot":"","sources":["../src/store-handlers.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAwH/C,iBAAS,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAEpD;AAmND,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAMvF;AAMD,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAgBtB;AAeD,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAQtB;AAMD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAcvF;AAgBD,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAYnF;AAMD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAetB;AA0bD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAuBtB;AAMD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAQpF;AAMD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAkBtF;AAMD,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAwBtB;AA6CD,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAWtB;AAuBD,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAgBtB;AAGD,OAAO,EAAE,cAAc,EAAE,CAAC"}