@lucern/sdk 0.2.0-alpha.6 → 0.2.0-alpha.8

package/dist/lucern/contracts/src/events.contract.d.ts

@@ -1,176 +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).
- */
-export declare const DOMAIN_EVENT_VERSION: "1.0";
-export declare const EVENT_RETENTION_DEFAULT_DAYS = 30;
-export declare const WEBHOOK_MAX_ATTEMPTS = 5;
-export declare const WEBHOOK_RETRY_DELAYS_MS: readonly [1000, 5000, 30000, 300000];
-export 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"];
-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;
-};
-export declare function createEventId(): string;
-export declare function normalizeRetentionDays(value: number | undefined): number;
-export declare function buildDomainEvent(input: CreateDomainEventInput): DomainEvent;
-export declare function compareEventCursor(left: EventCursor, right: EventCursor): number;
-export declare function encodeEventCursor(cursor: EventCursor): string;
-export declare function decodeEventCursor(cursor: string | undefined): EventCursor | null;
-export declare function isAfterCursor(event: Pick<DomainEvent, "timestamp" | "eventId">, cursor: EventCursor | null): boolean;
-export declare function sortEventsByCursor<T extends Pick<DomainEvent, "timestamp" | "eventId">>(events: readonly T[]): T[];
-export declare function inferActorType(args: {
-    sessionType?: "agent" | "user";
-    authMode?: string;
-    principalType?: string;
-}): DomainActorType;
-export declare function emitDomainEvent(invokeMutation: (reference: any, args: CreateDomainEventInput) => Promise<unknown>, input: CreateDomainEventInput): Promise<unknown>;

package/dist/lucern/contracts/src/events.contract.js

@@ -1,159 +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";
-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];
-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",
-];
-// =============================================================================
-// EVENT HELPERS
-// (Formerly the body of src/events.contract.ts)
-// =============================================================================
-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)));
-}
-export function createEventId() {
-    const random = crypto.randomUUID().replace(/-/g, "");
-    return `evt_${random}`;
-}
-export function normalizeRetentionDays(value) {
-    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) {
-    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, right) {
-    if (left.timestamp !== right.timestamp) {
-        return left.timestamp - right.timestamp;
-    }
-    return left.eventId.localeCompare(right.eventId);
-}
-export function encodeEventCursor(cursor) {
-    return toBase64(JSON.stringify(cursor));
-}
-export 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;
-    }
-}
-export function isAfterCursor(event, cursor) {
-    if (!cursor) {
-        return true;
-    }
-    return compareEventCursor(event, cursor) > 0;
-}
-export function sortEventsByCursor(events) {
-    return [...events].sort((left, right) => compareEventCursor(left, right));
-}
-export 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";
-}
-export async function emitDomainEvent(invokeMutation, input) {
-    return await invokeMutation("events:recordEvent", input);
-}

package/dist/lucern/contracts/src/gateway.contract.d.ts

@@ -1,74 +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";
-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";
-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";
-/**
- * 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;
-    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;
-};
-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 declare function requireActorPrincipalId(authContext: GatewayAuthContext): string;

package/dist/lucern/contracts/src/gateway.contract.js

@@ -1,19 +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
- */
-export 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.");
-}

package/dist/lucern/contracts/src/ids.contract.d.ts

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

package/dist/lucern/contracts/src/ids.contract.js

@@ -1,24 +0,0 @@
-const PREFIXED_ID_PATTERN = /^([a-z][a-z0-9]*)_(.+)$/;
-export function encodePrefixedId(prefix, value) {
-    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) {
-    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, prefix) {
-    const decoded = decodePrefixedId(id);
-    return decoded.prefix === prefix.trim();
-}

package/dist/lucern/contracts/src/index.d.ts

@@ -1,29 +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";

package/dist/lucern/contracts/src/index.js

