primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/function-grants-preflight.js

@@ -0,0 +1,105 @@
+/**
+ * `config push`'s local check of a function's capabilities — #3182,
+ * project `server-functions` phase 1, rewritten by #3279.
+ *
+ * The server is authoritative (the raw admin route exists, and it derives the
+ * capabilities from the TOML inside the envelope). This is the other
+ * enforcement point: an author who writes a retired grant string, or an
+ * `integration:` naming an integration the tree does not declare, should see
+ * it against their own file, in the front-loaded preflight pass, with nothing
+ * applied — not as a server refusal partway through a push that has already
+ * created three other things.
+ *
+ * The GRAMMAR is not restated here. It is the vendored `function-grants.ts` —
+ * the same module the server imports — so the two checks cannot drift into
+ * two rules. Since #3279 that grammar keeps three kinds (`integration:<key>`,
+ * `secret:<NAME>`, the high-blast opt-ins) and refuses everything it retired
+ * with the retirement, so a file still declaring a `database:` grant is
+ * told what changed rather than "unknown family".
+ *
+ * ── What "the app has this integration" means locally ────────────────────
+ *
+ * The tree is the intent: an integration declared in `integrations/` will
+ * exist after this push (objects are applied before functions). One that
+ * exists only on the server is real too, so the caller merges the live
+ * listing in when it could fetch one. When neither is available the target
+ * check is SKIPPED rather than guessed — the server will still refuse, and a
+ * preflight that refuses a valid tree because it could not reach the network
+ * would be worse than one that defers.
+ */
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { basename, join } from "path";
+import { parseConfigToml } from "./config-toml.js";
+import { parseCapabilities, validateKeyedGrantsAgainstTargets, } from "./generated-config-surfaces.js";
+/** The set, read from the tree's `integrations/`. */
+export function configObjectKeysFromTree(configDir) {
+    return {
+        integrations: keysFromDir(configDir, "integrations", "integration"),
+    };
+}
+/**
+ * One directory's object keys.
+ *
+ * The key is the `[<table>].key` the file declares, falling back to the file
+ * name — the same precedence the push path resolves an object's identity by.
+ *
+ * Every `.toml` in the directory counts. The generated document-schema copy is
+ * a rule about `functions/` and is not one here (CR3455-003) — dropping an
+ * object by a foreign directory's rule would refuse a grant on a target the
+ * tree really declares.
+ */
+function keysFromDir(configDir, dirName, table) {
+    const keys = new Set();
+    const dir = join(configDir, dirName);
+    if (!existsSync(dir))
+        return keys;
+    for (const file of readdirSync(dir).filter((f) => f.endsWith(".toml"))) {
+        let data;
+        try {
+            data = parseConfigToml(readFileSync(join(dir, file), "utf-8"));
+        }
+        catch {
+            // A file that does not parse is reported by its own preflight.
+            continue;
+        }
+        keys.add(String(data?.[table]?.key || basename(file, ".toml")));
+    }
+    return keys;
+}
+/** The server's keys, then the tree's — the tree is what this push applies. */
+export function mergeKnownGrantTargets(fromServer, fromTree) {
+    return {
+        integrations: new Set([...fromServer.integrations, ...fromTree.integrations]),
+    };
+}
+/**
+ * Everything wrong with one function file's capabilities, as push-ready lines.
+ *
+ * Each message names the file, because the preflight pass reports every file's
+ * errors together and "unknown integration 'stripe'" on its own does not say
+ * which function asked for it.
+ */
+export function functionGrantErrors(input) {
+    const { filePath, tomlData, knownTargets } = input;
+    const table = tomlData?.function ?? {};
+    const where = `${filePath}:`;
+    const messages = [];
+    const parsed = parseCapabilities(table.capabilities);
+    if (!parsed.ok) {
+        for (const error of parsed.errors)
+            messages.push(`${where} ${error}`);
+        return messages;
+    }
+    // #3183 — `integration:` names a config-tree object, so the same "does this
+    // app have it" question applies. The rule is the shared one; what is
+    // CLI-side is reading the tree for it.
+    if (knownTargets) {
+        for (const error of validateKeyedGrantsAgainstTargets(parsed.allGrants, {
+            integrations: knownTargets.integrations,
+        })) {
+            messages.push(`${where} ${error}`);
+        }
+    }
+    return messages;
+}
+//# sourceMappingURL=function-grants-preflight.js.map

