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

package/.turbo/turbo-build.log

@@ -0,0 +1,7 @@
+
+> @lucern/sdk@0.2.0-alpha.5 build /Users/petercasella/lucern-repo/packages/sdk
+> bash -lc 'cd ../../.. && npx tsx scripts/build-sdk-package.ts'
+
+npm warn Unknown env config "_lucern-registry". This will stop working in the next major version of npm.
+npm error A complete log of this run can be found in: /Users/petercasella/.npm/_logs/2026-04-19T23_24_01_220Z-debug-0.log
+ ELIFECYCLE  Command failed with exit code 1.

package/.turbo/turbo-typecheck.log

@@ -0,0 +1,4 @@
+
+> @lucern/sdk@0.2.0-alpha.5 typecheck /Users/petercasella/lucern-repo/packages/sdk
+> tsc --project tsconfig.json --noEmit
+

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `@lucern/sdk` will be documented in this file.
+
+## [Unreleased]
+- No unreleased changes yet.
+
+## [0.2.0-alpha.5] - 2026-04-18
+- Refresh publish from current stackos source under EK-16 T4.
+- Version-numbering note: 0.2.0-alpha.2 through 0.2.0-alpha.5 were published from earlier stackos source on 2026-04-12 by pete_c. This release (alpha.5) is the first to ship the current April 18 source — 56 commits of accumulated changes from the code-separation track.
+
+## [0.2.0-alpha.1] - 2026-03-17
+- Current private registry release baseline for the typed SDK client.

package/examples/README.md

@@ -0,0 +1,69 @@
+# SDK Examples
+
+Runnable examples for `@lucern/sdk` that exercise the belief lifecycle against a live deployment.
+
+Inside this repo, the examples import `../src/index.js` so they stay aligned with the current public surface during development. When the package is published, the same imports translate directly to `@lucern/sdk`. Each run creates a fresh child topic under the topic you provide, so the example state stays isolated from the parent scope.
+
+## Setup
+
+Export the deployment origin, API key, and a writable parent topic:
+
+```bash
+export LUCERN_BASE_URL="https://your-deployment.example.com"
+export LUCERN_API_KEY="luc_..."
+export LUCERN_TOPIC_ID="topic_you_can_write_into"
+export LUCERN_ENVIRONMENT="sandbox"
+```
+
+`LUCERN_BASE_URL` may also be provided as `LUCERN_API_BASE_URL`. `LUCERN_TOPIC_ID` may also be provided as `LUCERN_PROJECT_ID`.
+
+## Run
+
+Use `tsx` from the repo root:
+
+```bash
+npx tsx lucern/packages/sdk/examples/quickstart.ts
+npx tsx lucern/packages/sdk/examples/questions-and-tasks.ts
+npx tsx lucern/packages/sdk/examples/worktree-lifecycle.ts
+npx tsx lucern/packages/sdk/examples/investigation-context.ts
+npx tsx lucern/packages/sdk/examples/contradiction.ts
+```
+
+Every script prints a JSON payload with `status`, IDs, and the visible output of the operations it executed.
+
+## Example Map
+
+| File | Covers |
+| --- | --- |
+| `quickstart.ts` | Create topic, create belief with the `text` alias, add evidence, modulate confidence, fork belief, search beliefs |
+| `questions-and-tasks.ts` | Create a question linked to a belief, then create a task linked to that question and belief |
+| `worktree-lifecycle.ts` | Create branch, create worktree, activate it through the public SDK, then list the created worktree |
+| `investigation-context.ts` | Attempt hosted-MCP `compile_context`, with a public-SDK composed fallback when that tool is unavailable on the deployment |
+| `contradiction.ts` | Create two beliefs, flag a contradiction, and list the visible contradiction state |
+| `strict-public-types.ts` | Compile-time guard that public SDK types stay strict and do not regress to unknown-string index signatures |
+
+## Expected Output
+
+The quickstart returns a compact JSON summary:
+
+```json
+{
+  "example": "quickstart",
+  "status": "ok",
+  "topic": {
+    "topicId": "topic_..."
+  },
+  "quickstart": {
+    "beliefId": "belief_...",
+    "forkId": "belief_...",
+    "resultCount": 1
+  }
+}
+```
+
+The hosted-MCP-based examples stay runnable even when the deployment does not yet expose those tools. In that case they return a `mode` such as `hosted-mcp-preview` or `composed-fallback` instead of failing silently.
+
+## Notes
+
+- These scripts create fresh topics, beliefs, tasks, and worktrees. Use a sandbox topic and API key.
+- `investigation-context.ts` and `contradiction.ts` still make the remaining public-surface gaps explicit instead of patching the SDK source in-place.

