@lucern/sdk 0.2.0-alpha.3 → 0.2.0-alpha.5

package/dist/{packages/sdk/src → lib/platform/sdk}/decisionsClient.d.ts

@@ -3,7 +3,9 @@ import type { GetJudgmentResponse, JudgmentCalibrationResponse, JudgmentReadines
 export { LucernApiError };
 export type { PlatformGatewaySuccess } from "./coreClient";
 export type { GetJudgmentResponse, JudgmentCalibrationResponse, JudgmentReadinessResponse, JudgmentTransitionAuditIntegrityResponse, ListJudgmentsResponse, PendingJudgmentOutcomeReviewResponse, RecordJudgmentOutcomeResponse, RecordJudgmentResponse, } from "./types";
+/** Configuration for the decisions client. */
 export type DecisionsClientConfig = GatewayClientConfig;
+/** Input for recording a new judgment (irreversible decision commitment). */
 export type RecordJudgmentInput = {
     title: string;
     summary?: string;
@@ -23,22 +25,27 @@ export type RecordJudgmentInput = {
     terms?: string;
     themeIds?: string[];
 } & TopicIdentifierInput;
+/** Filter parameters for listing judgments within a topic scope. */
 export type ListJudgmentsInput = {
     topicId?: string;
     includeArchived?: boolean;
     limit?: number;
 } & TopicIdentifierInput;
+/** Input for recording the real-world outcome of a judgment. */
 export type RecordJudgmentOutcomeInput = {
     outcome: "pending" | "successful" | "unsuccessful" | "mixed" | "unknown" | "too_early";
     outcomeNotes?: string;
     notes?: string;
 };
+/** Input for retrieving judgment calibration analytics. */
 export type GetJudgmentCalibrationInput = {
     topicId?: string;
 } & TopicIdentifierInput;
+/** Input for listing judgments still awaiting outcome review. */
 export type ListPendingJudgmentOutcomeReviewInput = {
     topicId?: string;
 } & TopicIdentifierInput;
+/** Input for checking audit integrity of judgment state transitions. */
 export type GetJudgmentTransitionAuditIntegrityInput = {
     topicId?: string;
     judgmentId?: string;
@@ -46,6 +53,8 @@ export type GetJudgmentTransitionAuditIntegrityInput = {
 } & TopicIdentifierInput;
 /**
  * Create the judgments client for decision lifecycle operations.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to manage judgments, outcomes, readiness, and calibration.
  */
 export declare function createDecisionsClient(config?: DecisionsClientConfig): {
     /**

package/dist/lib/platform/sdk/decisionsClient.js

@@ -0,0 +1,129 @@
+import { createGatewayRequestClient, LucernApiError, randomIdempotencyKey, toQueryString, } from "./coreClient.js";
+import { createListResult, mapGatewayData, normalizeTopicQuery, withTopicAlias, } from "./sdkSurface.js";
+export { LucernApiError };
+/**
+ * Create the judgments client for decision lifecycle operations.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to manage judgments, outcomes, readiness, and calibration.
+ */
+export function createDecisionsClient(config = {}) {
+    const gateway = createGatewayRequestClient(config);
+    return {
+        /**
+         * List judgments for a topic scope.
+         */
+        async listJudgments(query) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/judgments${toQueryString({
+                    ...normalizeTopicQuery(query),
+                    includeArchived: typeof query.includeArchived === "boolean"
+                        ? query.includeArchived
+                            ? "true"
+                            : "false"
+                        : undefined,
+                    limit: query.limit,
+                })}`,
+            }).then((response) => mapGatewayData(response, (data) => {
+                const rows = Array.isArray(data) ? data : [];
+                const judgments = rows.map((row) => withTopicAlias(row));
+                return {
+                    ...createListResult(judgments, "judgments"),
+                };
+            }));
+        },
+        /**
+         * Get a single judgment by identifier.
+         */
+        async getJudgment(judgmentId) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/judgments/${encodeURIComponent(judgmentId)}`,
+            }).then((response) => mapGatewayData(response, (data) => data && typeof data === "object"
+                ? withTopicAlias(data)
+                : data));
+        },
+        /**
+         * Get readiness signals for creating a judgment.
+         */
+        async getJudgmentReadiness(query) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/judgments/readiness${toQueryString(normalizeTopicQuery(query))}`,
+            });
+        },
+        /**
+         * Get calibration analytics for judgment outcomes.
+         */
+        async getJudgmentCalibration(query) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/judgments/calibration${toQueryString(normalizeTopicQuery(query))}`,
+            });
+        },
+        /**
+         * List judgments still awaiting outcome review.
+         */
+        async listPendingOutcomeReviews(query) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/judgments/pending-outcome-review${toQueryString(normalizeTopicQuery(query))}`,
+            }).then((response) => mapGatewayData(response, (data) => {
+                const rows = Array.isArray(data) ? data : [];
+                const reviews = rows.map((row) => withTopicAlias(row));
+                return createListResult(reviews, "reviews");
+            }));
+        },
+        /**
+         * @deprecated Use listPendingOutcomeReviews.
+         */
+        async listPendingJudgmentOutcomeReview(query) {
+            return this.listPendingOutcomeReviews(query);
+        },
+        /**
+         * Get audit integrity checks for judgment transitions.
+         */
+        async getJudgmentTransitionAuditIntegrity(query) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/judgments/transition-audit-integrity${toQueryString({
+                    ...normalizeTopicQuery(query),
+                    judgmentId: query.judgmentId,
+                    includePassing: typeof query.includePassing === "boolean"
+                        ? query.includePassing
+                            ? "true"
+                            : "false"
+                        : undefined,
+                })}`,
+            });
+        },
+        /**
+         * Create a judgment.
+         */
+        async createJudgment(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/graph/judgments",
+                method: "POST",
+                body: normalizeTopicQuery(input),
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            }).then((response) => mapGatewayData(response, (data) => withTopicAlias(data)));
+        },
+        /**
+         * @deprecated Use createJudgment.
+         */
+        async recordJudgment(input, idempotencyKey) {
+            return this.createJudgment(input, idempotencyKey);
+        },
+        /**
+         * Update the outcome for an existing judgment.
+         */
+        async updateJudgmentOutcome(judgmentId, input, idempotencyKey) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/judgments/${encodeURIComponent(judgmentId)}/outcome`,
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * @deprecated Use updateJudgmentOutcome.
+         */
+        async recordJudgmentOutcome(judgmentId, input, idempotencyKey) {
+            return this.updateJudgmentOutcome(judgmentId, input, idempotencyKey);
+        },
+    };
+}

package/dist/lib/platform/sdk/domainContext.d.ts

@@ -0,0 +1 @@
+export type { CompileContextInput, ContextCompilationMode, ContextPackSectionKey, ContextRankingProfile, PackWeightOverride, PublicCompiledContext, PublicContextBelief, PublicContextContradiction, PublicContextEntity, PublicContextEvidence, PublicContextInjectionPolicy, PublicContextQuestion, RankingWeightVector, } from "./contextTypes";

package/dist/lib/platform/sdk/domainContext.js

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

package/dist/{lucern/packages/events/src/types.d.ts → lib/platform/sdk/events.d.ts}

@@ -149,3 +149,28 @@ export type ReplayEventsResult = EventListResult & {
     replayedDeliveries?: number;
     replayedWebhookId?: string;
 };
+export declare function eventPatternToRegExp(pattern: string): RegExp;
+export declare function matchesEventPattern(eventType: string, pattern: string): boolean;
+export declare function matchesAnyEventPattern(eventType: string, patterns: readonly string[]): boolean;
+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>;
+export declare function assertValidWebhookUrl(url: string): string;
+export declare function normalizeWebhookPatterns(patterns: readonly string[]): string[];
+export declare function assertValidWebhookSecret(secret: string): string;
+export declare function computeWebhookSignature(payload: string, secret: string): Promise<string>;
+export declare function nextDeliveryAttemptAt(currentAttemptCount: number, now?: number): number | undefined;
+export declare function resolveDeliveryFailureStatus(attemptCount: number): WebhookDeliveryStatus;
+export declare function sanitizeWebhookRecord(value: Record<string, unknown>): WebhookRecord;
+export declare function truncateWebhookResponseBody(responseBody: string | undefined, maxLength?: number): string | undefined;

package/dist/lib/platform/sdk/events.js

@@ -0,0 +1,261 @@
+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",
+];
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function eventPatternToRegExp(pattern) {
+    const normalized = pattern.trim();
+    if (!normalized) {
+        return /^$/;
+    }
+    if (normalized === "*") {
+        return /^.*$/;
+    }
+    const source = escapeRegex(normalized).replace(/\\\*/g, ".*");
+    return new RegExp(`^${source}$`);
+}
+export function matchesEventPattern(eventType, pattern) {
+    return eventPatternToRegExp(pattern).test(eventType.trim());
+}
+export function matchesAnyEventPattern(eventType, patterns) {
+    if (patterns.length === 0) {
+        return true;
+    }
+    return patterns.some((pattern) => matchesEventPattern(eventType, pattern));
+}
+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 = typeof globalThis.crypto?.randomUUID === "function"
+        ? globalThis.crypto.randomUUID().replace(/-/g, "")
+        : Array.from(typeof globalThis.crypto?.getRandomValues === "function"
+            ? globalThis.crypto.getRandomValues(new Uint8Array(16))
+            : Array.from({ length: 16 }, () => Math.floor(Math.random() * 256)), (value) => value.toString(16).padStart(2, "0")).join("");
+    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);
+}
+const LOCALHOST_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+function normalizeUrl(url) {
+    try {
+        return new URL(url.trim());
+    }
+    catch {
+        throw new Error("Webhook URL must be a valid absolute URL.");
+    }
+}
+export function assertValidWebhookUrl(url) {
+    const parsed = normalizeUrl(url);
+    const hostname = parsed.hostname.trim().toLowerCase();
+    const nodeEnv = typeof process !== "undefined" ? process.env?.NODE_ENV : undefined;
+    const allowLocalHttp = nodeEnv === "test" || LOCALHOST_HOSTS.has(hostname);
+    if (parsed.protocol !== "https:" && !(allowLocalHttp && parsed.protocol === "http:")) {
+        throw new Error("Webhook URL must use HTTPS.");
+    }
+    return parsed.toString();
+}
+export function normalizeWebhookPatterns(patterns) {
+    const normalized = Array.from(new Set(patterns
+        .map((pattern) => pattern.trim())
+        .filter((pattern) => pattern.length > 0)));
+    if (normalized.length === 0) {
+        throw new Error("At least one webhook event pattern is required.");
+    }
+    return normalized;
+}
+export function assertValidWebhookSecret(secret) {
+    const normalized = secret.trim();
+    if (normalized.length < 8) {
+        throw new Error("Webhook secret must be at least 8 characters.");
+    }
+    return normalized;
+}
+export async function computeWebhookSignature(payload, secret) {
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+    return Array.from(new Uint8Array(signature))
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+export function nextDeliveryAttemptAt(currentAttemptCount, now = Date.now()) {
+    if (currentAttemptCount >= WEBHOOK_MAX_ATTEMPTS) {
+        return undefined;
+    }
+    const retryIndex = currentAttemptCount - 1;
+    const delay = WEBHOOK_RETRY_DELAYS_MS[retryIndex];
+    return typeof delay === "number" ? now + delay : undefined;
+}
+export function resolveDeliveryFailureStatus(attemptCount) {
+    return attemptCount >= WEBHOOK_MAX_ATTEMPTS ? "dead_letter" : "failed";
+}
+export function sanitizeWebhookRecord(value) {
+    return {
+        id: String(value.id ?? value.webhookId ?? value._id ?? ""),
+        webhookId: String(value.webhookId ?? value.id ?? value._id ?? ""),
+        tenantId: typeof value.tenantId === "string" && value.tenantId.trim().length > 0
+            ? value.tenantId
+            : undefined,
+        workspaceId: typeof value.workspaceId === "string" && value.workspaceId.trim().length > 0
+            ? value.workspaceId
+            : undefined,
+        topicId: typeof value.topicId === "string" && value.topicId.trim().length > 0
+            ? value.topicId
+            : undefined,
+        url: String(value.url ?? ""),
+        events: Array.isArray(value.events)
+            ? value.events
+                .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+                .filter(Boolean)
+            : [],
+        active: value.active !== false,
+        secretConfigured: true,
+        createdAt: Number(value.createdAt ?? Date.now()),
+        updatedAt: Number(value.updatedAt ?? value.createdAt ?? Date.now()),
+        createdBy: String(value.createdBy ?? ""),
+        updatedBy: String(value.updatedBy ?? value.createdBy ?? ""),
+        lastDeliveryAt: typeof value.lastDeliveryAt === "number" ? value.lastDeliveryAt : undefined,
+        lastSuccessfulDeliveryAt: typeof value.lastSuccessfulDeliveryAt === "number"
+            ? value.lastSuccessfulDeliveryAt
+            : undefined,
+    };
+}
+export function truncateWebhookResponseBody(responseBody, maxLength = 2_000) {
+    if (!responseBody) {
+        return undefined;
+    }
+    if (responseBody.length <= maxLength) {
+        return responseBody;
+    }
+    return `${responseBody.slice(0, maxLength - 3)}...`;
+}