package/dist/src/lib/function-grants-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-grants-preflight.js","sourceRoot":"","sources":["../../../src/lib/function-grants-preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EACL,iBAAiB,EACjB,iCAAiC,GAClC,MAAM,gCAAgC,CAAC;AAcxC,qDAAqD;AACrD,MAAM,UAAU,wBAAwB,CACtC,SAAiB;IAEjB,OAAO;QACL,YAAY,EAAE,WAAW,CAAC,SAAS,EAAE,cAAc,EAAE,aAAa,CAAC;KACpE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,WAAW,CAClB,SAAiB,EACjB,OAAe,EACf,KAAa;IAEb,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACvE,IAAI,IAAS,CAAC;QACd,IAAI,CAAC;YACH,IAAI,GAAG,eAAe,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACjE,CAAC;QAAC,MAAM,CAAC;YACP,+DAA+D;YAC/D,SAAS;QACX,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,sBAAsB,CACpC,UAAiC,EACjC,QAA+B;IAE/B,OAAO;QACL,YAAY,EAAE,IAAI,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC,YAAY,EAAE,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;KAC9E,CAAC;AACJ,CAAC;AAeD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAkC;IAElC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC;IACnD,MAAM,KAAK,GAAG,QAAQ,EAAE,QAAQ,IAAI,EAAE,CAAC;IACvC,MAAM,KAAK,GAAG,GAAG,QAAQ,GAAG,CAAC;IAC7B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACrD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,KAAK,EAAE,CAAC,CAAC;QACtE,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,4EAA4E;IAC5E,qEAAqE;IACrE,uCAAuC;IACvC,IAAI,YAAY,EAAE,CAAC;QACjB,KAAK,MAAM,KAAK,IAAI,iCAAiC,CAAC,MAAM,CAAC,SAAS,EAAE;YACtE,YAAY,EAAE,YAAY,CAAC,YAAY;SACxC,CAAC,EAAE,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,KAAK,EAAE,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/src/lib/function-log-lines.d.ts

@@ -0,0 +1,76 @@
+/**
+ * One invocation's captured console output, in the order it was printed —
+ * #3453 (D3453-005).
+ *
+ * `primitive functions logs --run <run-id>` used to print the same one-row-per
+ * record table the listing prints, so the LINES — the thing an operator opened
+ * the logs for — were only reachable through `--json`. This renders them, under
+ * the step that wrote them.
+ *
+ * Pure, and separate from the command, for the reason `function-log-row.ts`
+ * gives: a rendering rule that lives inside an action can only be tested by
+ * spawning the CLI, and this one has enough cases (two orderings, a header that
+ * changes, a throw, a pre-change record) that spawning for each would be the
+ * wrong trade.
+ */
+/** The marker a truncated record ends with, so loss is never silent. */
+export declare const TRUNCATION_MARKER = "\u2026 truncated: the platform's per-record cap dropped later lines";
+/**
+ * What an EMPTY record whose attempt ended in the engine says — #3564,
+ * criterion 2 (D3564-007).
+ *
+ * The filing's own complaint: the invocation log held no console output for
+ * these attempts, with `truncated`, `logsUnavailable` and `contentSuppressed`
+ * all unset, so the silence read as "logs lost" when it meant "the handler
+ * printed nothing before the engine took the isolate away". This renderer
+ * printed nothing at all for such a record, which is the reading the filing
+ * asks to be able to make.
+ *
+ * Two facts, never collapsed into one: the first half says the attempt ended
+ * in the engine, and the SECOND half is chosen by the drain's own flags. A
+ * drain that failed — which `DrainedLogs.unavailable` names isolate eviction
+ * as a cause of — is reported as unavailable rather than as an empty handler,
+ * because those are opposite statements and this is precisely the case where
+ * guessing would be wrong.
+ */
+export declare const ENGINE_END_PREFIX = "ended in the engine";
+/**
+ * One record's console output, ready to print under its `functionLogLine`.
+ *
+ * A header is emitted whenever the label CHANGES, so two lines from one body
+ * sit under one header and a body re-entered after another step gets its own.
+ * A `thrown` entry — the wrapper's own record of a body that failed — takes a
+ * `!` in the gutter rather than an extra column, so the columns stay aligned.
+ *
+ * A record with NO lines whose attempt ended in the engine says so instead of
+ * printing nothing (#3564, {@link ENGINE_END_PREFIX}). The derivation is by
+ * the record's own `endedIn`, which the platform derived from its stored code
+ * — never by re-reading its message here, so a record written before this
+ * child renders exactly as it rendered then (edge 32).
+ */
+export declare function renderInvocationLines(record: any): string[];
+/** What `logs --run` was able to read before it renders anything. */
+export interface RunLogsInput {
+    /** The filtered page, NEWEST first, as the listing route answers it. */
+    records: any[];
+    /** The run's step rows, or null when the read failed. */
+    trace: any[] | null;
+    /** The trace read's failure, if it had one. */
+    traceError?: string | null;
+}
+/**
+ * The whole of `logs --run`'s human output — #3453 (D3453-005).
+ *
+ * Returned rather than printed so every one of its rules is decidable without
+ * a server (#3187's lesson): which runs get a table, what a failed trace read
+ * costs, and the order the records come out in. The command does the two I/O
+ * reads and prints what comes back.
+ *
+ * Records are reversed because the listing answers newest first and a run is
+ * read forwards — an operator following what happened wants the first
+ * invocation at the top.
+ */
+export declare function renderRunLogs(input: RunLogsInput): {
+    lines: string[];
+    warning: string | null;
+};

