@lucern/contracts 0.1.0 → 0.1.1-alpha.1

package/src/convex-admin.contract.ts

@@ -0,0 +1,14 @@
+export 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>;
+}

package/src/events-types.contract.ts

@@ -0,0 +1,9 @@
+/**
+ * @lucern/contracts — events-types compat shim
+ *
+ * This file consolidated into ./events.contract.ts during EK-16 T1 PR 3b.
+ * Retained here until the Lucern 1.0.0 barrel-sunset cut (D12).
+ * New code should import from "@lucern/contracts" (barrel) or "./events.contract".
+ */
+
+export * from "./events.contract";

package/src/events.contract.ts

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

package/src/evidence/v1.ts

@@ -0,0 +1,8 @@
+/**
+ * Evidence API Contract v1
+ *
+ * Defines the public surface for evidence operations:
+ * create, link, search, context-bound retrieval.
+ * Migrates from front-end/lucern/contracts/ during EK-16.
+ */
+export {};

package/src/gateway.contract.ts

@@ -0,0 +1,151 @@
+/**
+ * Gateway contract types — shared between Stack's gateway middleware and
+ * Lucern's server-core / gateway route handlers.
+ *
+ * These types describe the authenticated request context that flows from
+ * the gateway into Lucern route handlers. The gateway (Stack-side) creates
+ * the context; Lucern consumes it read-only.
+ *
+ * @module @lucern/contracts/src/gateway
+ */
+
+import type {
+  SessionAuthMode,
+  SessionDelegationHop,
+  SessionPrincipalType,
+} from "./auth-session.contract";
+
+// ---------------------------------------------------------------------------
+// Error codes
+// ---------------------------------------------------------------------------
+
+export type PlatformApiErrorCode =
+  | "AUTH_REQUIRED"
+  | "AUTHENTICATION_REQUIRED"
+  | "AUTH_TOKEN_MISSING"
+  | "INVALID_REQUEST"
+  | "IDEMPOTENCY_KEY_REQUIRED"
+  | "FORBIDDEN"
+  | "SCOPE_INSUFFICIENT"
+  | "ENVIRONMENT_MISMATCH"
+  | "KEY_EXPIRED"
+  | "KEY_REVOKED"
+  | "RATE_LIMIT_EXCEEDED"
+  | "NOT_FOUND"
+  | "CONFLICT"
+  | "UPSTREAM_ERROR"
+  | "INTERNAL_ERROR";
+
+// ---------------------------------------------------------------------------
+// Gateway scope and environment
+// ---------------------------------------------------------------------------
+
+export type GatewayScope = {
+  tenantId?: string;
+  workspaceId?: string;
+};
+
+export type GatewayEnvironment = "sandbox" | "production";
+
+export type GatewayAuthMode =
+  | "interactive_user"
+  | "service_principal"
+  | "tenant_api_key"
+  | "session_token";
+
+export type KeyLifecycleStatus =
+  | "active"
+  | "rotating"
+  | "rotated"
+  | "expired"
+  | "revoked";
+
+export type CutoverDomain =
+  | "graph"
+  | "schema"
+  | "identity"
+  | "policy"
+  | "audit"
+  | "admin"
+  | "agent"
+  | "tool"
+  | "prompt"
+  | "intelligence";
+
+export type CutoverFlagState = "legacy" | "cutover" | "disabled";
+
+// ---------------------------------------------------------------------------
+// Gateway auth context — the canonical authenticated request shape
+// ---------------------------------------------------------------------------
+
+/**
+ * Authenticated request context created by the gateway middleware.
+ * Lucern route handlers receive this as a read-only parameter.
+ *
+ * The `convex` field is typed as `unknown` in the contract because Lucern
+ * consumers should not use the gateway's Convex client directly — they
+ * have their own kernel client. The gateway (Stack-side) narrows this to
+ * `ConvexHttpClient` at the construction site.
+ */
+export type GatewayAuthContext = {
+  userId: string;
+  convexToken?: string;
+  /** Opaque in contract — narrowed to ConvexHttpClient at the gateway. */
+  convex: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+  authMode: GatewayAuthMode;
+  principalId?: string;
+  principalType?: SessionPrincipalType;
+  tenantId?: string;
+  workspaceId?: string;
+  roles?: string[];
+  sessionId?: string;
+  sessionAuthMode?: SessionAuthMode;
+  sessionExpiresAt?: number;
+  delegationChain?: SessionDelegationHop[];
+  servicePrincipalId?: string;
+  servicePrincipalKeyId?: string;
+  servicePrincipalTenantId?: string;
+  servicePrincipalWorkspaceId?: string;
+  requestEnvironment: GatewayEnvironment;
+  keyEnvironment?: GatewayEnvironment;
+  keyStatus: KeyLifecycleStatus | "unknown";
+  grantedScopes: Set<string>;
+  cutoverDomain: CutoverDomain;
+  cutoverState: CutoverFlagState;
+};
+
+// ---------------------------------------------------------------------------
+// Gateway response helpers — portable (no Next.js dependency)
+// ---------------------------------------------------------------------------
+
+export type GatewayErrorArgs = {
+  code: PlatformApiErrorCode;
+  message: string;
+  status: number;
+  correlationId: string;
+  policyTraceId?: string;
+  invariant?: string;
+  suggestion?: string;
+  details?: unknown;
+  headers?: HeadersInit;
+};
+
+export type GatewaySuccessArgs = {
+  status?: number;
+  correlationId: string;
+  policyTraceId?: string;
+  idempotentReplay?: boolean;
+};
+
+export function requireActorPrincipalId(
+  authContext: GatewayAuthContext
+): string {
+  const principalId =
+    typeof authContext.principalId === "string"
+      ? authContext.principalId.trim()
+      : "";
+  if (principalId.length > 0) {
+    return principalId;
+  }
+  throw new Error("Access denied: federated principal context required.");
+}

