@lucern/contracts 0.1.0-alpha.1

package/dist/workflow-runtime.contract.js

@@ -0,0 +1,258 @@
+/**
+ * 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";
+export const WORKFLOW_MUTATION_TIERS = [
+    "read_only",
+    "low_risk_write",
+    "high_risk_write",
+];
+export const WORKFLOW_APPROVAL_MODES = [
+    "none",
+    "audit_only",
+    "human_required",
+    "auto_approve",
+];
+export const DEFAULT_TIER_APPROVAL_MODE = {
+    read_only: "none",
+    low_risk_write: "audit_only",
+    high_risk_write: "human_required",
+};
+export const WORKFLOW_ACTION_KINDS = [
+    "context_pack",
+    "integrity_check",
+    "lucern_tool",
+    "report_compile",
+    "brief_publish",
+    "notification",
+    "custom",
+];
+export const WORKFLOW_HOOK_EVENTS = [
+    "schedule.tick",
+    "worktree.activated",
+    "worktree.completed",
+    "question.created",
+    "question.answered",
+    "evidence.appended",
+    "inbox.item_created",
+];
+export const WORKFLOW_OUTPUT_KINDS = [
+    "engineering_brief",
+    "research_memo",
+    "strategy_artifact",
+    "inbox_summary",
+    "pipeline_brief",
+    "structured_payload",
+];
+export const WORKFLOW_RUN_STATUSES = [
+    "queued",
+    "running",
+    "awaiting_approval",
+    "completed",
+    "failed",
+    "cancelled",
+];
+export const WORKFLOW_TRIGGER_KINDS = [
+    "manual",
+    "schedule",
+    "hook",
+];
+export const WORKFLOW_PROOF_ARTIFACT_KINDS = [
+    "report",
+    "brief",
+    "artifact",
+    "dashboard",
+    "test_evidence",
+];
+export const WORKFLOW_STAFFING_HINTS = [
+    "solo",
+    "backend+tests",
+    "fullstack",
+    "mcp+tests",
+];
+export const WORKFLOW_AUTO_FIX_MODES = [
+    "disabled",
+    "dry_run",
+    "safe",
+    "aggressive",
+];
+export const WORKFLOW_INTEGRITY_CHECKS = [
+    "null_dependency_refs",
+    "superseded_blockers",
+    "band_order_inconsistency",
+    "sparse_shaping",
+    "failed_completed_gate",
+];
+export const DEFAULT_WORKFLOW_AUTO_FIX_POLICY = {
+    mode: "disabled",
+    permittedMutationTiers: ["read_only"],
+    requireAuditTrail: true,
+};
+export const NIGHTLY_RECONCILIATION_WORKFLOW_ID = "workflow.pipeline_reconciliation.v1";
+export const MORNING_BRIEF_WORKFLOW_ID = "workflow.morning_brief.v1";
+export const CANONICAL_WORKFLOW_DEFINITIONS = [
+    {
+        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"],
+    },
+];
+//# sourceMappingURL=workflow-runtime.contract.js.map

package/dist/workflow-runtime.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-runtime.contract.js","sourceRoot":"","sources":["../src/workflow-runtime.contract.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@lucern/contracts",
+  "version": "0.1.0-alpha.1",
+  "description": "Lucern shared boundary contracts and public types",
+  "license": "UNLICENSED",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./v1/beliefs": {
+      "types": "./dist/v1/beliefs/v1.d.ts",
+      "import": "./dist/v1/beliefs/v1.js"
+    },
+    "./v1/evidence": {
+      "types": "./dist/v1/evidence/v1.d.ts",
+      "import": "./dist/v1/evidence/v1.js"
+    },
+    "./v1/questions": {
+      "types": "./dist/v1/questions/v1.d.ts",
+      "import": "./dist/v1/questions/v1.js"
+    },
+    "./v1/topics": {
+      "types": "./dist/v1/topics/v1.d.ts",
+      "import": "./dist/v1/topics/v1.js"
+    },
+    "./v1/graph": {
+      "types": "./dist/v1/graph/v1.d.ts",
+      "import": "./dist/v1/graph/v1.js"
+    },
+    "./v1/agents": {
+      "types": "./dist/v1/agents/v1.d.ts",
+      "import": "./dist/v1/agents/v1.js"
+    },
+    "./v1/worktrees": {
+      "types": "./dist/v1/worktrees/v1.d.ts",
+      "import": "./dist/v1/worktrees/v1.js"
+    },
+    "./v1/ontologies": {
+      "types": "./dist/v1/ontologies/v1.d.ts",
+      "import": "./dist/v1/ontologies/v1.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "sideEffects": false
+}