package/dist/src/lib/function-log-lines.js

@@ -0,0 +1,160 @@
+/**
+ * One invocation's captured console output, in the order it was printed —
+ * #3453 (D3453-005).
+ *
+ * `primitive functions logs --run <run-id>` used to print the same one-row-per
+ * record table the listing prints, so the LINES — the thing an operator opened
+ * the logs for — were only reachable through `--json`. This renders them, under
+ * the step that wrote them.
+ *
+ * Pure, and separate from the command, for the reason `function-log-row.ts`
+ * gives: a rendering rule that lives inside an action can only be tested by
+ * spawning the CLI, and this one has enough cases (two orderings, a header that
+ * changes, a throw, a pre-change record) that spawning for each would be the
+ * wrong trade.
+ */
+import { functionLogLine } from "./function-log-row.js";
+import { renderStepRunTable } from "./step-run-table.js";
+/** The marker a truncated record ends with, so loss is never silent. */
+export const TRUNCATION_MARKER = "… truncated: the platform's per-record cap dropped later lines";
+/**
+ * What an EMPTY record whose attempt ended in the engine says — #3564,
+ * criterion 2 (D3564-007).
+ *
+ * The filing's own complaint: the invocation log held no console output for
+ * these attempts, with `truncated`, `logsUnavailable` and `contentSuppressed`
+ * all unset, so the silence read as "logs lost" when it meant "the handler
+ * printed nothing before the engine took the isolate away". This renderer
+ * printed nothing at all for such a record, which is the reading the filing
+ * asks to be able to make.
+ *
+ * Two facts, never collapsed into one: the first half says the attempt ended
+ * in the engine, and the SECOND half is chosen by the drain's own flags. A
+ * drain that failed — which `DrainedLogs.unavailable` names isolate eviction
+ * as a cause of — is reported as unavailable rather than as an empty handler,
+ * because those are opposite statements and this is precisely the case where
+ * guessing would be wrong.
+ */
+export const ENGINE_END_PREFIX = "ended in the engine";
+function engineEndLine(record) {
+    const why = record?.logsUnavailable === true
+        ? "logs unavailable"
+        : record?.contentSuppressed === true
+            ? "output suppressed"
+            : "no handler output";
+    return `${ENGINE_END_PREFIX} — ${why}`;
+}
+const INDENT = "  ";
+/**
+ * Put one record's two arrays back into CAPTURE order.
+ *
+ * The writer persists `stdout` and `stderr` as two arrays filtered by stream
+ * and `t` is a millisecond offset, so `console.error("first")` followed by
+ * `console.log("second")` in the same millisecond has no surviving order in
+ * the record itself: merging by `t` prints them backwards. `n` is stamped at
+ * capture, in one buffer, and is what restores it.
+ *
+ * A record written before #3453 carries no `n` at all, and one entry having it
+ * while another does not is not a state any writer produces — so the fallback
+ * is chosen for the WHOLE record rather than per entry. Interleaving two
+ * orders would put entries in an order neither of them claims.
+ *
+ * The `t` fallback sorts stably with stdout first on a tie, which is the order
+ * the two arrays already sit in.
+ */
+function inCaptureOrder(record) {
+    const stdout = Array.isArray(record?.stdout) ? record.stdout : [];
+    const stderr = Array.isArray(record?.stderr) ? record.stderr : [];
+    const merged = [...stdout, ...stderr];
+    const everyEntryNumbered = merged.length > 0 && merged.every((entry) => Number.isFinite(entry?.n));
+    const key = everyEntryNumbered
+        ? (entry) => Number(entry.n)
+        : (entry) => Number(entry.t ?? 0);
+    // `Array.prototype.sort` is stable, so equal keys keep the order above —
+    // stdout before stderr.
+    return merged.slice().sort((a, b) => key(a) - key(b));
+}
+/** `step <name> #<occurrence> attempt <n>`, or null between steps. */
+function headerFor(entry) {
+    if (!entry?.step || typeof entry.step.name !== "string")
+        return null;
+    return `step ${entry.step.name} #${entry.step.occurrence ?? 0} attempt ${entry.attempt ?? 1}`;
+}
+/**
+ * One record's console output, ready to print under its `functionLogLine`.
+ *
+ * A header is emitted whenever the label CHANGES, so two lines from one body
+ * sit under one header and a body re-entered after another step gets its own.
+ * A `thrown` entry — the wrapper's own record of a body that failed — takes a
+ * `!` in the gutter rather than an extra column, so the columns stay aligned.
+ *
+ * A record with NO lines whose attempt ended in the engine says so instead of
+ * printing nothing (#3564, {@link ENGINE_END_PREFIX}). The derivation is by
+ * the record's own `endedIn`, which the platform derived from its stored code
+ * — never by re-reading its message here, so a record written before this
+ * child renders exactly as it rendered then (edge 32).
+ */
+export function renderInvocationLines(record) {
+    const out = [];
+    let currentHeader = null;
+    let headerEmitted = false;
+    const entries = inCaptureOrder(record);
+    for (const entry of entries) {
+        const header = headerFor(entry);
+        if (header !== currentHeader) {
+            currentHeader = header;
+            headerEmitted = false;
+        }
+        if (header && !headerEmitted) {
+            out.push(`${INDENT}${header}`);
+            headerEmitted = true;
+        }
+        const indent = header ? INDENT.repeat(2) : INDENT;
+        const gutter = entry?.thrown === true ? `${indent.slice(0, -2)}! ` : indent;
+        const stream = entry?.s === "err" ? "err" : "out";
+        out.push(`${gutter}+${Number(entry?.t ?? 0)}ms  ${stream}  ${String(entry?.line ?? "")}`);
+    }
+    // #3564 — the empty record, explained. Only when the record really has no
+    // lines: one that printed something says more than the sentence does, and a
+    // reader who can see the output does not need to be told there is some.
+    if (entries.length === 0 && record?.endedIn === "engine") {
+        out.push(`${INDENT}${engineEndLine(record)}`);
+    }
+    // Said out loud, because the alternative is output that looks complete after
+    // the cap dropped the later lines or the throw entry. The record persists the
+    // boolean and not the count (F-3453-009), so the marker cannot name one.
+    if (record?.truncated === true)
+        out.push(`${INDENT}${TRUNCATION_MARKER}`);
+    return out;
+}
+/**
+ * The whole of `logs --run`'s human output — #3453 (D3453-005).
+ *
+ * Returned rather than printed so every one of its rules is decidable without
+ * a server (#3187's lesson): which runs get a table, what a failed trace read
+ * costs, and the order the records come out in. The command does the two I/O
+ * reads and prints what comes back.
+ *
+ * Records are reversed because the listing answers newest first and a run is
+ * read forwards — an operator following what happened wants the first
+ * invocation at the top.
+ */
+export function renderRunLogs(input) {
+    const lines = [];
+    // A trace this reader could not fetch is not a reason to withhold the
+    // output: the lines say more than the failure does.
+    const warning = input.traceError
+        ? `Could not read the step trace: ${input.traceError}`
+        : null;
+    // A request invocation has no step rows at all, and an empty table would
+    // say there were steps and none ran.
+    if (input.trace && input.trace.length > 0) {
+        lines.push(renderStepRunTable(input.trace), "");
+    }
+    for (const record of [...(input.records ?? [])].reverse()) {
+        lines.push(functionLogLine(record));
+        lines.push(...renderInvocationLines(record));
+    }
+    return { lines, warning };
+}
+//# sourceMappingURL=function-log-lines.js.map

