waterplane 0.0.1 → 0.1.11

package/node_modules/@waterplane/shared/dist/wire/install.d.ts

@@ -0,0 +1,172 @@
+/**
+ * **What got installed on which phone** — the DTOs for the install log.
+ *
+ * One host, many clients. The installs themselves happen on the phones: a
+ * package on that phone's allow-list is installed by `ShellPullService` with the
+ * app closed and the document frozen, so the only account of it is a row in the
+ * phone's own download queue. Which is fine until there are two phones, and the
+ * question becomes *which version of what is on which device* — a question no
+ * single phone can answer, because it cannot see the other one.
+ *
+ * So the phones REPORT and the desktop KEEPS. The host is the only thing that
+ * outlives a reinstall of the app, sees every device, and is already where the
+ * builds came from.
+ *
+ * Two rules the shapes here exist to enforce:
+ *
+ *  - **The phone says what happened; the host says when it was told.** `at` is
+ *    the instant the install actually finished, which only the shell knows and
+ *    an older shell does not know at all — absent, never the report time
+ *    wearing an install's clothes. `reportedAt` is the host's own stamp and is
+ *    always there. A reader that needs "when" and has no `at` says *reported*,
+ *    which is a different and true sentence.
+ *  - **A report is a re-statement, not an event.** A phone re-sends everything
+ *    it still holds on every connect — that is what makes an install that
+ *    happened at 3 a.m. with the tunnel down eventually land — so every entry
+ *    carries a key the phone can reproduce, and the host merges on it. Nothing
+ *    is appended twice because the link flapped.
+ */
+/** How an install ended. Only terminal outcomes are logged: `asked` is the
+ *  system installer waiting for a person and is not a thing that happened. */
+export type InstallOutcome = "installed" | "failed";
+/** One install, as a PHONE reports it. The host adds identity and its own
+ *  clock; nothing here is trusted for either. */
+export interface InstallReportEntry {
+    /** The download row it came from. With the device id and `at`, this is what
+     *  makes a repeated report the same entry rather than a second one. */
+    pullId: string;
+    pkg: string;
+    /** The app's own label, where the package manager could read it. */
+    label?: string;
+    version?: string;
+    /** Build number (`versionCode`) — the only monotonic thing an APK carries. */
+    code?: number;
+    /** The file it arrived as, and the repo that produced it. Both are how a
+     *  person recognises a build that a package name does not identify. */
+    file?: string;
+    repo?: string;
+    outcome: InstallOutcome;
+    /** The installer's own words, where it failed. */
+    error?: string;
+    /**
+     * Did it install itself (the package was on this phone's allow-list), or did
+     * somebody tap? A log that cannot tell those apart cannot answer "why is this
+     * version on my phone".
+     *
+     * **Absent means nobody recorded it** — a row written by a shell older than
+     * the field, which is an ordinary state here because the UI updates over the
+     * air while the binary does not. It is optional for exactly the reason `at`
+     * is: `false` is not the absence of a claim, it is the positive claim *a
+     * person tapped this*, and printing that about an install that ran by itself
+     * overnight is a lie the log would tell every time.
+     */
+    auto?: boolean;
+    /** When the install finished, by the phone's clock. Absent where the shell
+     *  is older than this field — never substituted. */
+    at?: number;
+}
+/** One install, as the host keeps it. */
+export interface InstallLogEntry extends InstallReportEntry {
+    /** `<deviceId>:<pullId>:<at or 0>`. Stable across re-reports, and distinct
+     *  per install: re-installing the same build makes a second entry, because
+     *  it is a second thing that happened. */
+    key: string;
+    deviceId: string;
+    /** What that phone is called, as it called itself at report time. */
+    deviceName?: string;
+    /** Model read off the user agent, where it was legible. */
+    deviceModel?: string;
+    /** When the host was told. Always present. */
+    reportedAt: number;
+}
+/** One device that has ever reported. Derived from the entries, never stored
+ *  apart from them — a device list that can disagree with the log is a device
+ *  list nobody can trust. */
+export interface InstallDevice {
+    id: string;
+    name?: string;
+    model?: string;
+    /** The newest install this device has reported (its `at`, else `reportedAt`). */
+    lastAt: number;
+    installs: number;
+    failures: number;
+}
+/** The whole log, as the host sends it. */
+export interface InstallLogDoc {
+    /** Newest first, capped. */
+    entries: InstallLogEntry[];
+    devices: InstallDevice[];
+    /** How many entries the host holds — the same as `entries.length` today, and
+     *  a separate field so a future page of the log cannot silently claim to be
+     *  the whole of it. */
+    total: number;
+}
+/** How this device identifies itself when it reports. */
+export interface InstallReporter {
+    id: string;
+    name?: string;
+    model?: string;
+}
+/**
+ * **The desktop's half of "will the next build of this app install itself"**,
+ * one per Android app module across every repo — `GET /api/apps/readiness`.
+ *
+ * The repo half used to exist only as one PROSE row in each repo's setup
+ * checklist (`host/apkcheck.ts`), so the question *which of my apps are fully
+ * set up* meant opening every repo's setup sheet and reading a paragraph. The
+ * phone joins these facts with its own half (install access, the app's switch,
+ * who owns its updates, the last attempts on this phone) on the Apps screen.
+ *
+ * Facts, never a verdict: the phone words the checks, and every field degrades
+ * to ABSENT — a `targetSdk` behind a variable is not read, never a number.
+ */
+export interface AppRepoFacts {
+    repoId: string;
+    repoName: string;
+    repoDir: string;
+    /** `applicationId`, where the gradle file holds it as a literal. */
+    pkg?: string;
+    /** `pkg` plus each literal `applicationIdSuffix` — the package a flavor or
+     *  build type actually installs as (`dev.waterplane.app.dev`). */
+    variants?: string[];
+    /** The app module's gradle file, worktree-relative. */
+    module: string;
+    targetSdk?: number;
+    /**
+     * Which key signs its builds. `desktop` / `debug` / `other`: named in
+     * `keystore.properties` (this desktop's sideload key, this desktop's debug
+     * key, anything else). `repo`: the module's own `signingConfig`.
+     * `debug-default`: nothing configured, so the debug key of whichever machine
+     * builds it. `missing`: the module reads `keystore.properties` and there is
+     * none — the build has no key.
+     */
+    key: "desktop" | "debug" | "other" | "repo" | "debug-default" | "missing";
+    /** APKs in the repo's outbox dirs. */
+    apks: number;
+    newestApk?: {
+        rel: string;
+        mtime: number;
+        size: number;
+    };
+    /** The repo's configured build commands; `apk` where the command reads like
+     *  one that makes an APK (gradle `assemble…`, `flutter build apk`, a name
+     *  saying APK). A heuristic label, never a filter. */
+    builds: {
+        id: string;
+        name: string;
+        apk: boolean;
+    }[];
+    /** The repo's auto-download rule. `newestMatches`: would the rule queue the
+     *  newest outbox APK (pattern and size cap) — absent with no APK. */
+    autoPull: {
+        enabled: boolean;
+        builds: boolean;
+        maxBytes: number;
+        newestMatches?: boolean;
+    };
+}
+export interface AppReadinessReport {
+    /** When the desktop read it. */
+    at: number;
+    apps: AppRepoFacts[];
+}

