@lucern/sdk 0.3.0-alpha.1 → 0.3.0-alpha.11

package/dist/clientHelpers.d.ts

@@ -0,0 +1,48 @@
+import { JsonObject, PlatformGraphEdge, PlatformGraphNode } from './types.js';
+import './contracts/workflow-runtime.contract.js';
+import './contracts/lens-workflow.contract.js';
+import './contracts/lens-filter.contract.js';
+
+type NodeLike = PlatformGraphNode;
+type EdgeLike = PlatformGraphEdge;
+type CustomToolInput = JsonObject;
+type BeliefsRefineInput = string | {
+    text: string;
+    rationale?: string;
+};
+type BeliefsArchiveInput = {
+    reason?: string;
+    rationale?: string;
+} | string;
+declare function normalizeCustomNamespace(namespace: string): string;
+declare function normalizeCustomToolPayload(input: unknown): CustomToolInput;
+declare function resolveCustomToolFullName(name: string): string;
+declare function buildBeliefsRefinePayload(textOrInput: BeliefsRefineInput, rationale?: string): {
+    text: string;
+    rationale?: string;
+};
+declare function buildBeliefsArchivePayload(input?: BeliefsArchiveInput): {
+    reason?: string;
+} | undefined;
+declare function asNodeArray(data: unknown): NodeLike[];
+declare function asEdgeArray(data: unknown): EdgeLike[];
+declare function requireTopicId(args: {
+    topicId?: string;
+}): string;
+declare function requireTopicOrProjectId(args: {
+    topicId?: string;
+    projectId?: string;
+}): string;
+declare function matchesAuditNodeReference(value: unknown, nodeId: string): boolean;
+declare function requireText(args: {
+    text?: string;
+    canonicalText?: string;
+    formulation?: string;
+    newFormulation?: string;
+}): string;
+declare function requireBaseRate(args: {
+    baseRate?: number;
+}): number;
+declare function sdkQueryString(input: Record<string, unknown>): string;
+
+export { type BeliefsArchiveInput, type BeliefsRefineInput, type CustomToolInput, type EdgeLike, type NodeLike, asEdgeArray, asNodeArray, buildBeliefsArchivePayload, buildBeliefsRefinePayload, matchesAuditNodeReference, normalizeCustomNamespace, normalizeCustomToolPayload, requireBaseRate, requireText, requireTopicId, requireTopicOrProjectId, resolveCustomToolFullName, sdkQueryString };

package/dist/clientHelpers.js

