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

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

@@ -0,0 +1,133 @@
+export type ContextRankingProfile = "baseline_v1" | "hybrid_v1" | "weighted_v1";
+export type ContextCompilationMode = "standard" | "delta";
+export type ContextPackSectionKey = "invariants" | "activeBeliefs" | "openQuestions" | "recentEvidence" | "contradictions";
+export type RankingWeightVector = {
+    query: number;
+    recency: number;
+    confidence?: number;
+    beliefType?: number;
+    priority?: number;
+    severity?: number;
+};
+export type PackWeightOverride = {
+    section: ContextPackSectionKey;
+    weights: Partial<RankingWeightVector>;
+};
+export type CompileContextInput = {
+    query?: string;
+    budget?: number;
+    ranking?: ContextRankingProfile;
+    limit?: number;
+    maxDepth?: number;
+    includeEntities?: boolean;
+    mode?: ContextCompilationMode;
+    includeFailures?: boolean;
+    worktreeId?: string;
+    sessionId?: string;
+    packWeightOverrides?: PackWeightOverride[];
+    tokenBudget?: number;
+    rankingProfile?: ContextRankingProfile;
+};
+export type PublicContextBelief = {
+    beliefId: string;
+    text: string;
+    confidence: number | null;
+    beliefType?: string | null;
+    status?: string;
+    updatedAt?: number | null;
+    score: number;
+    justification?: string;
+};
+export type PublicContextQuestion = {
+    questionId: string;
+    text: string;
+    status: string;
+    priority: string;
+    updatedAt?: number | null;
+    score: number;
+    justification?: string;
+};
+export type PublicContextEvidence = {
+    evidenceId: string;
+    text: string;
+    sourceUrl?: string | null;
+    kind: string;
+    createdAt?: number | null;
+    score: number;
+    justification?: string;
+};
+export type PublicContextContradiction = {
+    contradictionId: string;
+    severity: string;
+    status: string;
+    description: string;
+    score: number;
+    justification?: string;
+};
+export type PublicContextEntity = {
+    entityId: string;
+    entityType: string;
+    title: string;
+    text?: string;
+    connectedBeliefCount: number;
+    connectedEvidenceCount: number;
+    score: number;
+    metadata?: Record<string, unknown>;
+};
+export type PublicContextInjectionPolicy = {
+    tokenBudget: number;
+    estimatedTokens: number;
+    sectionBudgets: Record<string, number>;
+    sectionUsage: Record<string, number>;
+    selected: Record<string, string[]>;
+    excludedItems?: Array<{
+        id: string;
+        section: string;
+        reason: "budget_exceeded" | "anti_repetition" | "below_threshold";
+        score: number;
+    }>;
+};
+export type PublicCompiledContext = {
+    schemaVersion: string;
+    topicId: string;
+    topicName: string;
+    scopedTopicIds: string[];
+    generatedAt: number;
+    ranking: ContextRankingProfile;
+    summary: Record<string, unknown>;
+    invariants: PublicContextBelief[];
+    activeBeliefs: PublicContextBelief[];
+    openQuestions: PublicContextQuestion[];
+    recentEvidence: PublicContextEvidence[];
+    contradictions: PublicContextContradiction[];
+    relatedEntities?: PublicContextEntity[];
+    contextNarrative: string[];
+    injectionPolicy: PublicContextInjectionPolicy;
+    diagnostics: Record<string, unknown>;
+    compilationMode?: string;
+    failureContext?: {
+        failures: Array<{
+            attemptId: string;
+            approach: string;
+            outcome: string;
+            recordedAt: number;
+            score: number;
+        }>;
+        suppressedIds: string[];
+    };
+    deltaReport?: {
+        changedItems: Array<{
+            id: string;
+            section: string;
+            changeType: string;
+            summary: string;
+        }>;
+        verificationObligations: Array<{
+            description: string;
+            source: string;
+            severity: "critical" | "high" | "medium" | "low";
+        }>;
+        referencePoint: string;
+    };
+    appliedWeightOverrides?: unknown[];
+};

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

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

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

@@ -1,13 +1,24 @@
+/** All recognized control object kinds in the ownership model. */
 export declare const CONTROL_OBJECT_KINDS: readonly ["tenant", "workspace", "principal", "tool", "pack", "ontology", "belief", "policy_rule"];
+/** A kind of control object (tenant, workspace, principal, tool, etc.). */
 export type ControlObjectKind = (typeof CONTROL_OBJECT_KINDS)[number];
+/** Canonical ownership scopes: platform, tenant, workspace, or resource. */
 export declare const CONTROL_OBJECT_OWNER_SCOPES: readonly ["platform", "tenant", "workspace", "resource"];