package/examples/contradiction.ts

@@ -0,0 +1,94 @@
+import {
+  callHostedMcpTool,
+  createExampleTopic,
+  requireStringField,
+  runExample,
+} from "./shared.js";
+
+runExample("contradiction", async (context) => {
+  const topic = await createExampleTopic(context, "contradiction");
+
+  const beliefA = await context.lucern.beliefs.create({
+    text: "Developers adopt the SDK faster when quickstarts stay linear and minimal.",
+    topicId: topic.topicId,
+  });
+  const beliefB = await context.lucern.beliefs.create({
+    text: "Developers adopt the SDK faster when examples enumerate every lifecycle branch on day one.",
+    topicId: topic.topicId,
+  });
+  const beliefAId = requireStringField(
+    beliefA.data,
+    ["nodeId", "globalId"],
+    "beliefAId"
+  );
+  const beliefBId = requireStringField(
+    beliefB.data,
+    ["nodeId", "globalId"],
+    "beliefBId"
+  );
+
+  const contradiction = await callHostedMcpTool(context, "flag_contradiction", {
+    beliefA: beliefAId,
+    beliefB: beliefBId,
+    defeatType: "rebuts",
+    description:
+      "The onboarding flow cannot be both minimal-first and exhaustive-first at the same time.",
+    topicId: topic.topicId,
+    severity: "high",
+  });
+
+  let contradictionId: string | null = null;
+  if (contradiction.ok) {
+    contradictionId =
+      typeof (contradiction.payload as { contradictionId?: unknown })
+        ?.contradictionId === "string"
+        ? String(
+            (contradiction.payload as { contradictionId: string })
+              .contradictionId
+          )
+        : null;
+  } else {
+    const fallback = await context.lucern.raw.graph.createNode({
+      metadata: {
+        beliefA: beliefAId,
+        beliefB: beliefBId,
+        defeatType: "rebuts",
+        severity: "high",
+        status: "unresolved",
+      },
+      nodeType: "contradiction",
+      text: "The onboarding flow cannot be both minimal-first and exhaustive-first at the same time.",
+      topicId: topic.topicId,
+    });
+    contradictionId = requireStringField(
+      fallback.data,
+      ["nodeId", "globalId"],
+      "contradictionId"
+    );
+  }
+
+  const contradictions = await context.lucern.graph.findContradictions({
+    topicId: topic.topicId,
+  });
+
+  return {
+    contradiction: contradiction.ok
+      ? {
+          contradictionId,
+          mode: "hosted-mcp",
+          payload: contradiction.payload,
+        }
+      : {
+          contradictionId,
+          mode: "raw-graph-fallback",
+          note: "Hosted MCP contradiction tooling was unavailable, so the example created the contradiction node through the raw graph client.",
+          payload: contradiction.payload,
+        },
+    beliefs: {
+      beliefAId,
+      beliefBId,
+    },
+    topic,
+    visibleContradictions: contradictions.contradictions,
+  };
+});

package/examples/investigation-context.ts

