looply-cli 0.0.0-stage → 0.3.0

package/dist/session-observation-store.d.ts

@@ -0,0 +1,98 @@
+import { type ObservationRecord } from '@looply/core';
+/**
+ * WHERE AN OBSERVATION LIVES AFTER THE PROCESS THAT MADE IT EXITS.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 IT DID NOT LIVE ANYWHERE. `looply sessions --watch` printed its record to a
+ * terminal and the record died with the process — so a watch was a thing you
+ * could do and never a thing you could later CONSULT. "Was that session
+ * observed, and what did it do?" had no answer an hour afterwards, which is
+ * most of what observing is for.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ⚠️ NOT THE SESSION LEDGER, AND THE DIFFERENCE IS NOT COSMETIC.
+ *
+ * `sessions.jsonl` is the handshake's history — who offered, what was decided,
+ * who acknowledged. It is small, permanent and append-only, and every line in
+ * it is a fact about PERMISSION. An observation is none of those things: it is
+ * large, it is about WORK rather than permission, and it stops being useful
+ * long before a grant does. Putting one in the ledger would make the ledger the
+ * default answer to every "where does this go" question by accident, and would
+ * make a file people rely on unbounded.
+ *
+ * So: its own root, one file per watch, and a root a retention policy can be
+ * pointed at — this product already decided how disposable artifacts are
+ * removed (D5), and an observation is exactly that kind of artifact.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 AN OPEN RECORD IS WRITTEN BEFORE THE WATCH BEGINS, AND THAT IS THE POINT.
+ *
+ * A record written only at the end exists only for watches that ENDED. Kill the
+ * process — which is the ordinary way a long watch stops — and the store
+ * contains nothing, and "no record on file" means both "never watched" and
+ * "watched and the terminal closed". The same ambiguity `session-observe.ts`
+ * exists to destroy, reintroduced by the storage layer.
+ *
+ * So the record is written at attach with `stop: null`, and rewritten when the
+ * watch closes. A record left open is a watch that never closed, and
+ * `observationCompleteness` already calls that `nothing-established`.
+ */
+export interface ObservationPaths {
+    readonly root: string;
+    readonly session: string;
+}
+export declare function observationPaths(stateDir: string, sessionId: string): ObservationPaths;
+/**
+ * Write the record, atomically.
+ *
+ * ⚠️ TEMP-THEN-RENAME, because this is called twice for one watch — once at
+ * attach and once at the close — and a reader arriving between the open and the
+ * write of the closed version must see one or the other, never half of each.
+ */
+export declare function writeObservation(paths: ObservationPaths, record: ObservationRecord): string;
+/**
+ * The record a watch writes before it has seen anything.
+ *
+ * 🔴 `attached: true` AND `stop: null` IS NOT AN OPTIMISTIC GUESS. A watcher
+ * that has taken its baseline HAS attached — that is what attaching is — and it
+ * genuinely has not stopped. Both fields are true at the moment this is
+ * written, and if the process dies here they stay true forever, which is
+ * exactly what a reader should be told.
+ */
+export declare function openRecord(sessionId: string, coversFrom: string): ObservationRecord;
+export interface StoredObservation {
+    readonly file: string;
+    readonly record: ObservationRecord;
+    /**
+     * 🔴 WRITTEN AND NEVER CLOSED. Distinct from every other answer: the fold
+     * calls an open record `nothing-established` and gives the reason "still
+     * running", which is true of a live watch and misleading about a dead one.
+     * The store knows something the fold cannot — that nobody is holding this
+     * file open — and says it rather than leaving the fold's wording to be read
+     * as a status.
+     */
+    readonly open: boolean;
+}
+export interface ReadOutcome {
+    readonly observations: readonly StoredObservation[];
+    readonly unreadable: readonly string[];
+    /** Whether this session has a directory at all. */
+    readonly present: boolean;
+}
+/**
+ * Every observation on file for one session, oldest first.
+ *
+ * ⚠️ A DIRECTORY THAT IS NOT THERE AND ONE THAT IS EMPTY ARE DIFFERENT FACTS,
+ * the same distinction the outbox keeps: never watched, versus watched and the
+ * records removed.
+ */
+export declare function readObservations(paths: ObservationPaths): ReadOutcome;
+/**
+ * The lines a person reads.
+ *
+ * 🔴 AN EMPTY LIST GETS A SENTENCE, ALWAYS, AND WHICH SENTENCE DEPENDS ON WHY.
+ * "Never watched" and "watched, and the records are gone" are the two readings
+ * of nothing, and a reader who has to guess will guess the reassuring one.
+ */
+export declare function reportObservations(sessionId: string, outcome: ReadOutcome, out: (line: string) => void): void;
+//# sourceMappingURL=session-observation-store.d.ts.map

