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

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"]}

package/dist/events.contract.d.ts

@@ -0,0 +1,178 @@
+/**
+ * @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).
+ */
+declare const DOMAIN_EVENT_VERSION: "1.0";
+declare const EVENT_RETENTION_DEFAULT_DAYS = 30;
+declare const WEBHOOK_MAX_ATTEMPTS = 5;
+declare const WEBHOOK_RETRY_DELAYS_MS: readonly [1000, 5000, 30000, 300000];
+declare const DOMAIN_EVENT_TYPES: readonly ["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"];
+type DomainEventType = (typeof DOMAIN_EVENT_TYPES)[number];
+type DomainResourceType = "belief" | "evidence" | "question" | "edge" | "contradiction" | "worktree" | "topic" | "task" | "ontology" | "context" | "identity" | "webhook";
+type DomainActorType = "human" | "agent" | "service";
+type DomainEventData = Record<string, unknown>;
+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;
+};
+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;
+};
+type EventCursor = {
+    timestamp: number;
+    eventId: string;
+};
+type EventListQuery = {
+    topicId?: string;
+    after?: string;
+    types?: string[];
+    startTime?: number;
+    endTime?: number;
+    limit?: number;
+};
+type EventListResult = {
+    events: DomainEvent[];
+    nextCursor: string | null;
+};
+type WebhookSecretMode = "configured";
+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;
+};
+type WebhookCreateInput = {
+    url: string;
+    events: string[];
+    secret: string;
+    topicId?: string;
+    active?: boolean;
+};
+type WebhookUpdateInput = {
+    url?: string;
+    events?: string[];
+    secret?: string;
+    topicId?: string | null;
+    active?: boolean;
+};
+type WebhookDeliveryStatus = "pending" | "delivering" | "succeeded" | "failed" | "dead_letter";
+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;
+};
+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;
+};
+type WebhookDeliveriesResult = {
+    deliveries: Array<WebhookDeliveryRecord & {
+        attempts?: WebhookDeliveryAttemptRecord[];
+    }>;
+};
+type WebhookHealthResult = {
+    webhookId: string;
+    totalAttempts: number;
+    successfulAttempts: number;
+    failedAttempts: number;
+    successRate: number;
+    pendingDeliveries: number;
+    deadLetterDeliveries: number;
+    lastDeliveryAt?: number;
+    lastSuccessfulDeliveryAt?: number;
+};
+type WebhookTestResult = {
+    webhookId: string;
+    deliveryId: string;
+    status: WebhookDeliveryStatus;
+    attempts: number;
+};
+type ReplayEventsInput = EventListQuery & {
+    webhookId?: string;
+};
+type ReplayEventsResult = EventListResult & {
+    replayedDeliveries?: number;
+    replayedWebhookId?: string;
+};
+declare function createEventId(): string;
+declare function normalizeRetentionDays(value: number | undefined): number;
+declare function buildDomainEvent(input: CreateDomainEventInput): DomainEvent;
+declare function compareEventCursor(left: EventCursor, right: EventCursor): number;
+declare function encodeEventCursor(cursor: EventCursor): string;
+declare function decodeEventCursor(cursor: string | undefined): EventCursor | null;
+declare function isAfterCursor(event: Pick<DomainEvent, "timestamp" | "eventId">, cursor: EventCursor | null): boolean;
+declare function sortEventsByCursor<T extends Pick<DomainEvent, "timestamp" | "eventId">>(events: readonly T[]): T[];
+declare function inferActorType(args: {
+    sessionType?: "agent" | "user";
+    authMode?: string;
+    principalType?: string;
+}): DomainActorType;
+declare function emitDomainEvent(invokeMutation: (reference: any, args: CreateDomainEventInput) => Promise<unknown>, input: CreateDomainEventInput): Promise<unknown>;
+
+export { type CreateDomainEventInput, DOMAIN_EVENT_TYPES, DOMAIN_EVENT_VERSION, type DomainActorType, type DomainEvent, type DomainEventData, type DomainEventType, type DomainResourceType, EVENT_RETENTION_DEFAULT_DAYS, type EventCursor, type EventListQuery, type EventListResult, type ReplayEventsInput, type ReplayEventsResult, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_RETRY_DELAYS_MS, type WebhookCreateInput, type WebhookDeliveriesResult, type WebhookDeliveryAttemptRecord, type WebhookDeliveryRecord, type WebhookDeliveryStatus, type WebhookHealthResult, type WebhookRecord, type WebhookSecretMode, type WebhookTestResult, type WebhookUpdateInput, buildDomainEvent, compareEventCursor, createEventId, decodeEventCursor, emitDomainEvent, encodeEventCursor, inferActorType, isAfterCursor, normalizeRetentionDays, sortEventsByCursor };