package/node_modules/@waterplane/shared/dist/wire/install.js

@@ -0,0 +1,30 @@
+/**
+ * **What got installed on which phone** — the DTOs for the install log.
+ *
+ * One host, many clients. The installs themselves happen on the phones: a
+ * package on that phone's allow-list is installed by `ShellPullService` with the
+ * app closed and the document frozen, so the only account of it is a row in the
+ * phone's own download queue. Which is fine until there are two phones, and the
+ * question becomes *which version of what is on which device* — a question no
+ * single phone can answer, because it cannot see the other one.
+ *
+ * So the phones REPORT and the desktop KEEPS. The host is the only thing that
+ * outlives a reinstall of the app, sees every device, and is already where the
+ * builds came from.
+ *
+ * Two rules the shapes here exist to enforce:
+ *
+ *  - **The phone says what happened; the host says when it was told.** `at` is
+ *    the instant the install actually finished, which only the shell knows and
+ *    an older shell does not know at all — absent, never the report time
+ *    wearing an install's clothes. `reportedAt` is the host's own stamp and is
+ *    always there. A reader that needs "when" and has no `at` says *reported*,
+ *    which is a different and true sentence.
+ *  - **A report is a re-statement, not an event.** A phone re-sends everything
+ *    it still holds on every connect — that is what makes an install that
+ *    happened at 3 a.m. with the tunnel down eventually land — so every entry
+ *    carries a key the phone can reproduce, and the host merges on it. Nothing
+ *    is appended twice because the link flapped.
+ */
+export {};
+//# sourceMappingURL=install.js.map