package/dist/session-observation-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-observation-store.d.ts","sourceRoot":"","sources":["../src/session-observation-store.ts"],"names":[],"mappings":"AAEA,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAGtF;AAOD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAY3F;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,iBAAiB,CAanF;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAaD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACpD,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAkCrE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CA6B7G"}

package/dist/session-observation-store.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observationPaths = observationPaths;
+exports.writeObservation = writeObservation;
+exports.openRecord = openRecord;
+exports.readObservations = readObservations;
+exports.reportObservations = reportObservations;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const core_1 = require("@looply/core");
+function observationPaths(stateDir, sessionId) {
+    const root = (0, node_path_1.join)(stateDir, 'observations');
+    return { root, session: (0, node_path_1.join)(root, sessionId) };
+}
+/** One watch's file, named by the moment it covers from. */
+function fileFor(paths, coversFrom) {
+    return (0, node_path_1.join)(paths.session, `${coversFrom.replace(/[:.]/g, '-')}.json`);
+}
+/**
+ * Write the record, atomically.
+ *
+ * ⚠️ TEMP-THEN-RENAME, because this is called twice for one watch — once at
+ * attach and once at the close — and a reader arriving between the open and the
+ * write of the closed version must see one or the other, never half of each.
+ */
+function writeObservation(paths, record) {
+    (0, node_fs_1.mkdirSync)(paths.session, { recursive: true });
+    const target = fileFor(paths, record.coversFrom);
+    const tmp = `${target}.partial`;
+    const fd = (0, node_fs_1.openSync)(tmp, 'w');
+    try {
+        (0, node_fs_1.writeSync)(fd, `${JSON.stringify(record, null, 2)}\n`);
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+    (0, node_fs_1.renameSync)(tmp, target);
+    return target;
+}
+/**
+ * The record a watch writes before it has seen anything.
+ *
+ * 🔴 `attached: true` AND `stop: null` IS NOT AN OPTIMISTIC GUESS. A watcher
+ * that has taken its baseline HAS attached — that is what attaching is — and it
+ * genuinely has not stopped. Both fields are true at the moment this is
+ * written, and if the process dies here they stay true forever, which is
+ * exactly what a reader should be told.
+ */
+function openRecord(sessionId, coversFrom) {
+    return {
+        sessionId,
+        coversFrom,
+        coversTo: null,
+        events: [],
+        predates: 0,
+        outOfScope: 0,
+        unjudgeable: 0,
+        unreadable: [],
+        stop: null,
+        attached: true,
+    };
+}
+const isRecord = (v) => {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const o = v;
+    return (typeof o['sessionId'] === 'string' &&
+        typeof o['coversFrom'] === 'string' &&
+        Array.isArray(o['events']) &&
+        typeof o['attached'] === 'boolean');
+};
+/**
+ * Every observation on file for one session, oldest first.
+ *
+ * ⚠️ A DIRECTORY THAT IS NOT THERE AND ONE THAT IS EMPTY ARE DIFFERENT FACTS,
+ * the same distinction the outbox keeps: never watched, versus watched and the
+ * records removed.
+ */
+function readObservations(paths) {
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)(paths.session).sort();
+    }
+    catch {
+        return { observations: [], unreadable: [], present: false };
+    }
+    const observations = [];
+    const unreadable = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const at = (0, node_path_1.join)(paths.session, name);
+        try {
+            /**
+             * 🔴 `lstat`, NEVER `stat`. This root is retention-eligible and therefore
+             * a place things get removed from; a link here would make a read reach
+             * somewhere nobody pointed it.
+             */
+            if ((0, node_fs_1.lstatSync)(at).isSymbolicLink()) {
+                unreadable.push(`${name} is a link and was not followed`);
+                continue;
+            }
+            const parsed = JSON.parse((0, node_fs_1.readFileSync)(at, 'utf8'));
+            if (!isRecord(parsed)) {
+                unreadable.push(`${name} is not an observation record`);
+                continue;
+            }
+            observations.push({ file: at, record: parsed, open: parsed.stop === null });
+        }
+        catch (e) {
+            unreadable.push(`${name} could not be read: ${e.message}`);
+        }
+    }
+    return { observations, unreadable, present: true };
+}
+/**
+ * The lines a person reads.
+ *
+ * 🔴 AN EMPTY LIST GETS A SENTENCE, ALWAYS, AND WHICH SENTENCE DEPENDS ON WHY.
+ * "Never watched" and "watched, and the records are gone" are the two readings
+ * of nothing, and a reader who has to guess will guess the reassuring one.
+ */
+function reportObservations(sessionId, outcome, out) {
+    if (!outcome.present) {
+        out(`observations: ${sessionId} has never been watched — nothing was ever recorded about what it did`);
+        return;
+    }
+    if (outcome.observations.length === 0 && outcome.unreadable.length === 0) {
+        out(`observations: ${sessionId} has been watched, and no record remains — they may have been retained away`);
+        return;
+    }
+    out(`observations: ${outcome.observations.length} on file for ${sessionId}`);
+    for (const stored of outcome.observations) {
+        const c = (0, core_1.observationCompleteness)(stored.record);
+        const span = `${stored.record.coversFrom} .. ${stored.record.coversTo ?? '(never closed)'}`;
+        out(`  ${span}  ${stored.record.events.length} event(s)`);
+        /**
+         * ⚠️ AN OPEN RECORD SAYS SO IN ITS OWN WORDS. The fold answers
+         * `nothing-established` with "still running", which is true of a live watch
+         * and misleading about one whose process was killed an hour ago.
+         */
+        if (stored.open) {
+            out('    open: the watch that wrote this never closed it — the process may have been stopped, and what happened after is unknown');
+        }
+        else {
+            out(`    ${c.kind}: ${c.because}`);
+        }
+        if (stored.record.predates > 0) {
+            out(`    ${stored.record.predates} event(s) predate it and are NOT certified by it`);
+        }
+    }
+    for (const u of outcome.unreadable)
+        out(`  blind: ${u}`);
+}
+//# sourceMappingURL=session-observation-store.js.map