@@ -0,0 +1,137 @@
+// src/sdkSurface.ts
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function asRecord(value) {
+  return isRecord(value) ? value : {};
+}
+function cleanString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function resolveTopicId(value) {
+  return cleanString(value.topicId);
+}
+function resolveText(value) {
+  return cleanString(value.text) ?? cleanString(value.canonicalText);
+}
+function asListItems(data, legacyKey) {
+  if (Array.isArray(data)) {
+    return data;
+  }
+  const record = asRecord(data);
+  if (Array.isArray(record.items)) {
+    return record.items;
+  }
+  if (legacyKey && Array.isArray(record[legacyKey])) {
+    return record[legacyKey];
+  }
+  return [];
+}
+
+// src/clientHelpers.ts
+function normalizeCustomNamespace(namespace) {
+  return namespace.trim() || "custom";
+}
+function normalizeCustomToolPayload(input) {
+  return input && typeof input === "object" && !Array.isArray(input) ? input : {};
+}
+function resolveCustomToolFullName(name) {
+  return name.includes(".") ? name : `custom.${name}`;
+}
+function buildBeliefsRefinePayload(textOrInput, rationale) {
+  return typeof textOrInput === "string" ? { text: textOrInput, rationale } : { text: textOrInput.text, rationale: textOrInput.rationale };
+}
+function buildBeliefsArchivePayload(input) {
+  return typeof input === "string" ? { reason: input } : input ? { reason: input.reason ?? input.rationale } : void 0;
+}
+function asNodeArray(data) {
+  const rows = asListItems(data, "nodes");
+  if (rows.length > 0) {
+    return rows.filter(
+      (value) => Boolean(value) && typeof value === "object"
+    );
+  }
+  if (data && typeof data === "object") {
+    return [data];
+  }
+  return [];
+}
+function asEdgeArray(data) {
+  const rows = asListItems(data, "edges");
+  if (rows.length > 0) {
+    return rows.filter(
+      (value) => Boolean(value) && typeof value === "object"
+    );
+  }
+  if (data && typeof data === "object") {
+    return [data];
+  }
+  return [];
+}
+function requireTopicId(args) {
+  const topicId = resolveTopicId(args);
+  if (!topicId) {
+    throw new Error("topicId is required");
+  }
+  return topicId;
+}
+function requireTopicOrProjectId(args) {
+  const topicId = args.topicId?.trim() || args.projectId?.trim() || void 0;
+  if (!topicId) {
+    throw new Error("topicId is required");
+  }
+  return topicId;
+}
+var AUDIT_NODE_REFERENCE_KEY_PATTERN = /(^|_)(id|nodeid|beliefid|resourceid|targetid|sourceid|subjectid|globalid|entityid|recordid|fromnodeid|tonodeid|linkednodeid|linkedbeliefid|nodeids|beliefids|resourceids)$/i;
+function matchesAuditNodeReference(value, nodeId) {
+  if (Array.isArray(value)) {
+    return value.some((entry) => matchesAuditNodeReference(entry, nodeId));
+  }
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  return Object.entries(value).some(([key, entry]) => {
+    if (typeof entry === "string" && entry === nodeId && AUDIT_NODE_REFERENCE_KEY_PATTERN.test(key)) {
+      return true;
+    }
+    if (Array.isArray(entry) && AUDIT_NODE_REFERENCE_KEY_PATTERN.test(key) && entry.some((item) => item === nodeId)) {
+      return true;
+    }
+    return matchesAuditNodeReference(entry, nodeId);
+  });
+}
+function requireText(args) {
+  const text = resolveText(args);
+  if (!text) {
+    throw new Error("text is required");
+  }
+  return text;
+}
+function requireBaseRate(args) {
+  const baseRate = typeof args.baseRate === "number" && Number.isFinite(args.baseRate) ? args.baseRate : 0.5;
+  if (baseRate < 0 || baseRate > 1) {
+    throw new Error("baseRate must be within [0, 1].");
+  }
+  return baseRate;
+}
+function sdkQueryString(input) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(input)) {
+    if (value === void 0 || value === null) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      if (value.length > 0) {
+        params.set(key, value.join(","));
+      }
+      continue;
+    }
+    params.set(key, String(value));
+  }
+  const serialized = params.toString();
+  return serialized ? `?${serialized}` : "";
+}
+
+export { asEdgeArray, asNodeArray, buildBeliefsArchivePayload, buildBeliefsRefinePayload, matchesAuditNodeReference, normalizeCustomNamespace, normalizeCustomToolPayload, requireBaseRate, requireText, requireTopicId, requireTopicOrProjectId, resolveCustomToolFullName, sdkQueryString };
+//# sourceMappingURL=clientHelpers.js.map
+//# sourceMappingURL=clientHelpers.js.map