package/node_modules/@waterplane/shared/dist/wire/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/wire/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}

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

@@ -0,0 +1,187 @@
+/**
+ * What a CLIENT may say about an intent — the two DTOs the wire carries, kept
+ * apart from the model itself.
+ *
+ * `shared/intent.ts` is the stored row: it has a lifecycle, a block reason, a
+ * result, and half a dozen fields only the host may write. None of those may
+ * arrive off a socket — a client that could set `state` could mark work `done`
+ * that never ran, and one that could set `lastOccurrence` could make a weekly
+ * sweep fire twice by claiming it had not fired at all. So the wire carries a
+ * DRAFT (what to do, where, and when) and a PATCH (absolute values for the
+ * three fields an unrun intent may still change), and the host derives
+ * everything else.
+ *
+ * Both are deliberately structural subsets of `Intent` rather than
+ * `Partial<Intent>`: `Partial` would have admitted every host-only field as
+ * optional, which is exactly the hole this file exists to close.
+ */
+import type { AssessPayload, BudgetPass, BudgetWaiver, BuildPayload, CapturePayload, IntentPayload, IntentTarget, IntentTrigger } from "../intent.js";
+import type { ItemCategory, NameAuthor } from "../naming.js";
+import type { SessionBudget } from "../sessionbudget.js";
+import type { LaunchOpts } from "./session.js";
+/**
+ * A new intent, as posted.
+ *
+ * `id` is client-minted and is THE at-most-once key — not for the ack ledger's
+ * 45 minutes, but for the row's whole life. A post replayed after the ledger has
+ * forgotten the ackId finds the row by this id and returns it, rather than
+ * doing the work a second time.
+ *
+ * `target` is optional because `cwd` is not: an absent target means "in this
+ * repo", which is the only reading it can have (`cleanTarget`).
+ */
+export interface IntentDraft {
+    id: string;
+    cwd: string;
+    payload: IntentPayload | BuildPayload | AssessPayload | CapturePayload;
+    target?: IntentTarget;
+    trigger: IntentTrigger;
+    serial?: boolean;
+    /** See `Intent.holdForHost` — hold this fire until nothing else on the host
+     *  is starting or running. */
+    holdForHost?: boolean;
+    /** See `Intent.pastBudget` — a person already let this past the budget, until
+     *  the reset of the window they did it in. The HOST posts it (a recurring rule's
+     *  child); a client lifts the budget with
+     *  `intent.waive`, never by posting it — `intent.post` strips it off the wire.
+     *  Not on `IntentPatch`: a waiver is not an edit to the row. */
+    pastBudget?: BudgetWaiver;
+    /** See `Intent.budgetPass` — the before-reset lift a recurring rule's child
+     *  is minted with. The HOST posts it (`workItemInherits`); cleaned strictly
+     *  by `cleanIntentRow`. */
+    budgetPass?: BudgetPass;
+    /** See `Intent.leftoverOf` — only the HOST may post it; a client never
+     *  does, and `intent.post` strips it. */
+    leftoverOf?: number;
+    auto?: boolean;
+    /** Aimed at one session by hand — exempt from the global auto-fire switch,
+     *  never from the account's budget. See `Intent.pinned`. */
+    pinned?: boolean;
+    /** May be typed into a session another intent holds. See `Intent.interject`. */
+    interject?: boolean;
+    /** `--continue` the repo's conversation when this opens a fresh session. */
+    resume?: boolean;
+    /** Close the session this opens once done (`true`), keep it open (`false`),
+     *  or — absent — follow the person's global setting. See
+     *  `Intent.closeWhenDone`. */
+    closeWhenDone?: boolean;
+    /** Flag the session this opens for follow up once done. See `Intent.flagWhenDone`. */
+    flagWhenDone?: boolean;
+    /** Set aside on arrival — kept in full, never run until brought back. */
+    archived?: boolean;
+    /** Waits for a person's tap — see `Intent.manual`. */
+    manual?: boolean;
+    /** Explicit sort position (0 is a value). */
+    order?: number;
+    label?: string;
+    title?: string;
+    /**
+     * A title a MACHINE wrote, with the author that says so — see
+     * `Intent.headline`. The pair is required together and `cleanIntentRow` drops
+     * one without the other, so a client that sends a title and forgets to say
+     * who wrote it posts a row with no title rather than one that cannot defend
+     * itself against the next naming run.
+     *
+     * A PERSON'S title does not come in here: it goes through the host's `edit()`
+     * as a `label`, which is the one write path that stamps `hand`.
+     */
+    headline?: string;
+    headlineBy?: NameAuthor;
+    /** What KIND of thing this is — one of `ITEM_CATEGORIES`, dropped rather than
+     *  rounded if it is not, and paired with its author the same way. Absent means
+     *  nobody said, never "chore". */
+    category?: ItemCategory;
+    categoryBy?: NameAuthor;
+    cols?: number;
+    rows?: number;
+    launch?: unknown;
+    /** The budget the session this opens is born with (`Intent.budget`).
+     *  `null` is an explicit CLEAR, for `upsert()` re-saving a row: absent there
+     *  means "this draft never heard of budgets" and keeps the stored cap, so a
+     *  person blanking it needs a value that says so. */
+    budget?: SessionBudget | null;
+    replaceSessionId?: string;
+    /** Provenance, for a row that was made by another row ("retry:<id>"). */
+    origin?: string;
+    /** Ties a sweep's children to the parent that made them. */
+    groupId?: string;
+}
+/**
+ * An edit to an intent that has not started.
+ *
+ * Every field is an ABSOLUTE value, never a delta, which is what makes the
+ * message idempotent by construction: a patch replayed after the receipt was
+ * lost lands the same row in the same state. The host refuses one aimed at a
+ * `starting`/`running` or terminal row — an edit to work already in flight is a
+ * different prompt than the one that ran, and pretending otherwise is how a row
+ * ends up describing something that never happened.
+ */
+export interface IntentPatch {
+    payload?: IntentPayload | BuildPayload | AssessPayload | CapturePayload;
+    trigger?: IntentTrigger;
+    label?: string;
+    title?: string;
+    serial?: boolean;
+    auto?: boolean;
+    /**
+     * Hold the fire until nothing else on the host is starting or running
+     * (`Intent.holdForHost`) — the send sheet's *wait until it's free* ticked
+     * beside a clock.
+     *
+     * Here for `resume`'s reason, one field along: a clock aimed at a SESSION is
+     * re-timed through this message (`whenRoute` routes that pair to a patch,
+     * because `ScheduleEntry` cannot name a session), and a patch that could not
+     * carry the hold would drop a decision the person had made in the same
+     * breath as the time — silently, which is the one way this app may not lose
+     * an answer.
+     */
+    holdForHost?: boolean;
+    /** Where it lands. `intent.retarget` is the recovery verb for this; the patch
+     *  carries it too because a backlog edit moves an item between repos and
+     *  between sessions in the same breath as its words. */
+    cwd?: string;
+    target?: IntentTarget;
+    archived?: boolean;
+    order?: number;
+    /**
+     * The "a person aimed this here themselves" exemption (`Intent.pinned`), as a
+     * patch — the backlog's per-item auto-fire flag on a row that already exists.
+     * Only ever set by a tap that says exactly that; nothing infers it.
+     */
+    pinned?: boolean;
+    /**
+     * `--continue` the repo's last conversation when this row opens its fresh
+     * session (`Intent.resume`).
+     *
+     * It was missing here while `Intent` had it and `cleanIntentRow` already read
+     * it, so `backlog.update` — the one message that edits an item somebody has
+     * already posted — carried it through a locally widened
+     * `IntentPatch & { resume?: boolean }` in the host. A type widened at the
+     * call site is a field with no owner: nothing documents it, nothing else can
+     * find it, and the next surface that wants to edit the flag widens the type
+     * a second time.
+     *
+     * ABSENT leaves the row's own value alone, which is what makes `false`
+     * meaningful — "start clean after all" is a decision a person can make about
+     * an item they already queued, and a patch that could only ever turn the flag
+     * on would make that decision unsayable without deleting the words and
+     * posting them again.
+     */
+    resume?: boolean;
+    /**
+     * The per-item *close the session when done* override (`Intent.
+     * closeWhenDone`): `true`/`false` set it, `null` CLEARS it back to "follow
+     * the global setting", absent leaves it alone. `null` rather than overloading
+     * `false`, because `false` is itself an answer ("keep this one open").
+     */
+    closeWhenDone?: boolean | null;
+    /** `Intent.flagWhenDone`: `true` sets it, `false`/`null` clears it, absent leaves it alone. */
+    flagWhenDone?: boolean | null;
+    /**
+     * The launch the session this row OPENS starts with (`Intent.launch`) — the
+     * send sheet's *model* row, re-decided on a row that is still waiting.
+     * `null` CLEARS it back to the desktop's new-session defaults; absent leaves
+     * it alone. An old host never reads it, and the row keeps the launch it had.
+     */
+    launch?: LaunchOpts | null;
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=intent.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"intent.js","sourceRoot":"","sources":["../../src/wire/intent.ts"],"names":[],"mappings":""}

