@llm4ts/flow 2.19.0 → 2.20.0

package/src/FlowContext.ts

@@ -51,6 +51,8 @@ export interface FlowContextShape {
    * this context's coder. Absent on a run with one executor per seat.
    */
   readonly roster?: RosterView
+  /** The trace this run writes (ADR 0022), when it writes one: the root context only. */
+  readonly trace?: { readonly runId: string; readonly path: string }
 }
 
 export class FlowContext extends Context.Service<FlowContext, FlowContextShape>()(

package/src/FlowEvents.ts

@@ -181,6 +181,106 @@ export class BlackboardRun extends Schema.TaggedClass<BlackboardRun>()("Blackboa
   result: RunResult
 }) {}
 
+/** One rubric dimension of a story verdict: its score out of `max`. */
+export const JudgedDimension = Schema.Struct({
+  id: Schema.String,
+  score: Schema.Number,
+  max: Schema.Number
+})
+export type JudgedDimension = typeof JudgedDimension.Type
+
+/** The story judge ruled on a story's branch (ADR 0022): one event per judge round. */
+export class StoryJudged extends Schema.TaggedClass<StoryJudged>()("StoryJudged", {
+  lane: Schema.String,
+  round: Schema.Int,
+  cleared: Schema.Boolean,
+  /** Issues the coder gets back when it is not cleared. */
+  issues: Schema.Int,
+  /** The rubric's scores, when the judge reports them. */
+  dimensions: Schema.Array(JudgedDimension)
+}) {}
+
+/**
+ * The executor roster's events (ADR 0019, 0022). `label` names who holds the
+ * lease — a story's id, or "the run" — so a view can put an executor on its lane.
+ */
+export class ExecutorLeased extends Schema.TaggedClass<ExecutorLeased>()("ExecutorLeased", {
+  executor: Schema.String,
+  role: Schema.String,
+  label: Schema.optionalKey(Schema.String),
+  /** Took the role on its own context's coder slot: nobody independent could. */
+  borrowed: Schema.optionalKey(Schema.Boolean)
+}) {}
+
+export class ExecutorReleased extends Schema.TaggedClass<ExecutorReleased>()("ExecutorReleased", {
+  executor: Schema.String,
+  role: Schema.String,
+  label: Schema.optionalKey(Schema.String)
+}) {}
+
+export class ExecutorExcluded extends Schema.TaggedClass<ExecutorExcluded>()("ExecutorExcluded", {
+  executor: Schema.String,
+  /** How long and why, as the roster describes it ("for this run: not logged in"). */
+  reason: Schema.String
+}) {}
+
+export class ExecutorResumed extends Schema.TaggedClass<ExecutorResumed>()("ExecutorResumed", {
+  executor: Schema.String,
+  /** `expired`: its exclusion ran out; `health`: its engine answers again; `resumed`: by hand. */
+  why: Schema.Literals(["expired", "health", "resumed"])
+}) {}
+
+export class ExecutorHandedOver extends Schema.TaggedClass<ExecutorHandedOver>()(
+  "ExecutorHandedOver",
+  {
+    from: Schema.String,
+    role: Schema.String,
+    label: Schema.optionalKey(Schema.String),
+    reason: Schema.String,
+    /** `call`: one call moves to another executor; `coder`: a context's coder changes hands. */
+    scope: Schema.Literals(["call", "coder"])
+  }
+) {}
+
+export type RosterEvent =
+  | ExecutorLeased
+  | ExecutorReleased
+  | ExecutorExcluded
+  | ExecutorResumed
+  | ExecutorHandedOver
+
+const resumedWords: Readonly<Record<ExecutorResumed["why"], string>> = {
+  expired: "back in the round",
+  health: "answers its health check again; back in the round",
+  resumed: "resumed"
+}
+
+/**
+ * The line the classic terminal shows for a roster event — the same words
+ * the roster used to publish as `Info` — or `undefined` for one it does not
+ * show (a release) and for any other event.
+ */
+export const rosterEventMessage = (event: FlowEvent): string | undefined => {
+  const forLabel = (label: string | undefined): string =>
+    label === undefined ? "" : ` for ${label}`
+  switch (event._tag) {
+    case "ExecutorLeased":
+      return event.borrowed === true
+        ? `roster: ${event.executor} takes ${event.role}${forLabel(event.label)} on its own coder's slot — not independent (no other executor can take ${event.role})`
+        : `roster: ${event.executor} takes ${event.role}${forLabel(event.label)}`
+    case "ExecutorExcluded":
+      return `roster: ${event.executor} out of the round ${event.reason}`
+    case "ExecutorResumed":
+      return `roster: ${event.executor} ${resumedWords[event.why]}`
+    case "ExecutorHandedOver":
+      return event.scope === "coder"
+        ? `roster: ${event.label ?? "the run"}: handing the coder over from ${event.from} (${event.reason})`
+        : `roster: ${event.role}${forLabel(event.label)} moves off ${event.from} (${event.reason})`
+    default:
+      return undefined
+  }
+}
+
 export const FlowEvent = Schema.Union([
   JudgmentObserved,
   BlackboardRun,
@@ -197,7 +297,13 @@ export const FlowEvent = Schema.Union([
   CapabilityUsedEvent,
   CapabilityDeniedEvent,
   CapabilityUnenforceable,
-  Declassified
+  Declassified,
+  ExecutorLeased,
+  ExecutorReleased,
+  ExecutorExcluded,
+  ExecutorResumed,
+  ExecutorHandedOver,
+  StoryJudged
 ])
 export type FlowEvent = typeof FlowEvent.Type
 

package/src/FlowRecorder.ts

@@ -20,11 +20,17 @@ export class TraceLine extends Schema.Class<TraceLine>("TraceLine")({
   fields: Schema.Record(Schema.String, Schema.Json)
 }) {}
 
+/** How a run ended, as its trace's last line says (ADR 0022). */
+export const RunOutcome = Schema.Literals(["completed", "failed", "interrupted"])
+export type RunOutcome = typeof RunOutcome.Type
+
 export interface FlowRecorderShape extends StreamRecorder {
   readonly runId: string
   readonly tracePath: string
   readonly record: (event: FlowEvent) => Effect.Effect<void>
   readonly consume: (hub: FlowEventHub) => Effect.Effect<void, never, Scope.Scope>
+  /** Appends the `RunEnded` line: a reader knows the run is over, not stalled. */
+  readonly end: (outcome: RunOutcome) => Effect.Effect<void>
   /** Waits for this recorder to catch up; `false` means it gave up first. */
   readonly awaitDrained: (hub: FlowEventHub, timeout?: Duration.Input) => Effect.Effect<boolean>
 }
@@ -104,6 +110,7 @@ export const makeFlowRecorder = Effect.fn("@llm4ts/flow/FlowRecorder.make")(func
           Effect.asVoid
         )
       }),