@@ -0,0 +1,118 @@
+import {
+  callHostedMcpTool,
+  createExampleTopic,
+  listItems,
+  requireStringField,
+  runExample,
+  slugify,
+} from "./shared.js";
+
+runExample("investigation-context", async (context) => {
+  const topic = await createExampleTopic(context, "investigation-context");
+  const query = "SDK example context pack";
+
+  const belief = await context.lucern.beliefs.create({
+    text: "A focused context pack helps developers understand the next graph action without reading the whole ontology.",
+    topicId: topic.topicId,
+  });
+  const beliefId = requireStringField(
+    belief.data,
+    ["nodeId", "globalId"],
+    "beliefId"
+  );
+
+  await context.lucern.evidence.add({
+    sourceUrl: "https://example.invalid/sdk-example-context",
+    supports: {
+      nodeId: beliefId,
+      reasoning:
+        "The example seeds one belief and one evidence item for retrieval.",
+      weight: 0.74,
+    },
+    text: "Context-pack example seeded a concrete signal about first-run developer comprehension.",
+    topicId: topic.topicId,
+  });
+
+  await context.lucern.questions.create({
+    linkedBeliefId: beliefId,
+    priority: "high",
+    text: "Which belief, question, and worktree signals should show up first in a minimal onboarding context pack?",
+    topicId: topic.topicId,
+  });
+
+  const branch = await context.lucern.worktrees.createBranch({
+    description: "Branch for the investigation-context example.",
+    name: `sdk-context-${slugify(topic.name)}`,
+    topicId: topic.topicId,
+  });
+  const branchId = requireStringField(
+    branch.data,
+    ["branchId", "nodeId"],
+    "branchId"
+  );
+
+  await context.lucern.worktrees.create({
+    beliefIds: [beliefId],
+    branchId,
+    hypothesis:
+      "A compact context bundle gives enough orientation to take the next reasoning action.",
+    title: "SDK Example Investigation Context",
+    topicId: topic.topicId,
+  });
+
+  const compiledContext = await callHostedMcpTool(context, "compile_context", {
+    budget: 1200,
+    limit: 5,
+    query,
+    topicId: topic.topicId,
+  });
+
+  if (compiledContext.ok) {
+    return {
+      mode: "hosted-mcp",
+      topic,
+      contextPack: compiledContext.payload,
+    };
+  }
+
+  const beliefs = await context.lucern.graph.listBeliefs({
+    topicId: topic.topicId,
+  });
+  const questions = await context.lucern.questions.getHighPriority({
+    limit: 5,
+    topicId: topic.topicId,
+  });
+  const evidence = await context.lucern.evidence.search({
+    limit: 5,
+    query: "context-pack example",
+    topicId: topic.topicId,
+  });
+  const worktrees = await context.lucern.worktrees.list({
+    topicId: topic.topicId,
+  });
+  const recentEvidence = listItems<Record<string, unknown>>(evidence, "results");
+
+  return {
+    mode: "composed-fallback",
+    note: "The hosted MCP deployment did not expose compile_context in this environment, so this example composes an equivalent bundle from the public SDK reads.",
+    mcp: {
+      contextPack: compiledContext.payload,
+    },
+    topic,
+    contextPack: {
+      beliefs: beliefs.slice(0, 5),
+      openQuestions: questions.questions,
+      recentEvidence,
+      summary: {
+        beliefCount: beliefs.length,
+        evidenceCount: recentEvidence.length,
+        questionCount: questions.questions.length,
+        worktreeCount: listItems(worktrees.data, "worktrees").length,
+      },
+      worktrees: listItems<Record<string, unknown>>(
+        worktrees.data,
+        "worktrees"
+      ),
+    },
+  };
+});

package/examples/questions-and-tasks.ts

