waterplane 0.0.1 → 0.1.6

package/node_modules/@waterplane/shared/dist/installlog.js

@@ -0,0 +1,367 @@
+/** How many installs the host keeps. Two phones updating four apps a day reach
+ *  this in about two months, which is longer than anybody asks "when did this
+ *  land" about. Oldest goes first. */
+export const INSTALL_LOG_CAP = 500;
+/** Caps on the strings an entry carries. None of them is a sentence a person
+ *  typed — they are package names, labels and installer errors — so clipping is
+ *  the right answer where refusing would lose the whole row. */
+const MAX_ID = 128;
+const MAX_TEXT = 120;
+const MAX_ERROR = 300;
+/** Entries one report may carry. A phone holds at most a couple of hundred
+ *  download rows; past this something is wrong and the store is not the place
+ *  to find out. */
+export const MAX_REPORT_ENTRIES = 300;
+/** How far ahead of the host a phone's clock may be before its `at` stops
+ *  being usable. Generous: two devices that have both synced are within
+ *  seconds, and the failure this catches is not skew, it is a clock that is
+ *  wrong by months. */
+const CLOCK_SLACK_MS = 10 * 60 * 1000;
+const CTRL = /[\x00-\x1f\x7f]/g;
+const str = (v, cap) => (typeof v === "string" ? v : "").replace(CTRL, " ").trim().slice(0, cap);
+/** A real, whole, positive instant — or absent. A clock nobody could read is
+ *  never rounded to "now": the whole point of `at` is that it is the phone's
+ *  own, and a substituted one would be a wrong number wearing a right one's
+ *  name. */
+function when(v) {
+    return typeof v === "number" && Number.isFinite(v) && v > 0 ? Math.floor(v) : undefined;
+}
+/** A build number, or absent. `0` is refused on both paths — a `versionCode`
+ *  of zero is not a build, and two thresholds for one field in the module that
+ *  exists so the ends cannot disagree is how they start disagreeing. */
+function count(v) {
+    return typeof v === "number" && Number.isFinite(v) && v > 0 ? Math.floor(v) : undefined;
+}
+/** The identity of one install. The `at` is in it on purpose: installing the
+ *  same build twice is two things that happened, and a key that folded them
+ *  together would lose the second. A shell that cannot say when falls to `0`,
+ *  which folds its re-installs into one row — the honest consequence of not
+ *  knowing, rather than a row per reconnect. */
+export function installKey(deviceId, pullId, at) {
+    // JSON rather than `a:b:c`. Neither half is shape-checked — a device id is
+    // whatever the reporter sent — and with a bare separator `("a:b", "c")` and
+    // `("a", "b:c")` are the same key, which is one phone's install landing on
+    // another phone's row and being re-attributed to it.
+    return JSON.stringify([deviceId, pullId, at ?? 0]);
+}
+/**
+ * One reported entry, cleaned — or null where it is not an install.
+ *
+ * A row is dropped, never repaired, when it has no package or no recognisable
+ * outcome: an entry that cannot say WHAT was installed is not a log line, it is
+ * a gap pretending to be one.
+ */
+export function cleanInstallEntry(raw, reporter, reportedAt) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    const outcome = r.outcome === "installed" || r.outcome === "failed" ? r.outcome : null;
+    if (!outcome)
+        return null;
+    const pkg = str(r.pkg, MAX_ID);
+    if (!pkg)
+        return null;
+    const pullId = str(r.pullId, MAX_ID);
+    if (!pullId)
+        return null;
+    const deviceId = str(reporter.id, MAX_ID);
+    if (!deviceId)
+        return null;
+    // An install is reported AFTER it happened, so an `at` past the moment the
+    // host was told is provably not this install's instant — a phone whose clock
+    // is a year fast, or a field that arrived in the wrong unit. Dropped rather
+    // than clamped: the module's own rule is absent over a wrong number, and the
+    // entry then says *reported*, which is true. The slack absorbs ordinary skew
+    // between two devices that both believe their clocks.
+    const claimed = when(r.at);
+    const at = claimed !== undefined && claimed > reportedAt + CLOCK_SLACK_MS ? undefined : claimed;
+    const entry = {
+        key: installKey(deviceId, pullId, at),
+        deviceId,
+        pullId,
+        pkg,
+        outcome,
+        reportedAt,
+    };
+    // Tri-state on purpose: absent is "nobody recorded which way it went", and
+    // `false` is the positive claim that a person tapped. See `wire/install.ts`.
+    if (typeof r.auto === "boolean")
+        entry.auto = r.auto;
+    const name = str(reporter.name, MAX_TEXT);
+    if (name)
+        entry.deviceName = name;
+    const model = str(reporter.model, MAX_TEXT);
+    if (model)
+        entry.deviceModel = model;
+    const label = str(r.label, MAX_TEXT);
+    if (label)
+        entry.label = label;
+    const version = str(r.version, MAX_TEXT);
+    if (version)
+        entry.version = version;
+    const code = count(r.code);
+    if (code !== undefined)
+        entry.code = code;
+    const file = str(r.file, MAX_TEXT);
+    if (file)
+        entry.file = file;
+    const repo = str(r.repo, MAX_TEXT);
+    if (repo)
+        entry.repo = repo;
+    const error = str(r.error, MAX_ERROR);
+    if (error && outcome === "failed")
+        entry.error = error;
+    if (at !== undefined)
+        entry.at = at;
+    return entry;
+}
+/**
+ * Every install a phone still has a record of, as report entries.
+ *
+ * Two judgements, both of which are the point:
+ *
+ *  - **Only a TERMINAL outcome is reported.** `asked` is the system installer
+ *    waiting for a person — it may wait for hours and may never be answered —
+ *    and a log that recorded it would be claiming an install that has not
+ *    happened. `installing` is the same claim in the present tense.
+ *  - **A row with no package is dropped.** The log's whole subject is WHICH app,
+ *    and three repos on this desktop build a file called `app-debug.apk`.
+ */
+export function installReportFrom(rows) {
+    const out = [];
+    for (const r of rows) {
+        if (r.install !== "installed" && r.install !== "failed")
+            continue;
+        if (!r.pkg || !r.id)
+            continue;
+        const entry = {
+            pullId: r.id,
+            pkg: r.pkg,
+            outcome: r.install,
+        };
+        if (typeof r.installAuto === "boolean")
+            entry.auto = r.installAuto;
+        if (r.label)
+            entry.label = r.label;
+        if (r.version)
+            entry.version = r.version;
+        const code = count(r.code);
+        if (code !== undefined)
+            entry.code = code;
+        if (r.name)
+            entry.file = r.name;
+        if (r.repo)
+            entry.repo = r.repo;
+        if (r.installError)
+            entry.error = r.installError;
+        if (r.installedAt)
+            entry.at = r.installedAt;
+        out.push(entry);
+    }
+    return out;
+}
+/** When an entry HAPPENED, for sorting and for the device's own clock. The
+ *  install's instant where the phone could say, else the moment it was
+ *  reported — and every sentence that prints this says which it is. */
+export function entryAt(e) {
+    return e.at ?? e.reportedAt;
+}
+/**
+ * Fold a report into the store.
+ *
+ * **Re-reporting is not re-recording.** An entry already held keeps its
+ * original `reportedAt` — that is the moment the host first heard about it, and
+ * rewriting it on every reconnect would make a week-old install look like it
+ * happened at the last handshake. What a repeat MAY do is fill in facts that
+ * were absent the first time (the phone learnt the app's label, or got a name
+ * of its own), because absent is not a claim and an improvement is not a
+ * conflict.
+ *
+ * Returns the new list plus what actually changed, so a caller can decide
+ * whether anything is worth persisting or broadcasting.
+ */
+export function mergeInstallLog(existing, incoming, cap = INSTALL_LOG_CAP) {
+    const by = new Map();
+    for (const e of existing)
+        by.set(e.key, e);
+    let added = 0;
+    let updated = 0;
+    for (const e of incoming) {
+        const had = by.get(e.key);
+        if (!had) {
+            by.set(e.key, e);
+            added++;
+            continue;
+        }
+        const merged = { ...e, reportedAt: had.reportedAt };
+        // Anything the old copy knew and the new one does not is KEPT: a phone that
+        // has since forgotten the app's label must not erase it from the history.
+        for (const k of ["deviceName", "deviceModel", "label", "version", "file", "repo"]) {
+            if (merged[k] === undefined && had[k] !== undefined)
+                merged[k] = had[k];
+        }
+        // The failure's words travel only onto a failure. On a key with no `at` — an
+        // older shell, where a retry folds onto the same row — a failed install
+        // followed by a successful one would otherwise come out `installed` still
+        // carrying "no space", which is the one thing `cleanInstallEntry` refuses to
+        // build in the first place.
+        if (merged.error === undefined && had.error !== undefined && merged.outcome === "failed") {
+            merged.error = had.error;
+        }
+        if (merged.auto === undefined && had.auto !== undefined)
+            merged.auto = had.auto;
+        if (merged.code === undefined && had.code !== undefined)
+            merged.code = had.code;
+        if (merged.at === undefined && had.at !== undefined)
+            merged.at = had.at;
+        if (!sameEntry(had, merged)) {
+            by.set(e.key, merged);
+            updated++;
+        }
+    }
+    return { entries: evict([...by.values()], cap), added, updated };
+}
+/**
+ * Cut the log to size — and this is the one place a client's clock must not be
+ * allowed to decide anything.
+ *
+ * **Eviction is by `reportedAt`, which is the HOST's own stamp**; display order
+ * is by `entryAt`, which prefers the install's own instant. Sorting the cut by
+ * `entryAt` let a phone whose clock is a year fast hold the top of the log for
+ * a year, so the rows that aged out were every other device's real history —
+ * and a report can mint a new key per entry, so this was reachable by accident
+ * as well as on purpose.
+ *
+ * **Then an equal share per device, and the remainder by recency.** Recency
+ * alone lets one busy phone crowd out a phone that installs something once a
+ * month, and the whole subject of this log is the fleet rather than its loudest
+ * member — but a reserved share must not cost anything when there is only one
+ * device, which is the ordinary case.
+ */
+function evict(all, cap) {
+    const display = (a, b) => entryAt(b) - entryAt(a);
+    if (all.length <= cap)
+        return [...all].sort(display);
+    const byRecency = [...all].sort((a, b) => b.reportedAt - a.reportedAt);
+    const devices = new Set(byRecency.map((e) => e.deviceId)).size;
+    const reserve = Math.max(1, Math.floor(cap / devices));
+    const taken = new Map();
+    const kept = [];
+    const rest = [];
+    for (const e of byRecency) {
+        const n = taken.get(e.deviceId) ?? 0;
+        if (n < reserve) {
+            taken.set(e.deviceId, n + 1);
+            kept.push(e);
+        }
+        else
+            rest.push(e);
+    }
+    // Whatever the shares did not spend goes by recency, so one phone on its own
+    // still gets the whole cap: the share only ever costs the loudest device, and
+    // only while a quieter one has history it would otherwise have pushed out.
+    for (const e of rest) {
+        if (kept.length >= cap)
+            break;
+        kept.push(e);
+    }
+    return kept.sort(display);
+}
+function sameEntry(a, b) {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const k of keys)
+        if (a[k] !== b[k])
+            return false;
+    return true;
+}
+/**
+ * The devices, derived from the entries.
+ *
+ * Derived rather than stored for one reason: a device list kept beside the log
+ * can disagree with it — a phone whose entries all aged out would linger as a
+ * row claiming installs nobody can see. The newest entry's name wins, because a
+ * rename should show up as the name that phone has NOW.
+ */
+export function installDevices(entries) {
+    const by = new Map();
+    // Newest first, so the first sighting of a device is the freshest name.
+    for (const e of [...entries].sort((a, b) => entryAt(b) - entryAt(a))) {
+        const cur = by.get(e.deviceId);
+        if (!cur) {
+            by.set(e.deviceId, {
+                id: e.deviceId,
+                ...(e.deviceName ? { name: e.deviceName } : {}),
+                ...(e.deviceModel ? { model: e.deviceModel } : {}),
+                lastAt: entryAt(e),
+                installs: e.outcome === "installed" ? 1 : 0,
+                failures: e.outcome === "failed" ? 1 : 0,
+            });
+            continue;
+        }
+        if (e.outcome === "installed")
+            cur.installs++;
+        else
+            cur.failures++;
+        if (cur.name === undefined && e.deviceName)
+            cur.name = e.deviceName;
+        if (cur.model === undefined && e.deviceModel)
+            cur.model = e.deviceModel;
+    }
+    return [...by.values()].sort((a, b) => b.lastAt - a.lastAt);
+}
+/** What to call a device on screen: the name somebody gave it, then the model
+ *  the browser admitted to, then the id — which says nothing, so it is last and
+ *  is shortened, because twelve hex characters is not a name. */
+export function deviceLabel(d) {
+    return d.name || d.model || `device ${d.id.slice(0, 6)}`;
+}
+/** The same question about an ENTRY, whose device fields are a snapshot of what
+ *  that phone called itself at the time. */
+export function entryDeviceLabel(e) {
+    return deviceLabel({ id: e.deviceId, name: e.deviceName, model: e.deviceModel });
+}
+/** What was installed, as one name: the app's own label with the version it
+ *  landed at. The package is NOT in it — three repos here build `app-debug.apk`
+ *  and the package is what tells them apart, so it is its own line on screen
+ *  rather than glued into this one. */
+export function installTitle(e) {
+    const name = e.label || e.pkg;
+    return e.version ? `${name} ${e.version}` : name;
+}
+/**
+ * The sentence for one entry.
+ *
+ * Says WHEN honestly: an install the phone timed is said as a time, and one it
+ * could not is said as *reported*, which is a claim about the log rather than
+ * about the install. Says WHO by name. Says whether anybody tapped.
+ */
+export function installLogLine(e, fmt) {
+    const who = entryDeviceLabel(e);
+    // No clause at all where nobody recorded which way it went. "on a tap" is a
+    // claim about a person, and a shell older than the field would have had every
+    // unattended overnight install described as something somebody did by hand.
+    const how = e.auto === undefined ? "" : e.auto ? " by itself" : " on a tap";
+    const verb = e.outcome === "installed" ? "installed" : "failed to install";
+    const stamp = e.at !== undefined ? fmt(e.at) : `reported ${fmt(e.reportedAt)}`;
+    const tail = e.outcome === "failed" && e.error ? ` — ${e.error}` : "";
+    return `${verb}${how} on ${who} · ${stamp}${tail}`;
+}
+/** The one line above the log. Counts devices as well as installs, because the
+ *  whole reason this exists is that there is more than one phone. */
+export function installLogSummary(doc) {
+    const n = doc.entries.length;
+    if (!n)
+        return "Nothing has installed itself yet. An app on a phone's allow-list is logged here the moment a build lands on it.";
+    const devices = doc.devices.length;
+    const failed = doc.entries.filter((e) => e.outcome === "failed").length;
+    const head = `${n} install${n === 1 ? "" : "s"} on ${devices} device${devices === 1 ? "" : "s"}`;
+    return failed ? `${head} · ${failed} failed.` : `${head}.`;
+}
+/** The log cut to one device, or to one package. A count on a control is a
+ *  filter (`CLAUDE.md`), so the screen that prints "3 on this phone" has to be
+ *  able to open exactly those three. */
+export function filterInstallLog(entries, filter) {
+    return entries.filter((e) => (!filter.deviceId || e.deviceId === filter.deviceId)
+        && (!filter.pkg || e.pkg === filter.pkg));
+}
+//# sourceMappingURL=installlog.js.map