+    end: (outcome) => append("RunEnded", { outcome }),
     awaitDrained: (hub, timeout) => awaitConsumed(hub, consumed, timeout)
   }
   return recorder

package/src/Roster.ts

@@ -14,7 +14,14 @@ import type * as Scope from "effect/Scope"
 import * as Semaphore from "effect/Semaphore"
 import type { LlmError } from "@llm4ts/core/Errors"
 import { RosterExhausted, type FlowError } from "./FlowError.ts"
-import { Info, type FlowEventsShape } from "./FlowEvents.ts"
+import {
+  ExecutorExcluded,
+  ExecutorLeased,
+  ExecutorReleased,
+  ExecutorResumed,
+  Info,
+  type FlowEventsShape
+} from "./FlowEvents.ts"
 import { loadVersioned, saveVersioned, type PlainFileStoreShape } from "./Persistence.ts"
 import { isOutage } from "./TransientRetry.ts"
 
@@ -541,11 +548,22 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
       )
       .pipe(Effect.andThen(signal))
 
-  const leaseOf = (spec: ExecutorSpec, role: Role): Effect.Effect<Lease, never, Scope.Scope> =>
+  const leaseOf = (
+    spec: ExecutorSpec,
+    role: Role,
+    label: string | undefined
+  ): Effect.Effect<Lease, never, Scope.Scope> =>
     Effect.gen(function* () {
+      const labelled = label === undefined ? {} : { label }
+      yield* events.publish(ExecutorLeased.make({ executor: spec.id, role, ...labelled }))
       const done = yield* Ref.make(false)
       const free = Effect.flatMap(Ref.getAndSet(done, true), (was) =>
-        was ? Effect.void : release(spec, role)
+        was
+          ? Effect.void
+          : Effect.andThen(
+              release(spec, role),
+              events.publish(ExecutorReleased.make({ executor: spec.id, role, ...labelled }))
+            )
       )
       yield* Effect.addFinalizer(() => free)
       return { executor: spec, role, release: free }
@@ -577,7 +595,9 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
         })
       )
       if (back.length > 0) {
-        yield* say(`${back.join(", ")} back in the round`)
+        yield* Effect.forEach(back, (id) =>
+          events.publish(ExecutorResumed.make({ executor: id, why: "expired" }))
+        )
         yield* persist
       }
       return spec