package/dist/events.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.contract.js.map
+//# sourceMappingURL=events.contract.js.map

package/dist/events.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/events.contract.ts"],"names":[],"mappings":"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","file":"events.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"]}

package/dist/evidence/v1.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/evidence/v1.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=v1.js.map
+//# sourceMappingURL=v1.js.map

package/dist/evidence/v1.js.map

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

package/dist/gateway.contract.d.ts

@@ -0,0 +1,79 @@
+import { SessionPrincipalType, SessionAuthMode, SessionDelegationHop } from './auth.contract.js';
+import './convex-admin.contract.js';
+
+/**
+ * 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
+ */
+
+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";
+type GatewayScope = {
+    tenantId?: string;
+    workspaceId?: string;
+};
+type GatewayEnvironment = "sandbox" | "production";
+type GatewayAuthMode = "interactive_user" | "service_principal" | "tenant_api_key" | "session_token";
+type KeyLifecycleStatus = "active" | "rotating" | "rotated" | "expired" | "revoked";
+type CutoverDomain = "graph" | "schema" | "identity" | "policy" | "audit" | "admin" | "agent" | "tool" | "prompt" | "intelligence";
+type CutoverFlagState = "legacy" | "cutover" | "disabled";
+/**
+ * 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.
+ */
+type GatewayAuthContext = {
+    userId: string;
+    convexToken?: string;
+    /** Opaque in contract — narrowed to ConvexHttpClient at the gateway. */
+    convex: 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;
+};
+type GatewayErrorArgs = {
+    code: PlatformApiErrorCode;
+    message: string;
+    status: number;
+    correlationId: string;
+    policyTraceId?: string;
+    invariant?: string;
+    suggestion?: string;
+    details?: unknown;
+    headers?: HeadersInit;
+};
+type GatewaySuccessArgs = {
+    status?: number;
+    correlationId: string;
+    policyTraceId?: string;
+    idempotentReplay?: boolean;
+};
+declare function requireActorPrincipalId(authContext: GatewayAuthContext): string;
+
+export { type CutoverDomain, type CutoverFlagState, type GatewayAuthContext, type GatewayAuthMode, type GatewayEnvironment, type GatewayErrorArgs, type GatewayScope, type GatewaySuccessArgs, type KeyLifecycleStatus, type PlatformApiErrorCode, requireActorPrincipalId };

package/dist/gateway.contract.js

@@ -0,0 +1,12 @@
+// src/gateway.contract.ts
+function requireActorPrincipalId(authContext) {
+  const principalId = typeof authContext.principalId === "string" ? authContext.principalId.trim() : "";
+  if (principalId.length > 0) {
+    return principalId;
+  }
+  throw new Error("Access denied: federated principal context required.");
+}
+
+export { requireActorPrincipalId };
+//# sourceMappingURL=gateway.contract.js.map
+//# sourceMappingURL=gateway.contract.js.map

package/dist/gateway.contract.js.map

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

package/dist/graph/v1.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/graph/v1.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=v1.js.map
+//# sourceMappingURL=v1.js.map

package/dist/graph/v1.js.map

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

package/dist/ids.contract.d.ts

@@ -0,0 +1,9 @@
+type DecodedPrefixedId = {
+    prefix: string;
+    value: string;
+};
+declare function encodePrefixedId(prefix: string, value: string): string;
+declare function decodePrefixedId(id: string): DecodedPrefixedId;
+declare function hasPrefixedIdPrefix(id: string, prefix: string): boolean;
+
+export { type DecodedPrefixedId, decodePrefixedId, encodePrefixedId, hasPrefixedIdPrefix };