package/dist/session-observation-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-observation-store.js","sourceRoot":"","sources":["../src/session-observation-store.ts"],"names":[],"mappings":";;AAgDA,4CAGC;AAcD,4CAYC;AAWD,gCAaC;AAyCD,4CAkCC;AASD,gDA6BC;AAtND,qCAAsH;AACtH,yCAAiC;AACjC,uCAA+E;AA8C/E,SAAgB,gBAAgB,CAAC,QAAgB,EAAE,SAAiB;IAClE,MAAM,IAAI,GAAG,IAAA,gBAAI,EAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IAC5C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAA,gBAAI,EAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;AAClD,CAAC;AAED,4DAA4D;AAC5D,SAAS,OAAO,CAAC,KAAuB,EAAE,UAAkB;IAC1D,OAAO,IAAA,gBAAI,EAAC,KAAK,CAAC,OAAO,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAAC,KAAuB,EAAE,MAAyB;IACjF,IAAA,mBAAS,EAAC,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,GAAG,MAAM,UAAU,CAAC;IAChC,MAAM,EAAE,GAAG,IAAA,kBAAQ,EAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC9B,IAAI,CAAC;QACH,IAAA,mBAAS,EAAC,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACxD,CAAC;YAAS,CAAC;QACT,IAAA,mBAAS,EAAC,EAAE,CAAC,CAAC;IAChB,CAAC;IACD,IAAA,oBAAU,EAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,UAAU,CAAC,SAAiB,EAAE,UAAkB;IAC9D,OAAO;QACL,SAAS;QACT,UAAU;QACV,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,EAAE;QACV,QAAQ,EAAE,CAAC;QACX,UAAU,EAAE,CAAC;QACb,WAAW,EAAE,CAAC;QACd,UAAU,EAAE,EAAE;QACd,IAAI,EAAE,IAAI;QACV,QAAQ,EAAE,IAAI;KACf,CAAC;AACJ,CAAC;AAgBD,MAAM,QAAQ,GAAG,CAAC,CAAU,EAA0B,EAAE;IACtD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,CAA4B,CAAC;IACvC,OAAO,CACL,OAAO,CAAC,CAAC,WAAW,CAAC,KAAK,QAAQ;QAClC,OAAO,CAAC,CAAC,YAAY,CAAC,KAAK,QAAQ;QACnC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QAC1B,OAAO,CAAC,CAAC,UAAU,CAAC,KAAK,SAAS,CACnC,CAAC;AACJ,CAAC,CAAC;AASF;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAAC,KAAuB;IACtD,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,IAAA,qBAAW,EAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9D,CAAC;IAED,MAAM,YAAY,GAAwB,EAAE,CAAC;IAC7C,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,SAAS;QACtC,MAAM,EAAE,GAAG,IAAA,gBAAI,EAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC;YACH;;;;eAIG;YACH,IAAI,IAAA,mBAAS,EAAC,EAAE,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC;gBACnC,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI,iCAAiC,CAAC,CAAC;gBAC1D,SAAS;YACX,CAAC;YACD,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,IAAA,sBAAY,EAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;YAC7D,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBACtB,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI,+BAA+B,CAAC,CAAC;gBACxD,SAAS;YACX,CAAC;YACD,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC,CAAC;QAC9E,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI,uBAAwB,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IACD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACrD,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAC,SAAiB,EAAE,OAAoB,EAAE,GAA2B;IACrG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACrB,GAAG,CAAC,iBAAiB,SAAS,uEAAuE,CAAC,CAAC;QACvG,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzE,GAAG,CAAC,iBAAiB,SAAS,6EAA6E,CAAC,CAAC;QAC7G,OAAO;IACT,CAAC;IACD,GAAG,CAAC,iBAAiB,OAAO,CAAC,YAAY,CAAC,MAAM,gBAAgB,SAAS,EAAE,CAAC,CAAC;IAC7E,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QAC1C,MAAM,CAAC,GAAG,IAAA,8BAAuB,EAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACjD,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,IAAI,gBAAgB,EAAE,CAAC;QAC5F,GAAG,CAAC,KAAK,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,WAAW,CAAC,CAAC;QAC1D;;;;WAIG;QACH,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAChB,GAAG,CAAC,6HAA6H,CAAC,CAAC;QACrI,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACrC,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;YAC/B,GAAG,CAAC,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,kDAAkD,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,UAAU;QAAE,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;AAC3D,CAAC"}

