@agentskit/doc-bridge 1.4.3 → 1.5.0

package/src/schemas/knowledge.ts

@@ -0,0 +1,315 @@
+import { z } from 'zod'
+
+export const KNOWLEDGE_SCHEMA_VERSION = 1 as const
+export const KNOWLEDGE_CONTENT_HASH_ALGO = 'sha256-normalized-v1' as const
+
+const hash = z.string().regex(/^[a-f0-9]{64}$/)
+const boundedString = (max: number) => z.string().min(1).max(max)
+
+export const ProvenanceSchema = z.enum(['observed', 'declared', 'proposed'])
+export type Provenance = z.infer<typeof ProvenanceSchema>
+
+export const FindingStatusSchema = z.enum([
+  'confirmed',
+  'undocumented',
+  'stale-or-unverified',
+  'conflict',
+  'unresolved',
+  'not-analyzed',
+])
+export type FindingStatus = z.infer<typeof FindingStatusSchema>
+
+export const DiagnosticSeveritySchema = z.enum(['off', 'info', 'warn', 'error'])
+export type DiagnosticSeverity = z.infer<typeof DiagnosticSeveritySchema>
+
+export const EvidenceSourceSchema = z.enum([
+  'code',
+  'configuration',
+  'documentation',
+  'agent',
+  'derived',
+])
+
+export const EvidenceSchema = z
+  .object({
+    source: EvidenceSourceSchema,
+    path: boundedString(512),
+    lineStart: z.number().int().positive().optional(),
+    lineEnd: z.number().int().positive().optional(),
+    contentHash: hash.optional(),
+    context: z.string().max(1_024).optional(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.lineStart !== undefined && value.lineEnd !== undefined && value.lineEnd < value.lineStart) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['lineEnd'],
+        message: 'Must be greater than or equal to lineStart',
+      })
+    }
+  })
+export type Evidence = z.infer<typeof EvidenceSchema>
+
+export const CoverageStatusSchema = z.enum(['complete', 'partial', 'not-analyzed'])
+
+export const CoverageSchema = z
+  .object({
+    analyzer: boundedString(128),
+    scope: boundedString(512),
+    status: CoverageStatusSchema,
+    reason: z.string().max(1_024).optional(),
+    evidence: z.array(EvidenceSchema).max(32).optional(),
+  })
+  .strict()
+export type Coverage = z.infer<typeof CoverageSchema>
+
+export const ProjectIdentitySchema = z
+  .object({
+    name: boundedString(128),
+    root: boundedString(512).optional(),
+  })
+  .strict()
+
+const ArtifactMetadata = {
+  schemaVersion: z.literal(KNOWLEDGE_SCHEMA_VERSION),
+  contentHash: hash,
+  contentHashAlgo: z.literal(KNOWLEDGE_CONTENT_HASH_ALGO),
+  project: ProjectIdentitySchema,
+  sourceRevision: boundedString(128),
+  sourceRevisionKind: z.enum(['git', 'content']),
+  configurationHash: hash,
+  pipelineVersion: boundedString(64),
+  analyzerVersions: z.record(boundedString(128), boundedString(64)),
+}
+
+export const EntitySchema = z
+  .object({
+    id: boundedString(256),
+    kind: boundedString(128),
+    name: boundedString(256),
+    path: boundedString(512).optional(),
+    aliases: z.array(boundedString(256)).max(32).optional(),
+    provenance: ProvenanceSchema,
+    evidence: z.array(EvidenceSchema).max(64),
+    metadata: z.record(z.unknown()).optional(),
+  })
+  .strict()
+export type KnowledgeEntity = z.infer<typeof EntitySchema>
+
+export const RelationSchema = z
+  .object({
+    id: boundedString(256),
+    kind: boundedString(128),
+    from: boundedString(256),
+    to: boundedString(256),
+    discriminator: boundedString(256).optional(),
+    provenance: ProvenanceSchema,
+    evidence: z.array(EvidenceSchema).max(64),
+    metadata: z.record(z.unknown()).optional(),
+  })
+  .strict()
+export type KnowledgeRelation = z.infer<typeof RelationSchema>
+
+export const DiscoverySnapshotV1Schema = z
+  .object({
+    type: z.literal('discovery-snapshot'),
+    ...ArtifactMetadata,
+    entities: z.array(EntitySchema).max(50_000),
+    relations: z.array(RelationSchema).max(100_000),
+    coverage: z.array(CoverageSchema).max(1_000),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    const entityIds = new Set<string>()
+    for (const [index, entity] of value.entities.entries()) {
+      if (entityIds.has(entity.id)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ['entities', index, 'id'], message: `Duplicate entity id: ${entity.id}` })
+      }
+      entityIds.add(entity.id)
+    }
+
+    const relationIds = new Set<string>()
+    for (const [index, relation] of value.relations.entries()) {
+      if (relationIds.has(relation.id)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ['relations', index, 'id'], message: `Duplicate relation id: ${relation.id}` })
+      }
+      relationIds.add(relation.id)
+    }
+  })
+export type DiscoverySnapshotV1 = z.infer<typeof DiscoverySnapshotV1Schema>
+
+export const DiagnosticSchema = z
+  .object({
+    id: boundedString(256),
+    code: boundedString(128),
+    status: FindingStatusSchema,
+    severity: DiagnosticSeveritySchema,
+    message: boundedString(2_048),
+    evidence: z.array(EvidenceSchema).max(64),
+    entityIds: z.array(boundedString(256)).max(64).optional(),
+    relationIds: z.array(boundedString(256)).max(64).optional(),
+    remediation: z.string().max(2_048).optional(),
+  })
+  .strict()
+export type KnowledgeDiagnostic = z.infer<typeof DiagnosticSchema>
+
+export const ReconciliationReportV1Schema = z
+  .object({
+    type: z.literal('reconciliation-report'),
+    ...ArtifactMetadata,
+    snapshotHash: hash,
+    diagnostics: z.array(DiagnosticSchema).max(100_000),
+    summary: z
+      .object({
+        entityCount: z.number().int().nonnegative(),
+        relationCount: z.number().int().nonnegative(),
+        diagnosticCount: z.number().int().nonnegative(),
+      })
+      .strict(),
+  })
+  .strict()
+export type ReconciliationReportV1 = z.infer<typeof ReconciliationReportV1Schema>
+
+export const WorkflowStateSchema = z.enum([
+  'created',
+  'discovering',
+  'analyzed',
+  'compared',
+  'awaiting-agent',
+  'proposed',
+  'awaiting-approval',
+  'validating',
+  'delivered',
+  'failed',
+  'cancelled',
+  'stale',
+  'superseded',
+])
+export type WorkflowState = z.infer<typeof WorkflowStateSchema>
+
+export const WorkflowStepSchema = z
+  .object({
+    name: boundedString(128),
+    status: z.enum(['pending', 'running', 'completed', 'failed', 'skipped']),
+    inputHash: hash,
+    outputHash: hash.optional(),
+    artifactRefs: z.array(boundedString(512)).max(32).optional(),
+  })
+  .strict()
+export type WorkflowStep = z.infer<typeof WorkflowStepSchema>
+
+export const WorkflowTransitionSchema = z
+  .object({
+    from: WorkflowStateSchema.nullable(),
+    to: WorkflowStateSchema,
+    at: z.string().datetime(),
+    reason: z.string().max(1_024).optional(),
+  })
+  .strict()
+export type WorkflowTransition = z.infer<typeof WorkflowTransitionSchema>
+
+export const WorkflowRunV1Schema = z
+  .object({
+    type: z.literal('workflow-run'),
+    ...ArtifactMetadata,
+    runId: boundedString(128),
+    state: WorkflowStateSchema,
+    steps: z.array(WorkflowStepSchema).max(32),
+    transitions: z.array(WorkflowTransitionSchema).max(1_000),
+    artifactRefs: z.array(boundedString(512)).max(128),
+  })
+  .strict()
+export type WorkflowRunV1 = z.infer<typeof WorkflowRunV1Schema>
+
+export const ProposalOriginSchema = z
+  .object({
+    kind: z.enum(['registry-agent', 'manual', 'deterministic']),
+    id: boundedString(256).optional(),
+    version: boundedString(64).optional(),
+    provider: boundedString(128).optional(),
+    model: boundedString(256).optional(),
+    capabilities: z.array(boundedString(128)).max(32).optional(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.kind === 'registry-agent' && value.id === undefined) {
+      context.addIssue({ code: z.ZodIssueCode.custom, path: ['id'], message: 'Registry agent origin requires an id' })
+    }
+  })
+
+export const AgentProposalV1Schema = z
+  .object({
+    type: z.literal('agent-proposal'),
+    ...ArtifactMetadata,
+    proposalId: boundedString(128),
+    baseSnapshotHash: hash,
+    baseReportHash: hash,
+    relatedDiagnosticIds: z.array(boundedString(256)).max(64),
+    rationale: boundedString(4_000),
+    confidence: z.number().min(0).max(1),
+    evidence: z.array(EvidenceSchema).max(128),
+    intendedChanges: z.array(boundedString(4_000)).max(64),
+    origin: ProposalOriginSchema,
+    checks: z.array(boundedString(512)).max(32),
+  })
+  .strict()
+export type AgentProposalV1 = z.infer<typeof AgentProposalV1Schema>
+
+export const FixProposalStatusSchema = z.enum(['proposed', 'approved', 'rejected', 'stale', 'applied', 'failed'])
+
+export const AffectedFileSchema = z
+  .object({
+    path: boundedString(512),
+    contentHash: hash,
+  })
+  .strict()
+
+export const FixChangeSchema = z
+  .object({
+    path: boundedString(512),
+    before: z.string().max(100_000),
+    after: z.string().max(100_000),
+  })
+  .strict()
+export type FixChange = z.infer<typeof FixChangeSchema>
+
+export const FixProposalV1Schema = z
+  .object({
+    type: z.literal('fix-proposal'),
+    ...ArtifactMetadata,
+    proposalId: boundedString(128),
+    baseRevision: boundedString(128),
+    affectedFiles: z.array(AffectedFileSchema).max(256),
+    changes: z.array(FixChangeSchema).max(256).optional(),
+    preconditions: z.array(boundedString(2_048)).max(64),
+    diff: boundedString(100_000),
+    postconditions: z.array(boundedString(2_048)).max(64),
+    approval: z
+      .object({
+        proposalHash: hash,
+        approvedAt: z.string().datetime(),
+        approvedBy: boundedString(256),
+      })
+      .strict()
+      .optional(),
+    status: FixProposalStatusSchema,
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if ((value.status === 'approved' || value.status === 'applied') && value.approval === undefined) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['approval'],
+        message: `Fix proposal status ${value.status} requires an approval record`,
+      })
+    }
+  })
+export type FixProposalV1 = z.infer<typeof FixProposalV1Schema>
+
+export type KnowledgeArtifactV1 =
+  | DiscoverySnapshotV1
+  | ReconciliationReportV1
+  | WorkflowRunV1
+  | AgentProposalV1
+  | FixProposalV1

