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

package/src/contracts/sdkTools.ts

@@ -0,0 +1 @@
+export * from "./sdk-tools.contract";

package/src/contracts/workflow-runtime.contract.ts

@@ -0,0 +1,440 @@
+/**
+ * Workflow Runtime Contract v1
+ *
+ * Canonical TypeScript contract for Lucern's graph-local workflow runtime.
+ * WF-1 defines the typed substrate for:
+ *   - workflow definitions and run receipts
+ *   - action mutation tiering and approval expectations
+ *   - hooks over worktree/question/evidence/inbox events
+ *   - output unions for domain-specific artifacts
+ *   - deterministic integrity checks and operational metadata
+ *
+ * BREAKING CHANGE RULES:
+ *   - Adding optional fields is NON-breaking
+ *   - Removing fields or renaming enum values is BREAKING
+ *   - Reclassifying a mutation tier is BREAKING
+ *   - Changing canonical workflow IDs is BREAKING
+ */
+
+export const WORKFLOW_RUNTIME_SCHEMA_VERSION = "1.0.0" as const;
+
+export const WORKFLOW_MUTATION_TIERS = [
+  "read_only",
+  "low_risk_write",
+  "high_risk_write",
+] as const;
+export type WorkflowMutationTier = (typeof WORKFLOW_MUTATION_TIERS)[number];
+
+export const WORKFLOW_APPROVAL_MODES = [
+  "none",
+  "audit_only",
+  "human_required",
+  "auto_approve",
+] as const;
+export type WorkflowApprovalMode = (typeof WORKFLOW_APPROVAL_MODES)[number];
+
+export const DEFAULT_TIER_APPROVAL_MODE: Readonly<
+  Record<WorkflowMutationTier, WorkflowApprovalMode>
+> = {
+  read_only: "none",
+  low_risk_write: "audit_only",
+  high_risk_write: "human_required",
+} as const;
+
+export const WORKFLOW_ACTION_KINDS = [
+  "context_pack",
+  "integrity_check",
+  "lucern_tool",
+  "report_compile",
+  "brief_publish",
+  "notification",
+  "custom",
+] as const;
+export type WorkflowActionKind = (typeof WORKFLOW_ACTION_KINDS)[number];
+
+export const WORKFLOW_HOOK_EVENTS = [
+  "schedule.tick",
+  "worktree.activated",
+  "worktree.completed",
+  "question.created",
+  "question.answered",
+  "evidence.appended",
+  "inbox.item_created",
+] as const;
+export type WorkflowHookEvent = (typeof WORKFLOW_HOOK_EVENTS)[number];
+
+export const WORKFLOW_OUTPUT_KINDS = [
+  "engineering_brief",
+  "research_memo",
+  "strategy_artifact",
+  "inbox_summary",
+  "pipeline_brief",
+  "structured_payload",
+] as const;
+export type WorkflowOutputKind = (typeof WORKFLOW_OUTPUT_KINDS)[number];
+
+export const WORKFLOW_RUN_STATUSES = [
+  "queued",
+  "running",
+  "awaiting_approval",
+  "completed",
+  "failed",
+  "cancelled",
+] as const;
+export type WorkflowRunStatus = (typeof WORKFLOW_RUN_STATUSES)[number];
+
+export const WORKFLOW_TRIGGER_KINDS = [
+  "manual",
+  "schedule",
+  "hook",
+] as const;
+export type WorkflowTriggerKind = (typeof WORKFLOW_TRIGGER_KINDS)[number];
+
+export const WORKFLOW_PROOF_ARTIFACT_KINDS = [
+  "report",
+  "brief",
+  "artifact",
+  "dashboard",
+  "test_evidence",
+] as const;
+export type WorkflowProofArtifactKind =
+  (typeof WORKFLOW_PROOF_ARTIFACT_KINDS)[number];
+
+export const WORKFLOW_STAFFING_HINTS = [
+  "solo",
+  "backend+tests",
+  "fullstack",
+  "mcp+tests",
+] as const;
+export type WorkflowStaffingHint = (typeof WORKFLOW_STAFFING_HINTS)[number];
+
+export const WORKFLOW_AUTO_FIX_MODES = [
+  "disabled",
+  "dry_run",
+  "safe",
+  "aggressive",
+] as const;
+export type WorkflowAutoFixMode = (typeof WORKFLOW_AUTO_FIX_MODES)[number];
+
+export const WORKFLOW_INTEGRITY_CHECKS = [
+  "null_dependency_refs",
+  "superseded_blockers",
+  "band_order_inconsistency",
+  "sparse_shaping",
+  "failed_completed_gate",
+] as const;
+export type WorkflowIntegrityCheckId =
+  (typeof WORKFLOW_INTEGRITY_CHECKS)[number];
+
+export type WorkflowProofArtifact = {
+  kind: WorkflowProofArtifactKind;
+  label: string;
+  required?: boolean;
+  sourceRef?: string;
+};
+
+export type WorkflowAutoFixPolicy = {
+  mode: WorkflowAutoFixMode;
+  maxActionsPerRun?: number;
+  permittedMutationTiers?: WorkflowMutationTier[];
+  requireAuditTrail?: boolean;
+  escalationGate?: string;
+};
+
+export const DEFAULT_WORKFLOW_AUTO_FIX_POLICY: WorkflowAutoFixPolicy = {
+  mode: "disabled",
+  permittedMutationTiers: ["read_only"],
+  requireAuditTrail: true,
+};
+
+export type WorkflowApprovalPolicy = {
+  mode: WorkflowApprovalMode;
+  approvalGate?: string;
+  autoApprovePolicyKey?: string;
+  rationaleRequired?: boolean;
+};
+
+export type WorkflowOutputBase = {
+  outputId: string;
+  kind: WorkflowOutputKind;
+  title: string;
+  summary: string;
+  generatedAt?: number;
+};
+
+export type EngineeringBriefOutput = WorkflowOutputBase & {
+  kind: "engineering_brief";
+  sections: Array<{
+    heading: string;
+    body: string;
+  }>;
+  touchedPaths?: string[];
+};
+
+export type ResearchMemoOutput = WorkflowOutputBase & {
+  kind: "research_memo";
+  claims: string[];
+  evidenceRefs?: string[];
+};
+
+export type StrategyArtifactOutput = WorkflowOutputBase & {
+  kind: "strategy_artifact";
+  recommendations: string[];
+  decisionWindow?: string;
+};
+
+export type InboxSummaryOutput = WorkflowOutputBase & {
+  kind: "inbox_summary";
+  channel: "developer_portal" | "chat" | "ops";
+  inboxTitle: string;
+  inboxBody: string;
+};
+
+export type PipelineBriefOutput = WorkflowOutputBase & {
+  kind: "pipeline_brief";
+  hingeWorktreeId?: string;
+  groupedBlockers: Array<{
+    blocker: string;
+    blockedWorktreeIds: string[];
+  }>;
+};
+
+export type StructuredPayloadOutput = WorkflowOutputBase & {
+  kind: "structured_payload";
+  payload: Record<string, unknown>;
+};
+
+export type WorkflowOutputContract =
+  | EngineeringBriefOutput
+  | ResearchMemoOutput
+  | StrategyArtifactOutput
+  | InboxSummaryOutput
+  | PipelineBriefOutput
+  | StructuredPayloadOutput;
+
+export type WorkflowActionContract = {
+  actionId: string;
+  kind: WorkflowActionKind;
+  title: string;
+  description: string;
+  mutationTier: WorkflowMutationTier;
+  toolName?: string;
+  produces?: WorkflowOutputKind[];
+  idempotent?: boolean;
+  approval: WorkflowApprovalPolicy;
+};
+
+export type WorkflowHookContract = {
+  hookId: string;
+  event: WorkflowHookEvent;
+  description: string;
+  condition?: string;
+  actionIds: string[];
+};
+
+export type WorkflowTriggerContract =
+  | {
+      kind: "manual";
+      description?: string;
+    }
+  | {
+      kind: "schedule";
+      cadence: "hourly" | "daily" | "weekly";
+      timezone?: string;
+    }
+  | {
+      kind: "hook";
+      event: WorkflowHookEvent;
+    };
+
+export type WorkflowDefinitionV1 = {
+  workflowId: string;
+  version: typeof WORKFLOW_RUNTIME_SCHEMA_VERSION;
+  title: string;
+  description: string;
+  trigger: WorkflowTriggerContract;
+  staffingHint?: WorkflowStaffingHint;
+  proofArtifacts?: WorkflowProofArtifact[];
+  autoFixPolicy?: WorkflowAutoFixPolicy;
+  actions: readonly WorkflowActionContract[];
+  hooks?: readonly WorkflowHookContract[];
+  outputs: readonly WorkflowOutputKind[];
+  integrityChecks?: readonly WorkflowIntegrityCheckId[];
+};
+
+export type WorkflowRunReceiptV1 = {
+  runId: string;
+  workflowId: string;
+  status: WorkflowRunStatus;
+  triggeredBy: WorkflowTriggerKind;
+  startedAt: number;
+  completedAt?: number;
+  outputKinds: WorkflowOutputKind[];
+  approvalsRequired?: number;
+};
+
+export const NIGHTLY_RECONCILIATION_WORKFLOW_ID =
+  "workflow.pipeline_reconciliation.v1" as const;
+
+export const MORNING_BRIEF_WORKFLOW_ID =
+  "workflow.morning_brief.v1" as const;
+
+export const CANONICAL_WORKFLOW_DEFINITIONS: readonly WorkflowDefinitionV1[] = [
+  {
+    workflowId: NIGHTLY_RECONCILIATION_WORKFLOW_ID,
+    version: WORKFLOW_RUNTIME_SCHEMA_VERSION,
+    title: "Nightly Pipeline Reconciliation",
+    description:
+      "Runs deterministic integrity checks, compiles pipeline state, and emits an operator-facing reconciliation brief.",
+    trigger: {
+      kind: "schedule",
+      cadence: "daily",
+      timezone: "America/New_York",
+    },
+    staffingHint: "backend+tests",
+    proofArtifacts: [
+      {
+        kind: "report",
+        label: "Pipeline reconciliation report",
+        required: true,
+      },
+      {
+        kind: "test_evidence",
+        label: "Integrity check receipt",
+        required: true,
+      },
+    ],
+    autoFixPolicy: {
+      mode: "safe",
+      maxActionsPerRun: 5,
+      permittedMutationTiers: ["read_only", "low_risk_write"],
+      requireAuditTrail: true,
+      escalationGate: "gate:workflow-runtime-contract-live",
+    },
+    actions: [
+      {
+        actionId: "compile_context_pack",
+        kind: "context_pack",
+        title: "Compile pipeline context",
+        description: "Build the ranked context needed for deterministic checks.",
+        mutationTier: "read_only",
+        produces: ["structured_payload"],
+        idempotent: true,
+        approval: { mode: "none" },
+      },
+      {
+        actionId: "run_integrity_checks",
+        kind: "integrity_check",
+        title: "Run integrity checks",
+        description:
+          "Evaluate dependency references, blockers, execution bands, shaping coverage, and completed gates.",
+        mutationTier: "read_only",
+        produces: ["structured_payload"],
+        idempotent: true,
+        approval: { mode: "none" },
+      },
+      {
+        actionId: "record_followup_questions",
+        kind: "lucern_tool",
+        title: "Record follow-up questions",
+        description:
+          "Create or reopen operator-facing questions for integrity failures that require human review.",
+        mutationTier: "low_risk_write",
+        toolName: "create_question",
+        produces: ["pipeline_brief"],
+        approval: { mode: "audit_only", rationaleRequired: true },
+      },
+      {
+        actionId: "publish_reconciliation_brief",
+        kind: "brief_publish",
+        title: "Publish reconciliation brief",
+        description:
+          "Emit an inbox-routed brief summarizing the nightly pipeline state and grouped blockers.",
+        mutationTier: "low_risk_write",
+        produces: ["pipeline_brief", "inbox_summary"],
+        approval: { mode: "audit_only" },
+      },
+    ],
+    hooks: [
+      {
+        hookId: "nightly-schedule",
+        event: "schedule.tick",
+        description: "Run once per nightly cadence.",
+        actionIds: [
+          "compile_context_pack",
+          "run_integrity_checks",
+          "record_followup_questions",
+          "publish_reconciliation_brief",
+        ],
+      },
+    ],
+    outputs: ["pipeline_brief", "inbox_summary", "structured_payload"],
+    integrityChecks: WORKFLOW_INTEGRITY_CHECKS,
+  },
+  {
+    workflowId: MORNING_BRIEF_WORKFLOW_ID,
+    version: WORKFLOW_RUNTIME_SCHEMA_VERSION,
+    title: "Morning Brief",
+    description:
+      "Compiles a developer-facing morning brief from graph state, overnight workflow outputs, and inbox routing preferences.",
+    trigger: {
+      kind: "schedule",
+      cadence: "daily",
+      timezone: "America/New_York",
+    },
+    staffingHint: "solo",
+    proofArtifacts: [
+      {
+        kind: "brief",
+        label: "Morning brief",
+        required: true,
+      },
+    ],
+    autoFixPolicy: {
+      mode: "dry_run",
+      maxActionsPerRun: 1,
+      permittedMutationTiers: ["read_only", "low_risk_write"],
+      requireAuditTrail: true,
+    },
+    actions: [
+      {
+        actionId: "compile_brief_inputs",
+        kind: "context_pack",
+        title: "Compile brief inputs",
+        description:
+          "Read graph state, worktree state, and overnight workflow receipts.",
+        mutationTier: "read_only",
+        produces: ["structured_payload"],
+        idempotent: true,
+        approval: { mode: "none" },
+      },
+      {
+        actionId: "publish_morning_brief",
+        kind: "brief_publish",
+        title: "Publish morning brief",
+        description:
+          "Publish a typed inbox summary with prioritized worktree and question context.",
+        mutationTier: "low_risk_write",
+        produces: ["engineering_brief", "inbox_summary"],
+        approval: { mode: "audit_only" },
+      },
+    ],
+    hooks: [
+      {
+        hookId: "morning-schedule",
+        event: "schedule.tick",
+        description: "Run once per morning cadence.",
+        actionIds: ["compile_brief_inputs", "publish_morning_brief"],
+      },
+      {
+        hookId: "worktree-complete-refresh",
+        event: "worktree.completed",
+        description:
+          "Refresh the queued morning brief inputs when worktree outcomes land overnight.",
+        actionIds: ["compile_brief_inputs"],
+      },
+    ],
+    outputs: ["engineering_brief", "inbox_summary", "structured_payload"],
+    integrityChecks: ["sparse_shaping"],
+  },
+] as const;

package/src/contracts/workflowRuntime.ts

@@ -0,0 +1 @@
+export * from "./workflow-runtime.contract";