package/dist/clientHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sdkSurface.ts","../src/clientHelpers.ts"],"names":[],"mappings":"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","file":"clientHelpers.js","sourcesContent":["import type { PlatformGatewaySuccess } from \"./coreClient\";\nimport type { JsonObject, ListResult } from \"./types\";\n\ntype TopicScopedValue = {\n  topicId?: string;\n};\n\ntype TextScopedValue = {\n  text?: string;\n  canonicalText?: string;\n};\n\ntype AnyRecord = Record<string, unknown>;\n\nexport function isRecord(value: unknown): value is AnyRecord {\n  return Boolean(value) && typeof value === \"object\" && !Array.isArray(value);\n}\n\nexport function asRecord(value: unknown): AnyRecord {\n  return isRecord(value) ? value : {};\n}\n\nfunction cleanString(value: unknown): string | undefined {\n  return typeof value === \"string\" && value.trim().length > 0\n    ? value.trim()\n    : undefined;\n}\n\nfunction normalizeVerificationStatus(value: unknown): string | undefined {\n  const status = cleanString(value);\n  if (!status) {\n    return undefined;\n  }\n  if (status === \"verified\") {\n    return \"human_verified\";\n  }\n  if (status === \"rejected\") {\n    return \"contradicted\";\n  }\n  return status;\n}\n\nfunction cloneWith<T extends AnyRecord>(value: T, patch: AnyRecord): T {\n  return { ...value, ...patch } as T;\n}\n\n/**\n * Resolve the canonical topic identifier.\n */\nexport function resolveTopicId(value: TopicScopedValue): string | undefined {\n  return cleanString(value.topicId);\n}\n\n/**\n * Resolve the canonical text field from text-first or legacy canonicalText-first inputs.\n */\nexport function resolveText(value: TextScopedValue): string | undefined {\n  return cleanString(value.text) ?? cleanString(value.canonicalText);\n}\n\n/**\n * Attach the topicId to a record.\n */\nexport function withTopicAlias<T extends AnyRecord>(value: T): T {\n  const topicId = cleanString(value.topicId) ?? undefined;\n  if (!topicId) {\n    return value;\n  }\n  return cloneWith(value, { topicId });\n}\n\n/**\n * Attach the text/canonicalText alias pair to a record.\n */\nexport function withTextAlias<T extends AnyRecord>(value: T): T {\n  const text =\n    cleanString(value.text) ?? cleanString(value.canonicalText) ?? undefined;\n  if (!text) {\n    return value;\n  }\n  return cloneWith(value, { text, canonicalText: text });\n}\n\n/**\n * Attach topic and text aliases to SDK node-like records.\n */\nexport function withSdkAliases<T extends AnyRecord>(value: T): T {\n  return withTopicAlias(withTextAlias(value));\n}\n\n/**\n * Normalize a belief/question/evidence write payload to the canonical gateway shape.\n */\nexport function normalizeNodeWriteInput<T extends JsonObject>(value: T): T {\n  const topicId = resolveTopicId(value);\n  const text = resolveText(value);\n  const verificationStatus = normalizeVerificationStatus(value.verificationStatus);\n  const next = { ...value } as JsonObject;\n\n  if (topicId) {\n    next.topicId = topicId;\n  }\n  if (text) {\n    next.text = text;\n    next.canonicalText = text;\n  }\n  if (verificationStatus) {\n    next.verificationStatus = verificationStatus;\n  }\n\n  return next as T;\n}\n\nexport const normalizeNodeVerificationStatus = normalizeVerificationStatus;\n\n/**\n * Build a topic-aware query object.\n */\nexport function normalizeTopicQuery<T extends JsonObject>(value: T): T {\n  const topicId = cleanString(value.topicId);\n  if (!topicId) {\n    return value;\n  }\n  return { ...value, topicId } as T;\n}\n\n/**\n * Extract list items from array or list-envelope payloads.\n */\nexport function asListItems<T>(data: unknown, legacyKey?: string): T[] {\n  if (Array.isArray(data)) {\n    return data;\n  }\n\n  const record = asRecord(data);\n  if (Array.isArray(record.items)) {\n    return record.items;\n  }\n  if (legacyKey && Array.isArray(record[legacyKey])) {\n    return record[legacyKey];\n  }\n\n  return [];\n}\n\n/**\n * Standardize list data to { items, total } while retaining an optional legacy array key.\n */\nexport function createListResult<T, LegacyKey extends string>(\n  items: T[],\n  legacyKey?: LegacyKey\n): ListResult<T, LegacyKey> {\n  const result = {\n    items,\n    total: items.length,\n  } as ListResult<T, LegacyKey>;\n\n  if (legacyKey) {\n    return {\n      ...result,\n      [legacyKey]: items,\n    } as ListResult<T, LegacyKey>;\n  }\n\n  return result;\n}\n\n/**\n * Map a gateway success envelope's data while preserving the transport metadata.\n */\nexport function mapGatewayData<T, U>(\n  response: PlatformGatewaySuccess<T>,\n  mapper: (data: T) => U\n): PlatformGatewaySuccess<U> {\n  return {\n    ...response,\n    data: mapper(response.data),\n  };\n}\n\n/**\n * Apply SDK aliases across all items in a list-like payload.\n */\nexport function mapAliasedList<\n  TItem extends AnyRecord,\n  LegacyKey extends string,\n>(\n  data: unknown,\n  legacyKey?: LegacyKey\n): ListResult<TItem, LegacyKey> {\n  const items = asListItems<TItem>(data, legacyKey).map((item) =>\n    withSdkAliases(item)\n  );\n  return createListResult(items, legacyKey);\n}\n","import { asListItems, resolveText, resolveTopicId } from \"./sdkSurface\";\nimport type { JsonObject, PlatformGraphEdge, PlatformGraphNode } from \"./types\";\n\nexport type NodeLike = PlatformGraphNode;\nexport type EdgeLike = PlatformGraphEdge;\nexport type CustomToolInput = JsonObject;\nexport type BeliefsRefineInput =\n  | string\n  | { text: string; rationale?: string };\nexport type BeliefsArchiveInput = { reason?: string; rationale?: string } | string;\n\nexport function normalizeCustomNamespace(namespace: string): string {\n  return namespace.trim() || \"custom\";\n}\n\nexport function normalizeCustomToolPayload(input: unknown): CustomToolInput {\n  return input && typeof input === \"object\" && !Array.isArray(input)\n    ? (input as CustomToolInput)\n    : {};\n}\n\nexport function resolveCustomToolFullName(name: string): string {\n  return name.includes(\".\") ? name : `custom.${name}`;\n}\n\nexport function buildBeliefsRefinePayload(\n  textOrInput: BeliefsRefineInput,\n  rationale?: string\n): { text: string; rationale?: string } {\n  return typeof textOrInput === \"string\"\n    ? { text: textOrInput, rationale }\n    : { text: textOrInput.text, rationale: textOrInput.rationale };\n}\n\nexport function buildBeliefsArchivePayload(\n  input?: BeliefsArchiveInput\n): { reason?: string } | undefined {\n  return typeof input === \"string\"\n    ? { reason: input }\n    : input\n      ? { reason: input.reason ?? input.rationale }\n      : undefined;\n}\n\nexport function asNodeArray(data: unknown): NodeLike[] {\n  const rows = asListItems<NodeLike>(data, \"nodes\");\n  if (rows.length > 0) {\n    return rows.filter(\n      (value): value is NodeLike => Boolean(value) && typeof value === \"object\"\n    );\n  }\n  if (data && typeof data === \"object\") {\n    return [data as NodeLike];\n  }\n  return [];\n}\n\nexport function asEdgeArray(data: unknown): EdgeLike[] {\n  const rows = asListItems<EdgeLike>(data, \"edges\");\n  if (rows.length > 0) {\n    return rows.filter(\n      (value): value is EdgeLike => Boolean(value) && typeof value === \"object\"\n    );\n  }\n  if (data && typeof data === \"object\") {\n    return [data as EdgeLike];\n  }\n  return [];\n}\n\nexport function requireTopicId(args: { topicId?: string }): string {\n  const topicId = resolveTopicId(args);\n  if (!topicId) {\n    throw new Error(\"topicId is required\");\n  }\n  return topicId;\n}\n\nexport function requireTopicOrProjectId(args: {\n  topicId?: string;\n  projectId?: string;\n}): string {\n  const topicId =\n    args.topicId?.trim() || args.projectId?.trim() || undefined;\n  if (!topicId) {\n    throw new Error(\"topicId is required\");\n  }\n  return topicId;\n}\n\nconst AUDIT_NODE_REFERENCE_KEY_PATTERN =\n  /(^|_)(id|nodeid|beliefid|resourceid|targetid|sourceid|subjectid|globalid|entityid|recordid|fromnodeid|tonodeid|linkednodeid|linkedbeliefid|nodeids|beliefids|resourceids)$/i;\n\nexport function matchesAuditNodeReference(\n  value: unknown,\n  nodeId: string\n): boolean {\n  if (Array.isArray(value)) {\n    return value.some((entry) => matchesAuditNodeReference(entry, nodeId));\n  }\n\n  if (!value || typeof value !== \"object\") {\n    return false;\n  }\n\n  return Object.entries(value as Record<string, unknown>).some(([key, entry]) => {\n    if (\n      typeof entry === \"string\" &&\n      entry === nodeId &&\n      AUDIT_NODE_REFERENCE_KEY_PATTERN.test(key)\n    ) {\n      return true;\n    }\n\n    if (\n      Array.isArray(entry) &&\n      AUDIT_NODE_REFERENCE_KEY_PATTERN.test(key) &&\n      entry.some((item) => item === nodeId)\n    ) {\n      return true;\n    }\n\n    return matchesAuditNodeReference(entry, nodeId);\n  });\n}\n\nexport function requireText(args: {\n  text?: string;\n  canonicalText?: string;\n  formulation?: string;\n  newFormulation?: string;\n}): string {\n  const text = resolveText(args);\n  if (!text) {\n    throw new Error(\"text is required\");\n  }\n  return text;\n}\n\nexport function requireBaseRate(args: { baseRate?: number }): number {\n  const baseRate =\n    typeof args.baseRate === \"number\" && Number.isFinite(args.baseRate)\n      ? args.baseRate\n      : 0.5;\n  if (baseRate < 0 || baseRate > 1) {\n    throw new Error(\"baseRate must be within [0, 1].\");\n  }\n  return baseRate;\n}\n\nexport function sdkQueryString(input: Record<string, unknown>): string {\n  const params = new URLSearchParams();\n  for (const [key, value] of Object.entries(input)) {\n    if (value === undefined || value === null) {\n      continue;\n    }\n    if (Array.isArray(value)) {\n      if (value.length > 0) {\n        params.set(key, value.join(\",\"));\n      }\n      continue;\n    }\n    params.set(key, String(value));\n  }\n  const serialized = params.toString();\n  return serialized ? `?${serialized}` : \"\";\n}\n"]}

