waterplane 0.0.1 → 0.1.11

package/node_modules/@waterplane/shared/dist/intent/facts.d.ts

@@ -0,0 +1,320 @@
+/**
+ * What the ladder READS (`IntentFacts`, `IntentSettlement`,
+ * `busyIntentGroups`) and what it ANSWERS (`IntentVerdict`).
+ *
+ * A slice of `../intent.ts`, which is the one door into the intent model —
+ * import from there, never from here. Layout and import order:
+ * docs/notes/shared-architecture.md.
+ */
+import type { BudgetCeiling } from "../budget.js";
+import type { SerialHolder, SerialSessionState } from "../queue.js";
+import type { BlockReason } from "./types.js";
+/**
+ * Everything `intentVerdict` is allowed to know, flattened to primitives.
+ *
+ * Primitives rather than live objects for the same reason `LaneSessionState`
+ * and `SerialSessionState` are: this module has to stay node-runnable and
+ * DOM-free so both ends and a bare `node --test` can compute the same answer.
+ * The caller does the looking-up; the rule does the deciding.
+ */
+export interface IntentFacts {
+    /** `files` trigger: which of the intent's `needs` exist under `cwd`. The
+     *  caller stats exactly those paths — a test hands in a literal set. */
+    present: ReadonlySet<string>;
+    /** Live sessions, so `laneBusy()`'s and `autoFireBlocker()`'s ladder is
+     *  computable here rather than in two places that drift. `turnActive` carries
+     *  the host's own answer — exact on a hooked session, its silence guess
+     *  otherwise — so the guess stays in the one place that can make it. */
+    sessions: readonly SerialSessionState[];
+    /**
+     * **Nothing reads this any more.** Kept only so the host keeps compiling
+     * while it stops building it.
+     *
+     * It answered "which session does a `{kind:"repo"}` target resolve to", for
+     * the legacy non-`fresh` repo branch in rung 5 — and that branch is gone:
+     * `cleanTarget` normalises every repo target to `fresh`, opening the session
+     * IS the work, and the rung passes unconditionally before any map is
+     * consulted. A required fact nobody reads still costs the host a map per
+     * tick, so this is optional and deprecated rather than quietly load-bearing.
+     *
+     * @deprecated Stop passing it; the field goes when the host no longer does.
+     */
+    repoSession?: ReadonlyMap<string, string | null>;
+    /** Serialization groups that are occupied — `serialGroup(cwd)` keys. Build it
+     *  with `busyIntentGroups()` so both sources are counted the same way. */
+    busyCwds: ReadonlySet<string>;
+    /**
+     * WHO holds each busy group (`intentSerialHolders`, the same inputs as `busyCwds`),
+     * so the `serial` wait can name the session instead of "the session before
+     * it". Optional: absent, or no entry for a group, is the generic sentence.
+     * Never consulted for the DECISION — `busyCwds` alone decides.
+     */
+    serialHolders?: ReadonlyMap<string, readonly SerialHolder[]>;
+    /**
+     * Sessions an intent is already `starting`/`running` in.
+     *
+     * The backlog's `sessionBusy()`: one item at a time per session, so two
+     * sessions in one repo still advance in parallel. It is a separate fact from
+     * `sessions` because of the DELIVERY window — an intent flipped to `starting`
+     * has not made its session `turnActive` yet (the TUI is sitting at its prompt
+     * waiting to be typed into), and that quiet is exactly what a second intent
+     * would read as "free".
+     */
+    busySessions?: ReadonlySet<string>;
+    /** Sessions whose own budget is spent (`sessionBudgetHeld`). Absent = nobody
+     *  said = none held. Only a row aimed AT a session reads it. */
+    budgetHeldSessions?: ReadonlySet<string>;
+    /** `shared/budget.ts`'s verdict: the account is past the ceiling. */
+    budgetBlocked: boolean;
+    /** The account's own sentence for that pause — which ceiling, and when it
+     *  lifts. Optional because the rule must answer without one (a test hands in
+     *  a bare boolean); when present it IS the answer, because "resumes at 14:20"
+     *  is the only actionable half of a pause. */
+    budgetDetail?: string;
+    /**
+     * Every ceiling the budget has tripped, session first (`budgetCeilings`).
+     * What lets rung 2 lift for a before-reset row against the SAME window's
+     * cap while still holding it on the other's. ABSENT means nobody said which
+     * cap ⇒ the old behaviour, hold on `budgetBlocked`; present and empty while
+     * `budgetBlocked` is true is read the same way.
+     */
+    budgetOver?: readonly BudgetCeiling[];
+    /** The LEFTOVER ceiling when it is tripped (`leftoverCeiling`), else absent.
+     *  Holds only rows `budgetLeftoverOf` names — never a reason for the rest. */
+    leftoverOver?: BudgetCeiling | null;
+    /** The global auto-fire switch. */
+    autoFire: boolean;
+    /** Directories a sweep may legally name — `discoverTargets()`'s answer.
+     *  Unknown dirs are dropped, never spawned. */
+    knownDirs: ReadonlySet<string>;
+    /**
+     * Any OTHER intent is `starting`/`running`, anywhere on this host.
+     *
+     * Only rung 4.5's `holdForHost` reads it. A `repo`-with-`fresh` target never
+     * passes through rung 5's session check at all — nothing has been created
+     * yet for the tick to see busy — so several such intents due at the same
+     * instant (the shape a "right after the weekly window resets" schedule
+     * takes in every repo at once) each read the world as idle and each open a
+     * session. This is the fact that lets an intent opt out of being one of
+     * that pile: wait for the desktop to be doing nothing else first.
+     */
+    hostBusy: boolean;
+    /**
+     * How many more sessions MACHINERY may open right now — `BACKLOG_SESSIONS_MAX`
+     * minus the automatic sessions currently alive.
+     *
+     * It is counted off the SESSIONS and never off a map of rows, which is the
+     * same rule `repoSession` has and for the same reason: the cap is about how
+     * many `claude` processes are running, so a session opened by the sheet's own
+     * button counts against it exactly like one an intent opened. A bookkeeping
+     * map would count the host's intentions instead of the host's processes, and
+     * those two disagree after every crash, every restart and every session a
+     * person closed by hand.
+     *
+     * Zero or less is a real value and means "none left", which is why this is a
+     * number and not a boolean: the manager decrements it per fire within one
+     * pass (the `hostBusy`/`busyCwds` trick), so five rows due in five repos in
+     * one tick open min(5, free) sessions rather than five.
+     */
+    autoSlotsFree: number;
+    /**
+     * The local-model cap (rung 4.55, `localModel`), as the host measured it.
+     *
+     * `rows` is every pending AUTOMATIC intent id (an `auto` row, or one target
+     * of a sweep) whose run would start a turn on a LOCAL model (its own launch,
+     * or the local session it is aimed at) — locality is a backend's fact, so
+     * only the host can say it, and a person's own tap is never in it. `free` is how many more
+     * local turns may start right now (cap minus local sessions mid-turn and
+     * local rows starting/running), decremented per fire within a pass exactly
+     * like `autoSlotsFree`. `busy` is the local sessions counted as working, so a
+     * row aimed at one of THEM waits on its own session (rung 5) instead of on
+     * the cap it is itself filling.
+     *
+     * ABSENT means the host did not say — the rung is skipped, which is the
+     * whole of the old behaviour.
+     */
+    local?: {
+        free: number;
+        rows: ReadonlySet<string>;
+        busy: ReadonlySet<string>;
+    };
+    /**
+     * How the rows that have FINISHED finished, by intent id.
+     *
+     * Membership is the settled test: a row in here is over, and `at` is when it
+     * went terminal (`Intent.settledAt`). The manager builds it from the live
+     * rows plus the tail of `intents-archive.jsonl`, so a predecessor that
+     * finished last week and has since been compacted still releases its chain
+     * instead of stranding it.
+     */
+    settled?: ReadonlyMap<string, IntentSettlement>;
+    /**
+     * Every intent id this host holds — live, terminal or archived.
+     *
+     * It is what tells "not finished yet" from "gone", which `settled` alone
+     * cannot: absence from `settled` is both. Without the distinction a chain
+     * whose predecessor was cancelled and dismissed waits for ever with a
+     * perfectly reasonable-looking sentence under it, which is the exact failure
+     * mode this whole store was built to stop — work that is never going to run
+     * and never says so.
+     */
+    knownIntents?: ReadonlySet<string>;
+    /**
+     * Who waits for whom: the id of every `after` row, mapped to the id it waits
+     * on. The one fact that makes a CYCLE visible from inside a single row —
+     * A after B after A settles nothing, so neither row can ever see anything but
+     * "not finished yet", and two rows waiting politely for each other for ever
+     * is indistinguishable on screen from two rows that are simply next. The
+     * manager already walks every row per tick to build `settled`; this is the
+     * same walk's other half.
+     */
+    chainWaits?: ReadonlyMap<string, string>;
+    /**
+     * The rows that can never go terminal, and therefore can never release a
+     * chain — today, exactly the RECURRING schedules.
+     *
+     * `settled` is terminal-only by contract, and a recurring rule never becomes
+     * terminal: it fires, records its occurrence and re-arms, for ever. So a row
+     * chained to "the nightly sweep" reads `not settled` on every tick until the
+     * desktop is switched off, under the most reassuring sentence in this file —
+     * *waits for “the nightly sweep” to finish*. That is the exact shape the
+     * store exists to prevent: work that is never going to run and never says
+     * so. It is the same failure `knownIntents` turns into a sentence, one
+     * question earlier — that one is "is it there?", this one is "is it the kind
+     * of thing that ends?".
+     *
+     * The PICKER already declines to offer one (`sendIntent.ts`'s
+     * `chainCandidates`), and that is a courtesy, never the guard: a rule can be
+     * edited from *once* to *every day* long after the chain behind it was made,
+     * at which point no filter that ran at pick time is in a position to help.
+     * Absent = nobody said = the old behaviour, which is to wait.
+     */
+    neverSettles?: ReadonlySet<string>;
+    /**
+     * The rows somebody has ARCHIVED and which have not finished — filed away,
+     * still `queued`, still in the store.
+     *
+     * The fifth fact, and the fifth different wrong answer: "has it finished?",
+     * "is it still there?", "does this bite its own tail?", "is it the kind of
+     * thing that ends?" and now "is anybody still expecting it to run?". An
+     * archived predecessor is in `knownIntents` (it has not left the store) and
+     * out of `settled` (it has not finished), so the ladder answered *waits for
+     * “X” to finish* on every tick, for ever, about work nobody is going to
+     * start — with nothing on either row saying that un-archiving X is what
+     * releases this one.
+     *
+     * It is a WAIT and not a `neverSettles`-style fail: bringing the row back is
+     * a real fix, one tap away, and failing the chain would throw away the work
+     * of the person who was only tidying a list. Absent = nobody said = the old
+     * wait, wearing the old sentence.
+     */
+    setAside?: ReadonlySet<string>;
+}
+/** How one intent finished: `ok` as its `IntentResult` recorded it, `at` the
+ *  instant it went terminal. The unit `facts.settled` is keyed on. */
+export interface IntentSettlement {
+    ok: boolean;
+    at: number;
+    /**
+     * It was CANCELLED, rather than having run and failed.
+     *
+     * A separate flag and not an `ok: false` reading, because the two release a
+     * chain differently and `ok` alone cannot tell them apart: a failure is the
+     * work having happened and gone wrong ("run the tests, then tell me what
+     * happened" still wants to run), a cancel is a person saying "not this" —
+     * which is not "afterwards". Optional, so a host that does not set it keeps
+     * the old behaviour exactly.
+     */
+    canceled?: boolean;
+}
+/**
+ * WHO holds each serial group for the intent ladder — `serialHolders` in its
+ * `automaticOnly` reading, and the ONE derivation behind both the hold
+ * (`busyIntentGroups`) and the sentence (`IntentFacts.serialHolders`).
+ *
+ * The owner's rule: no parallel CODING by queued work, but a predecessor that
+ * finished and is idle lets the next one start, and one with a question open
+ * holds it. So only work the queue itself put there holds a group — rows
+ * `starting`/`running` (`occupied`, wherever they run) and sessions opened FOR
+ * queued work (`SerialSessionState.automatic`). A session a person opened by
+ * hand never does: the owner runs several in one repo all day, and one of them
+ * mid-turn held a serial row for five hours.
+ */
+export declare function intentSerialHolders(sessions: readonly SerialSessionState[], occupied: Iterable<{
+    cwd: string;
+    sessionId?: string;
+    name?: string;
+}>): Map<string, SerialHolder[]>;
+/**
+ * Which serialization groups are occupied, from the host's own facts.
+ *
+ * Two sources, both QUEUED work (`intentSerialHolders` says why):
+ *
+ *   • a live AUTOMATIC session in that directory behind a wall — mid-turn,
+ *     parked on a question (a box, an unparsable dialog, or a turn that ended
+ *     asking in prose), or blocked on a usage limit. A hand session is not
+ *     this rung's business; the phone's own send queue (`busySerialGroups`)
+ *     still counts every session, because its serial entries are a person's
+ *     own sequential creates.
+ *   • any cwd where an intent is `starting` or `running` right now.
+ *
+ * What it does NOT need is `busySerialGroups`' whole `SerialWatch` startup-grace
+ * apparatus. That machinery exists only because the PHONE cannot see the gap
+ * between `op.ack` naming a new session and that session reporting its first
+ * turn — during which the repo looks idle and the queue would happily start a
+ * second one. The host is on the other side of that gap: it holds the intent in
+ * `starting` across exactly that window, so the second source above covers it
+ * with a fact instead of a timer.
+ */
+export declare function busyIntentGroups(sessions: readonly SerialSessionState[], occupiedCwds: Iterable<string>): Set<string>;
+/** What the world says about one intent right now. */
+export type IntentVerdict = 
+/** Run it. `sessionId` is the resolved target, when there is one. */
+{
+    kind: "go";
+    sessionId?: string;
+    occurrence?: number;
+    late?: boolean;
+}
+/**
+ * Not yet, and here is the one sentence for the row.
+ *
+ * `detail` is the FINISHED sentence (already through `intentReasonText`), not
+ * a fragment — a UI renders it as-is and must not re-weave it.
+ *
+ * `missedOccurrence` is the one piece of bookkeeping a wait can carry: a
+ * recurring `at` whose occurrence blew past its grace window is not run late
+ * and is not failed either — the manager records that occurrence as missed,
+ * recomputes `nextAt`, and the row keeps standing. Silently advancing would
+ * leave a row that looks like it fired.
+ *
+ * `missing` is the `files` trigger's outstanding paths, so the row can name
+ * them without the manager re-deriving the same subtraction.
+ *
+ * `clearedOccurrence` is the other half of that bookkeeping, and the one that
+ * keeps work alive rather than merely honest about being lost: it is present
+ * on every wait produced BELOW rung 3, and it names the `at` occurrence rung 3
+ * released before the lower rung took over. The manager stamps it on the row
+ * (`Intent.clearedOccurrence`) so the next tick's rung 3 does not re-judge an
+ * occurrence it has already let through. See `Intent.clearedOccurrence` for
+ * the real case this was found in.
+ *
+ * `holderSessionId` rides a `serial` wait only: the live session the
+ * sentence names (`serialLead`), so the row can offer to OPEN it — the
+ * question a person has to answer before the row behind it may start.
+ */
+ | {
+    kind: "wait";
+    reason: BlockReason;
+    detail: string;
+    missedOccurrence?: number;
+    missing?: string[];
+    clearedOccurrence?: number;
+    holderSessionId?: string;
+}
+/** It will never run. */
+ | {
+    kind: "fail";
+    detail: string;
+    missing?: string[];
+};

