@smthrs/harness 0.0.0-stage → 1.0.0-rc.3

package/src/VacuousVerification.ts

@@ -0,0 +1,280 @@
+/**
+ * The proof that was already true before anything changed.
+ *
+ * **This control is not wired into `CellTurn`. Nothing in a production run
+ * reads it, and no run is told anything by it.** The module, this suite and
+ * `AgentEvent.VacuousVerificationObserved` are kept intact so it can be
+ * measured on its own, in its own wave, against the contract text r92
+ * measured. Everything below describes what it does when an arm turns it on.
+ *
+ * **Its input no longer exists.** {@link stored} reads the reserved
+ * `verification` key out of the durable state a cell filed by hand, and the
+ * filing surface was deleted on 2026-08-24: `Cell.Continue.state` decodes and
+ * is populated by nothing. An arm that re-wires this module reads nothing until
+ * it first decides where a realm run declares its verification — a name bound
+ * in the realm, a print, or a new field — so the wave that turns this back on
+ * carries that decision with it. {@link stored} is left reading `Schema.Json`
+ * because that decision has not been made and the r90–r96 journals it can be
+ * replayed against are still filing journals.
+ *
+ * It was live for exactly one wave. the r93 wave report reads
+ * the result off the 45 journals, and the reason it is off is that the wave
+ * cannot price it:
+ *
+ * - It fired **twice in 45 journals**, and on neither of the instances the
+ *   diagnosis or the replay predicted. `django__django-14351`, the run it was
+ *   written for, resolved that wave with **no observation on its journal at
+ *   all** — so the row it was built to close was closed by something else, and
+ *   two prompt rules landed in the same round.
+ * - `sympy__sympy-13878` is the firing that worked: told at frame 1 that its
+ *   stored check was already green, the run replaced it, spent seventeen more
+ *   frames on a different proof, and resolved — cheaper and in fewer frames
+ *   than any earlier wave.
+ * - `django__django-15732` is the firing that did not. The observation landed
+ *   on frame 7, which is the frame that made the correct edit. On frame 8 the
+ *   run made a second edit that rewrote the enclosing block and restored the
+ *   first edit's text **byte for byte**. Both edits reported `mutated: true`
+ *   on an `observed` basis, the final tree equalled the base, and the captured
+ *   diff was zero bytes. The instance had resolved in r90, r91 and r92; it is
+ *   the wave's only empty patch.
+ *
+ * Nothing in this module's contract asks a run to revert, and one instance is
+ * not a mechanism. But it is the first evidence that a fact delivered on the
+ * `invalidProbe` channel can be read by a run as an instruction to retreat,
+ * and the one consequential firing in the wave preceded the wave's only
+ * revert-to-empty-patch. Two firings is not a rate. Turning this back on is a
+ * wave of its own — this control alone, on r92's contract text, with
+ * `django__django-15732` and `sympy__sympy-13878` as the rows to read — and
+ * not a change that rides along with another.
+ *
+ * A run is asked to store the check it verified with as
+ * `state.verification: { flow, input }` and to re-run that exact check after
+ * its edit. Nothing in that rule says the check ever failed. A run may pick a
+ * command that was green on the tree it was handed, watch it stay green after
+ * the edit, and complete citing a before-and-after that never moved.
+ *
+ * That is not a hypothetical either. `django__django-14351` lost a baseline
+ * verdict across two waves, and its journal says why in two rows: the same
+ * verification script — one content digest — ran at sequence 260, before any
+ * frame of the run had changed a byte, and exited 0; then again at sequence
+ * 582, after the edit, and exited 0. Both readings are true and the pair
+ * establishes nothing. The contract already says the words — *a command
+ * becomes evidence only once you have SEEN it fail on the unmodified tree* —
+ * and the run stored a check it had watched pass there instead.
+ *
+ * The harness can see this without re-running anything. It already records
+ * every check a frame ran, whether that check reported a passing exit status,
+ * and how many frames of the run had changed the workspace when it ran. A
+ * check that passed while that count was zero, in a frame that itself changed
+ * nothing, is a check that passed on the tree the run was handed. If a later
+ * cell stores that exact call as its verification, the run is standing on a
+ * proof that cannot distinguish its own change from no change at all.
+ *
+ * One reading takes it back: the same call reported *failing* over that same
+ * untouched tree. Then the run has watched the red the contract asks for, and a
+ * second, green reading of it before any edit says the command is unsteady
+ * rather than that the run never saw it fail. Such a signature is never
+ * admitted, so the observation can only ever be made about a check this run has
+ * no pre-edit failure for.
+ *
+ * So the harness says so, and does nothing else. It is delivered on the
+ * `invalidProbe` channel — the one place the loop already contradicts a
+ * reading of a result the flow itself could see through — because it is the
+ * same class of fact: a result that reads identically on a broken tree and on
+ * a fixed one. No bounce, no demand, no cap: the run continues on the
+ * transition it wrote. A harness that refused the completion would be grading
+ * the agent's work with its own, which is the line every control in this
+ * package holds, and it would be refusing on a *guess* — a check that was
+ * green before an edit is the right check for a task whose bug is a crash the
+ * command never reached, and only the run knows which it has.
+ *
+ * It fires at most once per distinct verification input. The fact is about a
+ * call, the record only grows, and a run that has been told and stored the
+ * same check again has decided, which is its decision to make.
+ *
+ * @since 0.1.0
+ */
+
+import { Schema } from "effect"
+import * as Effect from "effect/Effect"
+import type * as NarrowedCheck from "./NarrowedCheck.ts"
+
+/**
+ * How many pristine-tree passes one run carries forward.
+ *
+ * The ledger is durable controller state, so it is bounded, and it only ever
+ * grows while the run has changed nothing: the moment a frame edits, nothing
+ * new is admitted. The longest graded run made 43 calls across 24 frames with
+ * its first edit at frame 3, so sixteen covers every check a run takes before
+ * it commits to a change. A run that outlives the bound forgets its oldest
+ * passes first, which can cost the observation and can never invent one.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const retained = 16
+
+/**
+ * One check that passed over the tree the run was handed.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export class Pass extends Schema.Class<Pass>("flows/harness/VacuousVerification/Pass")({
+  /** The flow the call named. */
+  flow: Schema.String,
+  /** The call's identity, as the controller's own signature names it. */
+  signature: Schema.String,
+  /** The call's input as it was written, clipped, for the observation to quote. */
+  label: Schema.String
+}) {}
+
+/**
+ * The pristine-tree passes this run carries, oldest first and bounded.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Ledger = Schema.Array(Pass).pipe(
+  Schema.withConstructorDefault(Effect.succeed<ReadonlyArray<Pass>>([])),
+  Schema.withDecodingDefaultKey(Effect.succeed<ReadonlyArray<Pass>>([]))
+)
+
+/**
+ * The pristine-tree passes this run carries, oldest first and bounded.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Ledger = typeof Ledger.Type
+
+/**
+ * Records one frame's passing checks, but only while the tree is untouched.
+ *
+ * Three conditions, and all of them are refusals rather than readings. `epoch`
+ * is the run's own count of frames that changed the workspace *before* this
+ * one, so a non-zero epoch means some earlier frame already edited and a pass
+ * taken now says nothing about the tree the run was handed. `stable` is the
+ * same question inside one frame: a frame's calls are not ordered against its
+ * edits in anything the harness records, so a check from a frame that also
+ * edited might have run on either side of it. `Sufficiency` refuses the same
+ * stamp for the same reason; see `NarrowedCheck` `Check` `stable`.
+ *
+ * `failed` is the third, and it is the one that keeps the observation from
+ * contradicting the record it is read off. A check the run has already watched
+ * *fail* over the tree it was handed is a check the run has done the contract's
+ * work on, whatever it printed the second time: it is red on the unmodified
+ * tree, and a later green reading of it at the same epoch says the command is
+ * unsteady, not that the run never saw it fail. Telling such a run its proof
+ * was "already green" would be a sentence its own journal refutes, so the
+ * signature is refused on the way in and evicted if an earlier pass already put
+ * it there. The list is the run's failing-check ledger read at epoch zero —
+ * `Sufficiency` already keeps it, stamped with the epoch each failure was
+ * watched in — so nothing new is measured or stored for this. That ledger is
+ * bounded, so a run with more distinct pre-edit failures than `Sufficiency`
+ * retains can forget one; forgetting can cost the refusal and can never invent
+ * a pass.
+ *
+ * A repeated signature keeps its first entry rather than taking a second slot:
+ * the entries are all the same tree, so re-running one adds no information and
+ * re-stamping it would only cost the ledger its oldest genuinely distinct pass.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const remember = (
+  ledger: Ledger,
+  options: {
+    /** The checks this frame ran. */
+    readonly frame: ReadonlyArray<NarrowedCheck.Check>
+    /** Frames that had changed the workspace before this one. */
+    readonly epoch: number
+    /** Signatures this run has watched fail over the tree it was handed. */
+    readonly failed: ReadonlyArray<string>
+  }
+): Ledger => {
+  const refused = new Set(options.failed)
+  const kept = new Map(
+    ledger.filter((entry) => !refused.has(entry.signature)).map((entry) => [entry.signature, entry])
+  )
+  if (options.epoch === 0) {
+    for (const check of options.frame) {
+      if (!check.passing || !check.stable) continue
+      if (refused.has(check.signature)) continue
+      if (kept.has(check.signature)) continue
+      kept.set(check.signature, new Pass({ flow: check.flow, signature: check.signature, label: check.label }))
+    }
+  }
+  const distinct = [...kept.values()]
+  return distinct.slice(Math.max(0, distinct.length - retained))
+}
+
+/**
+ * The `{ flow, input }` pair a cell stored as its verification, if it stored
+ * one this module can read.
+ *
+ * The reserved key and its two fields are the contract's own words, and this
+ * is the only thing the controller ever reads out of `agentState`. Anything
+ * else under `verification` — a string, a bare command, a shape the contract
+ * does not describe — reads as absent, because a state key the harness cannot
+ * parse is the cell's own memory and not a claim about evidence.
+ *
+ * @category conversions
+ * @since 0.1.0
+ */
+export const stored = (
+  agentState: Schema.Json
+): { readonly flow: string; readonly input: Schema.Json } | undefined => {
+  if (agentState === null || typeof agentState !== "object" || Array.isArray(agentState)) return undefined
+  const declared = (agentState as Record<string, Schema.Json>)["verification"]
+  if (declared === null || declared === undefined || typeof declared !== "object" || Array.isArray(declared)) {
+    return undefined
+  }
+  const { flow, input } = declared as Record<string, Schema.Json>
+  return typeof flow === "string" && input !== undefined ? { flow, input } : undefined
+}
+
+/**
+ * Finds the pristine-tree pass a stored verification is standing on.
+ *
+ * The match is on the controller's own call signature, so it is the *exact*
+ * `{ flow, input }` the contract asks a run to reuse — a broadened or narrowed
+ * command is a different call and is not this failure.
+ *
+ * `stated` is the run's record of what it has already been told, which is what
+ * keeps this to one sentence per distinct input.
+ *
+ * @category conversions
+ * @since 0.1.0
+ */
+export const find = (options: {
+  /** Checks that passed over the tree the run was handed, oldest first. */
+  readonly ledger: Ledger
+  /** The signature of the `{ flow, input }` the cell stored. */
+  readonly signature: string
+  /** Verification signatures this run has already been told about. */
+  readonly stated: ReadonlyArray<string>
+}): Pass | undefined => {
+  if (options.stated.includes(options.signature)) return undefined
+  return options.ledger.find((entry) => entry.signature === options.signature)
+}
+
+/**
+ * States that the stored proof was already green before anything changed.
+ *
+ * It quotes the call, says what the record establishes about it, and names the
+ * two things the run may do — keep it, having a reason, or go find a reading
+ * that can move. Neither is refused and neither is graded: a check that was
+ * green before the edit is the right check for a task whose bug is a crash the
+ * command never reached, and only the run knows whether that is this task.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const observation = (found: Pass): string =>
+  `Vacuous verification — the check you stored as \`state.verification\` is a check this run already watched PASS on the unmodified tree, before any frame of it changed a byte.
+
+- the stored check: ${found.flow} ${found.label}
+- what this run saw it do on the tree it was handed: exit 0
+
+Re-running it after your edit cannot show your change did anything: it reads identically on a broken tree and on a fixed one, so a green result after the edit is the same green result as before it. A proof is a check you have watched FAIL and then watched pass. Nothing is being asked of you and nothing has been refused — if this command is genuinely the only observable the task has, keep it and say in your output that it never failed and why. Otherwise the reading you still need is one that is red right now. This notice is written once per distinct verification.`

package/src/VariablesPanel.ts

@@ -0,0 +1,165 @@
+/**
+ * The variables panel: what the realm holds, stated every frame.
+ *
+ * A run's memory is not a JSON document the cell filed — it is the set of names
+ * the realm is holding, and the model can only act on what the prompt says about
+ * them. This is what the prompt says.
+ *
+ * Every line is a name, its type, one *cheap* size, and when it was last bound.
+ * Nothing here is serialized whole: a panel that stringified every global would
+ * pay the heap for it every frame, and the value the model wants is already
+ * under the name the panel prints.
+ *
+ * Freshness is derived from the cheap size, which is what makes the panel cost
+ * nothing. A binding rewritten to a value of the same type and the same size —
+ * a 40-character string replaced by a different 40-character string — reads as
+ * unchanged and keeps its stamp. That bound is stated rather than hidden: the
+ * panel is a roster, and the run's own prints are what say a value moved.
+ *
+ * @since 0.1.0
+ */
+
+import { Effect, Schema } from "effect"
+import * as CallLedger from "./CallLedger.ts"
+import * as elide from "./internal/elide.ts"
+import { NonNegativeSafeInt } from "./internal/nonNegativeSafeInt.ts"
+
+/**
+ * How many names the panel prints before it starts counting instead.
+ *
+ * Sixty-four is the same order as `CallLedger` `bound` and well above what a
+ * round near par binds: the five golfed instances hold between 6 and 21 names
+ * at their last frame. A run past the bound is shown its most recently bound
+ * names and told how many older ones it still holds.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const bound = 64
+
+/**
+ * One name the realm holds, with the cheap facts a probe can read off it.
+ *
+ * `size` is already rendered by the probe — a string's length, an array's
+ * length, an object's key count, a function's arity, a number or boolean by
+ * value — because the value itself never crosses the realm boundary.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export class Binding extends Schema.Class<Binding>("flows/harness/VariablesPanel/Binding")({
+  name: Schema.String,
+  /**
+   * The name's JavaScript type, `unset` for a name a throw left unassigned, or
+   * `unreadable` for one whose value the probe could not even read — a throwing
+   * accessor, a proxy that refuses its own keys. The two are named apart because
+   * they say different things: one name holds nothing, the other holds something
+   * that will not be looked at.
+   */
+  type: Schema.String,
+  /** One cheap measure of the value, already rendered; empty when there is none. */
+  size: Schema.String
+}) {}
+
+/**
+ * One name the realm holds, with the frames that first and last bound it.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export class Stamp extends Schema.Class<Stamp>("flows/harness/VariablesPanel/Stamp")({
+  name: Schema.String,
+  type: Schema.String,
+  size: Schema.String,
+  /** The frame whose cell last changed the binding's cheap shape. */
+  frame: NonNegativeSafeInt,
+  /** The frame whose cell first bound the name. */
+  since: NonNegativeSafeInt
+}) {}
+
+/**
+ * Every name the realm holds, with the frames that bound it.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Ledger = Schema.Array(Stamp).pipe(
+  Schema.withConstructorDefault(Effect.succeed<ReadonlyArray<Stamp>>([])),
+  Schema.withDecodingDefaultKey(Effect.succeed<ReadonlyArray<Stamp>>([]))
+)
+
+/**
+ * Every name the realm holds, with the frames that bound it.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Ledger = typeof Ledger.Type
+
+/**
+ * Re-stamps the panel against the bindings a frame closed on.
+ *
+ * A name whose type and size are unchanged keeps both of its frames, so the
+ * panel says when a binding last moved rather than that every name was touched
+ * again. A name the realm no longer reports is dropped: a `var` global cannot
+ * be deleted, so the only way a name leaves the probe's answer is the realm
+ * being rebuilt, and a roster that outlived its realm would be a lie.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const stamp = (known: Ledger, bindings: ReadonlyArray<Binding>, frame: number): Ledger => {
+  const previous = new Map(known.map((entry) => [entry.name, entry] as const))
+  return bindings.map((binding) => {
+    const before = previous.get(binding.name)
+    if (before === undefined) {
+      return new Stamp({ name: binding.name, type: binding.type, size: binding.size, frame, since: frame })
+    }
+    return before.type === binding.type && before.size === binding.size
+      ? before
+      : new Stamp({ name: binding.name, type: binding.type, size: binding.size, frame, since: before.since })
+  })
+}
+
+/** Names how a binding stands relative to the frame that just ran. */
+const marked = (entry: Stamp, frame: number): string => {
+  if (entry.since === frame) return "new this frame"
+  if (entry.frame === frame) return "changed this frame"
+  const age = frame - entry.frame
+  return `bound at frame ${entry.frame}, ${age} frame${age === 1 ? "" : "s"} ago`
+}
+
+/**
+ * Renders the panel for one frame's prompt.
+ *
+ * `frame` is the frame whose cell just ran, which is what `new` and `changed`
+ * are relative to.
+ *
+ * @category conversions
+ * @since 0.1.0
+ */
+export const render = (options: {
+  readonly ledger: Ledger
+  readonly frame: number
+}): string => {
+  if (options.ledger.length === 0) {
+    return "Your realm holds no names yet. Anything a cell declares at the top level is still bound in every later cell of this run."
+  }
+  const ordered = [...options.ledger].sort((left, right) => left.frame - right.frame)
+  const listed = ordered.slice(Math.max(0, ordered.length - bound))
+  const uncounted = ordered.length - listed.length
+  const lines = listed.map((entry) =>
+    elide.head(
+      `- ${entry.name} (${entry.type}${entry.size === "" ? "" : `, ${entry.size}`}) — ${marked(entry, options.frame)}`,
+      CallLedger.width,
+      "the name is what recalls the value"
+    )
+  )
+  return [
+    `Names your realm holds (${options.ledger.length}), least recently bound first. Read and compute with these instead of fetching them again:`,
+    ...lines,
+    ...(uncounted > 0
+      ? [`- … and ${uncounted} older name${uncounted === 1 ? "" : "s"} not listed here; they are still bound.`]
+      : [])
+  ].join("\n")
+}