package/node_modules/@waterplane/shared/dist/installlog.js.map

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

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

@@ -0,0 +1,103 @@
+/**
+ * Rung 2's two lifts: the before-reset pass (a row timed ahead of a reset
+ * runs past THAT window's ceiling) and the person's waiver (`pastBudget`).
+ * `budgetHold` is the rung's answer for one row; it is exported for
+ * `verdict.ts` only, and the barrel does not re-export it.
+ *
+ * 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 { BudgetCeiling } from "../budget.js";
+import type { BudgetPass, BudgetWaiver } from "./types.js";
+import type { Intent } from "./row.js";
+import type { IntentFacts } from "./facts.js";
+/**
+ * How far a ceiling's `resetAt` may sit from the reset a row was armed against
+ * and still be THAT reset, inclusive.
+ *
+ * Measured, not guessed: `usagelog.jsonl` shows `sr`/`wr` flipping by EXACTLY
+ * 60 000 ms between consecutive scrapes — the CLI's relative *resets in 1h 59m*
+ * is read as now + that, truncated to the minute, so one reset lands on two
+ * neighbouring minutes. `nextAt` is fixed from ONE reading at arm time and the
+ * ceiling carries the LATEST, so a one-minute tolerance failed on alternate
+ * ticks and the lift flickered. Five minutes absorbs that jitter with room to
+ * spare, and cannot mistake one window for another: the nearest other reset is
+ * hours (session) or days (weekly) away.
+ */
+export declare const RESET_MATCH_MS: number;
+/**
+ * The pass an occurrence of this rule carries, or `null`. Only a `window` rule
+ * on the `before` edge (absent = before, as `cleanRule` and `nextFireAt` read
+ * it) with a NEGATIVE lead time: the occurrence is `reset + offset`, so the
+ * reset it guards is `occurrence − offset`. `offsetMin` 0 fires AT the reset,
+ * where the new window's ceiling is the one that applies; `after` fires into a
+ * window that has just emptied.
+ */
+export declare function budgetPassAt(rule: ScheduleRule, occurrence: number): BudgetPass | null;
+/** The pass this row carries: read off its own armed clock when it has one,
+ *  else the stamp a recurring rule's child was minted with. */
+export declare function budgetPassOf(i: Intent): BudgetPass | null;
+/**
+ * Rung 2's answer for one `auto` row while the budget is over: the sentence to
+ * hold it with, or `null` for *every tripped ceiling is one this row is exempt
+ * from right now*. `""` is "hold, nobody said which cap" — `wait` finishes it.
+ */
+export declare function budgetHold(i: Intent, facts: IntentFacts, now: number): string | null;
+/**
+ * Is this row's waiver in force at `now`? The one reading of `pastBudget` —
+ * rung 2, the `budget` trigger, the tick's expiry sweep and the phone's chip all ask this, so an expired waiver cannot read as
+ * live in one of them.
+ */
+export declare function budgetWaived(i: {
+    pastBudget?: BudgetWaiver;
+}, now: number): boolean;
+/**
+ * The `until` a waiver granted now gets: the LATEST known reset among the
+ * ceilings tripped right now, so the waiver outlives every cap that holds the
+ * row and no window after them. `null` when nothing is tripped or no tripped
+ * ceiling says when it resets — there is then no window to scope it to, and
+ * the host refuses the waiver in words rather than inventing one.
+ */
+export declare function budgetWaiverUntil(over: readonly BudgetCeiling[] | undefined, now: number): number | null;
+/** The CONFIGURED period whose reset is the waiver's `until` (the tripped ceiling that resets last), or
+ *  undefined - `session`/`weekly` are already what `weekly` says and stay unrecorded, so those waivers keep their shape. */
+export declare function budgetWaiverPeriod(over: readonly BudgetCeiling[] | undefined, until: number): string | undefined;
+/** The host's refusal of a waiver when no ceiling is tripped — the one refusal
+ *  a waiver asked for AHEAD of the budget (`backlog.add`'s `pastBudget`) may
+ *  stay silent about: nothing holds the row, so it runs when free anyway. */
+export declare const BUDGET_NOT_HOLDING = "the budget is not holding anything right now";
+/** `Intent.pastBudget`, read strictly: one finite instant. Anything else —
+ *  the legacy `true` of a waiver that had no window included — is DROPPED,
+ *  never repaired: a waiver whose window nobody recorded cannot be scoped, and
+ *  dropping it only makes the row wait for the budget again. */
+export declare function cleanBudgetWaiver(v: unknown): BudgetWaiver | undefined;
+/**
+ * The weekly reset this row is a leftover of, or `null`. A row let past a
+ * week's budget — a weekly before-reset pass, or a person's weekly waiver
+ * (stamped `leftoverOf` when it expired) — that is still waiting once that
+ * week has reset. Read by rung 2 against `facts.leftoverOver`.
+ *
+ * WEEKLY only, on purpose: a session window refills in hours, so what a
+ * session pass leaves behind costs a few hours of a window that refills
+ * anyway; the week is the budget that does not come back.
+ */
+export declare function budgetLeftoverOf(i: Intent, now: number): number | null;
+/**
+ * How far past a weekly reset a row still counts as starting "right after" it:
+ * the new week's first session window. Further in, the row was timed for a
+ * moment of the week, not for the reset, and the ordinary ceilings are its.
+ */
+export declare const AFTER_RESET_LEFTOVER_MS: number;
+/**
+ * The weekly reset a row is timed to start AT or RIGHT AFTER, or `null` —
+ * the other half of the leftover. Rows moved past a reset (so they do not all
+ * start in the lead window before it) used to start together the moment the
+ * new week began, at ~0% of it, with nothing on the ordinary ceilings to slow
+ * them: the burst the leftover ceiling exists to stop, from the other side of
+ * the reset. So a `window`/weekly occurrence on the `after` edge, or at a
+ * non-negative offset, up to `AFTER_RESET_LEFTOVER_MS` past the reset, is held
+ * by the same leftover ceiling — once that reset has happened, never before.
+ */
+export declare function budgetAfterResetOf(i: Intent, now: number): number | null;