pi-onlyne 1.1.2 → 1.2.0

package/src/protocol.mjs

@@ -111,9 +111,13 @@ export function readyReport({ taskId, sessionId, generation, seq }) {
 }
 
 /**
- * `report.heartbeat`. `observed` is a full `Observation` (`onlyne-session`'s
- * reducer type), not a loose status string: the host deserialises it and rejects
- * anything that is not a legal state tuple.
+ * `report.heartbeat`. `observed` is an `Observation` (`onlyne-session`'s reducer
+ * type), not a loose status string: the host deserialises the tuple, overwrites
+ * the six dimensions it owns — `delivery` and `recovery` from its intent drain
+ * and reducer history, `generation_live` and the reconcile tuning with its
+ * counter from the role's own records — and repairs whatever pairing that leaves
+ * before the reducer reads it. What
+ * this plugin puts into the body is `observationFor`'s exact key set.
  */
 export function heartbeatReport({ taskId, generation, seq, agent, host = null }) {
   return {
@@ -127,40 +131,6 @@ export function heartbeatReport({ taskId, generation, seq, agent, host = null })
   };
 }
 
-/**
- * The final observation of a settled session: `agent: idle` beside the outcome
- * the completion just stated.
- *
- * A session that only ever reported `running` and then completed leaves the
- * ledger's projection saying `running` forever, because nothing observes the
- * exit. This body is the tuple the host's own settle produces
- * (`onlyne-session/src/reconcile.rs::settle_body`) with the agent dimension
- * moved to `idle`, so `is_legal` accepts it: `outcome: done` requires
- * `delivery: accepted` and an idle agent requires `recovery: draining`, and any
- * other outcome carries the delivery unchanged.
- */
-export function settledReport({ taskId, outcome, generation, seq, host = null }) {
-  const normalized = normalizeOutcome(outcome);
-  const done = normalized === "done";
-  const observed = {
-    version: { generation, seq },
-    generation_live: true,
-    isolate_after: 1,
-    terminate_after: 3,
-    mismatch_count: 0,
-    agent: "idle",
-    delivery: done ? "accepted" : "none",
-    resource: "attached",
-    recovery: done ? "draining" : "none",
-    outcome: normalized,
-    // `project(idle, accepted, …, done)` is `exited`; every other outcome keeps
-    // the session `working` until its resource closes.
-    public: done ? "exited" : "working",
-  };
-  if (host) observed.host = host;
-  return { kind: "heartbeat", data: { task_id: taskId, generation, seq, observed } };
-}
-
 /** `report.complete` — the terminal fact the ledger keeps. */
 export function completeReport({ taskId, outcome, head }) {
   const report = { kind: "complete", data: { task_id: taskId, outcome: normalizeOutcome(outcome) } };
@@ -191,17 +161,29 @@ export function detachArgs(reason) {
 }
 
 /**
- * A legal `Observation` for one agent state.
+ * The observation for one agent state: the plugin's own report, on the wire as
+ * the `observed` body of a heartbeat.
  *
- * `onlyne-session`'s `is_legal` requires `public` to be `project(...)` of the
- * other dimensions and non-zero reconcile policy, so the tuple is built rather
- * than passed through: the plugin owns the agent dimension (the host never
- * synthesises turn state), and leaves delivery at `none`/outcome `pending`,
- * which is its own truth until it reports a completion.
+ * The plugin states three things and only three: the `agent` dimension (its turn
+ * hooks are the only witness), `resource: attached` — the process is running in
+ * the pane, which is the attach the host's dispatch path recorded — and the
+ * `host` binding. `delivery`, `recovery`, `generation_live`, `isolate_after`,
+ * `terminate_after` and `mismatch_count` are placeholders with a reason:
+ * `Observation` has no optional dimensions, the body must deserialize, and the
+ * client rewrites all six from its own records before the reducer reads them
+ * (`crates/onlyne-client/src/session/dispatch/reports.rs`) — the completion
+ * intent and its recovery label are the client's, the reconcile tuning and the
+ * counter beside it are the role's — so what the plugin sends there is never
+ * believed. Neither the task's outcome nor a public view
+ * belongs in a tuple any more — the ledger owns the result, `project` derives
+ * the view — so neither is sent.
  *
- * `host` is where this process runs (`hostBinding`); it is attached only when
- * the environment names a pane, so a pi outside Orca reports a tuple with no
- * host field at all.
+ * `gone` travels as `booting` on purpose: only the host's reconnect-grace window
+ * declares a session dead, and a beat that pre-declared `gone` would bury the
+ * row's agent before that window has run.
+ *
+ * `host` is attached only when the environment names a pane, so a pi outside
+ * Orca reports a tuple with no host field at all.
  * @param {"booting"|"ready"|"running"|"idle"|"gone"} agent
  */
 export function observationFor(agent, { generation, seq, host = null }) {
@@ -217,8 +199,6 @@ export function observationFor(agent, { generation, seq, host = null }) {
     delivery: "none",
     resource: "attached",
     recovery: "none",
-    outcome: "pending",
-    public: state === "running" ? "working" : state === "ready" || state === "idle" ? "idle" : "created",
   };
   if (host) observed.host = host;
   return observed;
@@ -331,13 +311,25 @@ export function normalizeOutcome(value) {
  * session transcript shows where the instruction came from; the role prose
  * (identical in `welcome` and `assign`) is folded in only when it has not
  * already been delivered.
+ *
+ * The header also carries the family's own figures — the hop this assignment
+ * sits at and the hops the family may spend — so a role reads its position off
+ * the instruction. Both appear only when the causality names a hop budget: the
+ * budget is what marks a payload as a member of a bounded family, and a payload
+ * that names none injects exactly the bytes it produced before this header
+ * carried them.
  * @param {{ assign: any, proseIsNew: boolean, attachmentPaths?: string[] }} options
  */
 export function injectionText({ assign, proseIsNew, attachmentPaths = [] }) {
   const envelope = assign.envelope ?? {};
+  const causality = envelope.causality ?? {};
   const taskId = assign.task_id ?? envelope.causality?.task ?? "unknown";
+  const position =
+    typeof causality.hop_budget === "number"
+      ? `, hop ${causality.hop ?? 0}, hop budget ${causality.hop_budget}`
+      : "";
   const lines = [
-    `[onlyne] task ${taskId} from ${describePrincipal(envelope.from)} (kind ${envelope.kind ?? "task"})`,
+    `[onlyne] task ${taskId} from ${describePrincipal(envelope.from)} (kind ${envelope.kind ?? "task"}${position})`,
   ];
   const prose = typeof assign.prose === "string" ? assign.prose.trim() : "";
   if (prose && proseIsNew) {

package/src/protocol.test.mjs

@@ -128,22 +128,38 @@ test("heartbeat carries a full legal observation", () => {
     delivery: "none",
     resource: "attached",
     recovery: "none",
-    outcome: "pending",
-    public: "working",
   });
 });
 
 test("every observation is a state tuple the reducer calls legal", () => {
-  // Mirrors onlyne-session's `project`: running works, idle/ready wait, booting creates.
-  const expected = { booting: "created", ready: "idle", running: "working", idle: "idle", gone: "created" };
-  for (const [agent, projected] of Object.entries(expected)) {
+  // The tuple carries no derived view and no task result any more: `Observation`
+  // dropped `public` and `outcome`, so the projection mapping that once had to be
+  // mirrored here is gone, and the key set is the whole contract.
+  const keys = [
+    "version",
+    "generation_live",
+    "isolate_after",
+    "terminate_after",
+    "mismatch_count",
+    "agent",
+    "delivery",
+    "resource",
+    "recovery",
+  ];
+  const agents = { booting: "booting", ready: "ready", running: "running", idle: "idle", gone: "booting" };
+  for (const [agent, state] of Object.entries(agents)) {
     const observed = observationFor(agent, { generation: 1, seq: 1 });
-    assert.equal(observed.public, projected, `agent=${agent}`);
+    assert.deepEqual(Object.keys(observed), keys, `agent=${agent}`);
+    assert.equal(observed.agent, state, `agent=${agent}: gone travels as booting; only the host's grace declares death`);
     assert.notEqual(observed.isolate_after, 0);
     assert.notEqual(observed.terminate_after, 0);
-    assert.equal(observed.outcome, "pending");
+    // The plugin can see neither the intent drain nor its own resource's close,
+    // and it does not pretend otherwise: the two placeholders below are
+    // overwritten by the client's composition, and `resource: attached` is the
+    // attach the host's dispatch path already recorded.
     assert.equal(observed.delivery, "none");
     assert.equal(observed.recovery, "none");
+    assert.equal(observed.resource, "attached");
   }
 });
 
@@ -238,7 +254,12 @@ test("the ledger head is capped at the plan's 200 characters", () => {
 test("an assignment becomes one message naming its origin and payload", { skip: !hasVectors }, () => {
   const assign = ASSIGN().args;
   const text = injectionText({ assign, proseIsNew: true });
-  assert.match(text, /^\[onlyne\] task 11111111-1111-4111-8111-111111111111 from role:planner \(kind task\)/);
+  // The vector's causality names no hop budget, and the header is byte for byte
+  // the line this plugin has always injected.
+  assert.equal(
+    text.split("\n")[0],
+    "[onlyne] task 11111111-1111-4111-8111-111111111111 from role:planner (kind task)",
+  );
   assert.match(text, /\[onlyne\] role prose from the spec:\nRead the incoming task/);
   assert.match(text, /\nbuild it\n?$/);
 
@@ -247,6 +268,35 @@ test("an assignment becomes one message naming its origin and payload", { skip:
   assert.match(repeat, /build it/);
 });
 
+test("the header names the hop and the budget once the family names a budget", () => {
+  const header = (causality) =>
+    injectionText({
+      assign: {
+        task_id: "t9",
+        envelope: {
+          id: "e9",
+          kind: "task",
+          from: { role: { role: "planner" } },
+          causality,
+          body: { text: "pass it on" },
+        },
+      },
+      proseIsNew: false,
+    }).split("\n")[0];
+
+  assert.equal(
+    header({ task: "t9", hop: 2, attempt: 0, family: "t1", hop_budget: 5 }),
+    "[onlyne] task t9 from role:planner (kind task, hop 2, hop budget 5)",
+  );
+  // A family may spend no further hop: zero is a figure the header carries.
+  assert.equal(
+    header({ task: "t9", hop: 0, attempt: 0, family: "t1", hop_budget: 0 }),
+    "[onlyne] task t9 from role:planner (kind task, hop 0, hop budget 0)",
+  );
+  // No budget named: the compat rule holds, hop or no hop.
+  assert.equal(header({ task: "t9", hop: 2, attempt: 0 }), "[onlyne] task t9 from role:planner (kind task)");
+});
+
 test("an empty-bodied assignment still produces an instruction", () => {
   const text = injectionText({
     assign: { task_id: "t9", envelope: { id: "e9", kind: "note", from: { gateway: { gateway: "fg1", channel: "fake", conversation: "c1" } }, body: {} } },