@jawache/flow 0.1.2 → 0.3.0

package/dist/types/adapter/archive.d.ts

@@ -1,6 +1,13 @@
 import type { LoadResult } from "../language/domain.ts";
 import { type Facts, type SelectOpts, type SpawnMeta, type TranscriptRef } from "./domain.ts";
-/** Where this harness keeps a working directory's conversations. */
+/**
+ * Where this harness keeps a working directory's conversations.
+ *
+ * Under the host's own folder, and `CLAUDE_CONFIG_DIR` moves that folder — the host honours it for
+ * the store as it does for settings.json, so a store read from `~/.claude` regardless would be
+ * somebody else's. A `home` passed in is taken as the user's home and wins: that is a test naming
+ * its own world.
+ */
 export declare function projectDir(cwd: string, home?: string): string;
 /** One conversation in the store, with everything findable about it without opening it twice. */
 export interface StoredTranscript {

package/dist/types/adapter/claude.d.ts

@@ -1,5 +1,6 @@
 import { type ExecResult, type FlowConfig, type LoadResult, type Grammar, type Settings, type World } from "../language/domain.ts";
-import { type HookEvent, type HookPayload, type HookResult } from "./domain.ts";
+import { type AgentOf } from "../engine/domain.ts";
+import { type CommitScope, type CallRecord, type Change, type Delta, type HookEvent, type HookPayload, type HookResult } from "./domain.ts";
 /**
  * Run one command the way a check means it — through a shell, in the repo, hermetically.
  *
@@ -13,7 +14,7 @@ import { type HookEvent, type HookPayload, type HookResult } from "./domain.ts";
  * installed refuses the commit instead of passing it. bash answers 127 itself; the only case left
  * is bash being unspawnable, which is the same fact one level up and is answered the same way.
  */
-export declare function runCommand(command: string, root: string): ExecResult;
+export declare function runCommand(command: string, root: string, env?: Record<string, string | undefined>): ExecResult;
 /** A file's text, or null when it is not there / not readable. */
 export declare function readText(root: string, path: string): string | null;
 /**
@@ -52,16 +53,56 @@ export declare function currentBranch(root: string): string | null;
  * who is here — and a rule that fires at the gate for a wearer status never showed is the exact
  * surprise the marker exists to prevent.
  *
- * `agent` is null when the marker is missing, stale or malformed, and then the wearer wears NOTHING
- * rather than a guess: there is no transcript and no sidecar out here, so the stored verdict is the
- * only truthful answer there can be.
+ * `who` is null when the marker is missing, stale or malformed, and then the wearer wears NOTHING
+ * rather than a guess: there is no transcript and no hook message out here, so the stored verdict is
+ * the only truthful answer there can be.
  */
 export declare function wearer(root: string): {
     readonly branch: string | null;
     readonly session: string;
-    readonly agent: string | null;
+    readonly who: AgentOf | null;
     readonly wearing: readonly string[];
 };
+/**
+ * RECORD THE TREE BEFORE A CALL, filed under the host's `tool_use_id`.
+ *
+ * A snapshot that cannot be taken is RECORDED as a fault rather than skipped, so the after-call rail
+ * reports it instead of finding nothing and calling the call clean. `who` is kept beside the tree so
+ * a snapshot with no after is readable as a call still in flight, per session and agent.
+ */
+export declare function takeSnapshot(root: string, key: string, include: readonly string[], who: {
+    readonly session: string;
+    readonly agent: string;
+    readonly tool: string;
+}): void;
+/**
+ * WHAT THE CALL CHANGED: the tree now against the tree its snapshot recorded, path by path, with
+ * the content either side, less each path git put there (see `authored`). The before-snapshot is
+ * kept — a revert reads from it — until `forget`.
+ */
+export declare function observeDelta(root: string, key: string, include: readonly string[]): Delta & {
+    readonly before?: string;
+};
+/**
+ * PUT CHANGES BACK from the before-snapshot — a changed or removed file to its old content, a file
+ * the call created removed. Answers what could not be put back, never throws: a revert that failed
+ * is said to the model, loudly, rather than claimed.
+ */
+export declare function revertChanges(root: string, tree: string, changes: readonly Change[]): {
+    path: string;
+    why: string;
+}[];
+/**
+ * THE CALL LOG — every snapshot's record, read back: who made each call, when it started, and when
+ * it finished if it has. A record that cannot be read is left out; it is somebody's write racing
+ * this read, and the next diff reads it whole.
+ */
+export declare function callLog(root: string): CallRecord[];
+/**
+ * The call is over: its record says when it finished, so a diff still to come can tell it
+ * overlapped, and its throwaway indexes go. Records no diff still to come can overlap are dropped.
+ */
+export declare function finishSnapshot(root: string, key: string, now?: number): void;
 /**
  * The repo the session is standing in — the FOURTH question of §7.
  *
@@ -76,10 +117,10 @@ export declare function projectRoot(cwd: string): string;
  * once in the host's settings and fire in every repo the agent visits, so a missing config is the
  * ordinary case and blocking on it would make flow unusable the moment it was installed.
  *
- * `broken` is the opposite fact and gets the opposite answer: a config file that is THERE and will
- * not even import is a guard that cannot run, which is what fail-loud exists for. (A config that
- * imports and then will not load is the engine's own path — `load.ok === false` — and refuses with
- * the same shape from inside `guard`.)
+ * `broken` is the opposite fact and must never be silent: a config file that is THERE and will
+ * not even import is a guard that cannot run. The hook rail hands it to `whileBroken`, which lets
+ * every call through with the load error, and the commit gate refuses. (A config that imports and
+ * then will not load — `load.ok === false` — is the same fact and gets the same two answers.)
  */
 export type Regime = {
     readonly kind: "none";
@@ -110,7 +151,7 @@ export declare function loadRegime(root: string): Promise<Regime>;
  *
  * The shape is deliberately flat rather than a hook function per event: the events differ in what
  * they CARRY (toEvent's job) and in how their answer is rendered (toResult's job), and the middle —
- * load, classify, run, log — is identical for all five. The old engine had five files here, and the
+ * load, classify, run, log — is identical for all of them. The old engine had five files here, and the
  * off switch, the session marker and the fault handling were each written out four or five times
  * with small differences nobody had chosen.
  */
@@ -126,10 +167,10 @@ export declare function runHook(hook: HookEvent, payload: HookPayload, root: str
  * WHO IT IS comes from the marker the PreToolUse rail left — session AND agent — so a commit's rows
  * land in the session that caused them and an actor-scoped rule fires at this moment as honestly as
  * at any other. The classification itself is never re-derived here: there is no transcript and no
- * sidecar outside a session, so the STORED verdict is the only truthful answer, and a fresh commit
+ * hook message outside a session, so the STORED verdict is the only truthful answer, and a fresh commit
  * on a stale or absent marker wears nothing rather than wearing a guess.
  */
-export declare function runCommit(root: string, files: readonly string[]): Promise<HookResult>;
+export declare function runCommit(root: string, scope: CommitScope): Promise<HookResult>;
 /** What came in on stdin: a payload, or which of the two ways reading it failed. */
 export type PayloadRead = {
     readonly ok: true;
@@ -157,13 +198,21 @@ export declare function readPayload(): PayloadRead;
  *
  * `pre-tool-use` is the rail that GUARDS, so it fails CLOSED — a payload it cannot read is a tool
  * call it cannot judge, and "I could not look" must never be spelled the same way as "I looked and
- * it was fine". The other four annotate, and breaking a session over a hook that only adds a
- * breadcrumb would be the cure killing the patient — so they SPEAK on stderr and allow, because
- * silence is precisely what let the old swallow go unnoticed.
+ * it was fine". The after-call rails JUDGE too — every change a call made reaches the rules there —
+ * so a payload they cannot read is a call whose changes nobody judged, and they report it with exit
+ * 2, which on those rails reaches the model beside the result and blocks nothing. The rest only add
+ * a breadcrumb, and breaking a session over one would be the cure killing the patient, so they SPEAK
+ * on stderr and allow. `readFault` next door is where that split is decided.
  *
  * Everything is wrapped: a hook that throws is a hook that wedges a session, and an unknown event
  * is silence rather than a usage message in front of the model.
  */
 export declare function hookEntry(event: string, cwd: string): Promise<HookResult>;
-/** The git gate, end to end. Paths arrive repo-relative from git; a stray absolute one is folded. */
-export declare function commitEntry(files: readonly string[], cwd: string): Promise<HookResult>;
+/**
+ * The git gate, end to end — `flow hook commit`, or `flow hook commit --all` for the whole tree.
+ *
+ * It takes no file list: git is asked. `flow commit <files…>`, the name an older hook still calls,
+ * arrives here with `legacy` set and its list is dropped, because git's answer is the only list — a
+ * second source of the staged set is two answers that can disagree.
+ */
+export declare function commitEntry(args: readonly string[], cwd: string, legacy?: boolean): Promise<HookResult>;