@junghanacs/entwurf 0.21.0 → 0.23.0

package/mcp/entwurf-bridge/dist/pi-extensions/lib/herdr-placement.js

@@ -0,0 +1,213 @@
+/**
+ * herdr-placement — the PURE half of the placement evidence axis (#116 S1).
+ *
+ * WHAT THIS IS FOR. A citizen opened inside herdr is visible in one of herdr's panes.
+ * That pane is an EPHEMERAL VIEW, never an address and never a liveness receipt
+ * (AGENTS Hard Rule 16, `docs/mux-launch-rail.md` §7). It earns a column in
+ * `entwurf_peers` for one reason: on a herdr host the operator's own question is
+ * "which pane is that one in", and answering it by hand means reading two listings
+ * side by side.
+ *
+ * WHY THIS JOIN IS EXACT EVIDENCE AND NOT A GUESS. §7 admitted exactly two forms of
+ * exact placement evidence (our own launch receipt, and a peer's verifiable
+ * self-report) and named the guesses it refuses: window title, cwd match, and time
+ * proximity. This is a THIRD form and it belongs to neither the receipts nor the
+ * guesses: herdr reports the native session id its OWN OFFICIAL integration told it,
+ * and `nativeSessionId` is unique across the whole meta-store (Hard Rule 7). Two
+ * independently-owned facts meet on one unique key. Nothing here narrows candidates
+ * by cwd, reads a title, or prefers the nearest timestamp. §7 was amended in the same
+ * change that added this module; if the two ever disagree, §7 is the owning document.
+ *
+ * THE TWO AXES ARE NOT EQUALLY EXACT, AND THE DIFFERENCE IS NAMED. On the claude axis
+ * the reported value IS the key, byte for byte. On the pi axis it is a session FILE
+ * PATH, and the key is recovered from that filename by a strict conversion measured on
+ * pi 0.85.1 — a VENDOR FLOOR, not a key equality. Calling both "a unique-key join"
+ * would hide which one can drift when a vendor renames a file. The conversion is
+ * deliberately strict at both ends so that drift lands as a missed join, never a wrong
+ * one, and a listing that declined to read anything says so (see `declinedReports`).
+ *
+ * ONE READ, NO WATCHER. The observer performs exactly ONE `pane list` read for a
+ * whole listing and never retries. herdr publishes no event that says "this pane's
+ * `agent_session` is now settled" — measured on herdr 0.9.0: `pane.updated` is the
+ * only event whose payload carries `agent_session` and plugin `[[events]]` refuses
+ * that name, `events.subscribe` offers three pane kinds and none of them carry it,
+ * and `pane.agent_detected` arrives BEFORE the session reference exists. A retry loop
+ * around that gap is a discovery watcher, which §7 forbids by name. So a citizen
+ * whose pane has not reported yet reads `none` on this pass and is simply asked again
+ * next time.
+ *
+ * FACTS, NOT VERBS. Nothing here returns a transport, a target, or a suggestion. A
+ * pane id must never reach dispatch: `entwurf_v2` resolves its rail from the record
+ * and a live probe, and a placement that is one server restart from being false has
+ * no business in that decision.
+ */
+export const UNOBSERVED_PLACEMENT = { kind: "unobserved" };
+export const NO_PLACEMENT = { kind: "none" };
+export const AMBIGUOUS_PLACEMENT = { kind: "ambiguous" };
+/**
+ * The OFFICIAL integration reports this join accepts, and nothing else.
+ *
+ * WHY THIS TABLE EXISTS. herdr accepts a session reference from any integration,
+ * including one a user wrote (`integrations.mdx:65-90 @ c77af189`), and the row
+ * carries who reported it in `agent_session.agent` / `.source`. Reading only
+ * `kind`/`value` would have let a third party's report stand in for the placement
+ * owner's own — and "the placement owner reported it" is the entire reason
+ * `docs/mux-launch-rail.md` §7 admits this as exact evidence. So the triple is
+ * pinned: source, agent, AND the shape that source is measured to emit. A row that
+ * misses any leg carries no key.
+ *
+ * `backend` is the meta-record backend this report may speak for. It is checked at
+ * resolve time so a claude-reported pane can never be handed to a pi citizen whose
+ * native id happens to collide.
+ */
+const OFFICIAL_REPORTS = {
+    "herdr:claude": { agent: "claude", kind: "id", backend: "claude-code" },
+    "herdr:pi": { agent: "pi", kind: "path", backend: "pi" },
+};
+/**
+ * A pi session filename, measured 2026-09-14 on pi 0.85.1:
+ *
+ *   2026-09-14T05-17-03-979Z_01a09e58-f06a-70e8-b14a-1f0f0c7f7c7d.jsonl
+ *   └────────── start stamp ─────────┘ └──────── nativeSessionId ────────┘
+ *
+ * WHY THIS IS PINNED HERE AND NOT INFERRED. The uuid is the join key and it lives in
+ * a VENDOR filename, so this rule depends on pi's naming and would break silently if
+ * pi changed it. **Vendor floor: pi 0.85.1, measured 2026-09-14** — whether that layout
+ * is a vendor contract or a convention is NOT measured, so this is the one place in the
+ * axis that can drift under us. It is therefore strict on both ends — the name must end
+ * in `.jsonl` and the tail after the last `_` must be a well-formed uuid — and a name
+ * that fails either test yields no key at all rather than a substring that happens to
+ * look plausible. Drift then lands as a DECLINED report (the citizen reads `unobserved`,
+ * not `none`), never as a wrong join onto someone else's pane.
+ */
+const PI_SESSION_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const PI_SESSION_SUFFIX = ".jsonl";
+export function piNativeSessionIdFromPath(value) {
+    if (!value.endsWith(PI_SESSION_SUFFIX))
+        return null;
+    const stem = value.slice(0, -PI_SESSION_SUFFIX.length);
+    const base = stem.slice(stem.lastIndexOf("/") + 1);
+    const cut = base.lastIndexOf("_");
+    if (cut < 0)
+        return null;
+    const candidate = base.slice(cut + 1);
+    return PI_SESSION_UUID.test(candidate) ? candidate : null;
+}
+export function joinKeyOf(row) {
+    if (row.sessionSource === null)
+        return null;
+    const official = OFFICIAL_REPORTS[row.sessionSource];
+    // An unmeasured source — a herdr version we have not run, or a third-party
+    // integration. Declined on purpose: coercing it would invent a rule, and the
+    // whole exact-evidence argument rests on WHO reported.
+    if (official === undefined)
+        return null;
+    if (row.agent !== official.agent)
+        return null;
+    if (row.sessionKind !== official.kind)
+        return null;
+    if (row.sessionValue === null || row.sessionValue.length === 0)
+        return null;
+    const nativeSessionId = official.kind === "id" ? row.sessionValue : piNativeSessionIdFromPath(row.sessionValue);
+    return nativeSessionId === null ? null : { nativeSessionId, backend: official.backend };
+}
+export function buildPlacementIndex(rows) {
+    const byNativeSessionId = new Map();
+    const ambiguous = new Set();
+    let declinedReports = 0;
+    for (const row of rows) {
+        const entry = joinKeyOf(row);
+        if (entry === null) {
+            // Only a row that actually CARRIED a report counts as declined.
+            if (row.sessionSource !== null || row.sessionValue !== null)
+                declinedReports++;
+            continue;
+        }
+        const key = entry.nativeSessionId;
+        if (ambiguous.has(key))
+            continue;
+        const seen = byNativeSessionId.get(key);
+        if (seen !== undefined && seen.paneId !== row.paneId) {
+            byNativeSessionId.delete(key);
+            ambiguous.add(key);
+            continue;
+        }
+        byNativeSessionId.set(key, { ...entry, paneId: row.paneId });
+    }
+    return { byNativeSessionId, ambiguous, declinedReports };
+}
+/**
+ * Parse what `herdr pane list` printed. Returns `null` — "nobody looked" — for any
+ * payload this does not recognise, because a herdr that answered in a shape we cannot
+ * read has told us nothing, and reporting `none` for every citizen on that basis
+ * would be a fabricated measurement. A row missing `pane_id` is the one hard error:
+ * the whole payload is unreadable rather than partially trusted.
+ */
+export function parseHerdrPaneList(stdout) {
+    let raw;
+    try {
+        raw = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const result = raw.result;
+    if (typeof result !== "object" || result === null)
+        return null;
+    const panes = result.panes;
+    if (!Array.isArray(panes))
+        return null;
+    const rows = [];
+    for (const pane of panes) {
+        if (typeof pane !== "object" || pane === null)
+            return null;
+        const paneId = pane.pane_id;
+        if (typeof paneId !== "string" || paneId.length === 0)
+            return null;
+        const session = pane.agent_session;
+        if (typeof session !== "object" || session === null) {
+            rows.push({ paneId, agent: null, sessionSource: null, sessionKind: null, sessionValue: null });
+            continue;
+        }
+        const agent = session.agent;
+        const source = session.source;
+        const kind = session.kind;
+        const value = session.value;
+        rows.push({
+            paneId,
+            agent: typeof agent === "string" ? agent : null,
+            sessionSource: typeof source === "string" ? source : null,
+            sessionKind: kind === "id" || kind === "path" ? kind : null,
+            sessionValue: typeof value === "string" ? value : null,
+        });
+    }
+    return rows;
+}
+/**
+ * The whole decision, for one citizen. A `null` index is the no-herdr host and every
+ * citizen on it reads `unobserved` — which is why this takes the index rather than a
+ * reader: the read happened once, above, and this stays pure.
+ */
+export function resolvePlacement(index, identity) {
+    if (index === null)
+        return UNOBSERVED_PLACEMENT;
+    if (index.ambiguous.has(identity.nativeSessionId))
+        return AMBIGUOUS_PLACEMENT;
+    const entry = index.byNativeSessionId.get(identity.nativeSessionId);
+    if (entry !== undefined) {
+        // The reporting integration must speak for THIS citizen's backend. A pi
+        // integration reporting an id that collides with a claude-code record is a
+        // contradiction, not a placement, and we decline to claim either way.
+        return entry.backend === identity.backend ? { kind: "herdr-pane", paneId: entry.paneId } : UNOBSERVED_PLACEMENT;
+    }
+    // No join. `none` is only honest when the read was COMPLETE — if any report was
+    // declined, the thing we did not read might have been this one.
+    return index.declinedReports > 0 ? UNOBSERVED_PLACEMENT : NO_PLACEMENT;
+}
+/** Render one observation as the listing's column value. `herdr <pane>` says WHERE it
+ * was seen and by WHOM, so a reader never mistakes the pane id for one of ours. */
+export function renderPlacement(placement) {
+    return placement.kind === "herdr-pane" ? `herdr ${placement.paneId}` : placement.kind;
+}