looply-cli 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,195 @@
+import { type AdapterContext, type InboxMessage, type Instruction, type OutboxRuling, type ResultRuling, type SessionAcknowledgement } from '@looply/core';
+/**
+ * THE ADAPTER'S TWO DIRECTORIES. `session-adapter.ts` decides; this reads and
+ * writes.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHERE THE CHANNEL LIVES, AND WHY NOT IN THE WORKSPACE.
+ *
+ *   <stateDir>/sessions/<sessionId>/inbox/     looply → the session
+ *   <stateDir>/sessions/<sessionId>/outbox/    the session → looply, about CONTROL
+ *   <stateDir>/sessions/<sessionId>/results/   the session → looply, about INSTRUCTIONS
+ *   <stateDir>/sessions/<sessionId>/consumed/  files already ruled on
+ *   <stateDir>/sessions/<sessionId>/spent.jsonl  handshakes that are finished
+ *
+ * ⚠️ RESULTS HAVE THEIR OWN DIRECTORY RATHER THAN SHARING THE OUTBOX, and the
+ * reason is mechanical: `readOutboxMessage` answers `null` for anything that is
+ * not a control message, so a result sitting in the outbox would be reported as
+ * "not an outbox message" on every single collection, for as long as it sat
+ * there. Two protocols, two directories, and neither collector trips over the
+ * other's files.
+ *
+ * The obvious alternative — a directory inside the session's own checkout —
+ * puts looply's writes inside the tree a watch is walking, so every offer
+ * becomes an observed event in the session's own record. The project's state
+ * directory is already looply's to write, is already where the session ledger
+ * lives, and is outside every granted scope.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 THE SPENT JOURNAL IS WRITTEN BEFORE THE ACKNOWLEDGEMENT IS ACTED ON, AND
+ * THE ORDER IS A SAFETY DECISION WITH A COST THAT IS WORTH PAYING.
+ *
+ * Act first and record after, and a crash in between leaves a nonce that is
+ * still replayable — the exact thing the nonce exists to prevent, reachable by
+ * pulling a plug at the right moment.
+ *
+ * Record first and crash, and the session's genuine acknowledgement is lost and
+ * cannot be retried: the grant has to be re-issued. That is an inconvenience
+ * with a person in the loop, and the other is a hole. `retention-apply.ts`
+ * settles the same question the same way, for the same reason.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ⚠️ AND IT SURVIVES A RESTART, WHICH THE CHARTER ASKS FOR BY NAME (§6.E:
+ * "revocation, restart and expired authority"). The spent handshakes are a file,
+ * not a set in a process — an in-memory one would make every restart a fresh
+ * opportunity to replay everything that came before it.
+ */
+export interface AdapterPaths {
+    readonly dir: string;
+    readonly inbox: string;
+    readonly outbox: string;
+    readonly results: string;
+    readonly consumed: string;
+    readonly spent: string;
+}
+export declare function adapterPaths(stateDir: string, sessionId: string): AdapterPaths;
+export interface CollectLimits {
+    /**
+     * How many outbox files one collection reads.
+     *
+     * 🔴 NOT A PERFORMANCE KNOB. The outbox is a directory a SESSION writes, and
+     * an unbounded read of it is an unbounded amount of work this process does on
+     * the word of the thing it is deciding about. Files past the limit are left
+     * where they are and NAMED, never silently skipped.
+     */
+    readonly maxFiles: number;
+    /** Bytes. A message is a handful of fields; anything larger is not one. */
+    readonly maxBytes: number;
+}
+export declare const DEFAULT_COLLECT_LIMITS: CollectLimits;
+export interface Collected {
+    /** The outbox file this came from, relative to the outbox. */
+    readonly file: string;
+    readonly ruling: OutboxRuling;
+}
+export interface CollectOutcome {
+    readonly rulings: readonly Collected[];
+    /**
+     * What could not be looked at, and why. Blind spots, named — the same rule
+     * `session-observe.ts` keeps, and for the same reason: an empty list of
+     * rulings must not be able to mean "the session said nothing" when it means
+     * "the outbox could not be read".
+     */
+    readonly unreadable: readonly string[];
+    /** Whether the outbox directory existed at all. */
+    readonly present: boolean;
+}
+/**
+ * Put a message in the session's inbox.
+ *
+ * ⚠️ WRITTEN TO A TEMPORARY NAME AND RENAMED. A session polling this directory
+ * would otherwise be able to read a half-written offer, parse it as malformed,
+ * and discard the only copy of a handshake it will ever be sent.
+ */
+export declare function deliver(paths: AdapterPaths, message: InboxMessage, name?: string): string;
+/** The handshakes this machine has already finished with, across restarts. */
+export declare function spentHandshakes(paths: AdapterPaths): string[];
+/**
+ * Record a handshake as finished, and WHAT IT ESTABLISHED. Append-only.
+ *
+ * 🔴 THE ACKNOWLEDGEMENT IS KEPT, NOT ONLY THE FACT THAT IT WAS SPENT, AND A
+ * LIVE RUN IS WHY.
+ *
+ * Without it, control lasted exactly one read: `sessions --offer` validated the
+ * acknowledgement, archived the file, reported `under management` — and the
+ * very next command found an empty outbox and answered "the session has not
+ * acknowledged this grant". Every `--direct` after a successful adoption ended
+ * direction. The whole feature worked once per acknowledgement and then
+ * un-worked itself.
+ *
+ * ⚠️ AND IT IS BOUND TO THE NONCE, WHICH IS WHAT KEEPS IT HONEST. A remembered
+ * acknowledgement answers for exactly one grant: the next grant carries a new
+ * server-minted handshake, this record does not match it, and the session has to
+ * acknowledge again. Control does not survive a re-issue, and a lapsed or
+ * revoked grant still refuses — because the GRANT is re-read from the server
+ * every time and only the session's cooperation is remembered here.
+ */
+export declare function markSpent(paths: AdapterPaths, nonce: string, at: string, why: string, ack?: SessionAcknowledgement): void;
+/**
+ * The acknowledgement this machine validated for one handshake, if any.
+ *
+ * 🔴 THIS IS A RECORD OF A LOCAL VALIDATION, NOT A SOURCE OF AUTHORITY, and
+ * the difference is the whole reason it is safe. The grant is the server's and
+ * is re-read on every call; this only answers "did the session cooperate with
+ * THAT handshake". A machine editing this file by hand could claim cooperation
+ * for a grant a person genuinely issued — strictly weaker than the `--authorize`
+ * hole, which manufactured the HUMAN half, and it is the price of control
+ * lasting longer than a single read.
+ *
+ * ⚠️ AN ENTRY WITHOUT AN ACKNOWLEDGEMENT DOES NOT MATCH. The journal has
+ * carried bare `{nonce, at, why}` rows since before this existed, and reading
+ * one as "cooperation established" would turn every previously-spent handshake
+ * into a live one.
+ */
+export declare function validatedAck(paths: AdapterPaths, nonce: string): SessionAcknowledgement | null;
+/**
+ * Read the outbox and rule on everything in it.
+ *
+ * 🔴 `lstat`, NEVER `stat`. An outbox entry that is a link is not descended and
+ * not read: a session that could point one at a file outside its own channel
+ * would be choosing what this process parses, and every path in the report
+ * would still look like an ordinary outbox file.
+ */
+export declare function collectOutbox(paths: AdapterPaths, ctx: Omit<AdapterContext, 'consumedNonces'>, limits?: CollectLimits): CollectOutcome;
+/**
+ * Move a ruled-on file out of the outbox.
+ *
+ * ⚠️ MOVED, NOT DELETED. The file is the evidence — of a genuine
+ * acknowledgement, or of an attempted replay — and a runtime that deleted it
+ * would leave the refusal with nothing behind it. It also stops the next
+ * collection re-reading the same message and reporting it again.
+ */
+export declare function archive(paths: AdapterPaths, file: string): string | null;
+/**
+ * One line each, for a person.
+ *
+ * ⚠️ THE BLIND SPOTS ARE PRINTED EVEN WHEN NOTHING WAS RULED ON. An outbox that
+ * could not be listed and an outbox that is empty produce the same empty list of
+ * rulings, and only one of them means the session said nothing.
+ */
+export declare function reportCollection(outcome: CollectOutcome, out: (line: string) => void): void;
+export interface CollectedResult {
+    readonly file: string;
+    /** The instruction this answers, when it answers one this caller knows about. */
+    readonly instructionId: string;
+    readonly ruling: ResultRuling;
+}
+export interface ResultOutcome {
+    readonly results: readonly CollectedResult[];
+    readonly unreadable: readonly string[];
+    readonly present: boolean;
+}
+/**
+ * Read the results directory and rule on everything in it.
+ *
+ * 🔴 A RESULT FOR AN INSTRUCTION THIS CALLER NEVER SENT IS NOT DISCARDED. It
+ * is reported as unjudgeable with its own id, because "I do not know that
+ * instruction" is a fact worth seeing — it is what a replayed result, a
+ * confused adapter and a second looply on the same channel all look like, and
+ * dropping it would make all three invisible.
+ *
+ * The same bounds as the outbox, for the same reason: this is a directory the
+ * SESSION writes.
+ */
+export declare function collectResults(paths: AdapterPaths, instructions: readonly Instruction[], at: string, limits?: CollectLimits): ResultOutcome;
+/** Move a ruled-on result out of the way, keeping it as evidence. */
+export declare function archiveResult(paths: AdapterPaths, file: string): string | null;
+/**
+ * One line each, for a person.
+ *
+ * ⚠️ AN ABSENT RESULTS DIRECTORY AND AN EMPTY ONE ARE DIFFERENT FACTS, the
+ * same distinction the outbox keeps: one means the session has never answered an
+ * instruction, the other that it has not answered THIS one yet.
+ */
+export declare function reportResults(outcome: ResultOutcome, out: (line: string) => void): void;
+//# sourceMappingURL=session-adapter-runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-adapter-runtime.d.ts","sourceRoot":"","sources":["../src/session-adapter-runtime.ts"],"names":[],"mappings":"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"}