package/dist/src/lib/function-log-lines.js.map

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

package/dist/src/lib/function-log-row.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One invocation, as a human reads it — the columns and the tail line.
+ *
+ * Extracted from `commands/functions.ts` by #3462 so the VERSION it added has
+ * somewhere to be tested. The one-shot table, the `--invocation` point read and
+ * the `--follow` tail all render the same facts in the same order, and three
+ * copies of that order in one command file is three chances for them to drift;
+ * a tail line that dropped a column would be a difference nobody could see
+ * without two terminals.
+ */
+/** The columns the one-shot and `--invocation` tables share, in order. */
+export declare const FUNCTION_LOG_COLUMNS: readonly ["TIME", "STATUS", "TRIGGER", "RUNTIME", "VERSION", "RUN/INVOCATION ID", "CODE", "ERROR"];
+/**
+ * The FIRST error line only — #3287.
+ *
+ * A stack is eight kilobytes and a table row is one line, so the row says what
+ * happened and `--json` carries the rest.
+ */
+export declare function firstErrorLine(row: any): string;
+/** The cells one record contributes to a table row. */
+export declare function functionLogCells(row: any): Record<string, string>;
+/**
+ * The same record as one line, for `--follow`.
+ *
+ * Same facts in the same order as the table's columns, so a reader who switches
+ * between them is reading the same thing. An absent value contributes nothing
+ * rather than an empty gap, because a tail line has no columns to keep aligned.
+ */
+export declare function functionLogLine(row: any): string;