package/dist/contextClient.d.ts

@@ -1,5 +1,7 @@
 import { GatewayClientConfig, PlatformGatewaySuccess } from './coreClient.js';
 import { PublicCompiledContext, CompileContextInput } from './contextTypes.js';
+import './authContext.js';
+import './contracts/auth-session.contract.js';
 import './types.js';
 import './contracts/workflow-runtime.contract.js';
 import './contracts/lens-workflow.contract.js';
@@ -16,12 +18,13 @@ type CompileContextResponse = PublicCompiledContext;
  */
 declare function createContextClient(config?: ContextClientConfig): {
     /**
-     * Compile a focused reasoning context pack for a topic scope.
-     * @param topicId - The topic to compile context for.
+     * Compile a focused reasoning context pack.
+     * @param topicIdOrInput - Optional topic ID, or compile input for query-first resolution.
      * @param input - Optional compile parameters (query, budget, ranking, etc.).
      * @returns The compiled context payload with beliefs, questions, and evidence.
      */
-    compile(topicId: string, input?: CompileContextInput): Promise<PlatformGatewaySuccess<PublicCompiledContext>>;
+    compile(topicIdOrInput?: string | CompileContextInput, input?: CompileContextInput): Promise<PlatformGatewaySuccess<PublicCompiledContext>>;
+    compileByQuery(input?: CompileContextInput): Promise<PlatformGatewaySuccess<PublicCompiledContext>>;
 };
 
 export { CompileContextInput, type CompileContextResponse, type ContextClientConfig, PublicCompiledContext, createContextClient };