package/dist/session-adapter-runtime.js

@@ -0,0 +1,373 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_COLLECT_LIMITS = void 0;
+exports.adapterPaths = adapterPaths;
+exports.deliver = deliver;
+exports.spentHandshakes = spentHandshakes;
+exports.markSpent = markSpent;
+exports.validatedAck = validatedAck;
+exports.collectOutbox = collectOutbox;
+exports.archive = archive;
+exports.reportCollection = reportCollection;
+exports.collectResults = collectResults;
+exports.archiveResult = archiveResult;
+exports.reportResults = reportResults;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const core_1 = require("@looply/core");
+function adapterPaths(stateDir, sessionId) {
+    const dir = (0, node_path_1.join)(stateDir, 'sessions', sessionId);
+    return {
+        dir,
+        inbox: (0, node_path_1.join)(dir, 'inbox'),
+        outbox: (0, node_path_1.join)(dir, 'outbox'),
+        results: (0, node_path_1.join)(dir, 'results'),
+        consumed: (0, node_path_1.join)(dir, 'consumed'),
+        spent: (0, node_path_1.join)(dir, 'spent.jsonl'),
+    };
+}
+exports.DEFAULT_COLLECT_LIMITS = { maxFiles: 64, maxBytes: 64 * 1024 };
+const ensure = (dir) => {
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+};
+/**
+ * Put a message in the session's inbox.
+ *
+ * ⚠️ WRITTEN TO A TEMPORARY NAME AND RENAMED. A session polling this directory
+ * would otherwise be able to read a half-written offer, parse it as malformed,
+ * and discard the only copy of a handshake it will ever be sent.
+ */
+function deliver(paths, message, name) {
+    ensure(paths.inbox);
+    /**
+     * ⚠️ AN INSTRUCTION IS NAMED BY ITS OWN ID, NOT BY ITS GRANT. Every message
+     * about control is the latest word on one grant and replacing the previous one
+     * is right; every instruction is a separate thing to do, and naming them all
+     * after the grant would make each one delete the last.
+     */
+    const base = name ??
+        (message.kind === 'instruction'
+            ? `instruction-${message.instructionId}.json`
+            : `${message.kind}-${message.grantId}.json`);
+    const target = (0, node_path_1.join)(paths.inbox, base);
+    const temp = `${target}.partial`;
+    const fd = (0, node_fs_1.openSync)(temp, 'w');
+    try {
+        (0, node_fs_1.writeSync)(fd, JSON.stringify(message, null, 2));
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+    (0, node_fs_1.renameSync)(temp, target);
+    return target;
+}
+/** The handshakes this machine has already finished with, across restarts. */
+function spentHandshakes(paths) {
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(paths.spent, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.trim() === '')
+            continue;
+        try {
+            const v = JSON.parse(line);
+            /**
+             * ⚠️ A TORN LAST LINE IS SKIPPED, NOT FATAL, and the rest of the journal
+             * still counts. A crash mid-append is the ordinary way this file ends,
+             * and refusing to read any of it would turn one bad line into every
+             * earlier handshake becoming replayable again.
+             */
+            if (typeof v.nonce === 'string' && v.nonce !== '')
+                out.push(v.nonce);
+        }
+        catch {
+            // Not a record; keep reading.
+        }
+    }
+    return out;
+}
+/**
+ * Record a handshake as finished, and WHAT IT ESTABLISHED. Append-only.
+ *
+ * 🔴 THE ACKNOWLEDGEMENT IS KEPT, NOT ONLY THE FACT THAT IT WAS SPENT, AND A
+ * LIVE RUN IS WHY.
+ *
+ * Without it, control lasted exactly one read: `sessions --offer` validated the
+ * acknowledgement, archived the file, reported `under management` — and the
+ * very next command found an empty outbox and answered "the session has not
+ * acknowledged this grant". Every `--direct` after a successful adoption ended
+ * direction. The whole feature worked once per acknowledgement and then
+ * un-worked itself.
+ *
+ * ⚠️ AND IT IS BOUND TO THE NONCE, WHICH IS WHAT KEEPS IT HONEST. A remembered
+ * acknowledgement answers for exactly one grant: the next grant carries a new
+ * server-minted handshake, this record does not match it, and the session has to
+ * acknowledge again. Control does not survive a re-issue, and a lapsed or
+ * revoked grant still refuses — because the GRANT is re-read from the server
+ * every time and only the session's cooperation is remembered here.
+ */
+function markSpent(paths, nonce, at, why, ack) {
+    ensure(paths.dir);
+    const fd = (0, node_fs_1.openSync)(paths.spent, 'a');
+    try {
+        (0, node_fs_1.writeSync)(fd, `${JSON.stringify(ack === undefined ? { nonce, at, why } : { nonce, at, why, ack })}\n`);
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+}
+/**
+ * The acknowledgement this machine validated for one handshake, if any.
+ *
+ * 🔴 THIS IS A RECORD OF A LOCAL VALIDATION, NOT A SOURCE OF AUTHORITY, and
+ * the difference is the whole reason it is safe. The grant is the server's and
+ * is re-read on every call; this only answers "did the session cooperate with
+ * THAT handshake". A machine editing this file by hand could claim cooperation
+ * for a grant a person genuinely issued — strictly weaker than the `--authorize`
+ * hole, which manufactured the HUMAN half, and it is the price of control
+ * lasting longer than a single read.
+ *
+ * ⚠️ AN ENTRY WITHOUT AN ACKNOWLEDGEMENT DOES NOT MATCH. The journal has
+ * carried bare `{nonce, at, why}` rows since before this existed, and reading
+ * one as "cooperation established" would turn every previously-spent handshake
+ * into a live one.
+ */
+function validatedAck(paths, nonce) {
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(paths.spent, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let found = null;
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.trim() === '')
+            continue;
+        try {
+            const v = JSON.parse(line);
+            if (v.nonce !== nonce || typeof v.ack !== 'object' || v.ack === null)
+                continue;
+            const a = v.ack;
+            if (a['handshakeNonce'] !== nonce)
+                continue;
+            if (a['via'] !== 'adapter')
+                continue;
+            found = v.ack;
+        }
+        catch {
+            // Not a record; keep reading.
+        }
+    }
+    return found;
+}
+/**
+ * Read the outbox and rule on everything in it.
+ *
+ * 🔴 `lstat`, NEVER `stat`. An outbox entry that is a link is not descended and
+ * not read: a session that could point one at a file outside its own channel
+ * would be choosing what this process parses, and every path in the report
+ * would still look like an ordinary outbox file.
+ */
+function collectOutbox(paths, ctx, limits = exports.DEFAULT_COLLECT_LIMITS) {
+    const unreadable = [];
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)(paths.outbox).sort();
+    }
+    catch {
+        return { rulings: [], unreadable: [], present: false };
+    }
+    const spent = spentHandshakes(paths);
+    const rulings = [];
+    let read = 0;
+    for (const name of names) {
+        if (read >= limits.maxFiles) {
+            unreadable.push(`${names.length - read} more outbox file(s) were left unread — ${limits.maxFiles} is this collection's limit`);
+            break;
+        }
+        const at = (0, node_path_1.join)(paths.outbox, name);
+        let st;
+        try {
+            st = (0, node_fs_1.lstatSync)(at);
+        }
+        catch {
+            unreadable.push(`${name} could not be read`);
+            continue;
+        }
+        if (st.isSymbolicLink()) {
+            unreadable.push(`${name} is a link, and a link in an outbox chooses what this process parses — not followed`);
+            continue;
+        }
+        if (!st.isFile())
+            continue;
+        if (st.size > limits.maxBytes) {
+            unreadable.push(`${name} is ${st.size} bytes, past the ${limits.maxBytes}-byte limit for a message — not parsed`);
+            continue;
+        }
+        read += 1;
+        let parsed;
+        try {
+            parsed = JSON.parse((0, node_fs_1.readFileSync)(at, 'utf8'));
+        }
+        catch (e) {
+            rulings.push({ file: name, ruling: { kind: 'unjudgeable', because: `${name} is not JSON: ${e.message}` } });
+            continue;
+        }
+        const message = (0, core_1.readOutboxMessage)(parsed);
+        if (message === null) {
+            rulings.push({ file: name, ruling: { kind: 'unjudgeable', because: `${name} is not an outbox message` } });
+            continue;
+        }
+        rulings.push({ file: name, ruling: (0, core_1.ruleOnOutbox)(message, { ...ctx, consumedNonces: spent }) });
+    }
+    return { rulings, unreadable, present: true };
+}
+/**
+ * Move a ruled-on file out of the outbox.
+ *
+ * ⚠️ MOVED, NOT DELETED. The file is the evidence — of a genuine
+ * acknowledgement, or of an attempted replay — and a runtime that deleted it
+ * would leave the refusal with nothing behind it. It also stops the next
+ * collection re-reading the same message and reporting it again.
+ */
+function archive(paths, file) {
+    ensure(paths.consumed);
+    const from = (0, node_path_1.join)(paths.outbox, file);
+    const to = (0, node_path_1.join)(paths.consumed, file);
+    try {
+        (0, node_fs_1.renameSync)(from, to);
+        return to;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One line each, for a person.
+ *
+ * ⚠️ THE BLIND SPOTS ARE PRINTED EVEN WHEN NOTHING WAS RULED ON. An outbox that
+ * could not be listed and an outbox that is empty produce the same empty list of
+ * rulings, and only one of them means the session said nothing.
+ */
+function reportCollection(outcome, out) {
+    if (!outcome.present) {
+        out('  the session has no outbox — nothing was established about what it said');
+        return;
+    }
+    if (outcome.rulings.length === 0 && outcome.unreadable.length === 0) {
+        out('  the outbox is empty: the session has not answered yet');
+    }
+    for (const u of outcome.unreadable)
+        out(`  blind: ${u}`);
+}
+/**
+ * Read the results directory and rule on everything in it.
+ *
+ * 🔴 A RESULT FOR AN INSTRUCTION THIS CALLER NEVER SENT IS NOT DISCARDED. It
+ * is reported as unjudgeable with its own id, because "I do not know that
+ * instruction" is a fact worth seeing — it is what a replayed result, a
+ * confused adapter and a second looply on the same channel all look like, and
+ * dropping it would make all three invisible.
+ *
+ * The same bounds as the outbox, for the same reason: this is a directory the
+ * SESSION writes.
+ */
+function collectResults(paths, instructions, at, limits = exports.DEFAULT_COLLECT_LIMITS) {
+    const unreadable = [];
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)(paths.results).sort();
+    }
+    catch {
+        return { results: [], unreadable: [], present: false };
+    }
+    const byId = new Map(instructions.map((i) => [i.id, i]));
+    const out = [];
+    let read = 0;
+    for (const name of names) {
+        if (read >= limits.maxFiles) {
+            unreadable.push(`${names.length - read} more result file(s) were left unread — ${limits.maxFiles} is this collection's limit`);
+            break;
+        }
+        const abs = (0, node_path_1.join)(paths.results, name);
+        let st;
+        try {
+            st = (0, node_fs_1.lstatSync)(abs);
+        }
+        catch {
+            unreadable.push(`${name} could not be read`);
+            continue;
+        }
+        if (st.isSymbolicLink()) {
+            unreadable.push(`${name} is a link, and a link here chooses what this process parses — not followed`);
+            continue;
+        }
+        if (!st.isFile())
+            continue;
+        if (st.size > limits.maxBytes) {
+            unreadable.push(`${name} is ${st.size} bytes, past the ${limits.maxBytes}-byte limit for a result — not parsed`);
+            continue;
+        }
+        read += 1;
+        let parsed;
+        try {
+            parsed = JSON.parse((0, node_fs_1.readFileSync)(abs, 'utf8'));
+        }
+        catch (e) {
+            out.push({ file: name, instructionId: '', ruling: { kind: 'unjudgeable', because: `${name} is not JSON: ${e.message}` } });
+            continue;
+        }
+        const result = (0, core_1.readInstructionResult)(parsed);
+        if (result === null) {
+            out.push({ file: name, instructionId: '', ruling: { kind: 'unjudgeable', because: `${name} is not an instruction result` } });
+            continue;
+        }
+        const instruction = byId.get(result.instructionId);
+        if (instruction === undefined) {
+            out.push({
+                file: name,
+                instructionId: result.instructionId,
+                ruling: { kind: 'unjudgeable', because: `${result.instructionId} is not an instruction this caller sent` },
+            });
+            continue;
+        }
+        out.push({ file: name, instructionId: result.instructionId, ruling: (0, core_1.ruleOnResult)(instruction, result, at) });
+    }
+    return { results: out, unreadable, present: true };
+}
+/** Move a ruled-on result out of the way, keeping it as evidence. */
+function archiveResult(paths, file) {
+    ensure(paths.consumed);
+    try {
+        (0, node_fs_1.renameSync)((0, node_path_1.join)(paths.results, file), (0, node_path_1.join)(paths.consumed, file));
+        return (0, node_path_1.join)(paths.consumed, file);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One line each, for a person.
+ *
+ * ⚠️ AN ABSENT RESULTS DIRECTORY AND AN EMPTY ONE ARE DIFFERENT FACTS, the
+ * same distinction the outbox keeps: one means the session has never answered an
+ * instruction, the other that it has not answered THIS one yet.
+ */
+function reportResults(outcome, out) {
+    if (!outcome.present) {
+        out('  the session has written no results at all — nothing was established about what it did');
+        return;
+    }
+    if (outcome.results.length === 0 && outcome.unreadable.length === 0) {
+        out('  no result yet');
+    }
+    for (const u of outcome.unreadable)
+        out(`  blind: ${u}`);
+}
+//# sourceMappingURL=session-adapter-runtime.js.map

package/dist/session-adapter-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-adapter-runtime.js","sourceRoot":"","sources":["../src/session-adapter-runtime.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,62 @@
+import { type Checkpoint, type CheckpointMeasurements } from '@looply/core';
+export interface CheckpointLimits {
+    /** Bytes of diff kept. Past it, the diff is recorded as truncated. */
+    readonly maxDiffBytes: number;
+    /** Untracked files copied. Past it, the rest are named and not copied. */
+    readonly maxUntrackedFiles: number;
+    /** Bytes per untracked file. */
+    readonly maxFileBytes: number;
+}
+export declare const DEFAULT_CHECKPOINT_LIMITS: CheckpointLimits;
+/**
+ * What this machine can establish about the workspace.
+ *
+ * ⚠️ EVERY FAILURE IS `null`, NEVER AN EMPTY LIST. `checkpointVerdict` answers
+ * `unmeasurable` for a null and would produce a clean-looking checkpoint from an
+ * empty one — which is the single most consequential thing this file could get
+ * wrong, so the distinction is made here rather than left to a caller.
+ */
+/**
+ * 🔴 LOOPLY'S OWN STATE DIRECTORY IS NOT THE SESSION'S WORK, AND A LIVE RUN
+ * PROVED WHY IT MATTERS.
+ *
+ * The checkpoint store lives at `<workspace>/.looply/state/checkpoints`, and
+ * `git ls-files --others` lists everything under it. So the FIRST checkpoint
+ * copied the session's work; the SECOND copied the session's work AND the first
+ * checkpoint; a third would have copied both. Measured: 5 untracked files became
+ * 12 on the second run. Each capture contained every capture before it.
+ *
+ * ⚠️ AND IT WAS ALSO MISLABELLED. `.looply/state/sessions.jsonl` is looply's
+ * own ledger, and it landed in a directory labelled "this session's untracked
+ * work" — a product's bookkeeping presented as somebody else's output.
+ *
+ * ⚠️ ONLY `state` IS EXCLUDED, NOT ALL OF `.looply`. A session that created
+ * `.looply/config.yaml` really did create it, and dropping that would be a guess
+ * about what counts as work. `state` is this product's runtime bookkeeping by
+ * construction, which is not a guess.
+ */
+export declare const STATE_SUBDIR = ".looply/state";
+export interface WorkspaceReading extends CheckpointMeasurements {
+    /** Untracked paths left out because they are looply's own, named. */
+    readonly excluded: readonly string[];
+}
+export declare function measureWorkspace(workspace: string, liveness: CheckpointMeasurements['liveness'], heldBy: string | null, stateSubdir?: string): WorkspaceReading;
+export interface WrittenCheckpoint {
+    readonly dir: string;
+    readonly manifest: string;
+    readonly diff: string | null;
+    readonly copied: number;
+    /** Everything that could not be captured in full, named. */
+    readonly incomplete: readonly string[];
+}
+/**
+ * Write the checkpoint: a manifest, the diff, and the untracked files.
+ *
+ * 🔴 THE MANIFEST IS WRITTEN LAST. Everything it names must already exist, or a
+ * crash mid-capture leaves a manifest describing an export that is not there —
+ * and a manifest is exactly what a later reader will trust.
+ */
+export declare function writeCheckpoint(root: string, checkpoint: Checkpoint, limits?: CheckpointLimits): WrittenCheckpoint;
+/** The lines a person reads, with what the export actually contains. */
+export declare function reportCheckpoint(written: WrittenCheckpoint, checkpoint: Checkpoint, out: (line: string) => void, excluded?: readonly string[]): void;
+//# sourceMappingURL=session-checkpoint-runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-checkpoint-runtime.d.ts","sourceRoot":"","sources":["../src/session-checkpoint-runtime.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,UAAU,EAAE,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAgEhG,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,gCAAgC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,eAAO,MAAM,yBAAyB,EAAE,gBAIvC,CAAC;AAkBF;;;;;;;GAOG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAE5C,MAAM,WAAW,gBAAiB,SAAQ,sBAAsB;IAC9D,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,sBAAsB,CAAC,UAAU,CAAC,EAC5C,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,WAAW,GAAE,MAAqB,GACjC,gBAAgB,CA2BlB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAcD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,MAAM,GAAE,gBAA4C,GACnD,iBAAiB,CA6FnB;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,UAAU,EACtB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC3B,QAAQ,GAAE,SAAS,MAAM,EAAO,GAC/B,IAAI,CAaN"}