package/dist/src/lib/function-log-row.js

@@ -0,0 +1,73 @@
+/**
+ * One invocation, as a human reads it — the columns and the tail line.
+ *
+ * Extracted from `commands/functions.ts` by #3462 so the VERSION it added has
+ * somewhere to be tested. The one-shot table, the `--invocation` point read and
+ * the `--follow` tail all render the same facts in the same order, and three
+ * copies of that order in one command file is three chances for them to drift;
+ * a tail line that dropped a column would be a difference nobody could see
+ * without two terminals.
+ */
+/** The columns the one-shot and `--invocation` tables share, in order. */
+export const FUNCTION_LOG_COLUMNS = [
+    "TIME",
+    "STATUS",
+    "TRIGGER",
+    // #3482 — which RUNTIME the platform ran this invocation under, beside the
+    // DOOR that fired it. `ctx.trigger.kind` says which door; this says whether
+    // the platform ran the code inside the request or as a task run, which is
+    // what `assertRuntime` tests for and what the two budgets differ by. Blank
+    // for a record written before the column existed.
+    "RUNTIME",
+    // #3462 — WHICH version this invocation executed. The record has carried
+    // `configId` since #3287 and nothing rendered it.
+    "VERSION",
+    "RUN/INVOCATION ID",
+    "CODE",
+    "ERROR",
+];
+/**
+ * The FIRST error line only — #3287.
+ *
+ * A stack is eight kilobytes and a table row is one line, so the row says what
+ * happened and `--json` carries the rest.
+ */
+export function firstErrorLine(row) {
+    const message = String(row?.errorMessage ?? "").trim();
+    if (message)
+        return message.split("\n")[0];
+    const stderr = Array.isArray(row?.stderr) ? row.stderr : [];
+    return stderr.length > 0 ? String(stderr[0].line ?? "") : "";
+}
+/** The cells one record contributes to a table row. */
+export function functionLogCells(row) {
+    return {
+        startedAt: row?.startedAt ?? "",
+        status: row?.status ?? "",
+        trigger: row?.trigger?.kind ?? "",
+        runtime: row?.runtime ?? "",
+        configId: row?.configId ?? "",
+        // A trigger fire and a task run name their run; a request invocation's key
+        // is its own id.
+        runOrInvocation: row?.runId || row?.invocationId || "",
+        errorCode: row?.errorCode ?? "",
+        firstError: firstErrorLine(row),
+    };
+}
+/**
+ * The same record as one line, for `--follow`.
+ *
+ * Same facts in the same order as the table's columns, so a reader who switches
+ * between them is reading the same thing. An absent value contributes nothing
+ * rather than an empty gap, because a tail line has no columns to keep aligned.
+ */
+export function functionLogLine(row) {
+    const cells = functionLogCells(row);
+    const runtime = cells.runtime ? `  ${cells.runtime}` : "";
+    const version = cells.configId ? `  ${cells.configId}` : "";
+    const code = cells.errorCode ? `  ${cells.errorCode}` : "";
+    const detail = cells.firstError ? `  ${cells.firstError}` : "";
+    return (`${cells.startedAt}  ${cells.status}  ${cells.trigger}${runtime}${version}  ` +
+        `${cells.runOrInvocation}${code}${detail}`);
+}
+//# sourceMappingURL=function-log-row.js.map