package/node_modules/@waterplane/shared/dist/wire/localrt.d.ts

@@ -0,0 +1,78 @@
+/**
+ * What the LOCAL model runner is holding, on the wire.
+ *
+ * These two shapes were born in `packages/host/src/localrt.ts` and moved here
+ * the moment the phone had to draw them: a fact the host measures and the phone
+ * renders is a fact both ends must word identically, and two copies of
+ * "`reachable: false` is not an empty model list" is one copy too many.
+ *
+ * The host keeps NO history of these — it emits samples and the phone keeps the
+ * ring (`link.ts`'s pulse split, for its reason: a ring buffer on the host is a
+ * second copy of a series the phone is already drawing).
+ *
+ * **Tokens per second is deliberately absent and must stay absent** until there
+ * is a real measurement path. Neither ollama's `/api/ps` nor opencode publishes
+ * live throughput, and the available estimate — PTY bytes over wall clock — is
+ * wrong in both directions that matter: a TUI repaints (screen bytes are not
+ * output tokens) and a model thinking emits nothing while doing the expensive
+ * part. A throughput figure nobody can act on is worse than a blank space.
+ */
+import type { SysStat } from "./sysstat.js";
+/** One resident model, as the runner describes it. */
+export interface LoadedModel {
+    /** The runner's own name for it — `gemma4:e4b`, not `ollama/gemma4:e4b`. */
+    name: string;
+    /** Bytes the model is holding in total. */
+    size: number;
+    /** Bytes of that which are on the GPU. On Apple silicon this equals `size`
+     *  (unified memory) and is kept apart anyway, because on a discrete-GPU box
+     *  the difference is the whole story. */
+    vram: number;
+    /** When the runner intends to evict it, ms epoch — or absent when it said
+     *  nothing parseable. NOT defaulted to "now" or "never": both are claims. */
+    expiresAt?: number;
+    /** How many LIVE sessions on this host are currently running this model —
+     *  the host's own `SessionInfo.model`, joined by `modelBaseName`. Absent
+     *  when the host never wired the join (an old build, or a unit test with no
+     *  `SessionManager`); a real `0` is a measured "nobody", never a guess. */
+    sessionsUsing?: number;
+}
+/** One sample. The client keeps the history; this keeps none — see `link.ts`'s
+ *  pulse for the same split, and for the reason: a ring buffer on the host is a
+ *  second copy of a series the phone is already drawing. */
+export interface LocalRuntimeSample {
+    at: number;
+    /** Resident models. EMPTY means the runner answered and is holding nothing —
+     *  a different fact from `reachable: false`, and the two must not collapse. */
+    models: LoadedModel[];
+    /** Did the runner answer at all? False ⇒ every model field above is empty
+     *  because nothing was asked, not because nothing is loaded. */
+    reachable: boolean;
+    cpuPct: number;
+    memTotal: number;
+    memFree: number;
+    /** GPU compute utilization, 0-100, as the OS reports it. ABSENT — never 0 —
+     *  on a host with no reader for it: today that is Apple Silicon only
+     *  (`ioreg`'s own "Device Utilization %"), so a discrete-GPU box or a Linux
+     *  desktop says nothing rather than a borrowed CPU number. */
+    gpuPct?: number;
+    /** Bytes the GPU driver reports in use, system-wide — not just the models
+     *  below. Kept apart from a model's own `vram` on purpose: that is ollama's
+     *  per-model figure, this is the OS's total, and folding them into one
+     *  number would make a multi-model host's row disagree with what the
+     *  machine actually holds. */
+    gpuMemInUse?: number;
+    /**
+     * The rest of the machine — the CPU split, where the memory went, which
+     * programs are holding it, and how hot the box is running (`wire/sysstat.ts`).
+     *
+     * **Absent on a host that predates it, and every section inside it is
+     * optional again** for the same reason: a reader this platform has not got
+     * produces no field, never a zero. It rides HERE rather than on its own
+     * message because it answers the questions this sample provokes — "1.1 GB
+     * free of 64 GB, held by WHAT?" — and a second stream to join against would
+     * be a second lease, a second cadence and a readout that can disagree with
+     * the one beside it.
+     */
+    sys?: SysStat;
+}