package/src/index.ts

@@ -0,0 +1,204 @@
+/**
+ * @since 0.1.0
+ *
+ * `/harness` — built-in agent-loop translation contracts and pure
+ * turn helpers.
+ */
+
+/**
+ * @category errors
+ * @since 0.1.0
+ */
+export * as HarnessError from "./HarnessError.ts"
+
+/**
+ * @category events
+ * @since 0.1.0
+ */
+export * as AgentEvent from "./AgentEvent.ts"
+
+/**
+ * @category controls
+ * @since 1.0.0-rc.0
+ */
+export * as CompletionClaim from "./CompletionClaim.ts"
+
+/**
+ * @category controls
+ * @since 1.0.0-rc.0
+ */
+export * as Supervisor from "./Supervisor.ts"
+
+/**
+ * @category controls
+ * @since 1.0.0-rc.0
+ */
+export * as Monitor from "./Monitor.ts"
+
+/**
+ * @category controls
+ * @since 1.0.0-rc.0
+ */
+export * as Judgement from "./Judgement.ts"
+
+/**
+ * @category controls
+ * @since 1.0.0-rc.0
+ */
+export * as Relevance from "./Relevance.ts"
+
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as Plan from "./Plan.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as EngineLike from "./EngineLike.ts"
+
+/**
+ * @category utilities
+ * @since 0.1.0
+ */
+export * as Tokens from "./Tokens.ts"
+
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as ContextWindow from "./ContextWindow.ts"
+
+/**
+ * @category projections
+ * @since 0.1.0
+ */
+export * as Transcript from "./Transcript.ts"
+
+/**
+ * @category projections
+ * @since 1.0.0-rc.1
+ */
+export * as ExternalTranscript from "./ExternalTranscript.ts"
+
+/**
+ * @category compaction
+ * @since 0.1.0
+ */
+export * as Compaction from "./Compaction.ts"
+
+/**
+ * @category steering
+ * @since 0.1.0
+ */
+export * as Steering from "./Steering.ts"
+
+/**
+ * @category notifications
+ * @since 0.1.0
+ */
+export * as Notifications from "./Notifications.ts"
+
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as Cell from "./Cell.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as Sandbox from "./Sandbox.ts"
+
+/**
+ * @category streams
+ * @since 0.1.0
+ */
+export * as CellTurn from "./CellTurn.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as CellHistory from "./CellHistory.ts"
+
+/**
+ * @category constructors
+ * @since 0.1.0
+ */
+export * as CellCalls from "./CellCalls.ts"
+
+/**
+ * @category constructors
+ * @since 0.1.0
+ */
+export * as FlowBinding from "./FlowBinding.ts"
+
+/**
+ * @category decoding
+ * @since 0.1.0
+ */
+export * as StructuredOutput from "./StructuredOutput.ts"
+
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as TruncatedOutput from "./TruncatedOutput.ts"
+
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as CallLedger from "./CallLedger.ts"
+
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as NarrowedCheck from "./NarrowedCheck.ts"
+
+/**
+ * @category conversions
+ * @since 0.1.0
+ */
+export * as CellValidation from "./CellValidation.ts"
+
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as UnmovedTree from "./UnmovedTree.ts"
+
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as UnresolvedFailure from "./UnresolvedFailure.ts"
+
+/**
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export * as FailedCall from "./FailedCall.ts"
+
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as Sufficiency from "./Sufficiency.ts"
+
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as VacuousVerification from "./VacuousVerification.ts"
+
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as VariablesPanel from "./VariablesPanel.ts"