package/src/graph/v1.ts

@@ -0,0 +1,8 @@
+/**
+ * Graph Traversal API Contract v1
+ *
+ * Defines the public surface for graph operations:
+ * traverse, neighborhood, edges, contradictions, structural analysis.
+ * Migrates from front-end/lucern/contracts/ during EK-16.
+ */
+export {};

package/src/ids.contract.ts

@@ -0,0 +1,36 @@
+export type DecodedPrefixedId = {
+  prefix: string;
+  value: string;
+};
+
+const PREFIXED_ID_PATTERN = /^([a-z][a-z0-9]*)_(.+)$/;
+
+export function encodePrefixedId(prefix: string, value: string): string {
+  const normalizedPrefix = prefix.trim();
+  const normalizedValue = value.trim();
+
+  if (!normalizedPrefix || !normalizedValue) {
+    throw new Error("Both prefix and value are required to encode a prefixed ID.");
+  }
+
+  return `${normalizedPrefix}_${normalizedValue}`;
+}
+
+export function decodePrefixedId(id: string): DecodedPrefixedId {
+  const normalized = id.trim();
+  const match = PREFIXED_ID_PATTERN.exec(normalized);
+
+  if (!match) {
+    throw new Error(`Invalid prefixed ID: ${id}`);
+  }
+
+  return {
+    prefix: match[1],
+    value: match[2],
+  };
+}
+
+export function hasPrefixedIdPrefix(id: string, prefix: string): boolean {
+  const decoded = decodePrefixedId(id);
+  return decoded.prefix === prefix.trim();
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Lucern Platform Contracts
+ *
+ * Machine-readable source of truth for all external API surfaces.
+ * Enforcement hierarchy: MCP/API (co-equal) → SDK (derived) → Schema (internal).
+ *
+ * These contracts are consumed by:
+ *   - MCP tool registration (learning-loop module)
+ *   - API route validation (platform gateway)
+ *   - SDK type generation (@lucern/sdk-* packages)
+ *   - Contract lint gates (CI)
+ */
+
+export * from "./api-enums.contract";
+export * from "./auth-session.contract";
+export * from "./auth-context.contract";
+export * from "./convex-admin.contract";
+export * from "./gateway.contract";
+export * from "./context-pack.contract";
+export * from "./events.contract";
+export * from "./events-types.contract";
+export * from "./ids.contract";
+export * as mcpToolsContract from "./mcp-tools.contract";
+export * from "./ontology-matching.contract";
+export * from "./prompt.contract";
+export * from "./sdk-methods.contract";
+export * as sdkToolsContract from "./sdk-tools.contract";
+export * from "./text-matching.contract";
+export * from "./topic-scope.contract";
+export * from "./workflow-runtime.contract";