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

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

@@ -1,9 +1,17 @@
-import type { WorkflowAutoFixPolicy, WorkflowProofArtifact, WorkflowStaffingHint } from "@lucern/contracts/workflow-runtime.contract";
-import type { DeprecatedBranchMetadata, LensPerspectiveType, LensPromptTemplateReference, LensStatus, LensTaskTemplate, LensWorkflowTemplate } from "@lucern/contracts/lens-workflow.contract";
+import type { WorkflowAutoFixPolicy, WorkflowProofArtifact, WorkflowStaffingHint } from "./contracts/workflowRuntime";
+import type { DeprecatedBranchMetadata, LensPerspectiveType, LensPromptTemplateReference, LensStatus, LensTaskTemplate, LensWorkflowTemplate } from "./contracts/lensWorkflow";
+/** JSON-safe object whose values are recursively JSON-serializable. */
 export type JsonObject = {
     [key: string]: JsonValue | undefined;
 };
+/** JSON-safe array whose elements are recursively JSON-serializable. */
 export type JsonArray = JsonValue[];
+/**
+ * Union of all JSON-safe primitive and composite types.
+ *
+ * Used throughout the SDK for metadata, details, and other
+ * schemaless payloads that must survive JSON round-tripping.
+ */
 export type JsonValue = null | boolean | number | string | JsonArray | JsonObject;
 /**
  * Canonical scope identifiers for SDK inputs and records.
@@ -28,6 +36,13 @@ export type ListResult<T, LegacyKey extends string = never> = {
 } & {
     [Key in LegacyKey]: T[];
 };
+/**
+ * Atomic knowledge unit in the reasoning graph.
+ *
+ * A belief carries a confidence score, belongs to a topic scope, and follows
+ * the knowledge-as-code lifecycle: unscored (draft) -> scored (immutable) -> forked (evolved).
+ * Confidence is always modulated via the append-only credence log, never overwritten.
+ */
 export type PlatformBeliefRecord = {
     nodeId: string;
     globalId?: string;
@@ -51,7 +66,9 @@ export type PlatformBeliefRecord = {
     updatedAt?: number;
     createdBy?: string;
 };
+/** Response returned after creating a new belief node. */
 export type CreateBeliefResponse = PlatformBeliefRecord;
+/** Response returned after an append-only confidence modulation on a belief. */
 export type ModulateConfidenceResponse = {
     nodeId: string;
     newConfidence?: number;
@@ -62,10 +79,18 @@ export type ModulateConfidenceResponse = {
     certainty?: number;
     recordedAt?: number;
 };
+/** Response returned after forking a scored belief into a new formulation. The new node carries a `supersedes` edge to the parent. */
 export interface ForkBeliefResponse extends PlatformBeliefRecord {
     parentNodeId?: string;
     forkReason?: string;
 }
+/**
+ * Generic graph node spanning L1-L4 epistemic layers.
+ *
+ * Nodes include beliefs (L3), evidence (L2), sources (L1), and judgments (L4).
+ * The `nodeType` field discriminates the layer; `confidence` is meaningful only
+ * for belief-typed nodes.
+ */
 export type PlatformGraphNode = {
     nodeId?: string;
     globalId?: string;
@@ -86,6 +111,13 @@ export type PlatformGraphNode = {
     createdAt?: number;
     updatedAt?: number;
 };
+/**
+ * Directed edge between two graph nodes.
+ *
+ * Weight indicates support strength: -1.0 (contradicts) to +1.0 (strongly supports).
+ * The `edgeType` field classifies the relationship (informs, tests, depends_on, supersedes, etc.).
+ * Layer transition rules are enforced: L1 -> L3 direct edges are forbidden.
+ */
 export type PlatformGraphEdge = {
     edgeId?: string;
     globalId?: string;
@@ -104,22 +136,146 @@ export type PlatformGraphEdge = {
     createdAt?: number;
     updatedAt?: number;
 };
+/** The resolved principal context returned by the public SDK identity surface. */
+export type SdkPrincipalContext = {
+    principalId: string;
+    principalType: "user" | "human" | "service" | "group" | "external_viewer" | "agent";
+    tenantId: string | null;
+    workspaceId: string | null;
+    scopes: string[];
+    roles: string[];
+    isPlatformAdmin: boolean;
+    isTenantAdmin: boolean;
+    isWorkspaceAdmin: boolean;
+    authMode?: string;
+    sessionId?: string;
+    delegatedBy?: string;
+    expiresAt?: number;
+};
+/** Evidence node record returned by evidence lifecycle APIs. */
+export type PlatformEvidenceRecord = {
+    nodeId?: string;
+    evidenceId?: string;
+    globalId?: string;
+    topicId?: string;
+    text?: string;
+    canonicalText?: string;
+    title?: string;
+    kind?: string;
+    status?: string;
+    source?: string;
+    sourceUrl?: string;
+    externalSourceUrl?: string;
+    linkedBeliefId?: string;
+    linkedQuestionId?: string;
+    verificationStatus?: string;
+    metadata?: JsonObject | null;
+    tags?: string[];
+    createdAt?: number;
+    updatedAt?: number;
+    createdBy?: string;
+};
+/** Question node record returned by question lifecycle APIs. */
+export type PlatformQuestionRecord = {
+    nodeId?: string;
+    questionId?: string;
+    globalId?: string;
+    topicId?: string;
+    text?: string;
+    canonicalText?: string;
+    question?: string;
+    status?: string;
+    priority?: string;
+    category?: string;
+    questionType?: string;
+    linkedBeliefId?: string;
+    linkedWorktreeId?: string;
+    conviction?: number;
+    answerCompleteness?: string;
+    convictionRationale?: string;
+    metadata?: JsonObject | null;
+    createdAt?: number;
+    updatedAt?: number;
+    createdBy?: string;
+};
+/** Answer record returned by answer/question APIs. */
+export type PlatformAnswerRecord = {
+    nodeId?: string | null;
+    answerId?: string | null;
+    globalId?: string | null;
+    questionNodeId?: string | null;
+    answerText?: string | null;
+    confidence?: string | null;
+    versionNumber?: number;
+    isLatest?: boolean;
+    evidenceCount?: number;
+    answeredBy?: string;
+    answerSource?: string;
+    status?: string;
+    metadata?: JsonObject | null;
+    createdAt?: number;
+    updatedAt?: number;
+};
+/** Contract record returned by contract APIs. */
+export type PlatformContract = {
+    contractId?: string;
+    beliefId?: string;
+    beliefNodeId?: string;
+    title?: string;
+    description?: string;
+    status?: string;
+    conditionType?: string;
+    direction?: string;
+    condition?: JsonValue;
+    deadline?: number;
+    compositeOf?: string[];
+    compositeOperator?: string;
+    modulation?: JsonValue;
+    evaluationSchedule?: string;
+    periodicIntervalMs?: number;
+    createdAt?: number;
+    updatedAt?: number;
+    metadata?: JsonObject | null;
+};
+/** Evaluation result for an epistemic contract. */
+export type PlatformContractEvaluation = {
+    contractId?: string;
+    beliefId?: string;
+    beliefNodeId?: string;
+    status?: string;
+    evaluationStatus?: string;
+    satisfied?: boolean;
+    trigger?: JsonValue;
+    evaluatedAt?: number;
+    nextEvaluationAt?: number;
+    modulationApplied?: JsonValue;
+    details?: JsonValue;
+};
+/** Response from a graph node query. May be a single node, an array, or null if not found. */
 export type QueryNodesResponse = PlatformGraphNode | PlatformGraphNode[] | null;
+/** Response returned after creating a new graph node. */
 export type CreateNodeResponse = PlatformGraphNode;
+/** Response returned after updating an existing graph node. */
 export type UpdateNodeResponse = PlatformGraphNode;
+/** Response from a graph edge query. May be a single edge, an array, or null if not found. */
 export type QueryEdgesResponse = PlatformGraphEdge | PlatformGraphEdge[] | null;
+/** Response returned after creating a new graph edge. */
 export type CreateEdgeResponse = PlatformGraphEdge;
+/** Count of edges removed in a bulk delete operation. */
 export type DeleteEdgeCountResponse = {
     removed?: number;
     deleted?: number;
 };
+/** Response from an edge delete operation. May include removed edge details or a count summary. */
 export type DeleteEdgeResponse = PlatformGraphEdge | PlatformGraphEdge[] | DeleteEdgeCountResponse | null;
+/** Local neighborhood around one or more graph nodes, including connected nodes and edges up to `maxDepth`. */
 export type GraphNeighborhoodResponse = {
     nodes?: PlatformGraphNode[];
     edges?: PlatformGraphEdge[];
     rootGlobalIds?: string[];
     maxDepth?: number;
 };
+/** Path traversal result between two graph nodes, including direct edges and the connected subgraph. */
 export type GraphPathResponse = {
     fromGlobalId: string;
     toGlobalId: string;
@@ -127,11 +283,14 @@ export type GraphPathResponse = {
     directEdges: PlatformGraphEdge[];
     connectedGraph: GraphNeighborhoodResponse;
 };
+/** Available graph analytics metric types for structural analysis. */
 export type GraphAnalyticsMetric = "graph_stats" | "contradiction_tension" | "confirmation_bias" | "reasoning_depth" | "knowledge_frontier";
+/** Response envelope for a graph analytics computation, parameterized by metric type. */
 export type GraphAnalyticsResponse<Metric extends GraphAnalyticsMetric = GraphAnalyticsMetric> = {
     metric: Metric;
     payload: JsonValue;
 };
+/** A thematic branch within a topic. Worktrees are checked out from branches. */
 export type WorkflowBranchRecord = {
     branchId?: string;
     topicId?: string;
@@ -143,12 +302,20 @@ export type WorkflowBranchRecord = {
     updatedAt?: number;
     createdBy?: string;
 } & Partial<DeprecatedBranchMetadata>;
+/**
+ * Isolated investigation scope within a branch.
+ *
+ * Worktrees track hypotheses, dependencies, proof artifacts, and execution sequencing.
+ * Beliefs committed within a worktree can be freely amended (draft code on a feature branch).
+ * When investigation is complete, `merge` integrates findings into the stable knowledge base.
+ */
 export type WorkflowWorktreeRecord = {
     worktreeId?: string;
     topicId?: string;
     branchId?: string;
     title?: string;
     status?: string;
+    phase?: string;
     hypothesis?: string;
     questionCount?: number;
     taskCount?: number;
@@ -171,8 +338,16 @@ export type WorkflowWorktreeRecord = {
     updatedAt?: number;
     createdBy?: string;
 };
+/** Paginated list of workflow branches. */
 export type ListBranchesResponse = ListResult<WorkflowBranchRecord, "branches">;
+/** Response returned after creating a new workflow branch. */
 export type CreateBranchResponse = WorkflowBranchRecord;
+/**
+ * Reusable analytical perspective with prompt templates, workflow templates, and task templates.
+ *
+ * A lens overlays a topic with a specific investigation frame. Multiple lenses can coexist
+ * on the same topic. Lenses persist across worktrees and carry operational scaffolding.
+ */
 export type WorkflowLensRecord = {
     lensId?: string;
     workspaceId?: string;
@@ -191,6 +366,7 @@ export type WorkflowLensRecord = {
     updatedAt?: number;
     createdBy?: string;
 };
+/** Record of a lens being applied to (or removed from) a topic. */
 export type WorkflowLensBindingRecord = {
     bindingId?: string;
     lensId?: string;
@@ -202,14 +378,20 @@ export type WorkflowLensBindingRecord = {
     updatedAt?: number;
     metadata?: JsonObject | null;
 };
+/** Paginated list of workflow lenses. */
 export type ListLensesResponse = ListResult<WorkflowLensRecord, "lenses">;
+/** Response returned after creating a new lens. */
 export type CreateLensResponse = WorkflowLensRecord;
+/** Response returned after binding or unbinding a lens to a topic. */
 export type LensTopicBindingResponse = WorkflowLensBindingRecord;
+/** Paginated list of worktrees with optional track and band summary counts. */
 export type ListWorktreesResponse = ListResult<WorkflowWorktreeRecord, "worktrees"> & {
     tracks?: Record<string, number>;
     bands?: Record<string, number>;
 };
+/** Response returned after adding a new worktree to a topic. */
 export type AddWorktreeResponse = WorkflowWorktreeRecord;
+/** Response returned after merging a worktree's findings into the stable knowledge base. */
 export type MergeWorktreeResponse = {
     worktreeId?: string;
     status?: string;
@@ -218,6 +400,7 @@ export type MergeWorktreeResponse = {
     summary?: string;
     mergedAt?: number;
 };
+/** Response returned after opening a pull request for peer review of a worktree. */
 export type OpenPullRequestResponse = {
     pullRequestId?: string;
     worktreeId?: string;
@@ -226,6 +409,7 @@ export type OpenPullRequestResponse = {
     reviewers?: string[];
     createdAt?: number;
 };
+/** Response returned after pushing scored beliefs from a merged worktree to a target context. */
 export type PushWorktreeResponse = {
     pushId?: string;
     pushedCount?: number;
@@ -233,6 +417,7 @@ export type PushWorktreeResponse = {
     status?: string;
     createdAt?: number;
 };
+/** Lightweight topic record used in workflow context (topic switching, listing). */
 export type WorkflowTopicRecord = {
     topicId: string;
     name: string;
@@ -241,7 +426,9 @@ export type WorkflowTopicRecord = {
     tenantId?: string;
     workspaceId?: string;
 };
+/** Paginated list of workflow topic records. */
 export type ListTopicsResponse = ListResult<WorkflowTopicRecord, "topics">;
+/** Response returned after switching the active topic context. */
 export type SwitchTopicContextResponse = {
     topicId: string;
     topicName: string;
@@ -260,6 +447,7 @@ export type ListProjectsResponse = ListTopicsResponse;
  * @deprecated Use SwitchTopicContextResponse.
  */
 export type SwitchProjectContextResponse = SwitchTopicContextResponse;
+/** Full topic record with hierarchy, visibility, and tenant/workspace scoping. */
 export type TopicRecord = {
     topicId?: string;
     id?: string;
@@ -276,13 +464,17 @@ export type TopicRecord = {
     createdAt?: number;
     updatedAt?: number;
 };
+/** Paginated list of full topic records. */
 export type TopicListResponse = ListResult<TopicRecord, "topics">;
+/** Topic record extended with ancestry path for tree traversals. */
 export type TopicTreeNode = TopicRecord & {
     path?: string[];
 };
+/** Response containing the full topic hierarchy from a given root. */
 export type TopicTreeResponse = {
     tree: TopicTreeNode[];
 };
+/** Per-topic belief, question, and evidence counts for coverage analysis. */
 export type TopicCoverageRecord = {
     topicId: string;
     name: string;
@@ -293,6 +485,7 @@ export type TopicCoverageRecord = {
     evidence: number;
     coverage: "full" | "partial" | "empty";
 };
+/** Aggregate coverage statistics across the topic tree. */
 export type TopicCoverageSummary = {
     totalTopics: number;
     coveredTopics: number;
@@ -302,11 +495,13 @@ export type TopicCoverageSummary = {
     totalQuestions: number;
     totalEvidence: number;
 };
+/** Full coverage report with per-topic records and an aggregate summary. */
 export type TopicCoverageResponse = {
     topics: TopicCoverageRecord[];
     summary: TopicCoverageSummary;
     scopeTopicId?: string | null;
 };
+/** Response returned after creating a new execution task. */
 export type CreateTaskResponse = {
     taskId: string;
     status: string;
@@ -315,18 +510,27 @@ export type CreateTaskResponse = {
     linkedQuestionId?: string;
     linkedBeliefId?: string;
 };
+/** Response returned after marking a task as complete. */
 export type CompleteTaskResponse = {
     taskId: string;
     completedAt: number;
     outputSummary: string;
     status?: string;
 };
+/** Response returned after updating a task's fields. */
 export type UpdateTaskResponse = {
     taskId: string;
     updatedAt: number;
     status?: string;
     title?: string;
 };
+/**
+ * Irreversible commitment based on the current epistemic state.
+ *
+ * A judgment synthesizes beliefs, evidence, and uncertainties into a determination.
+ * Once issued, it is evaluated against the epistemic state that existed when it was made
+ * (knowledge horizon evaluation, Invariant #10). Judgments are L4 entities in the graph.
+ */
 export type JudgmentRecord = {
     _id?: string;
     judgmentId?: string;
@@ -352,8 +556,11 @@ export type JudgmentRecord = {
     decisionMakers?: string[];
     themeIds?: string[];
 };
+/** Paginated list of judgment records. */
 export type ListJudgmentsResponse = ListResult<JudgmentRecord, "judgments">;
+/** A single judgment record, or null if not found. */
 export type GetJudgmentResponse = JudgmentRecord | null;
+/** Response returned after recording a new judgment, including the knowledge horizon snapshot. */
 export type RecordJudgmentResponse = {
     nodeId?: string;
     judgmentId?: string;
@@ -366,12 +573,14 @@ export type RecordJudgmentResponse = {
         contradictionCount?: number;
     };
 };
+/** Response returned after recording the real-world outcome of a judgment. */
 export type RecordJudgmentOutcomeResponse = {
     success?: boolean;
     judgmentId?: string;
     outcome?: string;
     updatedAt?: number;
 };
+/** Assessment of whether the epistemic state is sufficient to issue a judgment. */
 export type JudgmentReadinessResponse = {
     ready?: boolean;
     beliefCount?: number;
@@ -382,10 +591,12 @@ export type JudgmentReadinessResponse = {
     blockers?: string[];
     recommendation?: string;
 };
+/** Calibration statistics for a single judgment type bucket. */
 export type JudgmentCalibrationBucket = {
     total?: number;
     successful?: number;
 };
+/** Calibration analysis comparing judgment confidence against real outcomes. */
 export type JudgmentCalibrationResponse = {
     totalDecisions?: number;
     decisionsWithOutcomes?: number;
@@ -396,6 +607,7 @@ export type JudgmentCalibrationResponse = {
     } | null;
     byType?: Record<string, JudgmentCalibrationBucket>;
 };
+/** A judgment that has been made but whose real-world outcome has not yet been recorded. */
 export type PendingJudgmentOutcomeRecord = {
     _id?: string;
     globalId?: string;
@@ -408,12 +620,15 @@ export type PendingJudgmentOutcomeRecord = {
     outcome?: string;
     status?: string;
 };
+/** Paginated list of judgments pending outcome review. */
 export type PendingJudgmentOutcomeReviewResponse = ListResult<PendingJudgmentOutcomeRecord, "reviews">;
+/** A single integrity issue found during judgment transition audit. */
 export type JudgmentTransitionAuditIntegrityIssue = {
     code?: string;
     severity?: "error" | "warning" | string;
     message?: string;
 };
+/** Integrity check result for a single judgment's transition audit trail. */
 export type JudgmentTransitionAuditIntegrityCheck = {
     decisionNodeId?: string;
     globalId?: string;
@@ -422,6 +637,7 @@ export type JudgmentTransitionAuditIntegrityCheck = {
     auditEventCount?: number;
     issues?: JudgmentTransitionAuditIntegrityIssue[];
 };
+/** Full integrity report for all judgment transitions within a topic. */
 export type JudgmentTransitionAuditIntegrityResponse = {
     topicId?: string;
     checkedDecisionCount?: number;
@@ -430,6 +646,7 @@ export type JudgmentTransitionAuditIntegrityResponse = {
     issueTypeBreakdown?: Record<string, number>;
     checks?: JudgmentTransitionAuditIntegrityCheck[];
 };
+/** A report template definition for generating structured reports. */
 export type ReportTemplateRecord = {
     templateId?: string;
     slug?: string;
@@ -438,7 +655,9 @@ export type ReportTemplateRecord = {
     description?: string;
     status?: string;
 };
+/** Response for report template queries. May be a list, a single template, or null. */
 export type ReportTemplatesResponse = ListResult<ReportTemplateRecord, "templates"> | ReportTemplateRecord | null;
+/** A generated report instance for a topic. */
 export type ProjectReportRecord = {
     reportId?: string;
     topicId?: string;
@@ -449,7 +668,9 @@ export type ProjectReportRecord = {
     createdAt?: number;
     updatedAt?: number;
 };
+/** Paginated list of generated reports. */
 export type ProjectReportsResponse = ListResult<ProjectReportRecord, "reports">;
+/** A single section within a generated report. */
 export type ReportSectionRecord = {
     sectionId?: string;
     slug?: string;
@@ -460,6 +681,7 @@ export type ReportSectionRecord = {
     order?: number;
     metadata?: JsonObject | null;
 };
+/** A complete report including all its sections. */
 export type ReportWithSectionsResponse = {
     reportId?: string;
     topicId?: string;

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

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

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

@@ -0,0 +1,2 @@
+/** Current SDK package version. */
+export const LUCERN_SDK_VERSION = "0.2.0-alpha.1";

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

@@ -1,16 +1,23 @@
 import { type GatewayClientConfig, LucernApiError } from "./coreClient";
-import type { LensPerspectiveType, LensPromptTemplateReference, LensStatus, LensTaskTemplate, LensWorkflowTemplate } from "@lucern/contracts/lens-workflow.contract";
-import type { WorkflowAutoFixPolicy, WorkflowProofArtifact, WorkflowStaffingHint } from "@lucern/contracts/workflow-runtime.contract";
+import type { LensPerspectiveType, LensPromptTemplateReference, LensStatus, LensTaskTemplate, LensWorkflowTemplate } from "./contracts/lensWorkflow";
+import type { WorkflowAutoFixPolicy, WorkflowProofArtifact, WorkflowStaffingHint } from "./contracts/workflowRuntime";
 import type { CompleteTaskResponse, CreateTaskResponse, JsonObject, ListTopicsResponse, ListWorktreesResponse, MergeWorktreeResponse, OpenPullRequestResponse, PushWorktreeResponse, SwitchTopicContextResponse, TopicIdentifierInput, UpdateTaskResponse, WorkflowBranchRecord, WorkflowLensRecord, WorkflowWorktreeRecord } from "./types";
 export { LucernApiError };
 export type { PlatformGatewaySuccess } from "./coreClient";
 export type { AddWorktreeResponse, CompleteTaskResponse, CreateBranchResponse, CreateLensResponse, CreateTaskResponse, LensTopicBindingResponse, ListBranchesResponse, ListLensesResponse, ListTopicsResponse, ListWorktreesResponse, MergeWorktreeResponse, OpenPullRequestResponse, PushWorktreeResponse, SwitchTopicContextResponse, UpdateTaskResponse, } from "./types";
+/** Configuration for the workflow client. */
 export type WorkflowClientConfig = GatewayClientConfig;
+/** Lifecycle status of a workflow branch. */
 export type WorkflowBranchStatus = "dormant" | "active" | "archived";
+/** Lifecycle status of a workflow lens. */
 export type WorkflowLensStatus = LensStatus;
+/** Analytical perspective type for a lens overlay. */
 export type WorkflowLensPerspectiveType = LensPerspectiveType;
+/** Lifecycle status of a workflow worktree. */
 export type WorkflowWorktreeStatus = "planning" | "active" | "paused" | "completed" | "merged" | "failed" | "archived";
+/** Possible outcomes when merging worktree findings into the main belief line. */
 export type WorkflowMergeOutcome = "validated" | "invalidated" | "forked" | "inconclusive";
+/** Input for creating a new workflow worktree. */
 export type AddWorktreeInput = {
     title: string;
     topicId?: string;
@@ -29,6 +36,7 @@ export type AddWorktreeInput = {
     lastReconciledAt?: number;
     autoFixPolicy?: WorkflowAutoFixPolicy;
 } & TopicIdentifierInput;
+/** Input for merging worktree findings with belief confidence outcomes. */
 export type MergeInput = {
     outcomes: Array<{
         beliefId: string;
@@ -37,6 +45,7 @@ export type MergeInput = {
     }>;
     summary?: string;
 };
+/** Input for updating the beliefs and questions tracked by a worktree. */
 export type UpdateWorktreeTargetsInput = {
     worktreeId: string;
     addBeliefIds?: string[];
@@ -44,13 +53,41 @@ export type UpdateWorktreeTargetsInput = {
     removeBeliefIds?: string[];
     removeQuestionIds?: string[];
 };
+/** Input for marking a worktree complete with recorded outcomes. */
+export type CompleteWorktreeInput = {
+    worktreeId: string;
+    keyFindings?: string[];
+    decisionsReached?: string[];
+    nextSteps?: string[];
+};
+/** Input for moving a worktree forward to its next phase. */
+export type AdvanceWorktreePhaseInput = {
+    worktreeId: string;
+};
+/** Input for forcing a worktree into a specific phase. */
+export type SetWorktreePhaseInput = {
+    worktreeId: string;
+    phase: string;
+};
+/** Input for patching arbitrary structured worktree state. */
+export type PatchWorktreeStateInput = {
+    worktreeId: string;
+    patch: JsonObject;
+};
+/** Input for batch-creating worktrees through the workflow surface. */
+export type BulkCreateWorktreesInput = {
+    worktrees: unknown[];
+};
+/** Input for listing accessible topic contexts. */
 export type ListTopicsInput = {
     includeShared?: boolean;
     limit?: number;
 };
+/** Input for switching the active topic context by name. */
 export type SwitchTopicContextInput = {
     targetTopicName: string;
 };
+/** Input for creating a workflow task linked to a question or worktree. */
 export type CreateTaskInput = {
     title: string;
     topicId?: string;
@@ -61,10 +98,12 @@ export type CreateTaskInput = {
     description?: string;
     priority?: "low" | "medium" | "high" | "urgent";
 } & TopicIdentifierInput;
+/** Input for marking a workflow task as completed with an output summary. */
 export type CompleteTaskInput = {
     outputSummary: string;
     evidenceCreated?: boolean;
 };
+/** Input for partially updating an existing workflow task. */
 export type UpdateTaskInput = {
     title?: string;
     description?: string;
@@ -77,6 +116,8 @@ export type UpdateTaskInput = {
 /**
  * Create the workflow client for lenses, legacy branches, worktrees, context,
  * and tasks.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to manage branches, lenses, worktrees, topics, and tasks.
  */
 export declare function createWorkflowClient(config?: WorkflowClientConfig): {
     /**
@@ -174,6 +215,26 @@ export declare function createWorkflowClient(config?: WorkflowClientConfig): {
      * Update targeted beliefs/questions for a worktree.
      */
     updateWorktreeTargets(input: UpdateWorktreeTargetsInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<WorkflowWorktreeRecord>>;
+    /**
+     * Mark a worktree record complete.
+     */
+    completeWorktree(input: CompleteWorktreeInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Advance a worktree to its next lifecycle phase.
+     */
+    advanceWorktreePhase(input: AdvanceWorktreePhaseInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Force a worktree into a specific lifecycle phase.
+     */
+    setWorktreePhase(input: SetWorktreePhaseInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Patch opaque worktree state for orchestration flows.
+     */
+    patchWorktreeState(input: PatchWorktreeStateInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Batch create worktree records.
+     */
+    bulkCreateWorktrees(input: BulkCreateWorktreesInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
     /**
      * Open a pull request for a worktree.
      */