@@ -638,7 +658,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
         })
       )
       if (up) {
-        yield* say(`${exclusion.id} answers its health check again; back in the round`)
+        yield* events.publish(ExecutorResumed.make({ executor: exclusion.id, why: "health" }))
         yield* persist
         yield* signal
       }
@@ -693,10 +713,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
       while (true) {
         const spec = yield* attempt(role, leaseOptions)
         if (spec !== undefined) {
-          yield* say(
-            `${spec.id} takes ${role}${leaseOptions.label === undefined ? "" : ` for ${leaseOptions.label}`}`
-          )
-          return yield* leaseOf(spec, role)
+          return yield* leaseOf(spec, role, leaseOptions.label)
         }
         if (!(yield* canEverServe(role, avoid))) {
           const reasons = yield* lock.withPermit(
@@ -723,10 +740,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
         yield* probeDue
         const recovered = yield* attempt(role, leaseOptions)
         if (recovered !== undefined) {
-          yield* say(
-            `${recovered.id} takes ${role}${leaseOptions.label === undefined ? "" : ` for ${leaseOptions.label}`}`
-          )
-          return yield* leaseOf(recovered, role)
+          return yield* leaseOf(recovered, role, leaseOptions.label)
         }
         const probing = yield* lock.withPermit(
           Effect.sync(() =>
@@ -744,7 +758,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
     leaseOptions: LeaseOptions = {}
   ): Effect.Effect<Lease | undefined, never, Scope.Scope> =>
     Effect.flatMap(attempt(role, leaseOptions), (spec) =>
-      spec === undefined ? Effect.succeed(undefined) : leaseOf(spec, role)
+      spec === undefined ? Effect.succeed(undefined) : leaseOf(spec, role, leaseOptions.label)
     )
 
   const exclude = (exclusion: Exclusion): Effect.Effect<void> =>
@@ -753,7 +767,9 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
         return
       }
       yield* lock.withPermit(Effect.sync(() => exclusions.set(exclusion.id, exclusion)))
-      yield* say(`${exclusion.id} out of the round ${describeExclusion(exclusion)}`)
+      yield* events.publish(
+        ExecutorExcluded.make({ executor: exclusion.id, reason: describeExclusion(exclusion) })
+      )
       yield* persist
       yield* signal
     })
@@ -790,7 +806,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
     Effect.gen(function* () {
       const removed = yield* lock.withPermit(Effect.sync(() => exclusions.delete(id)))
       if (removed) {
-        yield* say(`${id} resumed`)
+        yield* events.publish(ExecutorResumed.make({ executor: id, why: "resumed" }))
         yield* persist
         yield* signal
       }

package/src/RosterSeats.ts

@@ -12,7 +12,7 @@ import { ConfigError, type LlmError } from "@llm4ts/core/Errors"
 import type { LlmServiceShape } from "@llm4ts/core/LlmService"
 import { Message, type ConnectorCapabilities, type LlmChunk } from "@llm4ts/core/Models"
 import { describeFlowError, type FlowError } from "./FlowError.ts"
-import { Info, type FlowEventsShape } from "./FlowEvents.ts"
+import { ExecutorHandedOver, ExecutorLeased, type FlowEventsShape } from "./FlowEvents.ts"
 import {
   describeExclusion,
   hasRole,
@@ -51,9 +51,6 @@ export interface RosterView {
 const asLlmError = (error: FlowError): LlmError =>
   ConfigError.make({ message: describeFlowError(error) })
 
-const say = (events: FlowEventsShape, message: string): Effect.Effect<void> =>
-  events.publish(Info.make({ message: `roster: ${message}` }))
-
 /** Shared plumbing: every service method as "run this on some seat". */
 interface SeatRunner {
   readonly run: <A, R>(
@@ -133,9 +130,13 @@ export const rosterSeat = (
       if (avoid.length > 0 && !(yield* roster.canEverServe(role, avoid))) {
         const borrowed = options.borrow === undefined ? undefined : yield* options.borrow
         if (borrowed !== undefined && hasRole(borrowed, role)) {
-          yield* say(
-            options.events,
-            `${borrowed.id} takes ${role}${options.label === undefined ? "" : ` for ${options.label}`} on its own coder's slot — not independent (no other executor can take ${role})`
+          yield* options.events.publish(
+            ExecutorLeased.make({
+              executor: borrowed.id,
+              role,
+              ...(options.label === undefined ? {} : { label: options.label }),
+              borrowed: true
+            })
           )
           return borrowed
         }
@@ -167,9 +168,14 @@ export const rosterSeat = (
       const avoid = options.avoid === undefined ? [] : yield* options.avoid
       const other = yield* roster.canEverServe(role, [...avoid, executor.id])
       if (other) {
-        yield* say(
-          options.events,
-          `${role}${options.label === undefined ? "" : ` for ${options.label}`} moves off ${executor.id} (${describeExclusion(exclusion)})`
+        yield* options.events.publish(
+          ExecutorHandedOver.make({
+            from: executor.id,
+            role,
+            ...(options.label === undefined ? {} : { label: options.label }),
+            reason: describeExclusion(exclusion),
+            scope: "call"
+          })
         )
       }
       return other
@@ -318,9 +324,14 @@ export const makeHeldCoder = Effect.fn("@llm4ts/flow/RosterSeats.heldCoder")(fun
       yield* Ref.set(prefer, undefined)
       yield* held.lease.release
       yield* Ref.set(current, undefined)
-      yield* say(
-        options.events,
-        `${options.label ?? workDir}: handing the coder over from ${held.lease.executor.id} (${describeExclusion(exclusion)})`
+      yield* options.events.publish(
+        ExecutorHandedOver.make({
+          from: held.lease.executor.id,
+          role: "coder",
+          label: options.label ?? workDir,
+          reason: describeExclusion(exclusion),
+          scope: "coder"
+        })
       )
       return takeoverNote(held.lease.executor.id, exclusion.reason)
     })

package/src/Stories.ts

@@ -28,7 +28,7 @@ import {
   StoryFailed,
   type FlowError
 } from "./FlowError.ts"
-import { Info, withLane, type FlowEventsShape } from "./FlowEvents.ts"
+import { Info, JudgedDimension, StoryJudged, withLane, type FlowEventsShape } from "./FlowEvents.ts"
 import { statusPaths, type GitToolShape } from "./GitTool.ts"
 import {
   checkPerimeter,
@@ -70,6 +70,11 @@ const join = (root: string, path: string): string =>
 // ---- Story seats ----------------------------------------------------------
 
 /** A flow context rooted in a story's worktree, plus that story's own usage totals. */
+/** A story judge's review with the rubric's scores; a plain `ReviewResult` has none. */
+export class StoryVerdict extends ReviewResult.extend<StoryVerdict>("StoryVerdict")({
+  dimensions: Schema.Array(JudgedDimension)
+}) {}
+
 export interface StorySeats {
   readonly context: FlowContextShape
   /** Running usage of this story's seats — estimates where the backend reports none. */
@@ -986,6 +991,15 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
           return yield* failed(story, "the story branch has no changes against the epic branch")
         }
         const verdict = yield* judge(story, diff, watchedSeats)
+        yield* laneOf(story).publish(
+          StoryJudged.make({
+            lane: story.id,
+            round,
+            cleared: verdict.isClean,
+            issues: verdict.issues.length,
+            dimensions: verdict instanceof StoryVerdict ? verdict.dimensions : []
+          })
+        )
         if (verdict.isClean) {
           judgeNote = `judge cleared (round ${round})`
           break