+/** The scope level that canonically owns a control object. */
 export type ControlObjectOwnerScope = (typeof CONTROL_OBJECT_OWNER_SCOPES)[number];
+/** UI surfaces authorized to edit control objects. */
 export declare const CONTROL_OBJECT_EDIT_SURFACES: readonly ["platform_admin", "tenant_admin", "workspace_admin", "graph_worktree"];
+/** A UI surface authorized to mutate a control object (platform admin, tenant admin, etc.). */
 export type ControlObjectEditSurface = (typeof CONTROL_OBJECT_EDIT_SURFACES)[number];
+/** Rules governing how control object configuration flows through the scope hierarchy. */
 export declare const CONTROL_OBJECT_INHERITANCE_RULES: readonly ["none", "platform_seed_to_tenant", "tenant_default_to_workspace", "workspace_narrowing_only", "pack_overlay_to_tenant", "topic_lineage_to_resource"];
+/** How a control object's configuration propagates through scope hierarchy. */
 export type ControlObjectInheritanceRule = (typeof CONTROL_OBJECT_INHERITANCE_RULES)[number];
+/** Scope of impact when a control object is modified. */
 export declare const CONTROL_OBJECT_BLAST_RADII: readonly ["platform", "tenant", "workspace", "resource"];
+/** The furthest scope impacted by a mutation to a control object. */
 export type ControlObjectBlastRadius = (typeof CONTROL_OBJECT_BLAST_RADII)[number];