package/node_modules/@waterplane/shared/dist/wire/localrt.js

@@ -0,0 +1,21 @@
+/**
+ * What the LOCAL model runner is holding, on the wire.
+ *
+ * These two shapes were born in `packages/host/src/localrt.ts` and moved here
+ * the moment the phone had to draw them: a fact the host measures and the phone
+ * renders is a fact both ends must word identically, and two copies of
+ * "`reachable: false` is not an empty model list" is one copy too many.
+ *
+ * The host keeps NO history of these — it emits samples and the phone keeps the
+ * ring (`link.ts`'s pulse split, for its reason: a ring buffer on the host is a
+ * second copy of a series the phone is already drawing).
+ *
+ * **Tokens per second is deliberately absent and must stay absent** until there
+ * is a real measurement path. Neither ollama's `/api/ps` nor opencode publishes
+ * live throughput, and the available estimate — PTY bytes over wall clock — is
+ * wrong in both directions that matter: a TUI repaints (screen bytes are not
+ * output tokens) and a model thinking emits nothing while doing the expensive
+ * part. A throughput figure nobody can act on is worse than a blank space.
+ */
+export {};
+//# sourceMappingURL=localrt.js.map

package/node_modules/@waterplane/shared/dist/wire/localrt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localrt.js","sourceRoot":"","sources":["../../src/wire/localrt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/node_modules/@waterplane/shared/dist/wire/localusage.d.ts