package/dist/session-observe-runtime.d.ts

@@ -0,0 +1,123 @@
+import { type ObservationRecord, type SessionEvent, type WatchWindow } from '@looply/core';
+/**
+ * THE MECHANICS OF A BOUNDED WATCH. `session-observe.ts` decides; this walks.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 THE FIRST SNAPSHOT IS NOT EVENTS, AND THAT IS THE WHOLE REASON THIS FILE
+ * IS CAREFUL RATHER THAN SHORT.
+ *
+ * A watcher that attaches to a repository and reports every file it finds has
+ * just certified the past — every edit the session made in the hour before
+ * anybody asked arrives stamped with the observer's clock, INSIDE the window,
+ * and `ruleOnEvent` waves all of it through because the timestamps it is
+ * judging are the moment of the walk. The fold cannot catch this; it never sees
+ * the difference between a file that changed and a file that merely exists.
+ *
+ * So `attach` takes a baseline and emits NOTHING from it. Only differences from
+ * that baseline become events, and the baseline's own existence is not a
+ * finding. `session-adoption.ts` puts it as "adoption cannot make those things
+ * observed", and this is the one place in the product where getting it wrong
+ * would be silent and total.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 AND THE WALK DOES NOT FOLLOW LINKS. `lstat`, never `stat` — the rule
+ * `retention-apply-runtime.ts` already carries for deletion, and it is the same
+ * rule for the same reason: a junction inside the granted scope pointing
+ * somewhere else would let a watch observe outside the grant while every path
+ * it recorded looked perfectly in-bounds. A link is NOTED (it is a real fact
+ * about the tree) and not descended.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ⚠️ EVERY BOUND HERE FAILS LOUD. A scope entry that cannot be read, a walk
+ * that hits its ceiling, a tick that throws — each becomes a named entry in
+ * `unreadable`, which makes the record `partial`. None of them is a shrug: a
+ * watch that quietly skipped an unreadable directory would report `complete`
+ * over a blind spot, which is the ambiguity the fold exists to prevent, smuggled
+ * back in through the runtime.
+ */
+/** What the observer can do. Injected, so a test drives a real clock nowhere. */
+export interface ObserveRuntimeDeps {
+    /** The observer's clock. Never a file's mtime — see `SessionEvent.at`. */
+    now(): string;
+    /** Is the session's process still there? `unknown` is a real answer. */
+    liveness(): 'alive' | 'gone' | 'unknown';
+    /** What the server says about the grant right now. `false` ends the watch. */
+    stillAuthorized(): Promise<boolean>;
+    /** The revision the workspace is on, or `null` when it could not be read. */
+    revision(): string | null;
+    /** Wait between ticks. */
+    sleep(ms: number): Promise<void>;
+    /** A caller-owned flag, checked every tick. */
+    askedToStop(): boolean;
+}
+export interface WatchOptions {
+    /** The checkout the scope is relative to. */
+    readonly root: string;
+    readonly tickMs: number;
+    /**
+     * How many filesystem entries one walk may visit.
+     *
+     * 🔴 NOT A PERFORMANCE KNOB. Without it a watch pointed at a scope containing
+     * `node_modules` stops responding to revocation — it is inside a walk — and a
+     * watch that cannot notice a revocation is the failure this whole feature is
+     * about. Hitting it is recorded as a blind spot, never as a clean walk.
+     */
+    readonly maxEntries: number;
+    readonly maxDepth: number;
+    /**
+     * How many bytes one walk may HASH.
+     *
+     * 🔴 THIS EXISTS BECAUSE SIZE AND TIMESTAMP DO NOT DETECT AN EDIT, AND THAT
+     * WAS MEASURED HERE RATHER THAN ASSUMED: writing '1' then '2' to the same
+     * file back to back, 139 of 200 pairs were byte-identical in `mtimeMs` — and
+     * identically 139 of 200 in `mtimeNs`, so it is not a precision problem that
+     * a finer field fixes. NTFS simply does not move the stamp. A watcher built
+     * on size and timestamp would have reported nothing for most same-size edits,
+     * and reported it as `complete`.
+     *
+     * So contents are hashed, and the budget keeps a 1s tick from turning into a
+     * full-repository scan. Files past the budget fall back to size and timestamp
+     * and are NAMED in `unreadable` — lower resolution is a thing the watch
+     * cannot see, and it is recorded as one rather than rounded up to fine.
+     */
+    readonly maxHashBytes: number;
+}
+export declare const DEFAULT_WATCH_OPTIONS: Omit<WatchOptions, 'root'>;
+/** path (repository-relative, forward slashes) -> size:mtimeMs:sha1|coarse */
+type Snapshot = ReadonlyMap<string, string>;
+interface WalkResult {
+    readonly files: Map<string, string>;
+    /** Scope entries or subtrees this walk could not see, or could not see fully. */
+    readonly unreadable: string[];
+    /** Links found and deliberately not descended. */
+    readonly links: string[];
+}
+/** A snapshot of everything the grant's scope covers, right now. */
+export declare function snapshot(root: string, scope: readonly string[], opt: WatchOptions): WalkResult;
+/**
+ * What changed between two snapshots, as candidate events.
+ *
+ * ⚠️ `at` IS PASSED IN AND IS THE OBSERVER'S CLOCK. Using each file's mtime
+ * would hand a session the ability to place its own events before `coversFrom`
+ * and out of the record — it can write a file, so it can write a timestamp.
+ */
+export declare function diffSnapshots(before: Snapshot, after: Snapshot, at: string): SessionEvent[];
+/**
+ * Watch a session, inside every bound the grant sets, and return the record.
+ *
+ * 🔴 IT RETURNS AN `ObservationRecord` WHATEVER HAPPENS, including when it could
+ * not start. `attached: false` is the honest answer to "the baseline walk
+ * failed", and the fold turns that into `nothing-established` rather than into
+ * an empty, reassuring list.
+ */
+export declare function watchSession(window: WatchWindow, opt: WatchOptions, deps: ObserveRuntimeDeps): Promise<ObservationRecord>;
+/**
+ * The lines a person reads after a watch.
+ *
+ * ⚠️ THE COMPLETENESS IS ON ITS OWN LINE, ALWAYS, even when it is `complete`.
+ * A reader who has to infer from the absence of a warning that a record is
+ * whole is a reader who will one day infer it from the absence of a bug.
+ */
+export declare function reportObservation(record: ObservationRecord, out: (line: string) => void): void;
+export {};
+//# sourceMappingURL=session-observe-runtime.d.ts.map

package/dist/session-observe-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-observe-runtime.d.ts","sourceRoot":"","sources":["../src/session-observe-runtime.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAEjB,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,GAAG,IAAI,MAAM,CAAC;IACd,wEAAwE;IACxE,QAAQ,IAAI,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IACzC,8EAA8E;IAC9E,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,6EAA6E;IAC7E,QAAQ,IAAI,MAAM,GAAG,IAAI,CAAC;IAC1B,0BAA0B;IAC1B,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,+CAA+C;IAC/C,WAAW,IAAI,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,eAAO,MAAM,qBAAqB,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAK5D,CAAC;AAEF,8EAA8E;AAC9E,KAAK,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5C,UAAU,UAAU;IAClB,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;CAC1B;AAsGD,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,YAAY,GAAG,UAAU,CAK9F;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,EAAE,CAW3F;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAuJ5B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAW9F"}