package/dist/contextClient.js

@@ -1,3 +1,170 @@
+// src/authContext.ts
+var LucernSdkAuthContextError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "LucernSdkAuthContextError";
+    this.reason = reason;
+  }
+};
+function cleanString(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
+function cleanStringList(values) {
+  if (!values) {
+    return [];
+  }
+  return values.map((value) => value.trim()).filter(
+    (value, index, list) => value.length > 0 && list.indexOf(value) === index
+  );
+}
+function requireString(value, reason, label) {
+  const normalized = cleanString(value);
+  if (!normalized) {
+    throw new LucernSdkAuthContextError(
+      reason,
+      `Canonical Lucern SDK auth context is missing ${label}.`
+    );
+  }
+  return normalized;
+}
+function requirePrincipalType(principalType) {
+  if (!principalType) {
+    throw new LucernSdkAuthContextError(
+      "principal_missing",
+      "Canonical Lucern SDK auth context is missing principalType."
+    );
+  }
+  return principalType;
+}
+function requireAuthMode(authMode) {
+  if (!authMode) {
+    throw new LucernSdkAuthContextError(
+      "principal_missing",
+      "Canonical Lucern SDK auth context is missing authMode."
+    );
+  }
+  return authMode;
+}
+function ensurePermitMatch(args) {
+  const actual = cleanString(args.actual);
+  if (actual && actual !== args.expected) {
+    throw new LucernSdkAuthContextError(
+      "policy_denied",
+      `Canonical Lucern SDK auth context has conflicting Permit ${args.field}.`
+    );
+  }
+}
+function normalizeCanonicalLucernAuthContext(input) {
+  if (!input) {
+    throw new LucernSdkAuthContextError(
+      "principal_missing",
+      "Canonical Lucern SDK auth context is required."
+    );
+  }
+  if (input.policyDecision === "deny") {
+    throw new LucernSdkAuthContextError(
+      "policy_denied",
+      "Canonical Lucern SDK auth context carries a denied policy decision."
+    );
+  }
+  const principalId = requireString(
+    input.principalId,
+    "principal_missing",
+    "principalId"
+  );
+  const tenantId = requireString(input.tenantId, "tenant_missing", "tenantId");
+  const workspaceId = requireString(
+    input.workspaceId,
+    "workspace_missing",
+    "workspaceId"
+  );
+  const roles = cleanStringList(input.roles);
+  const scopes = cleanStringList(input.scopes);
+  const principalType = requirePrincipalType(input.principalType);
+  const authMode = requireAuthMode(input.authMode);
+  const roleBasedInteractiveAuth = authMode === "interactive_user" && roles.length > 0;
+  if (roles.length === 0 || scopes.length === 0 && !roleBasedInteractiveAuth) {
+    throw new LucernSdkAuthContextError(
+      "membership_missing",
+      "Canonical Lucern SDK auth context requires non-empty roles and scopes."
+    );
+  }
+  const subject = cleanString(input.permit?.subject) ?? principalId;
+  const tenant = cleanString(input.permit?.tenant) ?? tenantId;
+  const workspace = cleanString(input.permit?.workspace) ?? workspaceId;
+  ensurePermitMatch({
+    field: "subject",
+    expected: principalId,
+    actual: subject
+  });
+  ensurePermitMatch({ field: "tenant", expected: tenantId, actual: tenant });
+  ensurePermitMatch({
+    field: "workspace",
+    expected: workspaceId,
+    actual: workspace
+  });
+  const context = input.permit?.context ? { ...input.permit.context } : void 0;
+  return {
+    clerkId: cleanString(input.clerkId),
+    principalId,
+    tenantId,
+    workspaceId,
+    principalType,
+    authMode,
+    roles,
+    scopes,
+    delegationChain: input.delegationChain ? [...input.delegationChain] : [],
+    policyTraceId: cleanString(input.policyTraceId),
+    correlationId: cleanString(input.correlationId),
+    membershipId: cleanString(input.membershipId),
+    permit: {
+      subject,
+      tenant,
+      workspace,
+      resource: cleanString(input.permit?.resource),
+      action: cleanString(input.permit?.action),
+      relation: cleanString(input.permit?.relation),
+      context
+    }
+  };
+}
+function createCanonicalAuthHeaders(authContext) {
+  const headers = {
+    "x-lucern-principal-id": authContext.principalId,
+    "x-lucern-principal-type": authContext.principalType,
+    "x-lucern-tenant": authContext.tenantId,
+    "x-lucern-tenant-id": authContext.tenantId,
+    "x-lucern-workspace": authContext.workspaceId,
+    "x-lucern-workspace-id": authContext.workspaceId,
+    "x-lucern-auth-mode": authContext.authMode,
+    "x-lucern-roles": authContext.roles.join(","),
+    "x-lucern-scopes": authContext.scopes.join(","),
+    "x-lucern-permit-context": JSON.stringify(authContext.permit)
+  };
+  if (authContext.clerkId) {
+    headers["x-lucern-clerk-id"] = authContext.clerkId;
+    headers["x-lucern-user-id"] = authContext.clerkId;
+  }
+  if (authContext.delegationChain.length > 0) {
+    headers["x-lucern-delegation-chain"] = JSON.stringify(
+      authContext.delegationChain
+    );
+  }
+  if (authContext.policyTraceId) {
+    headers["x-lucern-policy-trace-id"] = authContext.policyTraceId;
+  }
+  if (authContext.correlationId) {
+    headers["x-correlation-id"] = authContext.correlationId;
+    headers["x-lucern-correlation-id"] = authContext.correlationId;
+  }
+  if (authContext.membershipId) {
+    headers["x-lucern-membership-id"] = authContext.membershipId;
+  }
+  return headers;
+}
+
 // src/coreClient.ts
 var LucernApiError = class extends Error {
   code;
@@ -109,8 +276,11 @@ function timeoutError(timeoutMs) {
   error.name = "AbortError";
   return error;
 }
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 function readPolicySummaryFromDetails(details) {
-  if (!details || typeof details !== "object" || Array.isArray(details)) {
+  if (!isRecord(details)) {
     return null;
   }
   const directSummary = details.summary;
@@ -118,11 +288,11 @@ function readPolicySummaryFromDetails(details) {
     return directSummary.trim();
   }
   const policy = details.policy;
-  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+  if (!isRecord(policy)) {
     return null;
   }
   const explanation = policy.explanation;
-  if (!explanation || typeof explanation !== "object" || Array.isArray(explanation)) {
+  if (!isRecord(explanation)) {
     return null;
   }
   const nestedSummary = explanation.summary;
@@ -131,16 +301,41 @@ function readPolicySummaryFromDetails(details) {
   }
   return null;
 }
+async function resolveConfiguredAuthContext(authContext) {
+  if (typeof authContext === "function") {
+    return await authContext();
+  }
+  return authContext;
+}
+function mergeHeaderRecord(base, addition) {
+  const headers = new Headers(base);
+  for (const [key, value] of Object.entries(addition)) {
+    const existing = headers.get(key);
+    if (existing !== null && existing !== value) {
+      throw new LucernSdkAuthContextError(
+        "policy_denied",
+        `Canonical Lucern SDK auth context conflicts with existing ${key} header.`
+      );
+    }
+    headers.set(key, value);
+  }
+  return Object.fromEntries(headers.entries());
+}
 function createGatewayRequestClient(config = {}) {
   const fetchImpl = config.fetchImpl ?? fetch;
   const baseUrl = config.baseUrl?.replace(/\/+$/, "") ?? "";
   const maxRetries = config.maxRetries ?? 2;
   const requestIdFactory = config.requestIdFactory ?? (() => generatePortableRequestId());
   async function resolveAuthHeaders() {
-    if (!config.getAuthHeaders) {
-      return {};
+    const base = config.getAuthHeaders ? await config.getAuthHeaders() : {};
+    const authContextInput = await resolveConfiguredAuthContext(
+      config.authContext
+    );
+    if (!authContextInput && !config.requireCanonicalAuthContext) {
+      return base;
     }
-    return await config.getAuthHeaders();
+    const authContext = normalizeCanonicalLucernAuthContext(authContextInput);
+    return mergeHeaderRecord(base, createCanonicalAuthHeaders(authContext));
   }
   async function fetchWithTimeout(url, init, timeoutMs) {
     const controller = new AbortController();
@@ -161,11 +356,11 @@ function createGatewayRequestClient(config = {}) {
     if (!text) {
       return null;
     }
-    try {
-      return JSON.parse(text);
-    } catch {
+    const parsed = tryParseGatewayEnvelopeJson(text);
+    if (!parsed.ok) {
       return null;
     }
+    return isRecord(parsed.value) ? parsed.value : null;
   }
   function resolveTimeoutMs(method, requestTimeoutMs) {
     if (typeof requestTimeoutMs === "number") {
@@ -177,16 +372,31 @@ function createGatewayRequestClient(config = {}) {
     }
     return config.timeoutMs ?? 15e3;
   }
+  function tryParseGatewayEnvelopeJson(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+      return { ok: false, reason: "non-json" };
+    }
+    try {
+      return { ok: true, value: JSON.parse(trimmed) };
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        return { ok: false, reason: "invalid-json", error };
+      }
+      throw error;
+    }
+  }
   function buildApiError(args) {
     const failure = args.failure;
-    const legacyError = failure && typeof failure.error === "object" && failure.error !== null ? failure.error : failure?.legacyError;
+    const legacyError = failure && isRecord(failure.error) ? failure.error : failure?.legacyError;
     const correlationId = failure?.correlationId ?? args.response.headers.get("x-lucern-correlation-id")?.trim() ?? args.requestId;
     const policyTraceId = failure?.policyTraceId ?? args.response.headers.get("x-lucern-policy-trace-id")?.trim() ?? null;
     const details = failure?.details ?? legacyError?.details;
     const policySummary = readPolicySummaryFromDetails(details);
+    const failureMessage = typeof failure?.error === "string" ? failure.error : legacyError?.message;
     return new LucernApiError({
       code: failure?.code ?? legacyError?.code ?? fallbackErrorCode(args.response.status),
-      message: policySummary ?? (typeof failure?.error === "string" ? failure.error : legacyError?.message ?? (args.response.ok ? "Platform API returned an invalid success payload." : "Platform API request failed.")),
+      message: policySummary ?? failureMessage ?? (args.response.ok ? "Platform API returned an invalid success payload." : "Platform API request failed."),
       status: args.response.status,
       invariant: failure?.invariant,
       suggestion: failure?.suggestion,
@@ -312,7 +522,7 @@ function createGatewayRequestClient(config = {}) {
 }
 
 // src/contextClient.ts
-function cleanString(value) {
+function cleanString2(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
 function cleanNumber(value) {
@@ -321,50 +531,55 @@ function cleanNumber(value) {
 function cleanBoolean(value) {
   return typeof value === "boolean" ? value : void 0;
 }
-function buildCompileContextRequest(topicId, input = {}) {
-  const payload = { topicId };
-  const query = cleanString(input.query);
+function buildCompileContextRequest(topicIdOrInput = {}, input = {}) {
+  const effectiveInput = typeof topicIdOrInput === "string" ? input : topicIdOrInput;
+  const payload = {};
+  const topicId = typeof topicIdOrInput === "string" ? cleanString2(topicIdOrInput) : cleanString2(effectiveInput.topicId);
+  if (topicId) {
+    payload.topicId = topicId;
+  }
+  const query = cleanString2(effectiveInput.query);
   if (query) {
     payload.query = query;
   }
-  const budget = cleanNumber(input.budget) ?? cleanNumber(input.tokenBudget);
+  const budget = cleanNumber(effectiveInput.budget) ?? cleanNumber(effectiveInput.tokenBudget);
   if (budget !== void 0) {
     payload.budget = budget;
   }
-  const ranking = cleanString(input.ranking) ?? cleanString(input.rankingProfile);
+  const ranking = cleanString2(effectiveInput.ranking) ?? cleanString2(effectiveInput.rankingProfile);
   if (ranking) {
     payload.ranking = ranking;
   }
-  const limit = cleanNumber(input.limit);
+  const limit = cleanNumber(effectiveInput.limit);
   if (limit !== void 0) {
     payload.limit = limit;
   }
-  const maxDepth = cleanNumber(input.maxDepth);
+  const maxDepth = cleanNumber(effectiveInput.maxDepth);
   if (maxDepth !== void 0) {
     payload.maxDepth = maxDepth;
   }
-  const includeEntities = cleanBoolean(input.includeEntities);
+  const includeEntities = cleanBoolean(effectiveInput.includeEntities);
   if (includeEntities !== void 0) {
     payload.includeEntities = includeEntities;
   }
-  const mode = cleanString(input.mode);
+  const mode = cleanString2(effectiveInput.mode);
   if (mode) {
     payload.mode = mode;
   }
-  const includeFailures = cleanBoolean(input.includeFailures);
+  const includeFailures = cleanBoolean(effectiveInput.includeFailures);
   if (includeFailures !== void 0) {
     payload.includeFailures = includeFailures;
   }
-  const worktreeId = cleanString(input.worktreeId);
+  const worktreeId = cleanString2(effectiveInput.worktreeId);
   if (worktreeId) {
     payload.worktreeId = worktreeId;
   }
-  const sessionId = cleanString(input.sessionId);
+  const sessionId = cleanString2(effectiveInput.sessionId);
   if (sessionId) {
     payload.sessionId = sessionId;
   }
-  if (Array.isArray(input.packWeightOverrides) && input.packWeightOverrides.length > 0) {
-    payload.packWeightOverrides = input.packWeightOverrides;
+  if (Array.isArray(effectiveInput.packWeightOverrides) && effectiveInput.packWeightOverrides.length > 0) {
+    payload.packWeightOverrides = effectiveInput.packWeightOverrides;
   }
   return {
     path: "/api/platform/v1/context/compile",
@@ -376,13 +591,20 @@ function createContextClient(config = {}) {
   const gateway = createGatewayRequestClient(config);
   return {
     /**
-     * Compile a focused reasoning context pack for a topic scope.
-     * @param topicId - The topic to compile context for.
+     * Compile a focused reasoning context pack.
+     * @param topicIdOrInput - Optional topic ID, or compile input for query-first resolution.
      * @param input - Optional compile parameters (query, budget, ranking, etc.).
      * @returns The compiled context payload with beliefs, questions, and evidence.
      */
-    async compile(topicId, input = {}) {
-      const request = buildCompileContextRequest(topicId, input);
+    async compile(topicIdOrInput = {}, input = {}) {
+      const request = buildCompileContextRequest(topicIdOrInput, input);
+      return gateway.request({
+        ...request,
+        body: request.body
+      });
+    },
+    async compileByQuery(input = {}) {
+      const request = buildCompileContextRequest(input);
       return gateway.request({
         ...request,
         body: request.body