package/dist/src/lib/function-log-row.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-log-row.js","sourceRoot":"","sources":["../../../src/lib/function-log-row.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,MAAM;IACN,QAAQ;IACR,SAAS;IACT,2EAA2E;IAC3E,4EAA4E;IAC5E,0EAA0E;IAC1E,2EAA2E;IAC3E,kDAAkD;IAClD,SAAS;IACT,yEAAyE;IACzE,kDAAkD;IAClD,SAAS;IACT,mBAAmB;IACnB,MAAM;IACN,OAAO;CACC,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAQ;IACrC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,EAAE,YAAY,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,gBAAgB,CAAC,GAAQ;IACvC,OAAO;QACL,SAAS,EAAE,GAAG,EAAE,SAAS,IAAI,EAAE;QAC/B,MAAM,EAAE,GAAG,EAAE,MAAM,IAAI,EAAE;QACzB,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,IAAI,EAAE;QACjC,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,EAAE;QAC3B,QAAQ,EAAE,GAAG,EAAE,QAAQ,IAAI,EAAE;QAC7B,2EAA2E;QAC3E,iBAAiB;QACjB,eAAe,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,EAAE,YAAY,IAAI,EAAE;QACtD,SAAS,EAAE,GAAG,EAAE,SAAS,IAAI,EAAE;QAC/B,UAAU,EAAE,cAAc,CAAC,GAAG,CAAC;KAChC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,GAAQ;IACtC,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/D,OAAO,CACL,GAAG,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,OAAO,GAAG,OAAO,GAAG,OAAO,IAAI;QAC7E,GAAG,KAAK,CAAC,eAAe,GAAG,IAAI,GAAG,MAAM,EAAE,CAC3C,CAAC;AACJ,CAAC"}

package/dist/src/lib/function-log-tail.d.ts