@@ -0,0 +1,121 @@
+/**
+ * What the LOCAL runner has done, kept — `GET /api/localusage`.
+ *
+ * A THIRD kind of document beside the two token ledgers, never merged with
+ * either: Claude's jsonl and opencode's store count what a CLIENT sent; this
+ * counts what the RUNNER did (ollama's own `print_timing` lines and its `/api/ps`),
+ * whichever client asked — claude-local, Codex and opencode all reach the same
+ * runner. Reasoning and measurements:
+ * docs/analysis/spikes/2026-10-02-local-usage-metrics.md.
+ *
+ * Three families, each kept apart for ever:
+ *  - COMPUTE — the runner's own durations (prompt processing vs generation),
+ *    loading apart, and "time to answer" (the HTTP request's wall time, which
+ *    includes waiting in the runner's queue) apart again. Never summed together.
+ *  - TOKENS — the runner's own counts: prompt tokens it PROCESSED vs prompt
+ *    tokens it reused from its prompt cache, and tokens it generated.
+ *  - MEMORY — the resident size `/api/ps` reported while the model was loaded,
+ *    and the machine's memory while it was.
+ *
+ * Every field is optional and absent means NOT MEASURED — never zero.
+ */
+/** The runner's own durations and counts, for the requests that had them. */
+export interface LocalCompute {
+    /** Requests whose timing block was read. */
+    requests: number;
+    /** Prompt tokens the runner processed (not served from its cache), and how long that took. */
+    promptTok: number;
+    promptMs: number;
+    /** Prompt tokens reused from the runner's prompt cache — no compute. Only
+     *  counted where the block logged the prompt's full length. */
+    cachedTok: number;
+    /** Tokens generated, and how long generating them took. */
+    genTok: number;
+    genMs: number;
+}
+/** Wall-clock time to answer (the runner's HTTP access line), for a set of requests. */
+export interface LocalWall {
+    requests: number;
+    ms: number;
+}
+/** Model loads the runner logged, and how long they took. */
+export interface LocalLoads {
+    loads: number;
+    ms: number;
+}
+/** What `/api/ps` said a model held, over the samples it was resident in. */
+export interface LocalMemory {
+    samples: number;
+    /** Σ resident bytes over the samples — mean = sumBytes / samples. */
+    sumBytes: number;
+    peakBytes: number;
+    /** The same for the GPU's share (equal on Apple silicon: unified memory). */
+    sumVram: number;
+    peakVram: number;
+    /** How long it was seen resident: sum of sample intervals, each capped. */
+    residentMs: number;
+    /** The context the runner allocated for it, when ps said. */
+    contextLength?: number;
+}
+/** The machine's memory, sampled while a model was resident. */
+export interface LocalMachine {
+    samples: number;
+    usedSum: number;
+    usedPeak: number;
+    /** The least memory a new program could have had. */
+    availMin: number;
+    totalBytes: number;
+    /** Swap in use at its highest — absent where no reader. */
+    swapPeak?: number;
+    source: "vm_stat" | "meminfo";
+}
+/** One model on one day. `model: null` = the runner ran it but this host
+ *  could not tell which model (see `LocalUsageAvailable.unattributedWhy`). */
+export interface LocalModelDay {
+    model: string | null;
+    compute?: LocalCompute;
+    /** Time to answer for the requests that ALSO have `compute` (paired). */
+    timed?: LocalWall;
+    /** Requests the access log closed with no runner timings — time to answer only. */
+    untimed?: LocalWall;
+    loads?: LocalLoads;
+    /** Requests per HTTP path (`/v1/messages`, `/v1/responses`, …): which API asked. */
+    byApi?: Record<string, number>;
+    mem?: LocalMemory;
+    machine?: LocalMachine;
+}
+export interface LocalUsageDay {
+    /** Local calendar day, `YYYY-MM-DD`. */
+    day: string;
+    models: LocalModelDay[];
+}
+export type LocalUsageLog = {
+    readable: true;
+    file: string;
+    readAt: number | null;
+} | {
+    readable: false;
+    file: string | null;
+    reason: string;
+};
+export interface LocalUsageAvailable {
+    available: true;
+    runner: "ollama";
+    url: string;
+    /** When this host started keeping the ledger — nothing before it is in it. */
+    since: number;
+    /** The last `/api/ps` attempt, and whether it answered. null = not asked yet. */
+    lastSampleAt: number | null;
+    reachable: boolean | null;
+    /** Models resident at the last answered sample. */
+    loaded: string[];
+    intervalMs: number;
+    log: LocalUsageLog;
+    days: LocalUsageDay[];
+    /** Why a `model: null` row exists — one sentence, the same everywhere. */
+    unattributedWhy: string;
+}
+export type LocalUsageDoc = LocalUsageAvailable | {
+    available: false;
+    reason: string;
+};