package/node_modules/@waterplane/shared/dist/intent/facts.js

@@ -0,0 +1,52 @@
+/**
+ * What the ladder READS (`IntentFacts`, `IntentSettlement`,
+ * `busyIntentGroups`) and what it ANSWERS (`IntentVerdict`).
+ *
+ * A slice of `../intent.ts`, which is the one door into the intent model —
+ * import from there, never from here. Layout and import order:
+ * docs/notes/shared-architecture.md.
+ */
+import { serialHolders } from "../queue.js";
+/**
+ * WHO holds each serial group for the intent ladder — `serialHolders` in its
+ * `automaticOnly` reading, and the ONE derivation behind both the hold
+ * (`busyIntentGroups`) and the sentence (`IntentFacts.serialHolders`).
+ *
+ * The owner's rule: no parallel CODING by queued work, but a predecessor that
+ * finished and is idle lets the next one start, and one with a question open
+ * holds it. So only work the queue itself put there holds a group — rows
+ * `starting`/`running` (`occupied`, wherever they run) and sessions opened FOR
+ * queued work (`SerialSessionState.automatic`). A session a person opened by
+ * hand never does: the owner runs several in one repo all day, and one of them
+ * mid-turn held a serial row for five hours.
+ */
+export function intentSerialHolders(sessions, occupied) {
+    return serialHolders(sessions, occupied, { automaticOnly: true });
+}
+/**
+ * Which serialization groups are occupied, from the host's own facts.
+ *
+ * Two sources, both QUEUED work (`intentSerialHolders` says why):
+ *
+ *   • a live AUTOMATIC session in that directory behind a wall — mid-turn,
+ *     parked on a question (a box, an unparsable dialog, or a turn that ended
+ *     asking in prose), or blocked on a usage limit. A hand session is not
+ *     this rung's business; the phone's own send queue (`busySerialGroups`)
+ *     still counts every session, because its serial entries are a person's
+ *     own sequential creates.
+ *   • any cwd where an intent is `starting` or `running` right now.
+ *
+ * What it does NOT need is `busySerialGroups`' whole `SerialWatch` startup-grace
+ * apparatus. That machinery exists only because the PHONE cannot see the gap
+ * between `op.ack` naming a new session and that session reporting its first
+ * turn — during which the repo looks idle and the queue would happily start a
+ * second one. The host is on the other side of that gap: it holds the intent in
+ * `starting` across exactly that window, so the second source above covers it
+ * with a fact instead of a timer.
+ */
+export function busyIntentGroups(sessions, occupiedCwds) {
+    // Built FROM `intentSerialHolders`, so the holders a sentence names and the
+    // groups the ladder holds are one derivation (`sessionWall`), never two.
+    return new Set(intentSerialHolders(sessions, [...occupiedCwds].map((cwd) => ({ cwd }))).keys());
+}
+//# sourceMappingURL=facts.js.map

