@singularityfm/contracts 0.0.0-stage → 0.1.0

package/dist/contracts/src/session.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The command center's session cookie: a signed end time, made by the admin gate (apps/admin/src/gate/gate.ts) at sign-in and
+ * read by whoever must know the owner is signed in, which is the gate and the reader's two report
+ * routes (apps/web/src/server/adminGuard.ts). Web Crypto only, so it runs in Vercel Routing
+ * Middleware, a function and the reader's server alike.
+ */
+export declare const COOKIE = "singularity_admin";
+export declare const SESSION_SECONDS: number;
+export declare function hmac(secret: string, message: string): Promise<string>;
+/** Equal strings, compared without stopping at the first difference. */
+export declare function same(a: string, b: string): boolean;
+/** A session value: when it ends, and the signature of that moment. */
+export declare function createSession(secret: string, now: number): Promise<string>;
+export declare function sessionValid(value: string | undefined, secret: string, now: number): Promise<boolean>;
+export declare function cookieOf(request: Request, name: string): string | undefined;

package/dist/contracts/src/session.js

@@ -0,0 +1,46 @@
+/**
+ * The command center's session cookie: a signed end time, made by the admin gate (apps/admin/src/gate/gate.ts) at sign-in and
+ * read by whoever must know the owner is signed in, which is the gate and the reader's two report
+ * routes (apps/web/src/server/adminGuard.ts). Web Crypto only, so it runs in Vercel Routing
+ * Middleware, a function and the reader's server alike.
+ */
+export const COOKIE = "singularity_admin";
+export const SESSION_SECONDS = 30 * 24 * 60 * 60;
+const encoder = new TextEncoder();
+export async function hmac(secret, message) {
+    const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const bytes = new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(message)));
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Equal strings, compared without stopping at the first difference. */
+export function same(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i += 1)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/** A session value: when it ends, and the signature of that moment. */
+export async function createSession(secret, now) {
+    const ends = Math.floor(now / 1000) + SESSION_SECONDS;
+    return `${ends}.${await hmac(secret, `session:${ends}`)}`;
+}
+export async function sessionValid(value, secret, now) {
+    if (!value)
+        return false;
+    const [ends, signature] = value.split(".");
+    if (!ends || !signature || !/^\d+$/.test(ends))
+        return false;
+    if (Number(ends) * 1000 <= now)
+        return false;
+    return same(signature, await hmac(secret, `session:${ends}`));
+}
+export function cookieOf(request, name) {
+    for (const part of (request.headers.get("cookie") ?? "").split(";")) {
+        const [key, ...rest] = part.trim().split("=");
+        if (key === name)
+            return rest.join("=");
+    }
+    return undefined;
+}

package/dist/contracts/src/store.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The store readers the admin app needs, as one entry the published package compiles (D382 step 3).
+ * The engine owns these files and keeps writing through them; this entry only names what a reader
+ * outside this repository may import.
+ */
+export * from "../../engine/src/store/configPaths.js";
+export * from "../../engine/src/store/experimentFlags.js";
+export * from "../../engine/src/store/experimentHits.js";
+export * from "../../engine/src/store/neon.js";
+export * from "../../engine/src/store/runsStore.js";

package/dist/contracts/src/store.js

@@ -0,0 +1,10 @@
+/**
+ * The store readers the admin app needs, as one entry the published package compiles (D382 step 3).
+ * The engine owns these files and keeps writing through them; this entry only names what a reader
+ * outside this repository may import.
+ */
+export * from "../../engine/src/store/configPaths.js";
+export * from "../../engine/src/store/experimentFlags.js";
+export * from "../../engine/src/store/experimentHits.js";
+export * from "../../engine/src/store/neon.js";
+export * from "../../engine/src/store/runsStore.js";