package/node_modules/@waterplane/shared/dist/wire/localusage.js

@@ -0,0 +1,23 @@
+/**
+ * What the LOCAL runner has done, kept — `GET /api/localusage`.
+ *
+ * A THIRD kind of document beside the two token ledgers, never merged with
+ * either: Claude's jsonl and opencode's store count what a CLIENT sent; this
+ * counts what the RUNNER did (ollama's own `print_timing` lines and its `/api/ps`),
+ * whichever client asked — claude-local, Codex and opencode all reach the same
+ * runner. Reasoning and measurements:
+ * docs/analysis/spikes/2026-10-02-local-usage-metrics.md.
+ *
+ * Three families, each kept apart for ever:
+ *  - COMPUTE — the runner's own durations (prompt processing vs generation),
+ *    loading apart, and "time to answer" (the HTTP request's wall time, which
+ *    includes waiting in the runner's queue) apart again. Never summed together.
+ *  - TOKENS — the runner's own counts: prompt tokens it PROCESSED vs prompt
+ *    tokens it reused from its prompt cache, and tokens it generated.
+ *  - MEMORY — the resident size `/api/ps` reported while the model was loaded,
+ *    and the machine's memory while it was.
+ *
+ * Every field is optional and absent means NOT MEASURED — never zero.
+ */
+export {};
+//# sourceMappingURL=localusage.js.map

package/node_modules/@waterplane/shared/dist/wire/localusage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localusage.js","sourceRoot":"","sources":["../../src/wire/localusage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}