@stackbilt/aegis-core 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbilt/aegis-core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Persistent AI agent framework for Cloudflare Workers. Multi-tier memory, autonomous goals, dreaming cycles, MCP native.",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -59,7 +59,10 @@
     "./contracts/goal": "./src/contracts/goal.contract.ts",
     "./contracts/agenda-item": "./src/contracts/agenda-item.contract.ts",
     "./contracts/cc-task": "./src/contracts/cc-task.contract.ts",
-    "./contracts/memory-entry": "./src/contracts/memory-entry.contract.ts"
+    "./contracts/memory-entry": "./src/contracts/memory-entry.contract.ts",
+    "./wiki/client": "./src/wiki/client.ts",
+    "./wiki/types": "./src/wiki/types.ts",
+    "./kernel/memory-service": "./src/kernel/memory-service.ts"
   },
   "scripts": {
     "dev": "wrangler dev",

package/schema.sql

@@ -65,7 +65,9 @@ CREATE TABLE IF NOT EXISTS episodic_memory (
   reclassified INTEGER NOT NULL DEFAULT 0,
   thread_id TEXT,                              -- conversation thread for dreaming cycle
   executor TEXT,                               -- which executor handled this
+  court_card TEXT,                             -- composite court card (king/queen/knight/page)
   complexity_tier TEXT,                        -- aegis#563: procedureKey complement (low|mid|high); NULL for non-dispatcher producers
+  executor_config TEXT,                        -- aegis#563: config snapshot at emit time (evaluator-replay fidelity)
   created_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
@@ -111,6 +113,8 @@ CREATE TABLE IF NOT EXISTS procedural_memory (
   last_used TEXT,
   candidate_executor TEXT,                     -- probation: untrusted executor being tested
   candidate_successes INTEGER NOT NULL DEFAULT 0,  -- consecutive successes of candidate
+  gap_signal_count INTEGER NOT NULL DEFAULT 0, -- aegis#497: unresolved grounding-gap signals; >0 triggers tier escalation
+  gap_last_seen TEXT,
   created_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
@@ -204,6 +208,7 @@ CREATE INDEX IF NOT EXISTS idx_memory_validation_stage ON memory_entries(validat
 CREATE INDEX IF NOT EXISTS idx_episodic_class ON episodic_memory(intent_class);
 CREATE INDEX IF NOT EXISTS idx_episodic_created ON episodic_memory(created_at);
 CREATE INDEX IF NOT EXISTS idx_episodic_thread ON episodic_memory(thread_id);
+CREATE INDEX IF NOT EXISTS idx_episodic_class_complexity ON episodic_memory(intent_class, complexity_tier);
 CREATE INDEX IF NOT EXISTS idx_procedural_pattern ON procedural_memory(task_pattern);
 CREATE INDEX IF NOT EXISTS idx_procedural_status ON procedural_memory(status);
 CREATE INDEX IF NOT EXISTS idx_heartbeat_created ON heartbeat_results(created_at);

package/src/kernel/memory/index.ts

@@ -1,5 +1,5 @@
 export { recordEpisode, retrogradeEpisode, sanitizeEpisodicOutcome, getRecentEpisodes, getEpisodeStats, getEpisodeStatsByComplexity, getAllEpisodeStatsByComplexity, type EpisodeStatsAggregate, getConversationHistory, estimateTokens, budgetConversationHistory } from './episodic.js';
-export { PROCEDURE_MIN_SUCCESSES, PROCEDURE_MIN_SUCCESS_RATE, complexityTier, procedureKey, getProcedure, getAllProcedures, getProcedureWithDerivedStats, getAllProceduresWithDerivedStats, type DriftLogOpts, findNearMiss, upsertProcedure, addRefinement, degradeProcedure, maintainProcedures } from './procedural.js';
+export { PROCEDURE_MIN_SUCCESSES, PROCEDURE_MIN_SUCCESS_RATE, complexityTier, procedureKey, getProcedure, getAllProcedures, getProcedureWithDerivedStats, getAllProceduresWithDerivedStats, type DriftLogOpts, findNearMiss, upsertProcedure, addRefinement, degradeProcedure, recordGapSignal, clearGapSignal, maintainProcedures } from './procedural.js';
 export { normalizeTopic, tokenize, jaccardSimilarity, recordMemory, searchMemoryByKeywords, getMemoryEntries, recallMemory, computeEwaScore, getAllMemoryForContext } from './semantic.js';
 export { pruneMemory } from './pruning.js';
 export { consolidateEpisodicToSemantic } from './consolidation.js';

package/src/kernel/memory/procedural.ts

@@ -465,3 +465,37 @@ export async function maintainProcedures(db: D1Database): Promise<void> {
     console.log(`[procedures] Utility-pruned: ${proc.task_pattern} (${(rate * 100).toFixed(0)}% success over ${proc.success_count + proc.fail_count} invocations)`);
   }
 }
+
+/** Increment gap signal for a procedure. Called when the response carried
+ *  unverified_claims[] or unknowns[] on a grounding-gated classification. */
+export async function recordGapSignal(db: D1Database, taskPattern: string): Promise<void> {
+  const procedure = await getProcedure(db, taskPattern);
+  if (!procedure) return;
+
+  const newCount = (procedure.gap_signal_count ?? 0) + 1;
+  await db.prepare(
+    "UPDATE procedural_memory SET gap_signal_count = ?, gap_last_seen = datetime('now') WHERE task_pattern = ?"
+  ).bind(newCount, taskPattern).run();
+
+  console.log(`[procedures] Gap signal recorded: ${taskPattern} (count=${newCount})`);
+}
+
+/** Decrement gap signal for a procedure (min 0). Called on clean grounded
+ *  response. When the counter returns to 0, gap_last_seen is cleared. */
+export async function clearGapSignal(db: D1Database, taskPattern: string): Promise<void> {
+  const procedure = await getProcedure(db, taskPattern);
+  if (!procedure) return;
+
+  const current = procedure.gap_signal_count ?? 0;
+  if (current <= 0) return;
+
+  const newCount = current - 1;
+  const newLastSeen = newCount === 0 ? null : procedure.gap_last_seen ?? null;
+  await db.prepare(
+    'UPDATE procedural_memory SET gap_signal_count = ?, gap_last_seen = ? WHERE task_pattern = ?'
+  ).bind(newCount, newLastSeen, taskPattern).run();
+
+  if (newCount === 0) {
+    console.log(`[procedures] Gap signal cleared: ${taskPattern}`);
+  }
+}

package/src/kernel/memory-service.ts

@@ -0,0 +1,252 @@
+/**
+ * MemoryService — unified facade over the memory tiers (episodic,
+ * procedural, semantic, insights) + goals. Phase 1B of the god-object
+ * decomposition epic (aegis#532 / aegis#534).
+ *
+ * Why: the audit flagged that dispatch, self-improvement, ambient-capture
+ * each reach into memory/*.ts and memory-adapter.ts directly, repeating
+ * the `{db, memoryBinding}` threading and obscuring which tier each call
+ * actually hits. This service hands callers one object and hides the
+ * backing-store distinction.
+ *
+ * Tier → backing store:
+ *   - episodic, procedural, insights, goals → D1 (env.db)
+ *   - semantic, context-recall → memory-worker (env.memoryBinding) via
+ *     memory-adapter (aegis-core re-export)
+ *
+ * Prefer this over the raw tier functions in new code. Existing callers
+ * migrate incrementally — Phase 2/3 decomps will naturally fold the rest
+ * as those files get broken up.
+ */
+import {
+  recordEpisode as _recordEpisode,
+  retrogradeEpisode as _retrogradeEpisode,
+  getRecentEpisodes as _getRecentEpisodes,
+  getEpisodeStatsByComplexity as _getEpisodeStatsByComplexity,
+  upsertProcedure as _upsertProcedure,
+  getProcedure as _getProcedure,
+  getProcedureWithDerivedStats as _getProcedureWithDerivedStats,
+  getAllProceduresWithDerivedStats as _getAllProceduresWithDerivedStats,
+  type DriftLogOpts,
+  addRefinement as _addRefinement,
+  degradeProcedure as _degradeProcedure,
+  findNearMiss as _findNearMiss,
+  recordGapSignal as _recordGapSignal,
+  clearGapSignal as _clearGapSignal,
+  publishInsight as _publishInsight,
+  validateInsight as _validateInsight,
+  recordGoalAction as _recordGoalAction,
+  type InsightPayload,
+  type ValidationStage,
+  type AgentAction,
+} from './memory/index.js';
+import {
+  recordMemory as _recordMemoryViaAdapter,
+  searchMemoryByKeywords as _searchMemoryByKeywordsViaAdapter,
+  getAllMemoryForContext as _getAllMemoryForContextViaAdapter,
+} from './memory-adapter.js';
+import type { MemoryServiceBinding } from '../types.js';
+import type { EpisodicEntry, ProceduralEntry, Refinement } from './types.js';
+
+export type { ValidationStage, InsightPayload };
+
+export interface DispatchOutcomeArgs {
+  episode: Omit<EpisodicEntry, 'id' | 'created_at'>;
+  procedureKey: string;
+  executor: string;
+  executorConfig: string;
+  outcome: 'success' | 'failure' | 'partial_failure';
+  latencyMs: number;
+  cost: number;
+  /** Optional refinement log — added when a replan promotes a degraded procedure. */
+  refinement?: Refinement;
+}
+
+export interface GoalActionOpts {
+  autoExecuted?: boolean;
+  authorityLevel?: string;
+  toolCalled?: string;
+  toolArgsJson?: string;
+  toolResultJson?: string;
+}
+
+export class MemoryService {
+  constructor(
+    private readonly db: D1Database,
+    private readonly memoryBinding?: MemoryServiceBinding,
+  ) {}
+
+  // ─── Episodic ──────────────────────────────────────────────
+
+  recordEpisode(entry: Omit<EpisodicEntry, 'id' | 'created_at'>): Promise<void> {
+    return _recordEpisode(this.db, entry);
+  }
+
+  retrogradeEpisode(threadId: string): Promise<EpisodicEntry | null> {
+    return _retrogradeEpisode(this.db, threadId);
+  }
+
+  getRecentEpisodes(intentClass: string, limit = 5): Promise<EpisodicEntry[]> {
+    return _getRecentEpisodes(this.db, intentClass, limit);
+  }
+
+  // aegis#563: aggregates keyed by (intent_class, complexity_tier), matching
+  // procedural_memory's procedureKey shape. Foundation for the #564
+  // projection-vs-cache decomposition.
+  getEpisodeStatsByComplexity(intentClass: string, complexityTier: string) {
+    return _getEpisodeStatsByComplexity(this.db, intentClass, complexityTier);
+  }
+
+  // ─── Procedural ────────────────────────────────────────────
+
+  upsertProcedure(
+    taskPattern: string,
+    executor: string,
+    executorConfig: string,
+    outcome: 'success' | 'failure' | 'partial_failure',
+    latencyMs: number,
+    cost: number,
+  ): Promise<void> {
+    return _upsertProcedure(this.db, taskPattern, executor, executorConfig, outcome, latencyMs, cost);
+  }
+
+  getProcedure(taskPattern: string): Promise<ProceduralEntry | null> {
+    return _getProcedure(this.db, taskPattern);
+  }
+
+  // aegis#564 Phase 1 — callers that read the five cached aggregate
+  // columns (success_count, fail_count, avg_latency_ms, avg_cost,
+  // last_used) should route through this helper. Phase 1 is a pass-
+  // through; Phase 2 adds shadow-read logging; Phase 3 flips to derived.
+  getProcedureWithDerivedStats(taskPattern: string, opts?: DriftLogOpts): Promise<ProceduralEntry | null> {
+    return _getProcedureWithDerivedStats(this.db, taskPattern, opts);
+  }
+
+  getAllProceduresWithDerivedStats(opts?: DriftLogOpts): Promise<ProceduralEntry[]> {
+    return _getAllProceduresWithDerivedStats(this.db, opts);
+  }
+
+  addRefinement(taskPattern: string, refinement: Refinement): Promise<void> {
+    return _addRefinement(this.db, taskPattern, refinement);
+  }
+
+  degradeProcedure(taskPattern: string, executor: string): Promise<void> {
+    return _degradeProcedure(this.db, taskPattern, executor);
+  }
+
+  findNearMiss(taskPattern: string) {
+    return _findNearMiss(this.db, taskPattern);
+  }
+
+  recordGapSignal(taskPattern: string): Promise<void> {
+    return _recordGapSignal(this.db, taskPattern);
+  }
+
+  clearGapSignal(taskPattern: string): Promise<void> {
+    return _clearGapSignal(this.db, taskPattern);
+  }
+
+  // ─── Semantic (memory-worker via adapter) ──────────────────
+
+  async recordMemory(
+    topic: string,
+    fact: string,
+    confidence: number,
+    source: string,
+    metadata?: Record<string, unknown>,
+  ) {
+    this.requireBinding('recordMemory');
+    return _recordMemoryViaAdapter(this.memoryBinding!, topic, fact, confidence, source, metadata);
+  }
+
+  async searchMemory(query: string, limit?: number) {
+    this.requireBinding('searchMemory');
+    return _searchMemoryByKeywordsViaAdapter(this.memoryBinding!, query, limit);
+  }
+
+  async getMemoryForContext(query?: string) {
+    this.requireBinding('getMemoryForContext');
+    return _getAllMemoryForContextViaAdapter(this.memoryBinding!, query);
+  }
+
+  // ─── Insights ──────────────────────────────────────────────
+
+  publishInsight(payload: InsightPayload) {
+    return _publishInsight(this.db, payload, this.memoryBinding);
+  }
+
+  validateInsight(factHash: string, validatingRepo: string, confirmed: boolean) {
+    return _validateInsight(this.db, factHash, validatingRepo, confirmed);
+  }
+
+  // ─── Goals ─────────────────────────────────────────────────
+
+  recordGoalAction(
+    goalId: string | null,
+    actionType: AgentAction['action_type'],
+    description: string,
+    outcome: AgentAction['outcome'] = 'success',
+    opts?: GoalActionOpts,
+  ): Promise<void> {
+    return _recordGoalAction(this.db, goalId, actionType, description, outcome, opts);
+  }
+
+  // ─── Domain: dispatch outcome bookkeeping ──────────────────
+
+  /**
+   * Record a dispatch outcome: episode + procedural upsert, plus an
+   * optional refinement log when a replan happens on a degraded procedure.
+   * Collapses the three-call pattern that dispatch.recordOutcome carries
+   * inline.
+   */
+  async recordDispatchOutcome(args: DispatchOutcomeArgs): Promise<void> {
+    // aegis#563: enrich episode with complexity_tier (derived from
+    // procedureKey = `classification:complexity_tier`) and executor_config
+    // snapshot. Caller-supplied values win; otherwise derive from args so
+    // dispatcher call sites don't need to pass these explicitly.
+    const tierFromKey = args.procedureKey.includes(':')
+      ? args.procedureKey.slice(args.procedureKey.indexOf(':') + 1)
+      : null;
+    const enrichedEpisode: Omit<EpisodicEntry, 'id' | 'created_at'> = {
+      ...args.episode,
+      complexity_tier: args.episode.complexity_tier ?? tierFromKey,
+      executor_config: args.episode.executor_config ?? args.executorConfig,
+    };
+
+    await _recordEpisode(this.db, enrichedEpisode);
+    await _upsertProcedure(
+      this.db,
+      args.procedureKey,
+      args.executor,
+      args.executorConfig,
+      args.outcome,
+      args.latencyMs,
+      args.cost,
+    );
+    if (args.refinement) {
+      await _addRefinement(this.db, args.procedureKey, args.refinement);
+    }
+  }
+
+  // ─── Internal ──────────────────────────────────────────────
+
+  private requireBinding(method: string): void {
+    if (!this.memoryBinding) {
+      throw new Error(
+        `[memory-service] ${method}() requires memoryBinding — constructor received none`,
+      );
+    }
+  }
+}
+
+/**
+ * Factory: construct a MemoryService from any env-shape carrying
+ * `db` and (optionally) `memoryBinding`. The daemon's EdgeEnv satisfies
+ * this shape; scheduled tasks and tests can pass a narrower object.
+ */
+export function memoryServiceFor(env: {
+  db: D1Database;
+  memoryBinding?: MemoryServiceBinding;
+}): MemoryService {
+  return new MemoryService(env.db, env.memoryBinding);
+}

package/src/kernel/types.ts

@@ -38,6 +38,9 @@ export interface EpisodicEntry {
   reclassified?: boolean;
   thread_id?: string | null;
   executor?: string | null;
+  court_card?: string | null;
+  complexity_tier?: string | null;
+  executor_config?: string | null;
   created_at?: string;
 }
 
@@ -65,6 +68,9 @@ export interface ProceduralEntry {
   last_used?: string;
   candidate_executor?: string | null;
   candidate_successes?: number;
+  // aegis#497 — gap-driven tier escalation
+  gap_signal_count?: number;
+  gap_last_seen?: string | null;
   created_at?: string;
 }
 

package/src/wiki/client.ts

@@ -0,0 +1,346 @@
+import type {
+  ListPagesResult,
+  PageSummary,
+  ReadPageResult,
+  SearchPagesResult,
+  WikiPage,
+  WriteInput,
+  WritePageResult,
+} from './types.js';
+
+export interface WikiClientEnv {
+  wikiBaseUrl?: string;
+  wikiBinding?: Fetcher;
+  wikiToken?: string;
+}
+
+export class WikiClientError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly statusText: string,
+    public readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = 'WikiClientError';
+  }
+}
+
+function requireWikiToken(env: WikiClientEnv): string {
+  if (!env.wikiToken?.trim()) {
+    throw new WikiClientError('AEGIS_WIKI_TOKEN is not configured', 503, 'Service Unavailable');
+  }
+  return env.wikiToken;
+}
+
+function todayIsoDate(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function asObject(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function coerceBoolean(value: unknown): boolean | undefined {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return value !== 0;
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'string') {
+    if (value === 'true' || value === '1') return true;
+    if (value === 'false' || value === '0') return false;
+  }
+  return Boolean(value);
+}
+
+// Emdash stores body as portableText (an array of blocks). Agents want readable
+// prose, so serialize back to markdown-ish text. Walks blocks, applies heading
+// prefixes by style, drops marks/links — lossy but agent-readable.
+function portableTextToMarkdown(value: unknown): string | undefined {
+  if (typeof value === 'string') return value;
+  if (!Array.isArray(value)) return undefined;
+  const lines: string[] = [];
+  for (const block of value) {
+    if (!block || typeof block !== 'object') continue;
+    const b = block as Record<string, unknown>;
+    const style = typeof b.style === 'string' ? b.style : 'normal';
+    const children = Array.isArray(b.children) ? b.children : [];
+    const text = children
+      .map(c => (c && typeof c === 'object' && typeof (c as Record<string, unknown>).text === 'string'
+        ? String((c as Record<string, unknown>).text)
+        : ''))
+      .join('');
+    if (!text) { lines.push(''); continue; }
+    if (style === 'h1') lines.push(`# ${text}`);
+    else if (style === 'h2') lines.push(`## ${text}`);
+    else if (style === 'h3') lines.push(`### ${text}`);
+    else if (style === 'h4') lines.push(`#### ${text}`);
+    else if (style === 'h5') lines.push(`##### ${text}`);
+    else if (style === 'h6') lines.push(`###### ${text}`);
+    else if (style === 'blockquote') lines.push(`> ${text}`);
+    else lines.push(text);
+    lines.push('');
+  }
+  return lines.join('\n').trim();
+}
+
+// Emdash response envelope: { data: { item: ContentItem, _rev?: string } }
+// ContentItem shape:        { id, type, slug, status, data: <frontmatter+body>, ... }
+// Returns merged WikiPage with frontmatter spread + top-level id/slug/status/_rev.
+function normalizePage(value: unknown): WikiPage | null {
+  const envelope = asObject(value);
+  if (!envelope) return null;
+
+  // Drill into the wrapper. Accept both { data: { item } } and a bare ContentItem
+  // (in case the response shape ever flattens). Walk both shapes safely.
+  const inner = asObject(envelope.data) ?? envelope;
+  const item = asObject(inner.item) ?? inner;
+  if (!item.slug && !item.id) return null;
+
+  const data = asObject(item.data) ?? {};
+  const canonical = coerceBoolean(data.canonical);
+
+  const merged: WikiPage = {
+    id: String(item.id ?? ''),
+    slug: String(item.slug ?? data.slug ?? ''),
+    status: typeof item.status === 'string' ? item.status : undefined,
+    revision_id: typeof inner._rev === 'string' ? inner._rev : undefined,
+    title: String(data.title ?? ''),
+    scope: String(data.scope ?? ''),
+    type: String(data.type ?? ''),
+    confidence: String(data.confidence ?? ''),
+    summary: typeof data.summary === 'string' ? data.summary : '',
+    body: portableTextToMarkdown(data.body),
+    canonical,
+    last_verified: typeof data.last_verified === 'string' ? data.last_verified : undefined,
+    sources: Array.isArray(data.sources) ? (data.sources as WikiPage['sources']) : undefined,
+    related: Array.isArray(data.related) ? (data.related as string[]) : undefined,
+    supersedes: Array.isArray(data.supersedes) ? (data.supersedes as string[]) : undefined,
+    owners: Array.isArray(data.owners) ? (data.owners as string[]) : undefined,
+    consumers: Array.isArray(data.consumers) ? (data.consumers as string[]) : undefined,
+    guarded_paths: Array.isArray(data.guarded_paths) ? (data.guarded_paths as string[]) : undefined,
+    updated_at: typeof item.updatedAt === 'string' ? item.updatedAt : '',
+  };
+
+  // Preserve any additional fields from data that we didn't explicitly map.
+  for (const [k, v] of Object.entries(data)) {
+    if (!(k in merged)) merged[k] = v;
+  }
+
+  return merged;
+}
+
+// Handles both shapes:
+//  - ContentItem (list endpoint): { id, slug, data: { title, scope, type, ... } }
+//  - SearchHit (search endpoint):  { collection, id, slug, title, snippet, score }
+// Search hits don't carry scope/type/confidence — those fields stay empty and the
+// agent can call wiki_read for full details on any hit.
+function normalizeContentItemToSummary(item: Record<string, unknown>): PageSummary {
+  const data = asObject(item.data) ?? {};
+  const summary: PageSummary = {
+    slug: String(item.slug ?? ''),
+    title: String(item.title ?? data.title ?? ''),
+    scope: String(item.scope ?? data.scope ?? ''),
+    type: typeof data.type === 'string' ? data.type : '', // top-level item.type is the collection name, not the wiki type
+    confidence: String(data.confidence ?? ''),
+    summary: typeof data.summary === 'string' ? data.summary : '',
+    updated_at: typeof item.updatedAt === 'string' ? item.updatedAt : '',
+  };
+  if (typeof item.snippet === 'string') summary.snippet = item.snippet;
+  return summary;
+}
+
+function normalizeSummaryArray(value: unknown): PageSummary[] {
+  const envelope = asObject(value);
+  if (!envelope) return [];
+  const inner = asObject(envelope.data) ?? envelope;
+
+  // Cursor-based list: { data: { items: [...] } }
+  // Search hits:       { data: { results: [...] } }
+  const arr =
+    (Array.isArray(inner.items) && inner.items) ||
+    (Array.isArray(inner.results) && inner.results) ||
+    (Array.isArray(inner.pages) && inner.pages) ||
+    (Array.isArray(envelope.items) && envelope.items) ||
+    (Array.isArray(envelope.results) && envelope.results) ||
+    [];
+
+  return (arr as unknown[])
+    .map(item => asObject(item))
+    .filter((item): item is Record<string, unknown> => !!item)
+    .map(normalizeContentItemToSummary);
+}
+
+function normalizeWriteResult(value: unknown, fallback: { slug: string; id?: string }): WritePageResult {
+  const page = normalizePage(value);
+  const id = page?.id || fallback.id || '';
+  if (!id) {
+    throw new WikiClientError('Wiki write response did not include an id', 502, 'Bad Gateway', value);
+  }
+  return {
+    slug: page?.slug || fallback.slug,
+    id,
+    revision_id: page?.revision_id,
+  };
+}
+
+async function requestJson<T>(env: WikiClientEnv, path: string, init: RequestInit = {}): Promise<T> {
+  const token = requireWikiToken(env);
+  const headers = new Headers(init.headers);
+  headers.set('Authorization', `Bearer ${token}`);
+  if (init.body && !headers.has('Content-Type')) {
+    headers.set('Content-Type', 'application/json');
+  }
+  headers.set('Accept', 'application/json');
+
+  const base = env.wikiBaseUrl ?? '';
+  const request = new Request(`${base}${path}`, { ...init, headers });
+
+  let response: Response;
+  if (env.wikiBinding) {
+    response = await env.wikiBinding.fetch(request);
+  } else if (env.wikiBaseUrl) {
+    response = await fetch(request);
+  } else {
+    throw new WikiClientError(
+      'WikiClientEnv requires wikiBaseUrl or wikiBinding',
+      503,
+      'Service Unavailable',
+    );
+  }
+
+  const text = await response.text();
+  let data: unknown = null;
+  if (text) {
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = text;
+    }
+  }
+
+  if (!response.ok) {
+    throw new WikiClientError(
+      `Wiki request failed: ${response.status} ${response.statusText}`,
+      response.status,
+      response.statusText,
+      data,
+    );
+  }
+
+  return data as T;
+}
+
+export async function readPage(env: WikiClientEnv, slug: string): Promise<ReadPageResult> {
+  try {
+    const data = await requestJson<unknown>(env, `/content/wiki/${encodeURIComponent(slug)}`);
+    return { page: normalizePage(data) };
+  } catch (err) {
+    if (err instanceof WikiClientError && err.status === 404) {
+      return { page: null };
+    }
+    throw err;
+  }
+}
+
+export async function searchPages(
+  env: WikiClientEnv,
+  query: string,
+  options: { limit?: number } = {},
+): Promise<SearchPagesResult> {
+  const params = new URLSearchParams({ q: query, collections: 'wiki' });
+  params.set('limit', String(options.limit ?? 10));
+
+  const data = await requestJson<unknown>(env, `/search?${params.toString()}`);
+  const results = normalizeSummaryArray(data);
+
+  // EmDash search hits don't carry scope/type in the response — client-side
+  // filtering on those fields would silently discard all results. Use
+  // wiki_list for scope-scoped enumeration (aegis#575).
+  return { results };
+}
+
+// Emdash's write endpoints land content in a draft revision. A separate
+// POST /publish call is required to promote the draft to live — otherwise
+// GET returns the previous live revision and the write is silently invisible.
+// See aegis#475 for the forensic trace.
+async function publishRevision(env: WikiClientEnv, id: string): Promise<void> {
+  await requestJson<unknown>(
+    env,
+    `/content/wiki/${encodeURIComponent(id)}/publish`,
+    { method: 'POST', body: JSON.stringify({}) },
+  );
+}
+
+export async function writePage(env: WikiClientEnv, input: WriteInput): Promise<WritePageResult> {
+  const { slug, ...rest } = input;
+  const dataPayload = {
+    canonical: false,
+    confidence: 'drifting' as const,
+    last_verified: todayIsoDate(),
+    sources: [],
+    related: [],
+    supersedes: [],
+    ...rest,
+  };
+
+  const existing = await readPage(env, slug);
+
+  if (existing.page?.id) {
+    const updateBody = {
+      slug,
+      status: existing.page.status ?? 'published',
+      data: dataPayload,
+      ...(existing.page.revision_id ? { _rev: existing.page.revision_id } : {}),
+    };
+    const data = await requestJson<unknown>(
+      env,
+      `/content/wiki/${encodeURIComponent(existing.page.id)}`,
+      {
+        method: 'PUT',
+        body: JSON.stringify(updateBody),
+      },
+    );
+    await publishRevision(env, existing.page.id);
+    return normalizeWriteResult(data, { slug, id: existing.page.id });
+  }
+
+  const createBody = {
+    slug,
+    status: 'published',
+    data: dataPayload,
+  };
+  const data = await requestJson<unknown>(env, '/content/wiki', {
+    method: 'POST',
+    body: JSON.stringify(createBody),
+  });
+  const result = normalizeWriteResult(data, { slug });
+  await publishRevision(env, result.id);
+  return result;
+}
+
+export async function listPages(
+  env: WikiClientEnv,
+  options: { scope?: string; limit?: number; cursor?: string } = {},
+): Promise<ListPagesResult> {
+  const params = new URLSearchParams();
+  params.set('limit', String(options.limit ?? 50));
+  if (options.cursor) params.set('cursor', options.cursor);
+
+  const raw = await requestJson<unknown>(env, `/content/wiki?${params.toString()}`);
+
+  let pages = normalizeSummaryArray(raw);
+  // Emdash list endpoint doesn't filter by inner data fields — scope is client-side.
+  if (options.scope) pages = pages.filter(p => p.scope === options.scope);
+
+  const envelope = asObject(raw);
+  const inner = asObject(envelope?.data) ?? envelope ?? {};
+  const nextCursor = typeof inner.nextCursor === 'string' ? inner.nextCursor : undefined;
+
+  return {
+    pages,
+    total: pages.length,
+    nextCursor,
+  };
+}

package/src/wiki/types.ts

@@ -0,0 +1,90 @@
+// Second source of truth vs emdash seed.json (stackbilt-emdash/seed/seed.json).
+// Intentional: this is the client-side MCP validator gate — narrower-than-server
+// is fail-closed (daemon rejects, surfaces loudly). Keep in sync with seed.json
+// when extending. Auto-generation from the seed schema is a separate epic.
+export const WIKI_SCOPES = ['aegis', 'concepts', 'entities', 'decisions', 'wiki', 'dreams', 'contracts'] as const;
+export const WIKI_TYPES = ['state', 'architecture', 'decision', 'concept', 'entity', 'agenda', 'synthesis'] as const;
+export const WIKI_CONFIDENCES = ['stable', 'drifting', 'unverified', 'contested'] as const;
+export const WIKI_STATUSES = ['experimental', 'stable', 'deprecated'] as const;
+
+export type WikiScope = typeof WIKI_SCOPES[number];
+export type WikiType = typeof WIKI_TYPES[number];
+export type WikiConfidence = typeof WIKI_CONFIDENCES[number];
+export type WikiStatus = typeof WIKI_STATUSES[number];
+
+export interface WikiSource {
+  type: string;
+  ref: string;
+  verified_date: string;
+}
+
+export interface WriteInput {
+  slug: string;
+  scope: WikiScope;
+  type: WikiType;
+  title: string;
+  summary: string;
+  body: string;
+  canonical?: boolean;
+  confidence?: WikiConfidence;
+  last_verified?: string;
+  sources?: WikiSource[];
+  related?: string[];
+  supersedes?: string[];
+  // Contracts-scope frontmatter (Nexus Gate A, aegis#523).
+  // Required when scope === 'contracts'; enforced in mcp/handlers.ts.
+  // `contract_status` disambiguates from emdash's built-in `status` content-
+  // lifecycle column (draft/published/archived) which would collide.
+  owners?: string[];
+  consumers?: string[];
+  guarded_paths?: string[];
+  contract_status?: WikiStatus;
+}
+
+export interface PageSummary {
+  slug: string;
+  title: string;
+  scope: string;
+  type: string;
+  confidence: string;
+  summary: string;
+  updated_at: string;
+  snippet?: string;
+}
+
+export interface WikiPage extends PageSummary {
+  id: string;
+  status?: string;
+  revision_id?: string;
+  body?: string;
+  canonical?: boolean;
+  last_verified?: string;
+  sources?: WikiSource[];
+  related?: string[];
+  supersedes?: string[];
+  // Contracts-scope frontmatter (Nexus Gate A, aegis#523).
+  owners?: string[];
+  consumers?: string[];
+  guarded_paths?: string[];
+  [key: string]: unknown;
+}
+
+export interface ReadPageResult {
+  page: WikiPage | null;
+}
+
+export interface SearchPagesResult {
+  results: PageSummary[];
+}
+
+export interface WritePageResult {
+  slug: string;
+  id: string;
+  revision_id?: string;
+}
+
+export interface ListPagesResult {
+  pages: PageSummary[];
+  total: number;
+  nextCursor?: string;
+}