@lucern/contracts 0.1.1-alpha.1 → 0.1.2-alpha.2

package/src/convex-admin.contract.ts

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

@@ -1,9 +0,0 @@
-/**
- * @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

@@ -1,376 +0,0 @@
-/**
- * @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

@@ -1,8 +0,0 @@
-/**
- * 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

@@ -1,151 +0,0 @@
-/**
- * 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

@@ -1,8 +0,0 @@
-/**
- * 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/index.ts

@@ -1,30 +0,0 @@
-/**
- * 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";