@@ -0,0 +1,55 @@
+import {
+  createExampleTopic,
+  requireStringField,
+  runExample,
+} from "./shared.js";
+
+runExample("questions-and-tasks", async (context) => {
+  const topic = await createExampleTopic(context, "questions-and-tasks");
+
+  const belief = await context.lucern.beliefs.create({
+    metadata: {
+      example: "questions-and-tasks",
+    },
+    text: "SDK onboarding friction drops when runnable examples answer concrete first-run questions.",
+    topicId: topic.topicId,
+  });
+  const beliefId = requireStringField(
+    belief.data,
+    ["nodeId", "globalId"],
+    "beliefId"
+  );
+
+  const question = await context.lucern.questions.create({
+    linkedBeliefId: beliefId,
+    priority: "high",
+    text: "Which setup step still blocks a developer before the first successful belief write?",
+    topicId: topic.topicId,
+  });
+  const questionId = requireStringField(
+    question.data,
+    ["nodeId", "globalId"],
+    "questionId"
+  );
+
+  const task = await context.lucern.tasks.create({
+    description:
+      "Validate the setup sequence from API key + base URL to a successful belief.create() call.",
+    linkedBeliefId: beliefId,
+    linkedQuestionId: questionId,
+    priority: "high",
+    taskType: "analysis",
+    title: "Audit the first-belief onboarding sequence",
+    topicId: topic.topicId,
+  });
+  const taskId = requireStringField(task.data, ["taskId", "id"], "taskId");
+
+  return {
+    topic,
+    workflow: {
+      beliefId,
+      questionId,
+      taskId,
+    },
+  };
+});

package/examples/quickstart.ts

@@ -0,0 +1,97 @@
+import {
+  createExampleTopic,
+  printJson,
+  requireStringField,
+  runExample,
+} from "./shared.js";
+
+if (process.argv.includes("--dry-run")) {
+  printJson({
+    example: "quickstart",
+    mode: "dry-run",
+    steps: [
+      "create topic",
+      "create belief with text alias",
+      "add evidence",
+      "modulate confidence",
+      "fork belief",
+      "search beliefs",
+    ],
+  });
+  process.exit(0);
+}
+
+runExample("quickstart", async (context) => {
+  const topic = await createExampleTopic(context, "quickstart");
+
+  const belief = await context.lucern.beliefs.create({
+    metadata: {
+      example: "quickstart",
+      source: "lucern/packages/sdk/examples/quickstart.ts",
+    },
+    text: "Time-to-first-belief drops when the SDK ships a concrete quickstart that exercises the core lifecycle end to end.",
+    topicId: topic.topicId,
+  });
+  const beliefId = requireStringField(
+    belief.data,
+    ["nodeId", "globalId"],
+    "beliefId"
+  );
+
+  const evidence = await context.lucern.evidence.add({
+    sourceUrl: "https://example.invalid/sdk-quickstart-signal",
+    supports: {
+      nodeId: beliefId,
+      reasoning:
+        "Example-driven onboarding reduces the amount of guesswork before a first successful write.",
+      weight: 0.81,
+    },
+    text: "A runnable example moved the first successful belief write into the first five minutes for a new developer.",
+    topicId: topic.topicId,
+  });
+  const evidenceId = requireStringField(
+    evidence,
+    ["nodeId", "globalId"],
+    "evidenceId"
+  );
+
+  await context.lucern.beliefs.modulateConfidence(beliefId, {
+    confidence: 0.79,
+    rationale:
+      "The quickstart now demonstrates a complete create → evidence → confidence → fork path.",
+    trigger: "evidence_added",
+  });
+
+  const fork = await context.lucern.beliefs.fork(beliefId, {
+    forkReason: "refinement",
+    newFormulation:
+      "Time-to-first-belief drops below five minutes when the SDK ships a concrete quickstart that exercises the core lifecycle end to end.",
+    rationale: "Narrow the claim to the under-five-minute onboarding target.",
+  });
+  const forkId = requireStringField(
+    fork.data,
+    ["nodeId", "forkedNodeId", "globalId"],
+    "forkId"
+  );
+
+  const search = await context.lucern.beliefs.search({
+    limit: 5,
+    query: "time-to-first-belief",
+    topicId: topic.topicId,
+  });
+
+  return {
+    quickstart: {
+      beliefId,
+      evidenceId,
+      forkId,
+      resultCount: search.results.length,
+      searchResults: search.results.map((result) => ({
+        canonicalText: result.canonicalText,
+        confidence: result.confidence,
+        nodeId: result.nodeId,
+      })),
+    },
+    topic,
+  };
+});