package/src/validate.ts

@@ -14,6 +14,18 @@ import {
   MemoryCandidateV1Schema,
   type MemoryCandidateV1,
 } from './schemas/memory-candidate.js'
+import {
+  AgentProposalV1Schema,
+  DiscoverySnapshotV1Schema,
+  FixProposalV1Schema,
+  ReconciliationReportV1Schema,
+  WorkflowRunV1Schema,
+  type AgentProposalV1,
+  type DiscoverySnapshotV1,
+  type FixProposalV1,
+  type ReconciliationReportV1,
+  type WorkflowRunV1,
+} from './schemas/knowledge.js'
 
 export type ParseIssue = {
   readonly path: string
@@ -56,6 +68,18 @@ export const parseDocBridgeIndex = (input: unknown): DocBridgeIndexV1 =>
 export const parseMemoryCandidate = (input: unknown): MemoryCandidateV1 =>
   MemoryCandidateV1Schema.parse(input)
 
+export const parseDiscoverySnapshot = (input: unknown): DiscoverySnapshotV1 =>
+  DiscoverySnapshotV1Schema.parse(input)
+
+export const parseReconciliationReport = (input: unknown): ReconciliationReportV1 =>
+  ReconciliationReportV1Schema.parse(input)
+
+export const parseWorkflowRun = (input: unknown): WorkflowRunV1 => WorkflowRunV1Schema.parse(input)
+
+export const parseAgentProposal = (input: unknown): AgentProposalV1 => AgentProposalV1Schema.parse(input)
+
+export const parseFixProposal = (input: unknown): FixProposalV1 => FixProposalV1Schema.parse(input)
+
 export const parseDocBridgeConfig = (input: unknown): DocBridgeConfigV1 => {
   const result = DocBridgeConfigV1Schema.safeParse(input)
   if (!result.success) {

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = '1.4.3'
+export const PACKAGE_VERSION = '1.5.0'

package/src/workflow/engine.ts

@@ -0,0 +1,238 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+
+import { contentHashForArtifactV1, sha256NormalizedV1 } from '../index-builder/content-hash.js'
+import { WorkflowRunV1Schema, type WorkflowRunV1, type WorkflowState, type WorkflowStep } from '../schemas/knowledge.js'
+
+export const WORKFLOW_STAGES = ['collect', 'normalize', 'reconcile', 'evaluate', 'report'] as const
+export type WorkflowStage = (typeof WORKFLOW_STAGES)[number]
+
+export type WorkflowStageContext = {
+  readonly root: string
+  readonly stage: WorkflowStage
+  readonly input: unknown
+  readonly previousOutput: unknown
+}
+
+export type WorkflowStageHandler = (context: WorkflowStageContext) => unknown
+
+export type WorkflowOptions = {
+  readonly root: string
+  readonly stateDir?: string
+  readonly sourceRevision: string
+  readonly configurationHash: string
+  readonly toolVersion?: string
+  readonly runId?: string
+  readonly stage?: WorkflowStage | 'all'
+  readonly inputs?: Partial<Record<WorkflowStage, unknown>>
+  readonly handlers: Partial<Record<WorkflowStage, WorkflowStageHandler>>
+}
+
+export type WorkflowExecutionResult = {
+  readonly run: WorkflowRunV1
+  readonly stateDir: string
+  readonly reusedStages: readonly WorkflowStage[]
+}
+
+type PersistedArtifact = {
+  readonly type: 'workflow-step-artifact'
+  readonly stage: WorkflowStage
+  readonly inputHash: string
+  readonly outputHash: string
+  readonly value: unknown
+}
+
+const stageState: Record<WorkflowStage, WorkflowState> = {
+  collect: 'discovering',
+  normalize: 'analyzed',
+  reconcile: 'compared',
+  evaluate: 'proposed',
+  report: 'delivered',
+}
+
+const defaultStateDir = (root: string): string => join(root, '.doc-bridge', 'workflow')
+
+const atomicWrite = (path: string, value: unknown): void => {
+  const temp = `${path}.tmp-${process.pid}-${Date.now()}`
+  writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
+  renameSync(temp, path)
+}
+
+const writeManifest = (stateDir: string, run: WorkflowRunV1): void => {
+  atomicWrite(join(stateDir, 'manifest.json'), run)
+}
+
+const appendTransition = (stateDir: string, transition: WorkflowRunV1['transitions'][number]): void => {
+  appendFileSync(join(stateDir, 'transitions.jsonl'), `${JSON.stringify(transition)}\n`, 'utf8')
+}
+
+const transition = (run: WorkflowRunV1, to: WorkflowState, reason?: string): WorkflowRunV1 => {
+  const item = {
+    from: run.state,
+    to,
+    at: new Date().toISOString(),
+    ...(reason ? { reason } : {}),
+  }
+  return { ...run, state: to, transitions: [...run.transitions, item] }
+}
+
+const runId = (): string => `${Date.now()}-${process.pid}`
+
+const stageInputHash = (options: WorkflowOptions, stage: WorkflowStage, input: unknown): string =>
+  sha256NormalizedV1({ stage, input, sourceRevision: options.sourceRevision, configurationHash: options.configurationHash, toolVersion: options.toolVersion ?? '1.0.0' })
+
+const stageArtifactPath = (stateDir: string, stage: WorkflowStage, inputHash: string): string => join(stateDir, 'artifacts', `${stage}-${inputHash}.json`)
+
+const readArtifact = (path: string): PersistedArtifact => JSON.parse(readFileSync(path, 'utf8')) as PersistedArtifact
+
+const stepArtifactPath = (stateDir: string, step: WorkflowStep): string => resolve(stateDir, step.artifactRefs?.[0] ?? '')
+
+const stepOutput = (stateDir: string, run: WorkflowRunV1, stage: WorkflowStage): unknown => {
+  const step = run.steps.find((item) => item.name === stage)
+  if (!step || step.status !== 'completed' || !step.artifactRefs?.[0]) return null
+  return readArtifact(stepArtifactPath(stateDir, step)).value
+}
+
+const acquireLock = (stateDir: string): (() => void) => {
+  const lock = join(stateDir, '.lock')
+  try {
+    mkdirSync(lock)
+  } catch {
+    const ownerPath = join(lock, 'owner.json')
+    try {
+      const owner = JSON.parse(readFileSync(ownerPath, 'utf8')) as { pid?: number }
+      if (typeof owner.pid === 'number') process.kill(owner.pid, 0)
+      throw new Error(`Workflow is already running (pid ${owner.pid ?? 'unknown'}).`)
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith('Workflow is already running')) throw error
+      rmSync(lock, { recursive: true, force: true })
+      mkdirSync(lock)
+    }
+  }
+  writeFileSync(join(lock, 'owner.json'), JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }), 'utf8')
+  return () => rmSync(lock, { recursive: true, force: true })
+}
+
+const loadManifest = (stateDir: string): WorkflowRunV1 | undefined => {
+  const path = join(stateDir, 'manifest.json')
+  if (!existsSync(path)) return undefined
+  return WorkflowRunV1Schema.parse(JSON.parse(readFileSync(path, 'utf8')) as unknown)
+}
+
+const baseRun = (options: WorkflowOptions, stateDir: string, supersedes?: string): WorkflowRunV1 => {
+  const inputHash = sha256NormalizedV1({ sourceRevision: options.sourceRevision, configurationHash: options.configurationHash, toolVersion: options.toolVersion ?? '1.0.0' })
+  return WorkflowRunV1Schema.parse({
+    type: 'workflow-run',
+    schemaVersion: 1,
+    contentHash: '0'.repeat(64),
+    contentHashAlgo: 'sha256-normalized-v1',
+    project: { name: resolve(options.root).split('/').pop() ?? 'project', root: '.' },
+    sourceRevision: options.sourceRevision,
+    sourceRevisionKind: 'content',
+    configurationHash: options.configurationHash,
+    pipelineVersion: '1.0.0',
+    analyzerVersions: { workflow: options.toolVersion ?? '1.0.0' },
+    runId: options.runId ?? runId(),
+    state: 'created',
+    steps: WORKFLOW_STAGES.map((name) => ({ name, status: 'pending', inputHash })) as WorkflowStep[],
+    transitions: [{ from: null, to: 'created', at: new Date().toISOString() }],
+    artifactRefs: [relative(resolve(options.root), stateDir), ...(supersedes ? [`supersedes:${supersedes}`] : [])],
+  })
+}
+
+const withHash = (run: WorkflowRunV1): WorkflowRunV1 => WorkflowRunV1Schema.parse({ ...run, contentHash: contentHashForArtifactV1(run) })
+
+const sameInputs = (run: WorkflowRunV1, options: WorkflowOptions): boolean =>
+  run.sourceRevision === options.sourceRevision &&
+  run.configurationHash === options.configurationHash &&
+  run.analyzerVersions.workflow === (options.toolVersion ?? '1.0.0')
+
+const selectedStages = (stage: WorkflowOptions['stage']): readonly WorkflowStage[] =>
+  stage && stage !== 'all' ? [stage] : WORKFLOW_STAGES
+
+export const runWorkflow = (options: WorkflowOptions): WorkflowExecutionResult => {
+  const root = resolve(options.root)
+  const stateDir = resolve(root, options.stateDir ?? defaultStateDir(root))
+  mkdirSync(join(stateDir, 'artifacts'), { recursive: true })
+  const release = acquireLock(stateDir)
+  try {
+    let run = loadManifest(stateDir)
+    let supersedes: string | undefined
+    if (run && !sameInputs(run, options)) {
+      supersedes = run.runId
+      run = withHash(transition(run, 'stale', 'Source revision, configuration hash, or tool version changed.'))
+      appendTransition(stateDir, run.transitions[run.transitions.length - 1]!)
+      writeManifest(stateDir, run)
+      run = undefined
+    }
+    if (!run) {
+      run = withHash(baseRun(options, stateDir, supersedes))
+      appendTransition(stateDir, run.transitions[0]!)
+      writeManifest(stateDir, run)
+    }
+
+    if (!run) throw new Error('Workflow manifest was not initialized.')
+    const firstSelectedStage = selectedStages(options.stage)[0]
+    const previousStageIndex = firstSelectedStage ? WORKFLOW_STAGES.indexOf(firstSelectedStage) - 1 : -1
+    let previousOutput: unknown = previousStageIndex >= 0 ? stepOutput(stateDir, run, WORKFLOW_STAGES[previousStageIndex]!) : null
+    const reusedStages: WorkflowStage[] = []
+    for (const stage of selectedStages(options.stage)) {
+      const input = options.inputs?.[stage] ?? previousOutput
+      const inputHash = stageInputHash(options, stage, input)
+      const existing = run.steps.find((step) => step.name === stage)
+      const artifactPath = existing?.artifactRefs?.[0] ? resolve(stateDir, existing.artifactRefs[0]) : stageArtifactPath(stateDir, stage, inputHash)
+      if (existing?.status === 'completed' && existing.inputHash === inputHash && existing.outputHash && existsSync(artifactPath)) {
+        previousOutput = readArtifact(artifactPath).value
+        reusedStages.push(stage)
+        continue
+      }
+
+      const handler = options.handlers[stage]
+      if (!handler) throw new Error(`No handler configured for workflow stage "${stage}".`)
+      run = withHash(transition(run, stageState[stage]))
+      appendTransition(stateDir, run.transitions[run.transitions.length - 1]!)
+      const runningStep: WorkflowStep = { name: stage, status: 'running', inputHash }
+      run = withHash({ ...run, steps: run.steps.map((step) => step.name === stage ? runningStep : step) })
+      writeManifest(stateDir, run)
+      try {
+        const value = handler({ root, stage, input, previousOutput })
+        const outputHash = sha256NormalizedV1(value)
+        const artifact: PersistedArtifact = { type: 'workflow-step-artifact', stage, inputHash, outputHash, value }
+        mkdirSync(join(stateDir, 'artifacts'), { recursive: true })
+        if (existsSync(artifactPath)) {
+          const existingArtifact = readArtifact(artifactPath)
+          if (existingArtifact.outputHash !== outputHash) throw new Error(`Immutable workflow artifact collision for stage "${stage}".`)
+        } else {
+          atomicWrite(artifactPath, artifact)
+        }
+        const ref = relative(stateDir, artifactPath)
+        const completedStep: WorkflowStep = { name: stage, status: 'completed', inputHash, outputHash, artifactRefs: [ref] }
+        run = withHash({ ...run, steps: run.steps.map((step) => step.name === stage ? completedStep : step) })
+        writeManifest(stateDir, run)
+        previousOutput = value
+      } catch (error) {
+        run = withHash(transition(run, 'failed', error instanceof Error ? error.message : String(error)))
+        appendTransition(stateDir, run.transitions[run.transitions.length - 1]!)
+        writeManifest(stateDir, run)
+        throw error
+      }
+    }
+
+    if (selectedStages(options.stage).every((stage) => run!.steps.find((step) => step.name === stage)?.status === 'completed')) {
+      const complete = selectedStages(options.stage).includes('report') && run.state !== 'delivered' ? withHash(transition(run, 'delivered')) : run
+      if (complete !== run) {
+        appendTransition(stateDir, complete.transitions[complete.transitions.length - 1]!)
+        run = complete
+      }
+      writeManifest(stateDir, run)
+      if (run.state === 'delivered') atomicWrite(join(stateDir, 'last-known-good.json'), { runId: run.runId, manifestHash: run.contentHash, report: run.steps.find((step) => step.name === 'report')?.artifactRefs?.[0] })
+    }
+    return { run, stateDir, reusedStages }
+  } finally {
+    release()
+  }
+}
+
+export const loadWorkflowManifest = (stateDir: string): WorkflowRunV1 => WorkflowRunV1Schema.parse(JSON.parse(readFileSync(join(resolve(stateDir), 'manifest.json'), 'utf8')) as unknown)
+
+export const loadWorkflowStepOutput = (stateDir: string, stage: WorkflowStage): unknown => stepOutput(resolve(stateDir), loadWorkflowManifest(stateDir), stage)

package/tsup.config.ts

@@ -12,4 +12,5 @@ export default defineConfig({
   clean: true,
   splitting: false,
   target: 'node22',
-})
+  external: ['typescript'],
+})