@@ -1,29 +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.js";
-export * from "./auth-session.contract.js";
-export * from "./auth-context.contract.js";
-export * from "./convex-admin.contract.js";
-export * from "./gateway.contract.js";
-export * from "./context-pack.contract.js";
-export * from "./events.contract.js";
-export * from "./events-types.contract.js";
-export * from "./ids.contract.js";
-export * as mcpToolsContract from "./mcp-tools.contract.js";
-export * from "./ontology-matching.contract.js";
-export * from "./prompt.contract.js";
-export * from "./sdk-methods.contract.js";
-export * as sdkToolsContract from "./sdk-tools.contract.js";
-export * from "./text-matching.contract.js";
-export * from "./topic-scope.contract.js";
-export * from "./workflow-runtime.contract.js";

package/dist/lucern/contracts/src/lens-filter.contract.js

@@ -1,95 +0,0 @@
-/**
- * Lens Filter Criteria Contract
- *
- * Version-discriminated filter DSL for lenses. Each filter criteria document
- * carries a `version` and `kind` discriminator so future shapes can coexist
- * without schema migrations. The Convex `filterCriteria` field remains v.any()
- * — all type enforcement happens here at the TypeScript contract layer.
- *
- * Forward-compatibility guarantees:
- * - `version` field: new versions add fields, never remove or rename existing ones
- * - `kind` field: new filter kinds (temporal, confidence-range) can be added
- *   without touching taxonomy code paths
- * - `entityTypeFilters` array items are open to extension in future versions
- * - Resolution logic switches on `version` + `kind` to select the right resolver
- *
- * @module lucern/contracts/src/lens-filter
- */
-// Future: | TemporalFilterCriteriaV1 | ConfidenceRangeFilterCriteriaV1 | ...
-// ---------------------------------------------------------------------------
-// Type guards
-// ---------------------------------------------------------------------------
-export function isLensFilterCriteria(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const obj = value;
-    return typeof obj.version === "number" && typeof obj.kind === "string";
-}
-export function isTaxonomyFilterCriteriaV1(value) {
-    if (!isLensFilterCriteria(value))
-        return false;
-    return value.version === 1 && value.kind === "taxonomy";
-}
-/**
- * Validate a filter criteria document at the contract layer.
- * This runs before persisting to Convex.
- */
-export function validateFilterCriteria(value) {
-    if (value === undefined || value === null) {
-        return { valid: true }; // filterCriteria is optional
-    }
-    if (!isLensFilterCriteria(value)) {
-        return {
-            valid: false,
-            errors: [
-                'filterCriteria must have numeric "version" and string "kind" fields',
-            ],
-        };
-    }
-    if (isTaxonomyFilterCriteriaV1(value)) {
-        return validateTaxonomyFilterV1(value);
-    }
-    // Cast to access properties — TypeScript narrows to `never` when all union
-    // members are exhausted, but at runtime unknown version/kind combos are possible.
-    const raw = value;
-    return {
-        valid: false,
-        errors: [
-            `Unsupported filter criteria: version=${raw.version}, kind=${raw.kind}`,
-        ],
-    };
-}
-function validateTaxonomyFilterV1(criteria) {
-    const errors = [];
-    if (!Array.isArray(criteria.entityTypeFilters)) {
-        errors.push("entityTypeFilters must be an array");
-        return { valid: false, errors };
-    }
-    if (criteria.entityTypeFilters.length === 0) {
-        errors.push("entityTypeFilters must contain at least one entry");
-        return { valid: false, errors };
-    }
-    for (let i = 0; i < criteria.entityTypeFilters.length; i++) {
-        const filter = criteria.entityTypeFilters[i];
-        if (!filter || typeof filter.entityTypeValue !== "string") {
-            errors.push(`entityTypeFilters[${i}].entityTypeValue must be a non-empty string`);
-            continue;
-        }
-        if (filter.entityTypeValue.trim().length === 0) {
-            errors.push(`entityTypeFilters[${i}].entityTypeValue must be a non-empty string`);
-        }
-        if (filter.subtypeValues !== undefined &&
-            !Array.isArray(filter.subtypeValues)) {
-            errors.push(`entityTypeFilters[${i}].subtypeValues must be an array`);
-        }
-    }
-    if (criteria.ontologyScope !== undefined) {
-        if (typeof criteria.ontologyScope !== "object" ||
-            criteria.ontologyScope === null) {
-            errors.push("ontologyScope must be an object");
-        }
-    }
-    return errors.length === 0
-        ? { valid: true }
-        : { valid: false, errors };
-}