+/** A single row in the ownership matrix describing who owns, edits, and inherits a control object. */
 export type ControlObjectOwnershipCase = {
     caseKey: string;
     caseLabel: string;
@@ -17,7 +28,9 @@ export type ControlObjectOwnershipCase = {
     inheritanceRule: ControlObjectInheritanceRule;
     blastRadius: ControlObjectBlastRadius;
 };
+/** Full ownership matrix keyed by control object kind. */
 export type ControlObjectOwnershipMatrix = Record<ControlObjectKind, readonly ControlObjectOwnershipCase[]>;
+/** Versioned ownership contract bundling all enums, the matrix, and flattened rows. */
 export type ControlObjectOwnershipContract = {
     version: "1.0.0";
     kinds: readonly ControlObjectKind[];
@@ -28,6 +41,7 @@ export type ControlObjectOwnershipContract = {
     matrix: ControlObjectOwnershipMatrix;
     rows: readonly ControlObjectOwnershipCase[];
 };
+/** Static ownership matrix mapping each control object kind to its ownership cases. */
 export declare const CONTROL_OBJECT_OWNERSHIP_MATRIX: {
     readonly tenant: readonly [{
         readonly caseKey: "platform-record";
@@ -150,6 +164,7 @@ export declare const CONTROL_OBJECT_OWNERSHIP_MATRIX: {
         readonly blastRadius: "workspace";
     }];
 };
+/** Flattened array of all ownership cases across all control object kinds. */
 export declare const CONTROL_OBJECT_OWNERSHIP_ROWS: readonly ControlObjectOwnershipCase[];
 /** The canonical ownership contract exposed by the SDK. */
 export declare const CONTROL_OBJECT_OWNERSHIP_CONTRACT: {

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

@@ -0,0 +1,220 @@
+/** All recognized control object kinds in the ownership model. */
+export const CONTROL_OBJECT_KINDS = [
+    "tenant",
+    "workspace",
+    "principal",
+    "tool",
+    "pack",
+    "ontology",
+    "belief",
+    "policy_rule",
+];
+/** Canonical ownership scopes: platform, tenant, workspace, or resource. */
+export const CONTROL_OBJECT_OWNER_SCOPES = [
+    "platform",
+    "tenant",
+    "workspace",
+    "resource",
+];
+/** UI surfaces authorized to edit control objects. */
+export const CONTROL_OBJECT_EDIT_SURFACES = [
+    "platform_admin",
+    "tenant_admin",
+    "workspace_admin",
+    "graph_worktree",
+];
+/** Rules governing how control object configuration flows through the scope hierarchy. */
+export const CONTROL_OBJECT_INHERITANCE_RULES = [
+    "none",
+    "platform_seed_to_tenant",
+    "tenant_default_to_workspace",
+    "workspace_narrowing_only",
+    "pack_overlay_to_tenant",
+    "topic_lineage_to_resource",
+];
+/** Scope of impact when a control object is modified. */
+export const CONTROL_OBJECT_BLAST_RADII = [
+    "platform",
+    "tenant",
+    "workspace",
+    "resource",
+];
+function defineCases(cases) {
+    return cases;
+}
+/** Static ownership matrix mapping each control object kind to its ownership cases. */
+export const CONTROL_OBJECT_OWNERSHIP_MATRIX = {
+    tenant: defineCases([
+        {
+            caseKey: "platform-record",
+            caseLabel: "Platform Record",
+            kind: "tenant",
+            canonicalOwnerScope: "platform",
+            editSurface: "platform_admin",
+            inheritanceRule: "none",
+            blastRadius: "tenant",
+        },
+    ]),
+    workspace: defineCases([
+        {
+            caseKey: "tenant-workspace",
+            caseLabel: "Tenant Workspace",
+            kind: "workspace",
+            canonicalOwnerScope: "tenant",
+            editSurface: "tenant_admin",
+            inheritanceRule: "tenant_default_to_workspace",
+            blastRadius: "workspace",
+        },
+    ]),
+    principal: defineCases([
+        {
+            caseKey: "tenant-principal",
+            caseLabel: "Tenant Principal",
+            kind: "principal",
+            canonicalOwnerScope: "tenant",
+            editSurface: "tenant_admin",
+            inheritanceRule: "workspace_narrowing_only",
+            blastRadius: "resource",
+        },
+    ]),
+    tool: defineCases([
+        {
+            caseKey: "platform-core",
+            caseLabel: "Platform Core",
+            kind: "tool",
+            canonicalOwnerScope: "platform",
+            editSurface: "platform_admin",
+            inheritanceRule: "platform_seed_to_tenant",
+            blastRadius: "platform",
+        },
+        {
+            caseKey: "tenant-custom",
+            caseLabel: "Tenant Custom",
+            kind: "tool",
+            canonicalOwnerScope: "tenant",
+            editSurface: "tenant_admin",
+            inheritanceRule: "tenant_default_to_workspace",
+            blastRadius: "tenant",
+        },
+    ]),
+    pack: defineCases([
+        {
+            caseKey: "platform-definition",
+            caseLabel: "Platform Definition",
+            kind: "pack",
+            canonicalOwnerScope: "platform",
+            editSurface: "platform_admin",
+            inheritanceRule: "platform_seed_to_tenant",
+            blastRadius: "platform",
+        },
+        {
+            caseKey: "tenant-installation",
+            caseLabel: "Tenant Installation",
+            kind: "pack",
+            canonicalOwnerScope: "tenant",
+            editSurface: "tenant_admin",
+            inheritanceRule: "platform_seed_to_tenant",
+            blastRadius: "tenant",
+        },
+    ]),
+    ontology: defineCases([
+        {
+            caseKey: "platform-base",
+            caseLabel: "Platform Base",
+            kind: "ontology",
+            canonicalOwnerScope: "platform",
+            editSurface: "platform_admin",
+            inheritanceRule: "platform_seed_to_tenant",
+            blastRadius: "platform",
+        },
+        {
+            caseKey: "pack-overlay",
+            caseLabel: "Pack Overlay",
+            kind: "ontology",
+            canonicalOwnerScope: "platform",
+            editSurface: "platform_admin",
+            inheritanceRule: "pack_overlay_to_tenant",
+            blastRadius: "platform",
+        },
+        {
+            caseKey: "tenant-extension",
+            caseLabel: "Tenant Extension",
+            kind: "ontology",
+            canonicalOwnerScope: "tenant",
+            editSurface: "tenant_admin",
+            inheritanceRule: "topic_lineage_to_resource",
+            blastRadius: "tenant",
+        },
+    ]),
+    belief: defineCases([
+        {
+            caseKey: "topic-resource",
+            caseLabel: "Topic Resource",
+            kind: "belief",
+            canonicalOwnerScope: "resource",
+            editSurface: "graph_worktree",
+            inheritanceRule: "topic_lineage_to_resource",
+            blastRadius: "resource",
+        },
+    ]),
+    policy_rule: defineCases([
+        {
+            caseKey: "platform-baseline",
+            caseLabel: "Platform Baseline",
+            kind: "policy_rule",
+            canonicalOwnerScope: "platform",
+            editSurface: "platform_admin",
+            inheritanceRule: "platform_seed_to_tenant",
+            blastRadius: "platform",
+        },
+        {
+            caseKey: "tenant-bundle",
+            caseLabel: "Tenant Bundle",
+            kind: "policy_rule",
+            canonicalOwnerScope: "tenant",
+            editSurface: "tenant_admin",
+            inheritanceRule: "tenant_default_to_workspace",
+            blastRadius: "tenant",
+        },
+        {
+            caseKey: "workspace-override",
+            caseLabel: "Workspace Override",
+            kind: "policy_rule",
+            canonicalOwnerScope: "workspace",
+            editSurface: "workspace_admin",
+            inheritanceRule: "none",
+            blastRadius: "workspace",
+        },
+    ]),
+};
+function flattenOwnershipMatrix(matrix) {
+    return CONTROL_OBJECT_KINDS.flatMap((kind) => [...matrix[kind]]);
+}
+/** Flattened array of all ownership cases across all control object kinds. */
+export const CONTROL_OBJECT_OWNERSHIP_ROWS = Object.freeze(flattenOwnershipMatrix(CONTROL_OBJECT_OWNERSHIP_MATRIX));
+/** The canonical ownership contract exposed by the SDK. */
+export const CONTROL_OBJECT_OWNERSHIP_CONTRACT = {
+    version: "1.0.0",
+    kinds: CONTROL_OBJECT_KINDS,
+    ownerScopes: CONTROL_OBJECT_OWNER_SCOPES,
+    editSurfaces: CONTROL_OBJECT_EDIT_SURFACES,
+    inheritanceRules: CONTROL_OBJECT_INHERITANCE_RULES,
+    blastRadii: CONTROL_OBJECT_BLAST_RADII,
+    matrix: CONTROL_OBJECT_OWNERSHIP_MATRIX,
+    rows: CONTROL_OBJECT_OWNERSHIP_ROWS,
+};
+/**
+ * List ownership cases for one control-object kind or the full matrix.
+ */
+export function listControlObjectOwnershipCases(kind) {
+    if (!kind) {
+        return CONTROL_OBJECT_OWNERSHIP_ROWS;
+    }
+    return CONTROL_OBJECT_OWNERSHIP_MATRIX[kind];
+}
+/**
+ * Get a specific ownership case by kind and case key.
+ */
+export function getControlObjectOwnershipCase(kind, caseKey) {
+    return CONTROL_OBJECT_OWNERSHIP_MATRIX[kind].find((ownershipCase) => ownershipCase.caseKey === caseKey);
+}

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

@@ -1,8 +1,10 @@
 import type { JsonObject, JsonValue } from "./types";
+/** Tenant and workspace identifiers used to scope gateway requests. */
 export type GatewayScope = {
     tenantId?: string;
     workspaceId?: string;
 };
+/** Successful response envelope from the platform gateway with correlation metadata. */
 export type PlatformGatewaySuccess<T> = {
     success: true;
     data: T;
@@ -10,6 +12,7 @@ export type PlatformGatewaySuccess<T> = {
     policyTraceId: string | null;
     idempotentReplay: boolean;
 };
+/** Failed response envelope with structured error codes and optional invariant references. */
 export type PlatformGatewayFailure = {
     success: false;
     /**
@@ -33,7 +36,14 @@ export type PlatformGatewayFailure = {
     correlationId: string;
     policyTraceId: string | null;
 };
+/** Discriminated union of success and failure gateway responses. */
 export type PlatformGatewayEnvelope<T> = PlatformGatewaySuccess<T> | PlatformGatewayFailure;
+/**
+ * Structured error thrown when a platform API request fails.
+ *
+ * Includes HTTP status, machine-readable error code, optional invariant
+ * reference, and actionable suggestions for common failure modes.
+ */
 export declare class LucernApiError extends Error {
     readonly code: string;
     readonly status: number;
@@ -55,8 +65,10 @@ export declare class LucernApiError extends Error {
         policyTraceId?: string | null;
     });
 }
+/** Supported HTTP methods for gateway requests. */
 export type GatewayHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/** Context passed to the `onRequest` hook before each gateway request attempt. */
 export type GatewayRequestHookContext = {
     requestId: string;
     attempt: number;
@@ -68,6 +80,7 @@ export type GatewayRequestHookContext = {
     body?: string;
     timeoutMs: number;
 };
+/** Context passed to the `onResponse` hook after each gateway request attempt (including retries and failures). */
 export type GatewayResponseHookContext = GatewayRequestHookContext & {
     durationMs: number;
     status?: number;
@@ -79,6 +92,12 @@ export type GatewayResponseHookContext = GatewayRequestHookContext & {
     retryAfterMs?: number | null;
     willRetry: boolean;
 };
+/**
+ * Low-level transport configuration for the platform gateway client.
+ *
+ * Most developers should use {@link createLucernClient} instead, which wraps
+ * this config with higher-level conveniences like `apiKey` and `environment`.
+ */
 export type GatewayClientConfig = {
     baseUrl?: string;
     fetchImpl?: FetchLike;