@lucern/contracts 0.1.0 → 0.1.2-alpha.1

package/dist/context-pack.contract.js

@@ -1,170 +1,98 @@
-/**
- * Context-Pack Contract v1
- *
- * Canonical TypeScript types and constants for the context-pack output schema.
- * This is the external contract consumed by:
- *   - MCP tool `compile_context` (canonical compiler read)
- *   - SDK/HTTP consumers that read compiled context packs programmatically
- *   - Benchmark harnesses (context-pack-ab)
- *
- * BREAKING CHANGE RULES:
- *   - Adding optional fields to ContextPackV1 is NON-breaking
- *   - Removing fields or changing types is BREAKING (bump CONTEXT_PACK_SCHEMA_VERSION)
- *   - Changing section budget ratios or ranking weights is NON-breaking (tuning)
- *   - Changing the version string is BREAKING (consumers check it)
- */
-// =============================================================================
-// SCHEMA VERSION
-// =============================================================================
-/** Canonical version string. Consumers MUST check this field for compatibility. */
-export const CONTEXT_PACK_SCHEMA_VERSION = "1.0.0";
-export const CONTEXT_RANKING_PROFILES = [
-    "baseline_v1",
-    "weighted_v1",
+// src/context-pack.contract.ts
+var CONTEXT_PACK_SCHEMA_VERSION = "1.0.0";
+var CONTEXT_RANKING_PROFILES = [
+  "baseline_v1",
+  "weighted_v1"
 ];
-export const DEFAULT_RANKING_PROFILE = "weighted_v1";
-export const DEFAULT_COMPILATION_MODE = "standard";
-export const CONTEXT_PACK_SECTION_KEYS = [
-    "invariants",
-    "activeBeliefs",
-    "openQuestions",
-    "recentEvidence",
-    "contradictions",
+var DEFAULT_RANKING_PROFILE = "weighted_v1";
+var DEFAULT_COMPILATION_MODE = "standard";
+var CONTEXT_PACK_SECTION_KEYS = [
+  "invariants",
+  "activeBeliefs",
+  "openQuestions",
+  "recentEvidence",
+  "contradictions"
 ];
-// =============================================================================
-// SECTION BUDGET RATIOS
-// =============================================================================
-/**
- * Token budget allocation ratios per section.
- * These sum to 1.0 and determine how the total tokenBudget is divided.
- *
- * Rationale:
- * - invariants (0.28): Highest-priority constraints, injected first
- * - activeBeliefs (0.30): Largest section, carries domain knowledge
- * - openQuestions (0.17): Unresolved work items guide agent behavior
- * - recentEvidence (0.17): Implementation context for grounding
- * - contradictions (0.08): Tension signals, smallest section
- */
-export const SECTION_BUDGET_RATIOS = {
-    invariants: 0.28,
-    activeBeliefs: 0.3,
-    openQuestions: 0.17,
-    recentEvidence: 0.17,
-    contradictions: 0.08,
+var SECTION_BUDGET_RATIOS = {
+  invariants: 0.28,
+  activeBeliefs: 0.3,
+  openQuestions: 0.17,
+  recentEvidence: 0.17,
+  contradictions: 0.08
 };
-// =============================================================================
-// TOKEN BUDGET CONSTRAINTS
-// =============================================================================
-/** Minimum allowed token budget. Below this, context packs lose utility. */
-export const MIN_TOKEN_BUDGET = 400;
-/** Maximum allowed token budget. Above this, context packs bloat prompts. */
-export const MAX_TOKEN_BUDGET = 8000;
-/** Default token budget when caller does not specify. */
-export const DEFAULT_TOKEN_BUDGET = 1800;
-/** Default max items per section. */
-export const DEFAULT_SECTION_LIMIT = 8;
-/** Hard ceiling on items per section. */
-export const MAX_SECTION_LIMIT = 25;
-/** Minimum contradiction section budget floor (tokens). */
-export const MIN_CONTRADICTION_BUDGET = 40;
-export const RANKING_WEIGHTS = {
-    invariants: {
-        query: 0.35,
-        recency: 0.1,
-        confidence: 0.4,
-        beliefType: 0.15,
-    },
-    activeBeliefs: {
-        query: 0.5,
-        recency: 0.2,
-        confidence: 0.2,
-        beliefType: 0.1,
-    },
-    openQuestions: {
-        query: 0.55,
-        recency: 0.2,
-        priority: 0.25,
-    },
-    recentEvidence: {
-        query: 0.6,
-        recency: 0.4,
-    },
-    contradictions: {
-        query: 0.4,
-        recency: 0.2,
-        severity: 0.4,
-    },
-};
-/** Recency decay half-life in days. After 30 days, recency score = 0.5. */
-export const RECENCY_HALF_LIFE_DAYS = 30;
-/**
- * Ranking weight vector for the relatedEntities section.
- * Entities are ranked by query relevance and connectivity (bridge edge count).
- * Separate from RANKING_WEIGHTS because entities are not part of the
- * token-budgeted injection plan.
- */
-export const ENTITY_RANKING_WEIGHTS = {
+var MIN_TOKEN_BUDGET = 400;
+var MAX_TOKEN_BUDGET = 8e3;
+var DEFAULT_TOKEN_BUDGET = 1800;
+var DEFAULT_SECTION_LIMIT = 8;
+var MAX_SECTION_LIMIT = 25;
+var MIN_CONTRADICTION_BUDGET = 40;
+var RANKING_WEIGHTS = {
+  invariants: {
+    query: 0.35,
+    recency: 0.1,
+    confidence: 0.4,
+    beliefType: 0.15
+  },
+  activeBeliefs: {
+    query: 0.5,
+    recency: 0.2,
+    confidence: 0.2,
+    beliefType: 0.1
+  },
+  openQuestions: {
+    query: 0.55,
+    recency: 0.2,
+    priority: 0.25
+  },
+  recentEvidence: {
+    query: 0.6,
+    recency: 0.4
+  },
+  contradictions: {
     query: 0.4,
-    connectivity: 0.6,
+    recency: 0.2,
+    severity: 0.4
+  }
+};
+var RECENCY_HALF_LIFE_DAYS = 30;
+var ENTITY_RANKING_WEIGHTS = {
+  query: 0.4,
+  connectivity: 0.6
 };
-/** Default max entities to include in the context pack. */
-export const DEFAULT_ENTITY_LIMIT = 10;
-/** Hard ceiling on entities per context pack. */
-export const MAX_ENTITY_LIMIT = 50;
-// =============================================================================
-// BELIEF TYPE BONUS MAP
-// =============================================================================
-/**
- * Bonus multiplier for belief types in ranking.
- * Invariants get 1.0, unknown types get 0.4.
- */
-export const BELIEF_TYPE_BONUS = {
-    invariant: 1.0,
-    tenet: 0.8,
-    principle: 0.6,
+var DEFAULT_ENTITY_LIMIT = 10;
+var MAX_ENTITY_LIMIT = 50;
+var BELIEF_TYPE_BONUS = {
+  invariant: 1,
+  tenet: 0.8,
+  principle: 0.6
 };
-export const DEFAULT_BELIEF_TYPE_BONUS = 0.4;
-// =============================================================================
-// PRIORITY / SEVERITY SCORE MAPS
-// =============================================================================
-export const PRIORITY_SCORES = {
-    critical: 1.0,
-    high: 0.85,
-    medium: 0.55,
-    low: 0.35,
+var DEFAULT_BELIEF_TYPE_BONUS = 0.4;
+var PRIORITY_SCORES = {
+  critical: 1,
+  high: 0.85,
+  medium: 0.55,
+  low: 0.35
 };
-export const DEFAULT_PRIORITY_SCORE = 0.5;
-export const SEVERITY_SCORES = {
-    critical: 1.0,
-    high: 0.85,
-    medium: 0.6,
-    low: 0.35,
+var DEFAULT_PRIORITY_SCORE = 0.5;
+var SEVERITY_SCORES = {
+  critical: 1,
+  high: 0.85,
+  medium: 0.6,
+  low: 0.35
 };
-export const DEFAULT_SEVERITY_SCORE = 0.5;
-// =============================================================================
-// RESOLVED QUESTION STATUSES
-// =============================================================================
-/**
- * Question statuses that are considered "resolved" (not open).
- * Used to filter which questions appear in the openQuestions section.
- */
-export const RESOLVED_QUESTION_STATUSES = [
-    "answered",
-    "archived",
-    "closed",
-    "resolved",
-    "resolved_support",
-    "resolved_contra",
-    "belief_forked",
+var DEFAULT_SEVERITY_SCORE = 0.5;
+var RESOLVED_QUESTION_STATUSES = [
+  "answered",
+  "archived",
+  "closed",
+  "resolved",
+  "resolved_support",
+  "resolved_contra",
+  "belief_forked"
 ];
-// =============================================================================
-// TOKEN ESTIMATION
-// =============================================================================
-/**
- * Tokens-per-word multiplier for rough token estimation.
- * Conservative estimate: ~1.35 tokens per whitespace-delimited word.
- */
-export const TOKENS_PER_WORD = 1.35;
-/** Minimum token estimate for any non-empty string. */
-export const MIN_TOKEN_ESTIMATE = 8;
+var TOKENS_PER_WORD = 1.35;
+var MIN_TOKEN_ESTIMATE = 8;
+
+export { BELIEF_TYPE_BONUS, CONTEXT_PACK_SCHEMA_VERSION, CONTEXT_PACK_SECTION_KEYS, CONTEXT_RANKING_PROFILES, DEFAULT_BELIEF_TYPE_BONUS, DEFAULT_COMPILATION_MODE, DEFAULT_ENTITY_LIMIT, DEFAULT_PRIORITY_SCORE, DEFAULT_RANKING_PROFILE, DEFAULT_SECTION_LIMIT, DEFAULT_SEVERITY_SCORE, DEFAULT_TOKEN_BUDGET, ENTITY_RANKING_WEIGHTS, MAX_ENTITY_LIMIT, MAX_SECTION_LIMIT, MAX_TOKEN_BUDGET, MIN_CONTRADICTION_BUDGET, MIN_TOKEN_BUDGET, MIN_TOKEN_ESTIMATE, PRIORITY_SCORES, RANKING_WEIGHTS, RECENCY_HALF_LIFE_DAYS, RESOLVED_QUESTION_STATUSES, SECTION_BUDGET_RATIOS, SEVERITY_SCORES, TOKENS_PER_WORD };
+//# sourceMappingURL=context-pack.contract.js.map
 //# sourceMappingURL=context-pack.contract.js.map

package/dist/context-pack.contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-pack.contract.js","sourceRoot":"","sources":["../src/context-pack.contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"sources":["../src/context-pack.contract.ts"],"names":[],"mappings":";AAqBO,IAAM,2BAAA,GAA8B;AAepC,IAAM,wBAAA,GAA6D;AAAA,EACxE,aAAA;AAAA,EACA;AACF;AAEO,IAAM,uBAAA,GAAiD;AAevD,IAAM,wBAAA,GAAmD;AAiBzD,IAAM,yBAAA,GAA8D;AAAA,EACzE,YAAA;AAAA,EACA,eAAA;AAAA,EACA,eAAA;AAAA,EACA,gBAAA;AAAA,EACA;AACF;AAiBO,IAAM,qBAAA,GAET;AAAA,EACF,UAAA,EAAY,IAAA;AAAA,EACZ,aAAA,EAAe,GAAA;AAAA,EACf,aAAA,EAAe,IAAA;AAAA,EACf,cAAA,EAAgB,IAAA;AAAA,EAChB,cAAA,EAAgB;AAClB;AAOO,IAAM,gBAAA,GAAmB;AAGzB,IAAM,gBAAA,GAAmB;AAGzB,IAAM,oBAAA,GAAuB;AAG7B,IAAM,qBAAA,GAAwB;AAG9B,IAAM,iBAAA,GAAoB;AAG1B,IAAM,wBAAA,GAA2B;AA0BjC,IAAM,eAAA,GAET;AAAA,EACF,UAAA,EAAY;AAAA,IACV,KAAA,EAAO,IAAA;AAAA,IACP,OAAA,EAAS,GAAA;AAAA,IACT,UAAA,EAAY,GAAA;AAAA,IACZ,UAAA,EAAY;AAAA,GACd;AAAA,EACA,aAAA,EAAe;AAAA,IACb,KAAA,EAAO,GAAA;AAAA,IACP,OAAA,EAAS,GAAA;AAAA,IACT,UAAA,EAAY,GAAA;AAAA,IACZ,UAAA,EAAY;AAAA,GACd;AAAA,EACA,aAAA,EAAe;AAAA,IACb,KAAA,EAAO,IAAA;AAAA,IACP,OAAA,EAAS,GAAA;AAAA,IACT,QAAA,EAAU;AAAA,GACZ;AAAA,EACA,cAAA,EAAgB;AAAA,IACd,KAAA,EAAO,GAAA;AAAA,IACP,OAAA,EAAS;AAAA,GACX;AAAA,EACA,cAAA,EAAgB;AAAA,IACd,KAAA,EAAO,GAAA;AAAA,IACP,OAAA,EAAS,GAAA;AAAA,IACT,QAAA,EAAU;AAAA;AAEd;AAGO,IAAM,sBAAA,GAAyB;AAQ/B,IAAM,sBAAA,GAAyB;AAAA,EACpC,KAAA,EAAO,GAAA;AAAA,EACP,YAAA,EAAc;AAChB;AAGO,IAAM,oBAAA,GAAuB;AAG7B,IAAM,gBAAA,GAAmB;AAUzB,IAAM,iBAAA,GAAsD;AAAA,EACjE,SAAA,EAAW,CAAA;AAAA,EACX,KAAA,EAAO,GAAA;AAAA,EACP,SAAA,EAAW;AACb;AAEO,IAAM,yBAAA,GAA4B;AAMlC,IAAM,eAAA,GAAoD;AAAA,EAC/D,QAAA,EAAU,CAAA;AAAA,EACV,IAAA,EAAM,IAAA;AAAA,EACN,MAAA,EAAQ,IAAA;AAAA,EACR,GAAA,EAAK;AACP;AAEO,IAAM,sBAAA,GAAyB;AAE/B,IAAM,eAAA,GAAoD;AAAA,EAC/D,QAAA,EAAU,CAAA;AAAA,EACV,IAAA,EAAM,IAAA;AAAA,EACN,MAAA,EAAQ,GAAA;AAAA,EACR,GAAA,EAAK;AACP;AAEO,IAAM,sBAAA,GAAyB;AA2b/B,IAAM,0BAAA,GAAgD;AAAA,EAC3D,UAAA;AAAA,EACA,UAAA;AAAA,EACA,QAAA;AAAA,EACA,UAAA;AAAA,EACA,kBAAA;AAAA,EACA,iBAAA;AAAA,EACA;AACF;AAUO,IAAM,eAAA,GAAkB;AAGxB,IAAM,kBAAA,GAAqB","file":"context-pack.contract.js","sourcesContent":["/**\n * Context-Pack Contract v1\n *\n * Canonical TypeScript types and constants for the context-pack output schema.\n * This is the external contract consumed by:\n *   - MCP tool `compile_context` (canonical compiler read)\n *   - SDK/HTTP consumers that read compiled context packs programmatically\n *   - Benchmark harnesses (context-pack-ab)\n *\n * BREAKING CHANGE RULES:\n *   - Adding optional fields to ContextPackV1 is NON-breaking\n *   - Removing fields or changing types is BREAKING (bump CONTEXT_PACK_SCHEMA_VERSION)\n *   - Changing section budget ratios or ranking weights is NON-breaking (tuning)\n *   - Changing the version string is BREAKING (consumers check it)\n */\n\n// =============================================================================\n// SCHEMA VERSION\n// =============================================================================\n\n/** Canonical version string. Consumers MUST check this field for compatibility. */\nexport const CONTEXT_PACK_SCHEMA_VERSION = \"1.0.0\" as const;\n\n// =============================================================================\n// RANKING PROFILES\n// =============================================================================\n\n/**\n * Available ranking profiles for context-pack assembly.\n *\n * - `baseline_v1`: Simple token-hit counting. Items with zero query hits are excluded.\n * - `weighted_v1`: Multi-signal scoring combining query relevance, recency, confidence,\n *    belief type, priority, and severity with section-specific weight vectors.\n */\nexport type ContextRankingProfile = \"baseline_v1\" | \"weighted_v1\";\n\nexport const CONTEXT_RANKING_PROFILES: readonly ContextRankingProfile[] = [\n  \"baseline_v1\",\n  \"weighted_v1\",\n] as const;\n\nexport const DEFAULT_RANKING_PROFILE: ContextRankingProfile = \"weighted_v1\";\n\n// =============================================================================\n// COMPILATION MODE (RS-2)\n// =============================================================================\n\n/**\n * Context compilation mode.\n *\n * - `standard`: Default — ranked beliefs, questions, evidence, contradictions.\n * - `delta`: Diff-aware — adds failure context, verification obligations,\n *    and worktree ledger analysis to the standard context pack.\n */\nexport type ContextCompilationMode = \"standard\" | \"delta\";\n\nexport const DEFAULT_COMPILATION_MODE: ContextCompilationMode = \"standard\";\n\n// =============================================================================\n// SECTION KEYS\n// =============================================================================\n\n/**\n * The five canonical sections of a context pack.\n * Order matters: invariants are injected first, contradictions last.\n */\nexport type ContextPackSectionKey =\n  | \"invariants\"\n  | \"activeBeliefs\"\n  | \"openQuestions\"\n  | \"recentEvidence\"\n  | \"contradictions\";\n\nexport const CONTEXT_PACK_SECTION_KEYS: readonly ContextPackSectionKey[] = [\n  \"invariants\",\n  \"activeBeliefs\",\n  \"openQuestions\",\n  \"recentEvidence\",\n  \"contradictions\",\n] as const;\n\n// =============================================================================\n// SECTION BUDGET RATIOS\n// =============================================================================\n\n/**\n * Token budget allocation ratios per section.\n * These sum to 1.0 and determine how the total tokenBudget is divided.\n *\n * Rationale:\n * - invariants (0.28): Highest-priority constraints, injected first\n * - activeBeliefs (0.30): Largest section, carries domain knowledge\n * - openQuestions (0.17): Unresolved work items guide agent behavior\n * - recentEvidence (0.17): Implementation context for grounding\n * - contradictions (0.08): Tension signals, smallest section\n */\nexport const SECTION_BUDGET_RATIOS: Readonly<\n  Record<ContextPackSectionKey, number>\n> = {\n  invariants: 0.28,\n  activeBeliefs: 0.3,\n  openQuestions: 0.17,\n  recentEvidence: 0.17,\n  contradictions: 0.08,\n} as const;\n\n// =============================================================================\n// TOKEN BUDGET CONSTRAINTS\n// =============================================================================\n\n/** Minimum allowed token budget. Below this, context packs lose utility. */\nexport const MIN_TOKEN_BUDGET = 400;\n\n/** Maximum allowed token budget. Above this, context packs bloat prompts. */\nexport const MAX_TOKEN_BUDGET = 8000;\n\n/** Default token budget when caller does not specify. */\nexport const DEFAULT_TOKEN_BUDGET = 1800;\n\n/** Default max items per section. */\nexport const DEFAULT_SECTION_LIMIT = 8;\n\n/** Hard ceiling on items per section. */\nexport const MAX_SECTION_LIMIT = 25;\n\n/** Minimum contradiction section budget floor (tokens). */\nexport const MIN_CONTRADICTION_BUDGET = 40;\n\n// =============================================================================\n// RANKING WEIGHT VECTORS\n// =============================================================================\n\n/**\n * Weight vectors for the weighted_v1 ranking profile.\n * Each section has a different signal mix:\n *\n * - query: How many query tokens appear in the candidate text\n * - recency: Exponential decay from updatedAt (half-life = 30 days)\n * - confidence: Belief confidence score [0,1]\n * - beliefType: Bonus for invariant > tenet > principle > other\n * - priority: Question priority (critical > high > medium > low)\n * - severity: Contradiction severity (critical > high > medium > low)\n */\nexport type RankingWeightVector = {\n  query: number;\n  recency: number;\n  confidence?: number;\n  beliefType?: number;\n  priority?: number;\n  severity?: number;\n};\n\nexport const RANKING_WEIGHTS: Readonly<\n  Record<ContextPackSectionKey, RankingWeightVector>\n> = {\n  invariants: {\n    query: 0.35,\n    recency: 0.1,\n    confidence: 0.4,\n    beliefType: 0.15,\n  },\n  activeBeliefs: {\n    query: 0.5,\n    recency: 0.2,\n    confidence: 0.2,\n    beliefType: 0.1,\n  },\n  openQuestions: {\n    query: 0.55,\n    recency: 0.2,\n    priority: 0.25,\n  },\n  recentEvidence: {\n    query: 0.6,\n    recency: 0.4,\n  },\n  contradictions: {\n    query: 0.4,\n    recency: 0.2,\n    severity: 0.4,\n  },\n} as const;\n\n/** Recency decay half-life in days. After 30 days, recency score = 0.5. */\nexport const RECENCY_HALF_LIFE_DAYS = 30;\n\n/**\n * Ranking weight vector for the relatedEntities section.\n * Entities are ranked by query relevance and connectivity (bridge edge count).\n * Separate from RANKING_WEIGHTS because entities are not part of the\n * token-budgeted injection plan.\n */\nexport const ENTITY_RANKING_WEIGHTS = {\n  query: 0.4,\n  connectivity: 0.6,\n} as const;\n\n/** Default max entities to include in the context pack. */\nexport const DEFAULT_ENTITY_LIMIT = 10;\n\n/** Hard ceiling on entities per context pack. */\nexport const MAX_ENTITY_LIMIT = 50;\n\n// =============================================================================\n// BELIEF TYPE BONUS MAP\n// =============================================================================\n\n/**\n * Bonus multiplier for belief types in ranking.\n * Invariants get 1.0, unknown types get 0.4.\n */\nexport const BELIEF_TYPE_BONUS: Readonly<Record<string, number>> = {\n  invariant: 1.0,\n  tenet: 0.8,\n  principle: 0.6,\n} as const;\n\nexport const DEFAULT_BELIEF_TYPE_BONUS = 0.4;\n\n// =============================================================================\n// PRIORITY / SEVERITY SCORE MAPS\n// =============================================================================\n\nexport const PRIORITY_SCORES: Readonly<Record<string, number>> = {\n  critical: 1.0,\n  high: 0.85,\n  medium: 0.55,\n  low: 0.35,\n} as const;\n\nexport const DEFAULT_PRIORITY_SCORE = 0.5;\n\nexport const SEVERITY_SCORES: Readonly<Record<string, number>> = {\n  critical: 1.0,\n  high: 0.85,\n  medium: 0.6,\n  low: 0.35,\n} as const;\n\nexport const DEFAULT_SEVERITY_SCORE = 0.5;\n\n// =============================================================================\n// SECTION ITEM TYPES\n// =============================================================================\n\n/** A ranked belief in the invariants or activeBeliefs section. */\nexport type ContextPackBelief = {\n  nodeId: string;\n  canonicalText: string;\n  confidence: number | null;\n  beliefType: string | null;\n  score: number;\n  /** Present in activeBeliefs, absent in invariants */\n  status?: string;\n  updatedAt?: number | null;\n  /** Human-readable explanation of why this item was ranked here (RS-2). */\n  justification?: string;\n};\n\n/** A ranked question in the openQuestions section. */\nexport type ContextPackQuestion = {\n  questionId: string;\n  text: string;\n  status: string;\n  priority: string;\n  updatedAt?: number | null;\n  score: number;\n  /** Human-readable explanation of why this item was ranked here (RS-2). */\n  justification?: string;\n};\n\n/** A ranked evidence item in the recentEvidence section. */\nexport type ContextPackEvidence = {\n  nodeId: string;\n  canonicalText: string;\n  sourceUrl: string | null;\n  kind: string;\n  createdAt: number | null;\n  score: number;\n  /** Human-readable explanation of why this item was ranked here (RS-2). */\n  justification?: string;\n};\n\n/** A ranked contradiction in the contradictions section. */\nexport type ContextPackContradiction = {\n  contradictionId: string;\n  severity: string;\n  status: string;\n  description: string;\n  score: number;\n  /** Human-readable explanation of why this item was ranked here (RS-2). */\n  justification?: string;\n};\n\n/**\n * An entity from the ontological layer surfaced in the context pack.\n * Entities are domain objects (companies, people, functions, etc.) connected\n * to beliefs via bridge edges. They provide the \"reality anchor\" that makes\n * the reasoning graph domain-aware.\n */\nexport type ContextPackEntity = {\n  /** Convex document ID of the entity node. */\n  nodeId: string;\n  /** Entity type (e.g., \"company\", \"person\", \"function\"). */\n  entityType: string;\n  /** Human-readable title/name of the entity. */\n  title: string;\n  /** Number of beliefs connected to this entity via bridge edges. */\n  connectedBeliefCount: number;\n  /** Number of evidence items referencing this entity. */\n  connectedEvidenceCount: number;\n  /** Relevance score from ranking algorithm. */\n  score: number;\n  /** Entity metadata (structured per ontology schema). */\n  metadata?: Record<string, unknown>;\n};\n\n/**\n * A lattice seed entry representing a belief that was auto-generated\n * to cover an ontology entity type within a topic scope.\n */\nexport type BeliefLatticeSeed = {\n  /** The belief node ID that was created or already existed. */\n  beliefNodeId: string;\n  /** The entity type this seed belief covers. */\n  entityType: string;\n  /** Whether this seed was newly created or already existed. */\n  created: boolean;\n  /** The canonical text of the seed belief. */\n  canonicalText: string;\n};\n\n// =============================================================================\n// SUMMARY\n// =============================================================================\n\n/** Counts and scoped health signals for the context pack. */\nexport type ContextPackSummary = {\n  totalBeliefs: number;\n  invariants: number;\n  openQuestions: number;\n  evidenceItems: number;\n  contradictions: number;\n  /** Number of ontological entities in scope (optional, present when entity graph is active). */\n  relatedEntities?: number;\n  scopedTopics: number;\n  descendantDepth: number;\n  query: string | null;\n};\n\n// =============================================================================\n// FAILURE CONTEXT (RS-2)\n// =============================================================================\n\n/** A failed approach surfaced from the failure log for anti-repetition. */\nexport type ContextPackFailure = {\n  /** Lucern attempt/evidence node ID. */\n  attemptId: string;\n  /** What was tried. */\n  approach: string;\n  /** Why it failed. */\n  outcome: string;\n  /** When the attempt was recorded (ms since epoch). */\n  recordedAt: number;\n  /** Relevance score from ranking algorithm. */\n  score: number;\n};\n\n/** Failure context section appended to context packs in delta mode. */\nexport type ContextPackFailureContext = {\n  /** Ranked failed approaches relevant to the current query. */\n  failures: ContextPackFailure[];\n  /** IDs of items suppressed from other sections due to anti-repetition. */\n  suppressedIds: string[];\n};\n\n// =============================================================================\n// DELTA REPORT (RS-2)\n// =============================================================================\n\n/** A verification obligation surfaced by delta compilation. */\nexport type VerificationObligation = {\n  /** What must be verified. */\n  description: string;\n  /** Source of the obligation (e.g., \"belief:xyz confidence drop\"). */\n  source: string;\n  /** Severity: how important it is to verify. */\n  severity: \"critical\" | \"high\" | \"medium\" | \"low\";\n};\n\n/** Delta report appended to context packs when mode = \"delta\". */\nexport type ContextPackDeltaReport = {\n  /** Items that changed since the reference point (new, updated, removed). */\n  changedItems: Array<{\n    id: string;\n    section: ContextPackSectionKey;\n    changeType: \"added\" | \"updated\" | \"removed\" | \"confidence_changed\";\n    summary: string;\n  }>;\n  /** Obligations the consuming session must verify. */\n  verificationObligations: VerificationObligation[];\n  /** Reference point for the delta (worktree ID, timestamp, or commit SHA). */\n  referencePoint: string;\n};\n\n// =============================================================================\n// PACK WEIGHT OVERRIDES (RS-2)\n// =============================================================================\n\n/**\n * Per-section weight overrides that domain packs can apply.\n * Overrides merge with RANKING_WEIGHTS — only specified fields replace defaults.\n */\nexport type PackWeightOverride = {\n  /** Which section to override weights for. */\n  section: ContextPackSectionKey;\n  /** Partial weight vector — only specified fields replace defaults. */\n  weights: Partial<RankingWeightVector>;\n};\n\n// =============================================================================\n// INJECTION POLICY\n// =============================================================================\n\n/** Token-budgeted section selections for prompt injection. */\nexport type ContextPackInjectionPolicy = {\n  /** Total token budget for the entire context pack. */\n  tokenBudget: number;\n  /** Estimated tokens consumed across all sections. */\n  estimatedTokens: number;\n  /** Per-section token budgets derived from SECTION_BUDGET_RATIOS. */\n  sectionBudgets: Record<ContextPackSectionKey, number>;\n  /** Actual token usage per section after greedy fill. */\n  sectionUsage: Record<ContextPackSectionKey, number>;\n  /** Node/question IDs selected for injection, per section. */\n  selected: Record<ContextPackSectionKey, string[]>;\n  /** Items that were scored but excluded from injection, with reason (RS-2). */\n  excludedItems?: Array<{\n    id: string;\n    section: ContextPackSectionKey;\n    reason: \"budget_exceeded\" | \"anti_repetition\" | \"below_threshold\";\n    score: number;\n  }>;\n};\n\n// =============================================================================\n// DIAGNOSTICS\n// =============================================================================\n\n/** Telemetry for context pack assembly. */\nexport type ContextPackDiagnostics = {\n  /** Total candidates scored across all sections. */\n  itemsScored: number;\n  /** Ratio of estimatedTokens / tokenBudget. Range [0, 1+]. */\n  tokenBudgetUtilization: number;\n};\n\n// =============================================================================\n// PUBLIC COMPILED CONTEXT TYPES\n// =============================================================================\n\n/**\n * Public context surface returned by the SDK-facing context client.\n *\n * This preserves the existing external shape while the canonical compiler\n * contract evolves in parallel as ContextPackV1.\n */\nexport type PublicContextBelief = {\n  beliefId: string;\n  text: string;\n  confidence: number | null;\n  beliefType?: string | null;\n  status?: string;\n  updatedAt?: number | null;\n  score: number;\n  justification?: string;\n};\n\nexport type PublicContextQuestion = {\n  questionId: string;\n  text: string;\n  status: string;\n  priority: string;\n  updatedAt?: number | null;\n  score: number;\n  justification?: string;\n};\n\nexport type PublicContextEvidence = {\n  evidenceId: string;\n  text: string;\n  sourceUrl?: string | null;\n  kind: string;\n  createdAt?: number | null;\n  score: number;\n  justification?: string;\n};\n\nexport type PublicContextContradiction = {\n  contradictionId: string;\n  severity: string;\n  status: string;\n  description: string;\n  score: number;\n  justification?: string;\n};\n\nexport type PublicContextEntity = {\n  entityId: string;\n  entityType: string;\n  title: string;\n  text?: string;\n  connectedBeliefCount: number;\n  connectedEvidenceCount: number;\n  score: number;\n  metadata?: Record<string, unknown>;\n};\n\nexport type PublicContextInjectionPolicy = {\n  tokenBudget: number;\n  estimatedTokens: number;\n  sectionBudgets: Record<string, number>;\n  sectionUsage: Record<string, number>;\n  selected: Record<string, string[]>;\n  excludedItems?: Array<{\n    id: string;\n    section: string;\n    reason: \"budget_exceeded\" | \"anti_repetition\" | \"below_threshold\";\n    score: number;\n  }>;\n};\n\nexport type PublicCompiledContext = {\n  schemaVersion: string;\n  topicId: string;\n  topicName: string;\n  scopedTopicIds: string[];\n  generatedAt: number;\n  ranking: ContextRankingProfile;\n  summary: Record<string, unknown>;\n  invariants: PublicContextBelief[];\n  activeBeliefs: PublicContextBelief[];\n  openQuestions: PublicContextQuestion[];\n  recentEvidence: PublicContextEvidence[];\n  contradictions: PublicContextContradiction[];\n  relatedEntities?: PublicContextEntity[];\n  contextNarrative: string[];\n  injectionPolicy: PublicContextInjectionPolicy;\n  diagnostics: Record<string, unknown>;\n  compilationMode?: string;\n  failureContext?: {\n    failures: Array<{\n      attemptId: string;\n      approach: string;\n      outcome: string;\n      recordedAt: number;\n      score: number;\n    }>;\n    suppressedIds: string[];\n  };\n  deltaReport?: {\n    changedItems: Array<{\n      id: string;\n      section: string;\n      changeType: string;\n      summary: string;\n    }>;\n    verificationObligations: Array<{\n      description: string;\n      source: string;\n      severity: \"critical\" | \"high\" | \"medium\" | \"low\";\n    }>;\n    referencePoint: string;\n  };\n  appliedWeightOverrides?: unknown[];\n};\n\n// =============================================================================\n// CONTEXT PACK V1 (TOP-LEVEL OUTPUT)\n// =============================================================================\n\n/**\n * The canonical output schema for context compilation responses.\n *\n * This is the contract that consumers depend on. All fields are required\n * in the output. Adding optional fields is non-breaking; removing or\n * changing types is breaking (requires version bump).\n */\nexport type ContextPackV1 = {\n  /** Schema version for compatibility checking. */\n  schemaVersion: typeof CONTEXT_PACK_SCHEMA_VERSION;\n  /** Deprecated compatibility alias for the requested scope ID. */\n  projectId?: string;\n  /** Resolved topic ID after scope resolution. */\n  topicId: string;\n  /** Human-readable topic name. */\n  topicName: string;\n  /** All topic IDs included in the neighborhood expansion. */\n  scopedTopicIds: string[];\n  /** Deterministic freshness watermark for this pack (ms since epoch). */\n  generatedAt: number;\n  /** Which ranking profile was used. */\n  rankingProfile: ContextRankingProfile;\n  /** Aggregate counts and health signals. */\n  summary: ContextPackSummary;\n  /** High-confidence invariant beliefs (beliefType = \"invariant\"). */\n  invariants: ContextPackBelief[];\n  /** Active beliefs ranked by query relevance. */\n  activeBeliefs: ContextPackBelief[];\n  /** Open questions ranked by relevance and priority. */\n  openQuestions: ContextPackQuestion[];\n  /** Recent evidence ranked by relevance and recency. */\n  recentEvidence: ContextPackEvidence[];\n  /** Active contradictions ranked by severity. */\n  contradictions: ContextPackContradiction[];\n  /**\n   * Ontological entities connected to beliefs in scope, ranked by connectivity.\n   * Optional — present when entity graph substrate is active for this topic.\n   * NON-BREAKING addition per contract rules.\n   */\n  relatedEntities?: ContextPackEntity[];\n  /** Concise instructions for agent context injection. */\n  contextNarrative: string[];\n  /** Token-budgeted injection selections. */\n  injectionPolicy: ContextPackInjectionPolicy;\n  /** Assembly telemetry. */\n  diagnostics: ContextPackDiagnostics;\n  /** Compilation mode used to generate this pack (RS-2). Default: \"standard\". */\n  compilationMode?: ContextCompilationMode;\n  /** Failure context for anti-repetition (RS-2). Present when failures are relevant. */\n  failureContext?: ContextPackFailureContext;\n  /** Delta report (RS-2). Present only when compilationMode = \"delta\". */\n  deltaReport?: ContextPackDeltaReport;\n  /** Pack weight overrides applied during ranking (RS-2). */\n  appliedWeightOverrides?: PackWeightOverride[];\n};\n\n// =============================================================================\n// CONTEXT PACK REQUEST V1 (INPUT)\n// =============================================================================\n\n/**\n * The canonical input schema for `compile_context`.\n * `topicId` is canonical. `projectId` remains an optional compatibility alias.\n */\nexport type ContextPackRequestV1 = {\n  /** Topic scope ID (required). */\n  topicId: string;\n  /** Deprecated compatibility alias for older callers. */\n  projectId?: string;\n  /** Focus query for relevance ranking. */\n  query?: string;\n  /** Max items per section. Default: DEFAULT_SECTION_LIMIT. */\n  limit?: number;\n  /** Ranking profile. Default: DEFAULT_RANKING_PROFILE. */\n  rankingProfile?: ContextRankingProfile;\n  /** Total token budget. Default: DEFAULT_TOKEN_BUDGET. */\n  tokenBudget?: number;\n  /** Descendant topic depth for neighborhood expansion. */\n  maxDepth?: number;\n  /** Include ontological entities connected to beliefs in scope. Default: true. */\n  includeEntities?: boolean;\n  /** Compilation mode (RS-2). Default: \"standard\". */\n  mode?: ContextCompilationMode;\n  /** Include failure log context for anti-repetition (RS-2). Default: false. */\n  includeFailures?: boolean;\n  /** Active worktree ID for delta mode reference point (RS-2). */\n  worktreeId?: string;\n  /** Session ID for anti-repetition dedup (RS-2). */\n  sessionId?: string;\n  /** Pack weight overrides from domain pack binding (RS-2). */\n  packWeightOverrides?: PackWeightOverride[];\n};\n\n// =============================================================================\n// RESOLVED QUESTION STATUSES\n// =============================================================================\n\n/**\n * Question statuses that are considered \"resolved\" (not open).\n * Used to filter which questions appear in the openQuestions section.\n */\nexport const RESOLVED_QUESTION_STATUSES: readonly string[] = [\n  \"answered\",\n  \"archived\",\n  \"closed\",\n  \"resolved\",\n  \"resolved_support\",\n  \"resolved_contra\",\n  \"belief_forked\",\n] as const;\n\n// =============================================================================\n// TOKEN ESTIMATION\n// =============================================================================\n\n/**\n * Tokens-per-word multiplier for rough token estimation.\n * Conservative estimate: ~1.35 tokens per whitespace-delimited word.\n */\nexport const TOKENS_PER_WORD = 1.35;\n\n/** Minimum token estimate for any non-empty string. */\nexport const MIN_TOKEN_ESTIMATE = 8;\n"]}

package/dist/convex-admin.contract.d.ts

@@ -0,0 +1,7 @@
+interface ConvexAdminClient {
+    query<T = unknown>(functionReference: unknown, args: Record<string, unknown>): Promise<T>;
+    mutation<T = unknown>(functionReference: unknown, args: Record<string, unknown>): Promise<T>;
+    action<T = unknown>(functionReference: unknown, args: Record<string, unknown>): Promise<T>;
+}
+
+export type { ConvexAdminClient };

package/dist/convex-admin.contract.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=convex-admin.contract.js.map
+//# sourceMappingURL=convex-admin.contract.js.map

package/dist/convex-admin.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"convex-admin.contract.js"}

package/dist/events-types.contract.d.ts

@@ -0,0 +1 @@
+export { CreateDomainEventInput, DOMAIN_EVENT_TYPES, DOMAIN_EVENT_VERSION, DomainActorType, DomainEvent, DomainEventData, DomainEventType, DomainResourceType, EVENT_RETENTION_DEFAULT_DAYS, EventCursor, EventListQuery, EventListResult, ReplayEventsInput, ReplayEventsResult, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_RETRY_DELAYS_MS, WebhookCreateInput, WebhookDeliveriesResult, WebhookDeliveryAttemptRecord, WebhookDeliveryRecord, WebhookDeliveryStatus, WebhookHealthResult, WebhookRecord, WebhookSecretMode, WebhookTestResult, WebhookUpdateInput, buildDomainEvent, compareEventCursor, createEventId, decodeEventCursor, emitDomainEvent, encodeEventCursor, inferActorType, isAfterCursor, normalizeRetentionDays, sortEventsByCursor } from './events.contract.js';

package/dist/events-types.contract.js

@@ -0,0 +1,136 @@
+// src/events.contract.ts
+var DOMAIN_EVENT_VERSION = "1.0";
+var EVENT_RETENTION_DEFAULT_DAYS = 30;
+var WEBHOOK_MAX_ATTEMPTS = 5;
+var WEBHOOK_RETRY_DELAYS_MS = [1e3, 5e3, 3e4, 3e5];
+var DOMAIN_EVENT_TYPES = [
+  "belief.created",
+  "belief.forked",
+  "belief.confidence_updated",
+  "belief.archived",
+  "belief.refined",
+  "belief.contract_created",
+  "belief.contract_evaluated",
+  "belief.lineage_queried",
+  "evidence.created",
+  "evidence.linked",
+  "evidence.search_executed",
+  "question.created",
+  "question.answered",
+  "question.refined",
+  "question.status_updated",
+  "question.archived",
+  "edge.created",
+  "contradiction.flagged",
+  "worktree.created",
+  "worktree.activated",
+  "worktree.merged",
+  "worktree.targets_updated",
+  "worktree.metadata_updated",
+  "topic.created",
+  "topic.updated",
+  "topic.archived",
+  "task.created",
+  "task.completed",
+  "task.updated",
+  "ontology.bound",
+  "context.compiled",
+  "identity.key_created",
+  "identity.key_rotated",
+  "identity.key_revoked",
+  "webhook.test"
+];
+function toBase64(value) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(value, "utf8").toString("base64url");
+  }
+  return btoa(unescape(encodeURIComponent(value))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function fromBase64(value) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(value, "base64url").toString("utf8");
+  }
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  return decodeURIComponent(escape(atob(normalized)));
+}
+function createEventId() {
+  const random = crypto.randomUUID().replace(/-/g, "");
+  return `evt_${random}`;
+}
+function normalizeRetentionDays(value) {
+  if (!Number.isFinite(value) || typeof value !== "number" || value <= 0) {
+    return EVENT_RETENTION_DEFAULT_DAYS;
+  }
+  return Math.max(1, Math.trunc(value));
+}
+function buildDomainEvent(input) {
+  const timestamp = input.timestamp ?? Date.now();
+  const retentionDays = normalizeRetentionDays(input.retentionDays);
+  return {
+    eventId: input.eventId?.trim() || createEventId(),
+    type: input.type.trim(),
+    version: DOMAIN_EVENT_VERSION,
+    timestamp,
+    tenantId: input.tenantId?.trim() || void 0,
+    workspaceId: input.workspaceId?.trim() || void 0,
+    topicId: input.topicId.trim(),
+    resourceId: input.resourceId.trim(),
+    resourceType: input.resourceType.trim(),
+    actorId: input.actorId.trim(),
+    actorType: input.actorType,
+    data: input.data ?? {},
+    correlationId: input.correlationId?.trim() || void 0,
+    expiresAt: timestamp + retentionDays * 24 * 60 * 60 * 1e3
+  };
+}
+function compareEventCursor(left, right) {
+  if (left.timestamp !== right.timestamp) {
+    return left.timestamp - right.timestamp;
+  }
+  return left.eventId.localeCompare(right.eventId);
+}
+function encodeEventCursor(cursor) {
+  return toBase64(JSON.stringify(cursor));
+}
+function decodeEventCursor(cursor) {
+  if (!cursor || cursor.trim().length === 0) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fromBase64(cursor.trim()));
+    if (typeof parsed.timestamp !== "number" || !Number.isFinite(parsed.timestamp) || typeof parsed.eventId !== "string" || parsed.eventId.trim().length === 0) {
+      return null;
+    }
+    return {
+      timestamp: parsed.timestamp,
+      eventId: parsed.eventId.trim()
+    };
+  } catch {
+    return null;
+  }
+}
+function isAfterCursor(event, cursor) {
+  if (!cursor) {
+    return true;
+  }
+  return compareEventCursor(event, cursor) > 0;
+}
+function sortEventsByCursor(events) {
+  return [...events].sort((left, right) => compareEventCursor(left, right));
+}
+function inferActorType(args) {
+  if (args.sessionType === "agent") {
+    return "agent";
+  }
+  if (args.authMode === "service_principal" || args.authMode === "tenant_api_key" || args.principalType === "service") {
+    return "service";
+  }
+  return "human";
+}
+async function emitDomainEvent(invokeMutation, input) {
+  return await invokeMutation("events:recordEvent", input);
+}
+
+export { DOMAIN_EVENT_TYPES, DOMAIN_EVENT_VERSION, EVENT_RETENTION_DEFAULT_DAYS, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_RETRY_DELAYS_MS, buildDomainEvent, compareEventCursor, createEventId, decodeEventCursor, emitDomainEvent, encodeEventCursor, inferActorType, isAfterCursor, normalizeRetentionDays, sortEventsByCursor };
+//# sourceMappingURL=events-types.contract.js.map
+//# sourceMappingURL=events-types.contract.js.map

package/dist/events-types.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/events.contract.ts"],"names":[],"mappings":"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","file":"events-types.contract.js","sourcesContent":["/**\n * @lucern/contracts — events (canonical support contract)\n *\n * Consolidated flat support surface for Lucern's domain event stream:\n *   - Event type definitions, constants, and shared enums\n *   - Event construction + cursor helpers\n *\n * Consolidated from the former split type-definition module\n * and the prior src/events.contract.ts (helpers) in EK-16 T1 PR 3b.\n * Compat shim remains at the old events-types path until Lucern 1.0.0 (D12).\n */\n\n// =============================================================================\n// EVENT TYPE DEFINITIONS & CONSTANTS\n// (Formerly the split events type-definition module)\n// =============================================================================\n\nexport const DOMAIN_EVENT_VERSION = \"1.0\" as const;\nexport const EVENT_RETENTION_DEFAULT_DAYS = 30;\nexport const WEBHOOK_MAX_ATTEMPTS = 5;\nexport const WEBHOOK_RETRY_DELAYS_MS = [1_000, 5_000, 30_000, 300_000] as const;\n\nexport const DOMAIN_EVENT_TYPES = [\n  \"belief.created\",\n  \"belief.forked\",\n  \"belief.confidence_updated\",\n  \"belief.archived\",\n  \"belief.refined\",\n  \"belief.contract_created\",\n  \"belief.contract_evaluated\",\n  \"belief.lineage_queried\",\n  \"evidence.created\",\n  \"evidence.linked\",\n  \"evidence.search_executed\",\n  \"question.created\",\n  \"question.answered\",\n  \"question.refined\",\n  \"question.status_updated\",\n  \"question.archived\",\n  \"edge.created\",\n  \"contradiction.flagged\",\n  \"worktree.created\",\n  \"worktree.activated\",\n  \"worktree.merged\",\n  \"worktree.targets_updated\",\n  \"worktree.metadata_updated\",\n  \"topic.created\",\n  \"topic.updated\",\n  \"topic.archived\",\n  \"task.created\",\n  \"task.completed\",\n  \"task.updated\",\n  \"ontology.bound\",\n  \"context.compiled\",\n  \"identity.key_created\",\n  \"identity.key_rotated\",\n  \"identity.key_revoked\",\n  \"webhook.test\",\n] as const;\n\nexport type DomainEventType = (typeof DOMAIN_EVENT_TYPES)[number];\n\nexport type DomainResourceType =\n  | \"belief\"\n  | \"evidence\"\n  | \"question\"\n  | \"edge\"\n  | \"contradiction\"\n  | \"worktree\"\n  | \"topic\"\n  | \"task\"\n  | \"ontology\"\n  | \"context\"\n  | \"identity\"\n  | \"webhook\";\n\nexport type DomainActorType = \"human\" | \"agent\" | \"service\";\n\nexport type DomainEventData = Record<string, unknown>;\n\nexport type DomainEvent = {\n  eventId: string;\n  type: DomainEventType | string;\n  version: typeof DOMAIN_EVENT_VERSION;\n  timestamp: number;\n  tenantId?: string;\n  workspaceId?: string;\n  topicId: string;\n  resourceId: string;\n  resourceType: DomainResourceType | string;\n  actorId: string;\n  actorType: DomainActorType;\n  data: DomainEventData;\n  correlationId?: string;\n  expiresAt: number;\n};\n\nexport type CreateDomainEventInput = {\n  eventId?: string;\n  timestamp?: number;\n  tenantId?: string;\n  workspaceId?: string;\n  topicId: string;\n  type: DomainEventType | string;\n  resourceId: string;\n  resourceType: DomainResourceType | string;\n  actorId: string;\n  actorType: DomainActorType;\n  data?: DomainEventData;\n  correlationId?: string;\n  retentionDays?: number;\n};\n\nexport type EventCursor = {\n  timestamp: number;\n  eventId: string;\n};\n\nexport type EventListQuery = {\n  topicId?: string;\n  after?: string;\n  types?: string[];\n  startTime?: number;\n  endTime?: number;\n  limit?: number;\n};\n\nexport type EventListResult = {\n  events: DomainEvent[];\n  nextCursor: string | null;\n};\n\nexport type WebhookSecretMode = \"configured\";\n\nexport type WebhookRecord = {\n  id: string;\n  webhookId: string;\n  tenantId?: string;\n  workspaceId?: string;\n  topicId?: string;\n  url: string;\n  events: string[];\n  active: boolean;\n  secretConfigured: boolean;\n  createdAt: number;\n  updatedAt: number;\n  createdBy: string;\n  updatedBy: string;\n  lastDeliveryAt?: number;\n  lastSuccessfulDeliveryAt?: number;\n};\n\nexport type WebhookCreateInput = {\n  url: string;\n  events: string[];\n  secret: string;\n  topicId?: string;\n  active?: boolean;\n};\n\nexport type WebhookUpdateInput = {\n  url?: string;\n  events?: string[];\n  secret?: string;\n  topicId?: string | null;\n  active?: boolean;\n};\n\nexport type WebhookDeliveryStatus =\n  | \"pending\"\n  | \"delivering\"\n  | \"succeeded\"\n  | \"failed\"\n  | \"dead_letter\";\n\nexport type WebhookDeliveryRecord = {\n  id: string;\n  deliveryId: string;\n  webhookId: string;\n  eventId: string;\n  eventType: string;\n  topicId: string;\n  status: WebhookDeliveryStatus;\n  attemptCount: number;\n  maxAttempts: number;\n  nextAttemptAt?: number;\n  lastAttemptAt?: number;\n  lastStatusCode?: number;\n  lastError?: string;\n  deliveredAt?: number;\n  createdAt: number;\n  updatedAt: number;\n};\n\nexport type WebhookDeliveryAttemptRecord = {\n  id: string;\n  attemptId: string;\n  deliveryId: string;\n  webhookId: string;\n  eventId: string;\n  eventType: string;\n  attemptNumber: number;\n  status: \"succeeded\" | \"failed\";\n  statusCode?: number;\n  error?: string;\n  responseBody?: string;\n  durationMs?: number;\n  createdAt: number;\n};\n\nexport type WebhookDeliveriesResult = {\n  deliveries: Array<\n    WebhookDeliveryRecord & {\n      attempts?: WebhookDeliveryAttemptRecord[];\n    }\n  >;\n};\n\nexport type WebhookHealthResult = {\n  webhookId: string;\n  totalAttempts: number;\n  successfulAttempts: number;\n  failedAttempts: number;\n  successRate: number;\n  pendingDeliveries: number;\n  deadLetterDeliveries: number;\n  lastDeliveryAt?: number;\n  lastSuccessfulDeliveryAt?: number;\n};\n\nexport type WebhookTestResult = {\n  webhookId: string;\n  deliveryId: string;\n  status: WebhookDeliveryStatus;\n  attempts: number;\n};\n\nexport type ReplayEventsInput = EventListQuery & {\n  webhookId?: string;\n};\n\nexport type ReplayEventsResult = EventListResult & {\n  replayedDeliveries?: number;\n  replayedWebhookId?: string;\n};\n\n// =============================================================================\n// EVENT HELPERS\n// (Formerly the body of src/events.contract.ts)\n// =============================================================================\n\nfunction toBase64(value: string): string {\n  if (typeof Buffer !== \"undefined\") {\n    return Buffer.from(value, \"utf8\").toString(\"base64url\");\n  }\n  return btoa(unescape(encodeURIComponent(value)))\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\")\n    .replace(/=+$/g, \"\");\n}\n\nfunction fromBase64(value: string): string {\n  if (typeof Buffer !== \"undefined\") {\n    return Buffer.from(value, \"base64url\").toString(\"utf8\");\n  }\n  const normalized = value.replace(/-/g, \"+\").replace(/_/g, \"/\");\n  return decodeURIComponent(escape(atob(normalized)));\n}\n\nexport function createEventId(): string {\n  const random = crypto.randomUUID().replace(/-/g, \"\");\n  return `evt_${random}`;\n}\n\nexport function normalizeRetentionDays(value: number | undefined): number {\n  if (!Number.isFinite(value) || typeof value !== \"number\" || value <= 0) {\n    return EVENT_RETENTION_DEFAULT_DAYS;\n  }\n  return Math.max(1, Math.trunc(value));\n}\n\nexport function buildDomainEvent(input: CreateDomainEventInput): DomainEvent {\n  const timestamp = input.timestamp ?? Date.now();\n  const retentionDays = normalizeRetentionDays(input.retentionDays);\n  return {\n    eventId: input.eventId?.trim() || createEventId(),\n    type: input.type.trim(),\n    version: DOMAIN_EVENT_VERSION,\n    timestamp,\n    tenantId: input.tenantId?.trim() || undefined,\n    workspaceId: input.workspaceId?.trim() || undefined,\n    topicId: input.topicId.trim(),\n    resourceId: input.resourceId.trim(),\n    resourceType: input.resourceType.trim(),\n    actorId: input.actorId.trim(),\n    actorType: input.actorType,\n    data: input.data ?? {},\n    correlationId: input.correlationId?.trim() || undefined,\n    expiresAt: timestamp + retentionDays * 24 * 60 * 60 * 1000,\n  };\n}\n\nexport function compareEventCursor(left: EventCursor, right: EventCursor): number {\n  if (left.timestamp !== right.timestamp) {\n    return left.timestamp - right.timestamp;\n  }\n  return left.eventId.localeCompare(right.eventId);\n}\n\nexport function encodeEventCursor(cursor: EventCursor): string {\n  return toBase64(JSON.stringify(cursor));\n}\n\nexport function decodeEventCursor(cursor: string | undefined): EventCursor | null {\n  if (!cursor || cursor.trim().length === 0) {\n    return null;\n  }\n  try {\n    const parsed = JSON.parse(fromBase64(cursor.trim())) as Partial<EventCursor>;\n    if (\n      typeof parsed.timestamp !== \"number\" ||\n      !Number.isFinite(parsed.timestamp) ||\n      typeof parsed.eventId !== \"string\" ||\n      parsed.eventId.trim().length === 0\n    ) {\n      return null;\n    }\n    return {\n      timestamp: parsed.timestamp,\n      eventId: parsed.eventId.trim(),\n    };\n  } catch {\n    return null;\n  }\n}\n\nexport function isAfterCursor(\n  event: Pick<DomainEvent, \"timestamp\" | \"eventId\">,\n  cursor: EventCursor | null\n): boolean {\n  if (!cursor) {\n    return true;\n  }\n  return compareEventCursor(event, cursor) > 0;\n}\n\nexport function sortEventsByCursor<T extends Pick<DomainEvent, \"timestamp\" | \"eventId\">>(\n  events: readonly T[]\n): T[] {\n  return [...events].sort((left, right) => compareEventCursor(left, right));\n}\n\nexport function inferActorType(args: {\n  sessionType?: \"agent\" | \"user\";\n  authMode?: string;\n  principalType?: string;\n}): DomainActorType {\n  if (args.sessionType === \"agent\") {\n    return \"agent\";\n  }\n  if (\n    args.authMode === \"service_principal\" ||\n    args.authMode === \"tenant_api_key\" ||\n    args.principalType === \"service\"\n  ) {\n    return \"service\";\n  }\n  return \"human\";\n}\n\nexport async function emitDomainEvent(\n  invokeMutation: (reference: any, args: CreateDomainEventInput) => Promise<unknown>,\n  input: CreateDomainEventInput\n): Promise<unknown> {\n  return await invokeMutation(\"events:recordEvent\" as any, input);\n}\n"]}