package/node_modules/@waterplane/shared/dist/intent/facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facts.js","sourceRoot":"","sources":["../../src/intent/facts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA0O5C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAuC,EACvC,QAAsE;IAEtE,OAAO,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAuC,EACvC,YAA8B;IAE9B,4EAA4E;IAC5E,yEAAyE;IACzE,OAAO,IAAI,GAAG,CAAC,mBAAmB,CAAC,QAAQ,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAClG,CAAC"}

package/node_modules/@waterplane/shared/dist/intent/kind.d.ts

@@ -0,0 +1,224 @@
+/**
+ * What KIND of thing an intent is: the origin strings, the row classifiers
+ * (`isScheduleRow`, `isTimedWorkRow`, …), the clock keys and `intentKind` —
+ * one classification for both ends.
+ *
+ * A slice of `../intent.ts`, which is the one door into the intent model —
+ * import from there, never from here. Layout and import order:
+ * docs/notes/shared-architecture.md.
+ */
+import type { ScheduleRule } from "../schedule.js";
+import type { Intent } from "./row.js";
+/**
+ * **The one classification of an intent, shared by both ends.**
+ *
+ * `intents/` folded five managers into one store, and each of the five old
+ * vocabularies became a FILTER over the same rows. Those filters lived in
+ * `host/intents/adapters.ts` — which is correct while the host is the only
+ * reader, and stops being correct the moment the phone reads the store too.
+ *
+ * The failure it prevents is not "two copies drift". It is worse and more
+ * specific: `adapters.ts` flattens an `Intent` into a per-vocabulary DTO that
+ * has **no `state`, no `blockReason` and no `blockDetail`**, and the phone then
+ * *reconstructed* a lifecycle from what survived. Five reconstructions, each
+ * guessing at facts the host had already decided and thrown away in transit —
+ * `activityRows.ts` said so in its own comments ("which of the ten block
+ * reasons it corresponds to is the host's to publish, and until it does, `null`
+ * is the honest answer rather than a guess this list would then sort on").
+ *
+ * So the classifiers move here, the phone reads `Intent` directly, and the
+ * guessing is deleted rather than kept in step.
+ *
+ * The origin strings are part of the classification (a fan-out row is one only
+ * by provenance), so they live here too rather than being re-typed on the far
+ * side of the wire.
+ */
+export declare const ORIGIN_FANOUT_RUN = "fanout:run";
+export declare const ORIGIN_FANOUT_TARGET = "fanout";
+export declare const ORIGIN_FANOUT_FOLLOWUP = "fanout:fu:";
+/**
+ * **An AGENT posted this row** — a `claude` working in one of this desktop's
+ * repos asked for later work through the host's loopback route
+ * (`agentintents.ts`), because the person asked it to ("run this 3 h before the
+ * weekly reset"). Written by the host on that route and nowhere else: a client
+ * cannot claim it, and the route cannot drop it.
+ *
+ * The row is otherwise an ordinary intent, edited and deleted on the phone like
+ * any other. The mark exists so the person can tell a row they did not type from
+ * one they did — `AGENT_POSTED_WORDS` is how both of the phone's lists say it.
+ */
+export declare const ORIGIN_AGENT = "agent";
+/** Did an agent post this? Exact, never a prefix — `origin` is capped at 40. */
+export declare const isAgentPosted: (i: {
+    origin?: string;
+}) => boolean;
+/**
+ * **The reason an agent's DELETE writes** (`agentintents.ts`) — and the one way
+ * the backlog tells a row the agent WITHDREW from one that failed. An agent that
+ * reposts a corrected draft calls the old one off seconds later, before it ever
+ * ran; drawn as `failed` (the backlog's only terminal word but `done`) it read as
+ * a broken run beside the one that actually ran, and offered `re-fire` on it.
+ */
+export declare const AGENT_WITHDREW_DETAIL = "called off by the agent that posted it";
+/** Did the agent that posted this row call it off itself? Exact on all three:
+ *  an agent's row the PERSON called off is theirs to read as they like. */
+export declare const isAgentWithdrawn: (i: {
+    origin?: string;
+    state?: string;
+    result?: {
+        detail?: string;
+    };
+}) => boolean;
+/** A job a PEER desktop posted here: `origin` is `peer:<name>` (the name this
+ *  host lists the peer by; `origin` is capped at 40). Written by the host on the
+ *  token-gated peer route and nowhere else. */
+export declare const ORIGIN_PEER_PREFIX = "peer:";
+export declare const isPeerPosted: (i: {
+    origin?: string;
+}) => boolean;
+/** Which peer posted it; undefined for any other origin or an empty name. */
+export declare const peerOfOrigin: (origin: string | undefined) => string | undefined;
+/** The one wording of that mark, for the backlog row and the Activity row. */
+export declare const AGENT_POSTED_WORDS = "posted by an agent \u2014 edit or delete it like any other";
+/** What a `manual` row says it is waiting for — rung 1's detail, and the
+ *  backlog row's note (`Intent.manual`). */
+export declare const MANUAL_HOLD_TEXT = "waits for your tap \u2014 nothing starts it by itself";
+/**
+ * **Which standing rule wrote this work item** — the schedule ↔ backlog seam as
+ * a FACT on the row, instead of a join a screen has to guess at.
+ *
+ * The link used to exist only as `ScheduleResult.childId`, which is the LAST
+ * item a rule wrote and nothing before it: a nightly rule that had run four
+ * times showed *backlog · 1 item*, and three rows in the list said nothing about
+ * where they came from. `origin` is durable, is already on the wire
+ * (`intentToBacklogItem`), and survives the rule firing again.
+ *
+ * Absent by design on rows written before this existed — a chip that is not
+ * there is the honest answer, and a guess from the label would be wrong on every
+ * item somebody typed a similar name for.
+ *
+ * ONE reader and ONE writer, because `schedule:` already had two RESERVED
+ * suffixes (`schedule:work` and `schedule:sweep` mark the rule's OWN row, in
+ * `intents/manager.ts`), and a bare `startsWith("schedule:")` on the far side of
+ * the wire would read those as an entry id called "work".
+ */
+export declare const ORIGIN_SCHEDULE_PREFIX = "schedule:";
+/** What a schedule stamps on the item it creates. */
+export declare const scheduleItemOrigin: (entryId: string) => string;
+/** …and the only way to read it back: the rule's id, or `undefined` for a row
+ *  that did not come from one (including the rule's own row). */
+export declare function scheduleIdFromOrigin(origin?: string): string | undefined;
+/** A parked `session.create`. The trigger IS the discriminator — a create
+ *  waiting on files is the only thing that waits on files. */
+export declare const isLaunchRow: (i: Intent) => boolean;
+/** One repo of a sweep, or the parent sweep itself. Provenance, not shape:
+ *  a fan-out child is otherwise indistinguishable from a work item. */
+export declare const isFanoutRow: (i: Intent) => boolean;
+/**
+ * **A one-off with a clock, aimed at ONE place.** Waiting work whose WHEN
+ * happens to be an instant rather than "as soon as the target is free" — and
+ * therefore a BACKLOG row, not a schedule card.
+ *
+ * It is `after`'s argument one trigger over (see `isBacklogRow`): such a row is
+ * spent by its one run, so there is no recurrence, no clock to ARM again,
+ * nothing for the schedule sheet to pause or skip. Filing it under Schedules
+ * put it on the one screen whose verbs it cannot use and took it off the list
+ * of the repo's waiting work — which is what it is. Measured, on this desktop:
+ * 9 live `at` rows, every one of them one-off, zero recurring; seven of them
+ * `failed`, in no backlog, where nobody grooming the list ever saw them.
+ *
+ * Two exclusions, both deliberate:
+ *  - a rule that RECURS is a standing thing, whatever it is aimed at;
+ *  - a one-off SWEEP (`repos`) has no single backlog to live in, so it stays a
+ *    card until it is spent.
+ *
+ * **Derived, never stored.** An edit that flips *once* ↔ *every week* moves the
+ * row between the two lists on the next read, with nothing to migrate and no
+ * field on disk that could disagree with the trigger beside it.
+ */
+export declare const isTimedWorkRow: (i: Intent) => boolean;
+/** A standing rule on the wall clock — or a one-off SWEEP, which has no single
+ *  backlog to live in. Again the trigger discriminates, minus the one-offs
+ *  above, which are work. */
+export declare const isScheduleRow: (i: Intent) => boolean;
+/**
+ * Origins the host's manager ROUTES on — the two schedule adapters. `origin`
+ * is otherwise free-form provenance; see the manager's note on them. Here so
+ * the phone can ask the same question the executor dispatch asks.
+ */
+export declare const ORIGIN_SCHEDULE_WORK = "schedule:work";
+export declare const ORIGIN_SCHEDULE_SWEEP = "schedule:sweep";
+/** A rule whose action is "run build X" (`ScheduleAction.build`): its row
+ *  holds the build's id and values, never a command, and each occurrence
+ *  posts one ordinary build run through the build manager's own path. */
+export declare const ORIGIN_SCHEDULE_BUILD = "schedule:build";
+/**
+ * Does firing this row ADD a backlog item rather than run anything? A standing
+ * rule whose action is "queue a work item" (`manager.execute`'s one exception):
+ * its run makes a child that waits its turn in the repo's queue, so a verb that
+ * fires it skips nothing and starts no second agent.
+ */
+export declare const queuesBacklogItem: (i: Intent) => boolean;
+/**
+ * Does firing this row POST a build run rather than be one? The build twin of
+ * `queuesBacklogItem`: the rule's own row carries a `build` payload (which
+ * build, which values) but is never a run — every occurrence makes a fresh
+ * `br_…` row stamped `scheduleItemOrigin(rule id)`, and that row is the run.
+ */
+export declare const postsScheduledBuild: (i: Intent) => boolean;
+/**
+ * Equality key for *these two rows wait on the SAME clock* — what any rule
+ * folding two items into one must ask, so it is never thereby deciding a
+ * clock.
+ *
+ * `undefined` for a row with no clock, so an untimed row never accidentally
+ * compares equal to a timed one: two `undefined`s are equal as values and the
+ * callers must ask `isTimedWorkRow` (or compare on the key AND its presence)
+ * rather than on `===` alone.
+ */
+export declare const timedWorkKey: (i: Intent) => string | undefined;
+/**
+ * …and the key itself, off the three fields that make a clock rather than off
+ * an `Intent`.
+ *
+ * The phone asks the same question of a `BacklogItem` (which carries the rule,
+ * the grace and the hold and no trigger at all) when it groups the rows waiting
+ * on one instant and says which of them runs first. Two spellings of *the same
+ * clock* would be two answers to "may these be folded into one" and "are these
+ * one group" — the failure `timedWorkKey` was written to prevent, one DTO over.
+ * So the comparison lives here once and `timedWorkKey` is the `Intent`-shaped
+ * door to it.
+ */
+export declare const clockKey: (rule: ScheduleRule, graceMin: number, holdForHost?: boolean) => string;
+/** A shell command with no agent in it — a RUN. A standing rule that posts
+ *  builds (`postsScheduledBuild`) carries a build payload too, and is not one:
+ *  it is a schedule card, never a line in the build history. */
+export declare const isBuildRow: (i: Intent) => boolean;
+/** The plainest intent there is: prose, aimed at a repo or a session, run when
+ *  the target is free. Defined by SHAPE and not by an `origin` marker, and
+ *  stated last because it is what is left once the four above have taken
+ *  theirs. */
+export declare const isBacklogRow: (i: Intent) => boolean;
+/** An assessment run — `assess.ts`'s headless grader. */
+export declare const isAssessRow: (i: Intent) => boolean;
+/** A verified capture run — `capture.ts`'s picture-with-a-verdict. Like
+ *  `isBuildRow`, defined by the PAYLOAD: it is a shell-target run with no agent
+ *  in it, and nothing else in the store has this payload kind. */
+export declare const isCaptureRow: (i: Intent) => boolean;
+/**
+ * The vocabularies, as one closed set.
+ *
+ * `other` is deliberate and is not a bucket for bugs: an intent kind added
+ * later must render as *something* on a phone pinned to an older bundle, and a
+ * row that silently disappears from the one screen that answers "did my work
+ * run?" is the failure that screen exists to prevent. `capture` is the proof
+ * that it works — an APK holding a bundle from before this line renders a
+ * capture run as `other`, which is a row with a state and a time on it, rather
+ * than nothing at all.
+ */
+export type IntentKind = "launch" | "schedule" | "fanout" | "build" | "assess" | "capture" | "work" | "other";
+/** Order matters: the specific tests run before the shape test that would
+ *  otherwise also match a fan-out child. The order is UNCHANGED by timed work —
+ *  `isScheduleRow` simply no longer claims a one-off aimed at one place, so it
+ *  falls through to `work`, which is the kind whose verbs it needs. */
+export declare function intentKind(i: Intent): IntentKind;