@@ -0,0 +1,132 @@
+import type { FollowSource } from "./watch.js";
+/**
+ * The tail's backlog walk — #3287, CR3287-007, CR3287-016, CR3287-017.
+ *
+ * `primitive functions logs --follow` polls a listing that answers NEWEST
+ * first, and `followLoop` carries one opaque checkpoint. The naive source
+ * reads one page and advances the mark to the newest row on it — which is
+ * correct only while fewer than one page of invocations arrive between two
+ * polls. A function at its admitted rate can record far more than that in two
+ * seconds, and every row the tail skipped past would be gone for good: the
+ * mark moved over them, so no later tick can reach back.
+ *
+ * So a call walks BACKWARD, page by page, until it meets the mark, and emits
+ * everything it collected oldest-first. The walk is bounded per call, and a
+ * call whose budget runs out before it meets the mark does NOT skip the gap
+ * (CR3287-017): it keeps what it collected, hands back a checkpoint carrying
+ * the page cursor it stopped at, and the next call resumes from there. The
+ * mark advances only once the whole backlog between it and the walk's top has
+ * been collected, so no row is passed over, and the rows are still printed in
+ * the order they were written.
+ *
+ * The one thing that means holding across calls is the collected-but-unemitted
+ * backlog, which lives in this closure rather than in the checkpoint: a page
+ * of inspection items is not a string to round-trip. The checkpoint is still
+ * the only thing `followLoop` carries, and it is self-describing: a bare mark
+ * means "walk from the top to here", a mark with a cursor means "a walk is in
+ * progress, continue it".
+ *
+ * An EMPTY listing is an initialized tail, not an uninitialized one
+ * (CR3287-016). `followLoop` reads an empty checkpoint as "bootstrap again",
+ * so a tail started before a function's first invocation would swallow that
+ * invocation as its baseline — the first failure the operator was waiting
+ * for. The mark for "nothing yet" is a sentinel that sorts below every ULID.
+ *
+ * It lives here rather than inside the command because the walk is the part
+ * with a bug in it, and a bug in paging is decidable without a server.
+ */
+/** One page of the listing, as the route answers it. */
+export interface LogPage<T> {
+    items: T[];
+    nextCursor?: string;
+}
+export interface LogPager<T> {
+    (args: {
+        cursor?: string;
+    }): Promise<LogPage<T>>;
+}
+export interface LogTailOptions<T> {
+    /** The row's ULID — string order IS creation order. */
+    idOf: (row: T) => string;
+    /**
+     * How many pages one CALL will walk toward the mark. `followLoop` calls
+     * again within the same tick while the checkpoint says a walk is still in
+     * progress, up to its own page bound, then waits for the next tick.
+     */
+    maxPagesPerTick: number;
+}
+/**
+ * The mark of a tail that has seen no row yet — CR3287-016.
+ *
+ * A ULID is 26 characters of Crockford base32, so this single character sorts
+ * below every one of them and above nothing: `idOf(row) <= EMPTY_TAIL_MARK`
+ * is false for every row, which is exactly "everything is new". It is a
+ * non-empty string, which is what keeps `followLoop` from reading it as an
+ * uninitialized tail.
+ */
+export declare const EMPTY_TAIL_MARK = "0";
+/**
+ * How far below the mark the walk still looks — #3448 D3448-013.
+ *
+ * #3448 mints an invocation's id BEFORE the run and writes its record at
+ * SETTLEMENT, so a record can be inserted BELOW a mark set while it was still
+ * running: A starts, B starts and settles and is emitted, A settles. Under
+ * `stop at id <= mark` A is never shown — and A is the slow, failed and
+ * timed-out invocation an operator tails for (D3448-SO-003).
+ *
+ * The bound is the longest a REQUEST record can lag its own id: the platform's
+ * 30 s request ceiling plus the token's skew grace, rounded up to a minute.
+ * Nothing below it can still be in flight, so a row older than the window is
+ * already settled and was already emitted or already skipped.
+ *
+ * A task run's slice records carry settle-time ids of their own and are
+ * unaffected — they were never out of order.
+ */
+export declare const TAIL_OVERLAP_MS = 60000;
+/**
+ * The id the walk stops below, given the mark.
+ *
+ * A mark this cannot read — the empty sentinel, or a fixture's short id — is
+ * its own bound: there is no instant to widen from, so the walk stops exactly
+ * where it stopped before this change, and #3287's own fixtures are unmoved.
+ */
+export declare function tailLowerBound(mark: string): string;
+/** What the checkpoint string carries. */
+interface TailCheckpoint {
+    /** The newest id already emitted (or the empty sentinel). */
+    mark: string;
+    /** Set while a walk toward `mark` is in progress: the page to resume at. */
+    cursor?: string;
+    /**
+     * The ids already emitted that still lie inside the overlap window — #3448.
+     *
+     * The walk now revisits rows at or below the mark, and this is what makes a
+     * row in the overlap emitted ONCE. It is pruned as the window slides, so it
+     * is bounded by what a minute can hold rather than by the tail's lifetime.
+     */
+    seen: string[];
+    /**
+     * The oldest id the bootstrap managed to read, when it could not reach the
+     * whole overlap window inside its page budget — CR3448-003.
+     *
+     * The walk must not go below it: rows under it existed BEFORE the tail
+     * started and the baseline never recorded them, so reaching them would print
+     * history as if it were arriving. It is dropped as soon as the mark has
+     * moved far enough that the window itself is the tighter bound.
+     */
+    floor?: string;
+}
+/**
+ * A bare mark stays a bare mark — the common case, and what an operator sees
+ * in a debug print. Anything more is JSON, which a ULID cannot start with, so
+ * the two are told apart by their first character.
+ */
+export declare function encodeTailCheckpoint(checkpoint: TailCheckpoint): string;
+/**
+ * A pre-#3448 checkpoint has no `seen` key and reads as an empty set, which is
+ * the honest answer: the tail that wrote it never looked below its mark, so it
+ * emitted nothing inside the window it needs to remember.
+ */
+export declare function decodeTailCheckpoint(token: string): TailCheckpoint;
+export declare function buildLogFollowSource<T>(fetchPage: LogPager<T>, options: LogTailOptions<T>): FollowSource<T>;
+export {};