@lucern/sdk 1.0.18 → 1.0.20

package/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to `@lucern/sdk` will be documented in this file.
 ## [Unreleased]
 - No unreleased changes yet.
 
+## [1.0.20] - 2026-06-05
+- Release notes pending.
+
+## [1.0.19] - 2026-06-04
+- Release notes pending.
+
 ## [1.0.18] - 2026-06-02
 - Release notes pending.
 

package/dist/beliefsClient.d.ts

@@ -29,16 +29,14 @@ export declare function mapOpinionHistoryEntriesFromGatewayData(payload: Gateway
  *
  * Use `text` as the canonical belief statement.
  * `canonicalText` remains available as a legacy alias for backwards compatibility.
+ * `topicGlobalId` is a required UUIDv7 topic epistemic-node globalId; SDK
+ * creation no longer translates `topicId` or `topicNodeId` into a write anchor.
  * Beliefs start as drafts with a vacuous prior `(0, 0, 1, a)`. When omitted,
  * `baseRate` defaults to the canonical neutral prior `0.5`.
  */
 export type CreateBeliefInput = {
-    /** Required topic epistemicNodes globalId. */
-    topicGlobalId?: string;
-    /** Optional internal epistemicNodes _id for the topic anchor. */
-    topicNodeId?: string;
-    /** @deprecated Use topicGlobalId. Must identify a topic epistemicNode, not a legacy topics-table row. */
-    topicId?: string;
+    /** Required UUIDv7 topic epistemicNodes globalId. */
+    topicGlobalId: string;
     /** Preferred belief statement alias. */
     text?: string;
     /** @deprecated Use text. */

package/dist/beliefsClient.js

@@ -1,5 +1,6 @@
 import { createGatewayRequestClient, LucernApiError, randomIdempotencyKey, } from "./coreClient.js";
 import { normalizeNodeWriteInput } from "./sdkSurface.js";
+import { isUuidV7 } from "@lucern/contracts/ids";
 export { LucernApiError };
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -101,6 +102,21 @@ export function createBeliefsClient(config = {}) {
         }
         return normalized;
     }
+    function normalizeCreateBeliefInput(input) {
+        const topicGlobalId = readString(input.topicGlobalId);
+        if (!topicGlobalId || !isUuidV7(topicGlobalId)) {
+            throw new Error("createBelief requires topicGlobalId to be a UUIDv7 topic epistemic-node globalId.");
+        }
+        const text = readString(input.text) ?? readString(input.canonicalText);
+        const body = { ...input, topicGlobalId };
+        delete body.topicId;
+        delete body.topicNodeId;
+        if (text) {
+            body.text = text;
+            body.canonicalText = text;
+        }
+        return body;
+    }
     const getOpinionHistory = async (beliefId) => {
         const response = await gateway.request({
             path: `/api/platform/v1/beliefs/${encodeURIComponent(beliefId)}/confidence-history`,
@@ -117,7 +133,7 @@ export function createBeliefsClient(config = {}) {
                 path: "/api/platform/v1/beliefs",
                 method: "POST",
                 body: {
-                    ...normalizeNodeWriteInput(input),
+                    ...normalizeCreateBeliefInput(input),
                     baseRate,
                 },
                 idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),

package/dist/client.d.ts

@@ -511,38 +511,7 @@ export declare function createLucernClient(config?: LucernClientConfig): {
         }): any;
     };
     evidence: {
-        create(args: {
-            text?: string;
-            canonicalText?: string;
-            topicId?: string;
-            source?: string;
-            sourceUrl?: string;
-            targetId?: string;
-            weight?: number;
-            evidenceRelation?: "supports" | "contradicts";
-            confidence?: number;
-            beliefRelations?: Array<{
-                beliefId?: string;
-                beliefNodeId?: string;
-                targetId?: string;
-                relation?: "supports" | "contradicts" | "supporting" | "contradicting";
-                evidenceRelation?: "supports" | "contradicts";
-                confidence?: number;
-                weight?: number;
-                rationale?: string;
-            }>;
-            metadata?: import("./types").JsonObject;
-            title?: string;
-            content?: string;
-            contentType?: string;
-            kind?: string;
-            rationale?: string;
-            supports?: {
-                nodeId: string;
-                weight: number;
-                reasoning?: string;
-            };
-        }): any;
+        create(args: import("./clientEvidenceCompat").EvidenceCompatInput): any;
         add: any;
         get(evidenceId: string): any;
         list(args: {
@@ -600,7 +569,12 @@ export declare function createLucernClient(config?: LucernClientConfig): {
             metadata?: import("./types").JsonObject;
         }): any;
         get(questionId: string): any;
-        refine(questionId: string, text: string, refinementReason?: string): any;
+        refine(questionId: string, input: string | {
+            text?: string;
+            question?: string;
+            rationale?: string;
+            linkedWorktreeId?: string;
+        }, refinementReason?: string): any;
         list(args: {
             topicId?: string;
             status?: string;

package/dist/clientEvidenceCompat.d.ts

@@ -6,6 +6,7 @@ export type EvidenceCompatInput = {
     topicId?: string;
     source?: string;
     sourceUrl?: string;
+    externalSourceUrl?: string;
     targetId?: string;
     weight?: number;
     evidenceRelation?: "supports" | "contradicts";
@@ -25,6 +26,14 @@ export type EvidenceCompatInput = {
     content?: string;
     contentType?: string;
     kind?: string;
+    tags?: string[];
+    sourceType?: string;
+    externalSourceType?: string;
+    sourceQuestionId?: string;
+    methodology?: string;
+    informationAsymmetry?: string;
+    sourceQuality?: "primary" | "analyzed" | "secondary" | "tertiary" | "unknown";
+    sourceDescription?: string;
     rationale?: string;
     supports?: {
         nodeId: string;
@@ -48,6 +57,16 @@ type EvidenceFacadeLike = {
         content?: string;
         contentType?: string;
         kind?: string;
+        tags?: string[];
+        sourceUrl?: string;
+        externalSourceUrl?: string;
+        sourceType?: string;
+        externalSourceType?: string;
+        sourceQuestionId?: string;
+        methodology?: string;
+        informationAsymmetry?: string;
+        sourceQuality?: "primary" | "analyzed" | "secondary" | "tertiary" | "unknown";
+        sourceDescription?: string;
     }): Promise<PlatformGatewaySuccess<Record<string, unknown>>>;
     link(args: {
         evidenceId: string;

package/dist/clientEvidenceCompat.js

@@ -16,6 +16,8 @@ export async function createEvidenceCompat(evidenceFacade, args) {
         topicId: resolveTopicId(args),
         text,
         source: args.source ?? args.sourceUrl,
+        sourceUrl: args.sourceUrl,
+        externalSourceUrl: args.externalSourceUrl,
         targetId: args.targetId ?? args.supports?.nodeId,
         weight: args.weight ?? args.supports?.weight,
         evidenceRelation: args.evidenceRelation,
@@ -27,33 +29,31 @@ export async function createEvidenceCompat(evidenceFacade, args) {
         content: args.content,
         contentType: args.contentType,
         kind: args.kind,
+        tags: args.tags,
+        sourceType: args.sourceType,
+        externalSourceType: args.externalSourceType,
+        sourceQuestionId: args.sourceQuestionId,
+        methodology: args.methodology,
+        informationAsymmetry: args.informationAsymmetry,
+        sourceQuality: args.sourceQuality,
+        sourceDescription: args.sourceDescription,
     });
 }
 export async function addEvidenceCompat(evidenceFacade, args) {
-    const created = await createEvidenceCompat(evidenceFacade, {
-        ...args,
-        targetId: args.supports ? undefined : args.targetId,
-        weight: args.supports ? undefined : args.weight,
-    });
     if (!args.supports) {
+        const created = await createEvidenceCompat(evidenceFacade, args);
         return created.data;
     }
-    const evidenceId = created.data.id;
-    if (typeof evidenceId !== "string" || evidenceId.length === 0) {
-        throw new Error("evidence create did not return an id");
-    }
-    const linked = await evidenceFacade.link({
-        evidenceId,
-        targetId: args.supports.nodeId,
-        weight: args.supports.weight,
+    const { supports, ...createArgs } = args;
+    const created = await createEvidenceCompat(evidenceFacade, {
+        ...createArgs,
+        targetId: args.targetId ?? supports.nodeId,
+        weight: args.weight ?? supports.weight,
         evidenceRelation: args.evidenceRelation ??
-            (args.supports.weight < 0 ? "contradicts" : "supports"),
-        confidence: args.confidence ?? Math.min(1, Math.abs(args.supports.weight)),
-        rationale: args.supports.reasoning,
+            (supports.weight < 0 ? "contradicts" : "supports"),
+        confidence: args.confidence ?? Math.min(1, Math.abs(supports.weight)),
+        rationale: args.rationale ?? supports.reasoning,
     });
-    return {
-        ...created.data,
-        edgeId: linked.data.edgeId,
-    };
+    return created.data;
 }
 //# sourceMappingURL=clientEvidenceCompat.js.map

package/dist/clientKnowledgeNamespaces.d.ts

@@ -1,5 +1,6 @@
 import type { ClientNamespaceContext } from "./clientAssemblyTypes";
 import type { BeliefsCompatCreateInput, BeliefsCompatForkInput } from "./clientConfig";
+import type { EvidenceCompatInput } from "./clientEvidenceCompat";
 import type { FunctionSurfaceInput } from "./generated/functionSurface";
 import type { JsonObject } from "./types";
 export declare function createClientKnowledgeNamespaces(ctx: ClientNamespaceContext): {
@@ -93,38 +94,7 @@ export declare function createClientKnowledgeNamespaces(ctx: ClientNamespaceCont
         }): any;
     };
     evidence: {
-        create(args: {
-            text?: string;
-            canonicalText?: string;
-            topicId?: string;
-            source?: string;
-            sourceUrl?: string;
-            targetId?: string;
-            weight?: number;
-            evidenceRelation?: "supports" | "contradicts";
-            confidence?: number;
-            beliefRelations?: Array<{
-                beliefId?: string;
-                beliefNodeId?: string;
-                targetId?: string;
-                relation?: "supports" | "contradicts" | "supporting" | "contradicting";
-                evidenceRelation?: "supports" | "contradicts";
-                confidence?: number;
-                weight?: number;
-                rationale?: string;
-            }>;
-            metadata?: JsonObject;
-            title?: string;
-            content?: string;
-            contentType?: string;
-            kind?: string;
-            rationale?: string;
-            supports?: {
-                nodeId: string;
-                weight: number;
-                reasoning?: string;
-            };
-        }): any;
+        create(args: EvidenceCompatInput): any;
         add: any;
         get(evidenceId: string): any;
         list(args: {
@@ -182,7 +152,12 @@ export declare function createClientKnowledgeNamespaces(ctx: ClientNamespaceCont
             metadata?: JsonObject;
         }): any;
         get(questionId: string): any;
-        refine(questionId: string, text: string, refinementReason?: string): any;
+        refine(questionId: string, input: string | {
+            text?: string;
+            question?: string;
+            rationale?: string;
+            linkedWorktreeId?: string;
+        }, refinementReason?: string): any;
         list(args: {
             topicId?: string;
             status?: string;

package/dist/clientKnowledgeNamespaces.js

@@ -359,12 +359,15 @@ export function createClientKnowledgeNamespaces(ctx) {
             get(questionId) {
                 return questionsFacade.get(questionId).then(exposeGatewayData);
             },
-            refine(questionId, text, refinementReason) {
+            refine(questionId, input, refinementReason) {
+                const payload = typeof input === "string"
+                    ? {
+                        text: input,
+                        rationale: refinementReason,
+                    }
+                    : input;
                 return questionsFacade
-                    .refine(questionId, {
-                    text,
-                    rationale: refinementReason,
-                })
+                    .refine(questionId, payload)
                     .then(exposeGatewayData);
             },
             list(args) {

package/dist/evidence/index.d.ts

@@ -4,38 +4,7 @@ export * as toolSchemas from "@lucern/contracts/tool-contracts";
 export type EvidenceClientConfig = LucernClientConfig;
 export type EvidenceClient = ReturnType<typeof createEvidenceClient>;
 export declare function createEvidenceClient(config?: EvidenceClientConfig): {
-    createEvidence: (args: {
-        text?: string;
-        canonicalText?: string;
-        topicId?: string;
-        source?: string;
-        sourceUrl?: string;
-        targetId?: string;
-        weight?: number;
-        evidenceRelation?: "supports" | "contradicts";
-        confidence?: number;
-        beliefRelations?: Array<{
-            beliefId?: string;
-            beliefNodeId?: string;
-            targetId?: string;
-            relation?: "supports" | "contradicts" | "supporting" | "contradicting";
-            evidenceRelation?: "supports" | "contradicts";
-            confidence?: number;
-            weight?: number;
-            rationale?: string;
-        }>;
-        metadata?: import("..").JsonObject;
-        title?: string;
-        content?: string;
-        contentType?: string;
-        kind?: string;
-        rationale?: string;
-        supports?: {
-            nodeId: string;
-            weight: number;
-            reasoning?: string;
-        };
-    }) => any;
+    createEvidence: (args: import("../clientEvidenceCompat").EvidenceCompatInput) => any;
     getEvidence: (evidenceId: string) => any;
     listEvidence: (args: {
         topicId?: string;
@@ -66,38 +35,7 @@ export declare function createEvidenceClient(config?: EvidenceClientConfig): {
     classifyEvidence: (beliefId: string, evidenceId: string, config?: Parameters<any>[2], idempotencyKey?: string) => any;
     classifyEvidenceBatch: (beliefId: string, evidence: Parameters<any>[1], config?: Parameters<any>[2], idempotencyKey?: string) => any;
     raw: {
-        create(args: {
-            text?: string;
-            canonicalText?: string;
-            topicId?: string;
-            source?: string;
-            sourceUrl?: string;
-            targetId?: string;
-            weight?: number;
-            evidenceRelation?: "supports" | "contradicts";
-            confidence?: number;
-            beliefRelations?: Array<{
-                beliefId?: string;
-                beliefNodeId?: string;
-                targetId?: string;
-                relation?: "supports" | "contradicts" | "supporting" | "contradicting";
-                evidenceRelation?: "supports" | "contradicts";
-                confidence?: number;
-                weight?: number;
-                rationale?: string;
-            }>;
-            metadata?: import("..").JsonObject;
-            title?: string;
-            content?: string;
-            contentType?: string;
-            kind?: string;
-            rationale?: string;
-            supports?: {
-                nodeId: string;
-                weight: number;
-                reasoning?: string;
-            };
-        }): any;
+        create(args: import("../clientEvidenceCompat").EvidenceCompatInput): any;
         add: any;
         get(evidenceId: string): any;
         list(args: {

package/dist/gatewayFacades.d.ts

@@ -171,6 +171,16 @@ export type EvidenceCreateInput = {
     content?: string;
     contentType?: string;
     kind?: string;
+    tags?: string[];
+    sourceUrl?: string;
+    externalSourceUrl?: string;
+    sourceType?: string;
+    externalSourceType?: string;
+    sourceQuestionId?: string;
+    methodology?: string;
+    informationAsymmetry?: string;
+    sourceQuality?: "primary" | "analyzed" | "secondary" | "tertiary" | "unknown";
+    sourceDescription?: string;
 };
 export type EvidenceListQuery = {
     topicId?: string;
@@ -217,8 +227,10 @@ export type QuestionAnswerInput = {
     rationale?: string;
 };
 export type QuestionRefineInput = {
-    text: string;
+    text?: string;
+    question?: string;
     rationale?: string;
+    linkedWorktreeId?: string;
 };
 export type QuestionArchiveInput = {
     reason?: string;

package/dist/proof-attestation.json

@@ -41,5 +41,5 @@
     "convex-validators",
     "proof-attestation"
   ],
-  "signedAt": 1780432640939
+  "signedAt": 1780649268504
 }

package/dist/questions/index.d.ts

@@ -26,7 +26,12 @@ export declare function createQuestionsClient(config?: QuestionsClientConfig): {
         evidenceIds?: string[];
         rationale?: string;
     }) => any;
-    refineQuestion: (questionId: string, text: string, refinementReason?: string) => any;
+    refineQuestion: (questionId: string, input: string | {
+        text?: string;
+        question?: string;
+        rationale?: string;
+        linkedWorktreeId?: string;
+    }, refinementReason?: string) => any;
     updateQuestionStatus: (questionId: string, status: string, rationale?: string) => any;
     archiveQuestion: (questionId: string, reason?: string) => any;
     getHighPriorityQuestions: (args: {
@@ -47,7 +52,12 @@ export declare function createQuestionsClient(config?: QuestionsClientConfig): {
             metadata?: import("..").JsonObject;
         }): any;
         get(questionId: string): any;
-        refine(questionId: string, text: string, refinementReason?: string): any;
+        refine(questionId: string, input: string | {
+            text?: string;
+            question?: string;
+            rationale?: string;
+            linkedWorktreeId?: string;
+        }, refinementReason?: string): any;
         list(args: {
             topicId?: string;
             status?: string;

package/dist/sdkSurface.d.ts

@@ -3,7 +3,6 @@ import type { JsonObject, ListResult } from "./types";
 type TopicScopedValue = {
     topicId?: string;
     topicGlobalId?: string;
-    topicNodeId?: string;
 };
 type TextScopedValue = {
     text?: string;

package/dist/sdkSurface.js

@@ -29,9 +29,7 @@ function cloneWith(value, patch) {
  * Resolve the canonical topic identifier.
  */
 export function resolveTopicId(value) {
-    return (cleanString(value.topicGlobalId) ??
-        cleanString(value.topicNodeId) ??
-        cleanString(value.topicId));
+    return cleanString(value.topicGlobalId) ?? cleanString(value.topicId);
 }
 /**
  * Resolve the canonical text field from text-first or legacy canonicalText-first inputs.

package/dist/types.d.ts

@@ -18,14 +18,11 @@ export type JsonValue = null | boolean | number | string | JsonArray | JsonObjec
  */
 export type TopicIdentifierInput = {
     /**
-     * Preferred write anchor for belief creation: the globalId of a topic
-     * epistemicNode. `topicId` remains a compatibility projection for read/query
-     * surfaces and must already refer to that same topic node when used for
-     * belief writes.
+     * Preferred write anchor for belief creation: the UUIDv7 globalId of a topic
+     * epistemicNode. `topicId` remains a read/query scope for non-belief-write
+     * surfaces.
      */
     topicGlobalId?: string;
-    /** Optional internal epistemicNodes _id for a topic node. */
-    topicNodeId?: string;
     topicId?: string;
 };
 /**

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 /** Current SDK package version. */
-export declare const LUCERN_SDK_VERSION = "1.0.18";
+export declare const LUCERN_SDK_VERSION = "1.0.20";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 /** Current SDK package version. */
-export const LUCERN_SDK_VERSION = "1.0.18";
+export const LUCERN_SDK_VERSION = "1.0.20";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucern/sdk",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -113,10 +113,10 @@
     "typecheck": "tsc --project tsconfig.typecheck.json --noEmit"
   },
   "dependencies": {
-    "@lucern/contracts": "1.0.18",
-    "@lucern/reasoning-kernel": "1.0.18",
-    "@lucern/secrets": "1.0.18",
-    "@lucern/transport-core": "1.0.18",
+    "@lucern/contracts": "1.0.20",
+    "@lucern/reasoning-kernel": "1.0.20",
+    "@lucern/secrets": "1.0.20",
+    "@lucern/transport-core": "1.0.20",
     "effect": "^3.21.2",
     "zod": "^3.25.76"
   },