package/dist/engine/src/store/configPaths.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The config store's names and switch (D149), with no database code: the CLI, the write guard and
+ * the site's route import this, so it loads no Neon driver itself; `connectConfigStore` does, on
+ * call (the config store, D149, and the site's rate-limit counter whenever DATABASE_URL is set, D150).
+ */
+/**
+ * The files the database may hold, and the only paths a row may ever be written to. They are the
+ * owner's own config and are not in git (D296); `config/examples` holds the public defaults.
+ */
+export declare const CONFIG_DOCUMENT_PATHS: readonly ["config/topics.json", "config/sources.user.json", "config/queries.json", "config/preferences.json", "config/schedule.json", "config/structure.json", "config/writer.json", "config/profiles/owner.json", "state/source-candidates.json"];
+export type ConfigDocumentPath = (typeof CONFIG_DOCUMENT_PATHS)[number];
+/** What the store needs from a SQL client: one parameterised query, rows back as objects. */
+export interface SqlClient {
+    query(text: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+}
+export interface ConfigDocument {
+    path: string;
+    content: string;
+    version: number;
+    /** When it was last written, in epoch milliseconds (absent from a test's fake rows). */
+    updatedAt?: number;
+}
+export interface DocumentWrite {
+    path: string;
+    content: string;
+    /** The version the edit was made on; null for a document the store does not hold yet. */
+    version: number | null;
+}
+/** The URL to use when the store is switched on, or null: the URL alone never turns it on. */
+export declare function configStoreUrl(env: {
+    DATABASE_URL?: string | undefined;
+    SINGULARITY_CONFIG_STORE?: string | undefined;
+}): string | null;
+/**
+ * The URL to use when the run state store is switched on, or null (D381). Its own switch, beside
+ * the config store's, so state can be turned on and off without touching the owner's config.
+ */
+export declare function stateStoreUrl(env: {
+    DATABASE_URL?: string | undefined;
+    SINGULARITY_STATE_STORE?: string | undefined;
+}): string | null;
+/** The URL and its password, decoded: an error that names either must be logged without it. */
+export declare function databaseSecrets(databaseUrl: string): string[];
+/** Opens the store over Neon's HTTP driver, which is loaded only on this call. */
+export declare function connectConfigStore(databaseUrl: string): Promise<SqlClient>;
+/**
+ * Whether a command reads the owner's config at its start: a whole run or the gate stage that opens
+ * one (the later stages of the same run, and its failure record, keep what the gate copied), the
+ * weekly podcast, ingest, which reads the sources the owner has now (D233), and `health`, which
+ * checks the config. Not `publish` (audio.yml): that job has no database access by design (SEC-03).
+ */
+export declare function readsConfigAtStart(command: string, argv: readonly string[]): boolean;
+/**
+ * Whether a command copies the run state (state/*.json) from the store at its start (D381). The
+ * same commands as the config, except that a podcast does it in its first stage only: its later
+ * stages run in the same checkout and hold spend and timings that are not committed yet, which a
+ * second pull would write over.
+ */
+export declare function readsStateAtStart(command: string, argv: readonly string[]): boolean;

package/dist/engine/src/store/configPaths.js

@@ -0,0 +1,97 @@
+/**
+ * The config store's names and switch (D149), with no database code: the CLI, the write guard and
+ * the site's route import this, so it loads no Neon driver itself; `connectConfigStore` does, on
+ * call (the config store, D149, and the site's rate-limit counter whenever DATABASE_URL is set, D150).
+ */
+/**
+ * The files the database may hold, and the only paths a row may ever be written to. They are the
+ * owner's own config and are not in git (D296); `config/examples` holds the public defaults.
+ */
+export const CONFIG_DOCUMENT_PATHS = [
+    "config/topics.json",
+    "config/sources.user.json",
+    "config/queries.json",
+    "config/preferences.json",
+    "config/schedule.json",
+    "config/structure.json",
+    "config/writer.json",
+    "config/profiles/owner.json",
+    // Suggested sources: topic.remove drops a removed topic's, so they live beside the topics.
+    "state/source-candidates.json",
+];
+/** The URL to use when the store is switched on, or null: the URL alone never turns it on. */
+export function configStoreUrl(env) {
+    const store = env.SINGULARITY_CONFIG_STORE;
+    return env.DATABASE_URL !== undefined && env.DATABASE_URL !== "" && store === "postgres"
+        ? env.DATABASE_URL
+        : null;
+}
+/**
+ * The URL to use when the run state store is switched on, or null (D381). Its own switch, beside
+ * the config store's, so state can be turned on and off without touching the owner's config.
+ */
+export function stateStoreUrl(env) {
+    return env.DATABASE_URL !== undefined &&
+        env.DATABASE_URL !== "" &&
+        env.SINGULARITY_STATE_STORE === "postgres"
+        ? env.DATABASE_URL
+        : null;
+}
+/** The URL and its password, decoded: an error that names either must be logged without it. */
+export function databaseSecrets(databaseUrl) {
+    try {
+        return [databaseUrl, decodeURIComponent(new URL(databaseUrl).password)];
+    }
+    catch {
+        return [databaseUrl];
+    }
+}
+/** Opens the store over Neon's HTTP driver, which is loaded only on this call. */
+export async function connectConfigStore(databaseUrl) {
+    const { connectNeon } = await import("./neon.js");
+    return connectNeon(databaseUrl);
+}
+/**
+ * Whether a command reads the owner's config at its start: a whole run or the gate stage that opens
+ * one (the later stages of the same run, and its failure record, keep what the gate copied), the
+ * weekly podcast, ingest, which reads the sources the owner has now (D233), and `health`, which
+ * checks the config. Not `publish` (audio.yml): that job has no database access by design (SEC-03).
+ */
+export function readsConfigAtStart(command, argv) {
+    if (command === "podcast" || command === "ingest")
+        return true;
+    if (command === "health")
+        return true;
+    if (command !== "run")
+        return false;
+    // A run's failure record commits after the gate copied the store; it must leave the gate's note.
+    if (argv.includes("--record-failed"))
+        return false;
+    const at = argv.findIndex((arg) => arg === "--stage" || arg.startsWith("--stage="));
+    if (at === -1)
+        return true;
+    const flag = argv[at] ?? "";
+    const stage = flag.includes("=") ? flag.slice(flag.indexOf("=") + 1) : argv[at + 1];
+    return stage === "gate";
+}
+/**
+ * Whether a command copies the run state (state/*.json) from the store at its start (D381). The
+ * same commands as the config, except that a podcast does it in its first stage only: its later
+ * stages run in the same checkout and hold spend and timings that are not committed yet, which a
+ * second pull would write over.
+ */
+export function readsStateAtStart(command, argv) {
+    // The audio job reads no config (SEC-03) but pulls its cost rows through its own login.
+    if (command === "publish")
+        return true;
+    if (!readsConfigAtStart(command, argv))
+        return false;
+    if (command !== "podcast")
+        return true;
+    const at = argv.findIndex((arg) => arg === "--stage" || arg.startsWith("--stage="));
+    if (at === -1)
+        return true;
+    const flag = argv[at] ?? "";
+    const stage = flag.includes("=") ? flag.slice(flag.indexOf("=") + 1) : argv[at + 1];
+    return stage === "select";
+}

package/dist/engine/src/store/experimentFlags.d.ts

@@ -0,0 +1,28 @@
+import type { SqlClient } from "./configPaths.js";
+/**
+ * The owner's switches for the experiments in the admin app: one row per experiment in Neon, read
+ * by the engine when a run starts and written by the admin app. A row overrides the `enabled` the
+ * experiment's config file holds in git, so switching one costs no commit and no deploy; no row
+ * means the file decides. `promoted_at` marks an experiment the owner has accepted as a feature; its
+ * flag stays on until the code that holds the switch is deleted. The table is created by its first
+ * write. No driver here: see neon.ts.
+ */
+export declare const EXPERIMENT_FLAGS_SCHEMA_SQL: readonly ["create table if not exists experiment_flags (\n  id text primary key,\n  enabled boolean not null,\n  promoted_at timestamptz,\n  updated_at timestamptz not null default now()\n)"];
+export interface ExperimentFlag {
+    enabled: boolean;
+    /** When the owner promoted it, in epoch milliseconds; null while it is still an experiment. */
+    promoted_at: number | null;
+}
+export type ExperimentFlags = Record<string, ExperimentFlag>;
+/** Every stored flag by experiment id. A table that does not exist yet holds none. */
+export declare function readExperimentFlags(sql: SqlClient): Promise<ExperimentFlags>;
+/**
+ * Switches an experiment on or off; its promotion, if any, is kept. A promoted experiment stays
+ * on, so the write that would turn one off touches no row and answers false.
+ */
+export declare function setExperimentEnabled(sql: SqlClient, id: string, enabled: boolean): Promise<boolean>;
+/**
+ * Marks an experiment promoted, which also turns it on; `false` takes the mark back (Undo) and keeps
+ * its switch. Taking it back never creates a row: no row means the file still decides.
+ */
+export declare function setExperimentPromoted(sql: SqlClient, id: string, promoted: boolean): Promise<void>;

package/dist/engine/src/store/experimentFlags.js

@@ -0,0 +1,63 @@
+import { missingTable, withTable } from "./pgErrors.js";
+/**
+ * The owner's switches for the experiments in the admin app: one row per experiment in Neon, read
+ * by the engine when a run starts and written by the admin app. A row overrides the `enabled` the
+ * experiment's config file holds in git, so switching one costs no commit and no deploy; no row
+ * means the file decides. `promoted_at` marks an experiment the owner has accepted as a feature; its
+ * flag stays on until the code that holds the switch is deleted. The table is created by its first
+ * write. No driver here: see neon.ts.
+ */
+export const EXPERIMENT_FLAGS_SCHEMA_SQL = [
+    `create table if not exists experiment_flags (
+  id text primary key,
+  enabled boolean not null,
+  promoted_at timestamptz,
+  updated_at timestamptz not null default now()
+)`,
+];
+/** Every stored flag by experiment id. A table that does not exist yet holds none. */
+export async function readExperimentFlags(sql) {
+    let rows;
+    try {
+        rows = await sql.query("select id, enabled, (extract(epoch from promoted_at) * 1000)::float8 as promoted_at from experiment_flags");
+    }
+    catch (error) {
+        if (missingTable(error))
+            return {};
+        throw error;
+    }
+    const flags = {};
+    for (const row of rows) {
+        flags[String(row.id)] = {
+            enabled: row.enabled === true,
+            promoted_at: row.promoted_at === null ? null : Number(row.promoted_at),
+        };
+    }
+    return flags;
+}
+/**
+ * Switches an experiment on or off; its promotion, if any, is kept. A promoted experiment stays
+ * on, so the write that would turn one off touches no row and answers false.
+ */
+export async function setExperimentEnabled(sql, id, enabled) {
+    const rows = await withTable(sql, EXPERIMENT_FLAGS_SCHEMA_SQL, () => sql.query(`insert into experiment_flags (id, enabled) values ($1, $2)
+       on conflict (id) do update set enabled = excluded.enabled, updated_at = now()
+       where experiment_flags.promoted_at is null or excluded.enabled
+       returning id`, [id, enabled]));
+    return rows.length > 0;
+}
+/**
+ * Marks an experiment promoted, which also turns it on; `false` takes the mark back (Undo) and keeps
+ * its switch. Taking it back never creates a row: no row means the file still decides.
+ */
+export async function setExperimentPromoted(sql, id, promoted) {
+    if (!promoted) {
+        await withTable(sql, EXPERIMENT_FLAGS_SCHEMA_SQL, () => sql.query("update experiment_flags set promoted_at = null, updated_at = now() where id = $1", [id]));
+        return;
+    }
+    await withTable(sql, EXPERIMENT_FLAGS_SCHEMA_SQL, () => sql.query(`insert into experiment_flags (id, enabled, promoted_at) values ($1, true, now())
+       on conflict (id) do update set
+         enabled = true,
+         promoted_at = now(),
+         updated_at = now()`, [id]));
+}

package/dist/engine/src/store/experimentHits.d.ts

@@ -0,0 +1,25 @@
+import type { SqlClient } from "./configPaths.js";
+/**
+ * What an experiment in shadow would have added, per pass of a run, kept in Neon beside the owner's
+ * switches (store/experimentFlags.ts) so the admin app can show it. A row is one pass's count and may
+ * be 0: a shadow that found nothing is evidence too, and no row at all means it has not run yet. Every
+ * write deletes what fell out of the window. No driver here: see neon.ts.
+ */
+/** How far back the admin app reads, and how long a row is kept. */
+export declare const EXPERIMENT_HITS_WINDOW_DAYS = 7;
+export declare const EXPERIMENT_HITS_SCHEMA_SQL: readonly ["create table if not exists experiment_hits (\n  at timestamptz not null,\n  experiment_id text not null,\n  pass text not null,\n  stories integer not null\n)", "create index if not exists experiment_hits_at on experiment_hits (at)"];
+/** One pass's count for one experiment. */
+export interface ExperimentHit {
+    id: string;
+    pass: string;
+    stories: number;
+}
+/** The window's total for one experiment, and how many passes it was counted over. */
+export interface ExperimentHitTotal {
+    stories: number;
+    passes: number;
+}
+/** Stores a run's counts at `now` (epoch ms) and drops the rows past the window. Throws when the database does. */
+export declare function recordExperimentHits(sql: SqlClient, hits: readonly ExperimentHit[], now: number): Promise<void>;
+/** Each experiment's window total; an experiment with no row has not run in shadow. A table that does not exist yet holds none. */
+export declare function readExperimentHits(sql: SqlClient, now: number): Promise<Record<string, ExperimentHitTotal>>;

package/dist/engine/src/store/experimentHits.js

@@ -0,0 +1,69 @@
+import { missingTable, withTable } from "./pgErrors.js";
+/**
+ * What an experiment in shadow would have added, per pass of a run, kept in Neon beside the owner's
+ * switches (store/experimentFlags.ts) so the admin app can show it. A row is one pass's count and may
+ * be 0: a shadow that found nothing is evidence too, and no row at all means it has not run yet. Every
+ * write deletes what fell out of the window. No driver here: see neon.ts.
+ */
+/** How far back the admin app reads, and how long a row is kept. */
+export const EXPERIMENT_HITS_WINDOW_DAYS = 7;
+export const EXPERIMENT_HITS_SCHEMA_SQL = [
+    `create table if not exists experiment_hits (
+  at timestamptz not null,
+  experiment_id text not null,
+  pass text not null,
+  stories integer not null
+)`,
+    "create index if not exists experiment_hits_at on experiment_hits (at)",
+];
+const PRUNE_SQL = `delete from experiment_hits
+where at <= to_timestamp($1::float8 / 1000) - $2::int * interval '1 day'`;
+/** Stores a run's counts at `now` (epoch ms) and drops the rows past the window. Throws when the database does. */
+export async function recordExperimentHits(sql, hits, now) {
+    if (hits.length === 0) {
+        // Both lists are on: nothing to add, but what fell out of the window still goes.
+        try {
+            await sql.query(PRUNE_SQL, [now, EXPERIMENT_HITS_WINDOW_DAYS]);
+        }
+        catch (error) {
+            if (!missingTable(error))
+                throw error;
+        }
+        return;
+    }
+    await withTable(sql, EXPERIMENT_HITS_SCHEMA_SQL, () => sql.query(`with gone as (
+  delete from experiment_hits where at <= to_timestamp($1::float8 / 1000) - $5::int * interval '1 day'
+)
+insert into experiment_hits (at, experiment_id, pass, stories)
+select to_timestamp($1::float8 / 1000), hit.id, hit.pass, hit.stories
+from unnest($2::text[], $3::text[], $4::int[]) as hit(id, pass, stories)`, [
+        now,
+        hits.map((hit) => hit.id),
+        hits.map((hit) => hit.pass),
+        hits.map((hit) => hit.stories),
+        EXPERIMENT_HITS_WINDOW_DAYS,
+    ]));
+}
+/** Each experiment's window total; an experiment with no row has not run in shadow. A table that does not exist yet holds none. */
+export async function readExperimentHits(sql, now) {
+    let rows;
+    try {
+        rows = await sql.query(`select experiment_id, sum(stories)::int as stories, count(*)::int as passes
+from experiment_hits
+where at > to_timestamp($1::float8 / 1000) - $2::int * interval '1 day'
+group by experiment_id`, [now, EXPERIMENT_HITS_WINDOW_DAYS]);
+    }
+    catch (error) {
+        if (missingTable(error))
+            return {};
+        throw error;
+    }
+    const totals = {};
+    for (const row of rows) {
+        totals[String(row.experiment_id)] = {
+            stories: Number(row.stories),
+            passes: Number(row.passes),
+        };
+    }
+    return totals;
+}

package/dist/engine/src/store/neon.d.ts

@@ -0,0 +1,8 @@
+import type { SqlClient } from "./configPaths.js";
+/**
+ * A client over Neon's HTTP endpoint: one fetch per query, nothing to close. The only module that
+ * imports the driver. It is loaded on demand: behind the store switch for config (D149), and on the
+ * site whenever DATABASE_URL is set, for the shared rate-limit counter (D150). The import is static
+ * within this module so Vercel's file tracing finds the package for the functions that use it.
+ */
+export declare function connectNeon(databaseUrl: string): SqlClient;

package/dist/engine/src/store/neon.js

@@ -0,0 +1,13 @@
+import { neon } from "@neondatabase/serverless";
+/**
+ * A client over Neon's HTTP endpoint: one fetch per query, nothing to close. The only module that
+ * imports the driver. It is loaded on demand: behind the store switch for config (D149), and on the
+ * site whenever DATABASE_URL is set, for the shared rate-limit counter (D150). The import is static
+ * within this module so Vercel's file tracing finds the package for the functions that use it.
+ */
+export function connectNeon(databaseUrl) {
+    const sql = neon(databaseUrl);
+    return {
+        query: async (text, params) => (await sql.query(text, params ?? [])),
+    };
+}

package/dist/engine/src/store/pgErrors.d.ts

@@ -0,0 +1,11 @@
+import type { SqlClient } from "./configPaths.js";
+/** The table is not there yet (42P01): create it and try once more. */
+export declare const missingTable: (error: unknown) => boolean;
+/** Whether `error` is the duplicate a lost `create ... if not exists` race answers. */
+export declare const lostCreateRace: (error: unknown) => boolean;
+/**
+ * Runs `write`, and when the table is not there yet creates it (`schema`, each statement `if not
+ * exists`) and runs it once more. Two first writes at once can race to create it, and Postgres then
+ * refuses one with a duplicate; the write after says whether the table is there.
+ */
+export declare function withTable<T>(sql: SqlClient, schema: readonly string[], write: () => Promise<T>): Promise<T>;

package/dist/engine/src/store/pgErrors.js

@@ -0,0 +1,29 @@
+/** The Postgres error codes the stores that create their own table on first use act on. */
+const errorCode = (error) => error?.code;
+/** The table is not there yet (42P01): create it and try once more. */
+export const missingTable = (error) => errorCode(error) === "42P01";
+/** What Postgres answers the loser of two `create ... if not exists` racing: a duplicate. */
+const DUPLICATE = new Set(["23505", "42P07"]);
+/** Whether `error` is the duplicate a lost `create ... if not exists` race answers. */
+export const lostCreateRace = (error) => DUPLICATE.has(String(errorCode(error)));
+/**
+ * Runs `write`, and when the table is not there yet creates it (`schema`, each statement `if not
+ * exists`) and runs it once more. Two first writes at once can race to create it, and Postgres then
+ * refuses one with a duplicate; the write after says whether the table is there.
+ */
+export async function withTable(sql, schema, write) {
+    try {
+        return await write();
+    }
+    catch (error) {
+        if (!missingTable(error))
+            throw error;
+        for (const statement of schema) {
+            await sql.query(statement).catch((raced) => {
+                if (!lostCreateRace(raced))
+                    throw raced;
+            });
+        }
+        return write();
+    }
+}

package/dist/engine/src/store/runsStore.d.ts

@@ -0,0 +1,69 @@
+import type { SqlClient } from "./configPaths.js";
+/**
+ * Every generation run in Neon (D221): one row in `pipeline_runs` and one per stage in
+ * `pipeline_stages`, written by the engine when a run ends, whatever its end (published, nothing,
+ * failed) and whatever its kind (a dry run, a regeneration, a Catch up). It is the measuring layer
+ * of the store-as-truth plan: timings and cost per stage that the committed run metrics and the
+ * cost ledger only hold for runs that published, and that Health reads without opening git.
+ * Writes are best effort and idempotent (a run id is written again with its newer end); the first
+ * write creates the tables. No driver here: see neon.ts.
+ */
+export declare const RUNS_SCHEMA_SQL: readonly ["create table if not exists pipeline_runs (\n  run_id text primary key,\n  workflow text not null,\n  kind text not null,\n  mode text not null,\n  replaces text,\n  dry_run boolean not null,\n  outcome text not null,\n  podcasts text[] not null,\n  started_at timestamptz not null,\n  finished_at timestamptz not null,\n  work_ms integer not null,\n  total_ms integer not null,\n  usd double precision not null,\n  failure_stage text,\n  failure_reason text,\n  github_run_id text\n)", "create index if not exists pipeline_runs_started on pipeline_runs (started_at)", "create table if not exists pipeline_stages (\n  run_id text not null,\n  stage text not null,\n  ms integer not null,\n  usd double precision not null,\n  primary key (run_id, stage)\n)"];
+export type RunOutcome = "published" | "nothing" | "failed" | "cancelled";
+/** One stage of a run: its wall time and what its paid calls cost, priced from config/prices.json. */
+export interface StageRecord {
+    stage: string;
+    ms: number;
+    usd: number;
+}
+export interface RunRecord {
+    /** The cost ledger's run id (the plan's `created_at`, or an episode id), so the two join. */
+    run_id: string;
+    /** `run` (run.yml) or `podcast` (podcast.yml). */
+    workflow: "run" | "podcast";
+    /** The ledger's kind: daily, weekly, on_demand or catch_up. */
+    kind: string;
+    mode: string;
+    /** The digest or episode this run replaced, for a regeneration. */
+    replaces: string | null;
+    dry_run: boolean;
+    outcome: RunOutcome;
+    /** The digest or episode ids the run made (or tried to). */
+    podcasts: readonly string[];
+    started_at: string;
+    finished_at: string;
+    /** The stages' time added up: generation, without the wait for the publish time. */
+    work_ms: number;
+    /** Start to finish, the wait for the publish time included. */
+    total_ms: number;
+    usd: number;
+    failure: {
+        stage: string;
+        reason: string;
+    } | null;
+    /** GITHUB_RUN_ID, to open the run's log from a row. */
+    github_run_id: string | null;
+    stages: readonly StageRecord[];
+}
+/**
+ * Stores a finished run and its stages. Writing the same run again replaces it, so a retry or a
+ * second end (a failure record after a commit) keeps one row. Throws when the database does; the
+ * caller decides what a failure means (the engine only warns).
+ */
+export declare function recordPipelineRun(sql: SqlClient, run: RunRecord): Promise<void>;
+/** One stage's time over a window: the median and the slowest tenth of its runs, and its cost. */
+export interface StageTiming {
+    workflow: string;
+    kind: string;
+    stage: string;
+    runs: number;
+    p50_ms: number;
+    p90_ms: number;
+    avg_usd: number;
+}
+/**
+ * Each stage's median and p90 time over the last `days` before `now` (epoch ms), per workflow and
+ * kind, from runs that finished: a dry run is a test of the pipeline and a failed or cancelled run stops
+ * early, so none says how long a stage takes. No table yet reads as no runs. Throws when the database does.
+ */
+export declare function readStageTimings(sql: SqlClient, now: number, days?: number): Promise<StageTiming[]>;

package/dist/engine/src/store/runsStore.js

@@ -0,0 +1,125 @@
+import { missingTable, withTable } from "./pgErrors.js";
+/**
+ * Every generation run in Neon (D221): one row in `pipeline_runs` and one per stage in
+ * `pipeline_stages`, written by the engine when a run ends, whatever its end (published, nothing,
+ * failed) and whatever its kind (a dry run, a regeneration, a Catch up). It is the measuring layer
+ * of the store-as-truth plan: timings and cost per stage that the committed run metrics and the
+ * cost ledger only hold for runs that published, and that Health reads without opening git.
+ * Writes are best effort and idempotent (a run id is written again with its newer end); the first
+ * write creates the tables. No driver here: see neon.ts.
+ */
+export const RUNS_SCHEMA_SQL = [
+    `create table if not exists pipeline_runs (
+  run_id text primary key,
+  workflow text not null,
+  kind text not null,
+  mode text not null,
+  replaces text,
+  dry_run boolean not null,
+  outcome text not null,
+  podcasts text[] not null,
+  started_at timestamptz not null,
+  finished_at timestamptz not null,
+  work_ms integer not null,
+  total_ms integer not null,
+  usd double precision not null,
+  failure_stage text,
+  failure_reason text,
+  github_run_id text
+)`,
+    "create index if not exists pipeline_runs_started on pipeline_runs (started_at)",
+    `create table if not exists pipeline_stages (
+  run_id text not null,
+  stage text not null,
+  ms integer not null,
+  usd double precision not null,
+  primary key (run_id, stage)
+)`,
+];
+const RUN_SQL = `insert into pipeline_runs (run_id, workflow, kind, mode, replaces, dry_run, outcome,
+  podcasts, started_at, finished_at, work_ms, total_ms, usd, failure_stage, failure_reason, github_run_id)
+values ($1, $2, $3, $4, $5, $6, $7, $8::text[], $9::timestamptz, $10::timestamptz, $11, $12, $13, $14, $15, $16)
+on conflict (run_id) do update set
+  started_at = least(pipeline_runs.started_at, excluded.started_at),
+  kind = excluded.kind, mode = excluded.mode, replaces = excluded.replaces,
+  dry_run = excluded.dry_run, outcome = excluded.outcome, podcasts = excluded.podcasts,
+  finished_at = excluded.finished_at, work_ms = excluded.work_ms,
+  total_ms = greatest(excluded.total_ms, least(2147483647, extract(epoch from excluded.finished_at
+    - least(pipeline_runs.started_at, excluded.started_at)) * 1000)::int),
+  usd = excluded.usd, failure_stage = excluded.failure_stage,
+  failure_reason = excluded.failure_reason, github_run_id = excluded.github_run_id`;
+const STAGES_SQL = `insert into pipeline_stages (run_id, stage, ms, usd)
+select $1, stage.name, stage.ms, stage.usd
+from unnest($2::text[], $3::int[], $4::float8[]) as stage(name, ms, usd)
+on conflict (run_id, stage) do update set ms = excluded.ms, usd = excluded.usd`;
+/** Whole milliseconds, never negative, and inside Postgres' integer. */
+const wholeMs = (value) => Math.min(2_147_483_647, Math.max(0, Math.round(Number.isFinite(value) ? value : 0)));
+/**
+ * Stores a finished run and its stages. Writing the same run again replaces it, so a retry or a
+ * second end (a failure record after a commit) keeps one row. Throws when the database does; the
+ * caller decides what a failure means (the engine only warns).
+ */
+export async function recordPipelineRun(sql, run) {
+    await withTable(sql, RUNS_SCHEMA_SQL, async () => {
+        await sql.query(RUN_SQL, [
+            run.run_id,
+            run.workflow,
+            run.kind,
+            run.mode,
+            run.replaces,
+            run.dry_run,
+            run.outcome,
+            [...run.podcasts],
+            run.started_at,
+            run.finished_at,
+            wholeMs(run.work_ms),
+            wholeMs(run.total_ms),
+            Math.round(run.usd * 1e6) / 1e6,
+            run.failure?.stage ?? null,
+            run.failure?.reason.slice(0, 280) ?? null,
+            run.github_run_id,
+        ]);
+        if (run.stages.length > 0) {
+            await sql.query(STAGES_SQL, [
+                run.run_id,
+                run.stages.map((stage) => stage.stage),
+                run.stages.map((stage) => wholeMs(stage.ms)),
+                run.stages.map((stage) => Math.round(stage.usd * 1e6) / 1e6),
+            ]);
+        }
+    });
+}
+const TIMINGS_SQL = `select r.workflow, r.kind, s.stage, count(*)::int as runs,
+  percentile_disc(0.5) within group (order by s.ms) as p50_ms,
+  percentile_disc(0.9) within group (order by s.ms) as p90_ms,
+  avg(s.usd) as avg_usd
+from pipeline_stages s join pipeline_runs r using (run_id)
+where r.started_at > to_timestamp($1::float8 / 1000) - $2::int * interval '1 day'
+  and r.dry_run = false and r.outcome in ('published', 'nothing')
+group by r.workflow, r.kind, s.stage
+order by r.workflow, r.kind, s.stage`;
+/**
+ * Each stage's median and p90 time over the last `days` before `now` (epoch ms), per workflow and
+ * kind, from runs that finished: a dry run is a test of the pipeline and a failed or cancelled run stops
+ * early, so none says how long a stage takes. No table yet reads as no runs. Throws when the database does.
+ */
+export async function readStageTimings(sql, now, days = 14) {
+    let rows;
+    try {
+        rows = await sql.query(TIMINGS_SQL, [now, days]);
+    }
+    catch (error) {
+        if (missingTable(error))
+            return [];
+        throw error;
+    }
+    return rows.map((row) => ({
+        workflow: String(row.workflow),
+        kind: String(row.kind),
+        stage: String(row.stage),
+        runs: Number(row.runs),
+        p50_ms: Number(row.p50_ms),
+        p90_ms: Number(row.p90_ms),
+        avg_usd: Number(row.avg_usd),
+    }));
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@singularityfm/contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Singularity's store readers and admin session cookie, compiled for apps outside the main repository.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/somesh-ks/singularityfm-app.git",
+    "directory": "packages/contracts"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./session": {
+      "types": "./dist/contracts/src/session.d.ts",
+      "default": "./dist/contracts/src/session.js"
+    },
+    "./store": {
+      "types": "./dist/contracts/src/store.d.ts",
+      "default": "./dist/contracts/src/store.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@neondatabase/serverless": "1.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.