@open-everywhere/core 0.1.0

package/dist/agent/analytics/execute.d.ts

@@ -0,0 +1,20 @@
+import type { OperationalStore } from "../operational/store.js";
+import type { Domain } from "../memory/domain.js";
+import { type CompiledAnalytics } from "./compile.js";
+import { type AssumedModelPricing } from "../spend/reporting.js";
+export interface AnalyticsResult {
+    readonly mode: "aggregate" | "rows";
+    readonly dataset: string;
+    /** aggregate: one object per output group ({...dims, ...measures}); rows: one per raw row. */
+    readonly rows: readonly Record<string, unknown>[];
+    readonly rowCount: number;
+    /** true when the SQL scan or the output cap dropped rows — the answer is a prefix, not complete. */
+    readonly truncated: boolean;
+}
+export interface AnalyticsExecuteDeps {
+    readonly store: Pick<OperationalStore, "runAnalyticsQuery">;
+    readonly domains: readonly Domain[];
+    readonly assumed: AssumedModelPricing;
+}
+export declare function executeAnalytics(compiled: CompiledAnalytics, deps: AnalyticsExecuteDeps): Promise<AnalyticsResult>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/agent/analytics/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../agent/analytics/execute.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAsB,KAAK,iBAAiB,EAA6B,MAAM,cAAc,CAAC;AAErG,OAAO,EAAc,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG7E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oGAAoG;IACpG,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,CAAC;IAC5D,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;CACvC;AAoDD,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CA6DxH"}

package/dist/agent/analytics/execute.js

@@ -0,0 +1,146 @@
+// ANALYTICS EXECUTE (OPE-66) — the host-side post-processing the SQL layer can't express: fold to
+// the requested output grain (computing the `domain` dimension and the ISO `week` bucket), price
+// the derived `est_usd` measure (spend/reporting.ts's honest per-row estimate), DM-mask surfaces
+// (the 2026-07-05 anti-doxxing rule), sort, and cap. PURE over injected deps (store + domains +
+// pricing) so the differential-oracle test can drive it directly on either engine.
+//
+// Aggregate mode: the SQL query already grouped at the finest grain (real columns + a ts substr +
+// the surface behind `domain` + `model` when est_usd is asked). This RE-AGGREGATES those raw groups
+// into the caller's requested output dims — the same host-side re-grouping spend_report does — so a
+// coarser output grain (by domain, by week, dropping the est_usd model split) sums correctly.
+import { domainOfRow, isoWeekStart } from "./compile.js";
+import { DATASETS } from "./registry.js";
+import { rowCostUsd } from "../spend/reporting.js";
+import { maskSurfaceKey, surfaceDisclosureOf } from "../spend/dm-mask.js";
+/**
+ * Is this measure one the SQL layer summed (and therefore one the host-side re-fold must add up)?
+ *
+ * 🔴 READ FROM THE REGISTRY, NOT FROM A LIST HERE. This used to be a hand-maintained
+ * `NUMERIC_MEASURE` set — and it had already drifted: it named the usage dataset's eight measures
+ * and NOT the spend dataset's `usd`, so `query_analytics dataset:"spend" select:["usd"]` initialised
+ * the accumulator to 0 and then never added anything to it, reporting **$0.00 of spend** for every
+ * query, silently, since the spend dataset shipped. A closed allowlist parallel to the registry is
+ * exactly the drift the registry's own header says it exists to prevent, so the predicate now
+ * derives from the one definition: every `kind: "sql"` measure is summable, `est_usd` (the only
+ * `kind: "est_usd"` one) is priced host-side just below. A new measure is now numeric BY DEFAULT —
+ * the failure mode flips from "silently zero" to "obviously wrong if it isn't a number", which is
+ * the right direction for a money figure. (Found while adding OPE-369's `usd_measured`.)
+ */
+function isSummableMeasure(dataset, measure) {
+    return DATASETS[dataset]?.measures[measure]?.kind === "sql";
+}
+/**
+ * Mask a surface value for the room's benefit, unless the scope may see DMs unbucketed.
+ *
+ * 🔴 ONE ROAD, AND NOW NO EXCEPTION (OPE-1862, OPE-1866): EVERY dataset — `audit` included — is
+ * classified by the CONVERSATION MODE its own row carries (`spend/dm-mask.ts`, the same decision
+ * `spend_report` and `usage_report` take), so a Discord or Teams DM masks exactly as a Slack one
+ * does, and a row nothing stamped masks too. `audit` was the last holdout: it carried no mode, so
+ * the mask fell back to the SLACK DM id shape against a bare surface id, and only Slack's audit
+ * DMs were covered. `audit_entry.surface_mode` closed that, the fallback is deleted, and NO id
+ * shape is read anywhere in this file. Nothing may reintroduce one — a report that has to guess
+ * what a surface id means has already failed.
+ */
+function maskSurface(value, row, plan, dmUnmasked) {
+    if (dmUnmasked || typeof value !== "string")
+        return value;
+    const mode = row[plan.surfaceModeColumn];
+    const kind = plan.surfaceKindColumn ? row[plan.surfaceKindColumn] : undefined;
+    return maskSurfaceKey(value, surfaceDisclosureOf({
+        surfaceKey: value,
+        ...(typeof mode === "string" ? { surfaceMode: mode } : {}),
+        ...(typeof kind === "string" ? { kind } : {}),
+    }));
+}
+/** Coerce a SQL scalar to a finite number (Postgres returns bigint sums as strings). */
+function num(v) {
+    const n = typeof v === "number" ? v : Number(v);
+    return Number.isFinite(n) ? n : 0;
+}
+export async function executeAnalytics(compiled, deps) {
+    const { sql, plan } = compiled;
+    const raw = await deps.store.runAnalyticsQuery(sql);
+    if (plan.mode === "rows") {
+        const rows = raw.slice(0, plan.outputLimit).map((r) => shapeRow(r, plan));
+        return { mode: "rows", dataset: plan.dataset, rows, rowCount: rows.length, truncated: raw.length >= plan.outputLimit };
+    }
+    // aggregate — fold raw SQL groups into the requested output grain.
+    const groups = new Map();
+    for (const r of raw) {
+        const dimValues = {};
+        const keyParts = [];
+        for (const d of plan.outputDims) {
+            let value;
+            if (d.kind === "domain")
+                value = domainOfRow(r, plan, deps.domains);
+            else if (d.kind === "ts")
+                value = d.tsBucket === "week" ? isoWeekStart(String(r.ts ?? "")) : r.ts;
+            else
+                value = maskSurface(r[d.column], r, plan, plan.dmUnmasked || d.name !== "surface");
+            dimValues[d.name] = value ?? null;
+            keyParts.push(`${d.name}=${String(value)}`);
+        }
+        const key = keyParts.join("\u0000");
+        let acc = groups.get(key);
+        if (!acc) {
+            acc = { ...dimValues };
+            for (const m of plan.measures)
+                if (m !== "est_usd")
+                    acc[m] = 0;
+            groups.set(key, acc);
+        }
+        for (const m of plan.measures) {
+            if (m === "est_usd")
+                continue;
+            if (isSummableMeasure(plan.dataset, m))
+                acc[m] = num(acc[m]) + num(r[m]);
+        }
+        if (plan.wantsEstUsd) {
+            // "one-call": `r` is a single dataset row (one model call), priced on its own and then summed
+            // into the group below — never the group's totals priced once. That order is what lets a
+            // long-context tier apply honestly: it fires on the calls that really were long (OPE-2055).
+            const cost = rowCostUsd({ inputTokens: num(r.input_tokens), outputTokens: num(r.output_tokens), cacheReadTokens: num(r.cache_read_tokens), model: typeof r.model === "string" ? r.model : undefined }, deps.assumed, "one-call");
+            if (cost !== undefined)
+                acc.est_usd = num(acc.est_usd) + cost;
+        }
+    }
+    let out = [...groups.values()];
+    // Sort: the requested orderBy (a measure or an output dim), else the first numeric measure desc.
+    const sortKey = plan.orderBy?.by ?? plan.measures.find((m) => m !== "est_usd" || plan.wantsEstUsd) ?? plan.measures[0];
+    const dir = plan.orderBy?.dir === "asc" ? 1 : -1;
+    if (sortKey) {
+        out.sort((a, b) => {
+            const av = a[sortKey];
+            const bv = b[sortKey];
+            if (typeof av === "number" && typeof bv === "number")
+                return (av - bv) * dir;
+            return String(av ?? "").localeCompare(String(bv ?? "")) * dir;
+        });
+    }
+    const truncated = raw.length >= sql.limit || out.length > plan.outputLimit;
+    out = out.slice(0, plan.outputLimit);
+    return { mode: "aggregate", dataset: plan.dataset, rows: out, rowCount: out.length, truncated };
+}
+/** Shape one raw rows-mode SQL row: keep the dataset's row columns, mask a DM surface, parse the
+ *  audit `detail` JSON (present only when org-admin standing selected it in compile). */
+function shapeRow(r, plan) {
+    const out = {};
+    for (const c of plan.rowColumns) {
+        let v = r[c];
+        if (v === null || v === undefined)
+            continue;
+        if (c === "surface_key" || c === "surface")
+            v = maskSurface(v, r, plan, plan.dmUnmasked);
+        out[c] = v;
+    }
+    if ("detail" in r && r.detail != null) {
+        try {
+            out.detail = typeof r.detail === "string" ? JSON.parse(r.detail) : r.detail;
+        }
+        catch {
+            out.detail = r.detail;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=execute.js.map

package/dist/agent/analytics/execute.js.map

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

package/dist/agent/analytics/registry.d.ts

@@ -0,0 +1,89 @@
+/** The three v1 datasets (data inventory §, all already stored — no new tables). */
+export type DatasetName = "audit" | "usage" | "spend";
+/** ts bucket granularity for the time dimension. hour/day/month compile to substr() in SQL
+ *  (engine-identical); week groups by DAY in SQL and folds to the ISO-week start host-side. */
+export type TsBucket = "hour" | "day" | "week" | "month";
+/** How one named dimension maps onto the physical schema. */
+export type DimensionSpec = 
+/** A plain physical column — usable directly in SELECT / GROUP BY / a filter. */
+{
+    readonly kind: "column";
+    readonly column: string;
+}
+/** The `ts` time dimension — bucketed by substr() (host passes the bucket at compile). */
+ | {
+    readonly kind: "ts";
+    readonly column: string;
+}
+/** The computed `domain` — folded host-side from the surface column(s); never a SQL column. */
+ | {
+    readonly kind: "domain";
+};
+/** How one named measure aggregates. `sql` fragments are engine-identical; `est_usd` is derived
+ *  host-side (spend/reporting.ts rowCostUsd) from token sums + the per-group model. */
+export type MeasureSpec = {
+    readonly kind: "sql";
+    readonly expr: string;
+} | {
+    readonly kind: "est_usd";
+};
+export interface DatasetSpec {
+    /** The physical table (never a model-supplied string). */
+    readonly table: "audit_entry" | "usage_events" | "spend_ledger";
+    readonly dims: Readonly<Record<string, DimensionSpec>>;
+    readonly measures: Readonly<Record<string, MeasureSpec>>;
+    /** Raw columns returned in rows mode (audit `detail` is added CONDITIONALLY by the compiler —
+     *  org-admin only — never listed here so it can't leak at a lower standing). */
+    readonly rowColumns: readonly string[];
+    /** The full-surface-key column for domain scoping/folding (usage/spend). Null for audit,
+     *  whose surface identity is the (platform, workspace, surface) triple, not one column. */
+    readonly surfaceColumn: string | null;
+    /**
+     * The column carrying each row's CONVERSATION MODE (OPE-1862) — what the DM mask reads before it
+     * publishes a surface value. The compiler forces it into the SQL grouping whenever `surface` is
+     * an output dimension, so every group arrives classifiable.
+     *
+     * 🔴 REQUIRED ON EVERY DATASET, AND THAT IS THE SECURITY PROPERTY (OPE-1866). While `audit` was
+     * allowed to name none, the mask fell back to a SLACK id shape for it — so Slack audit DMs
+     * masked and Discord and Teams ones were published by name. `audit_entry` now carries
+     * `surface_mode` like the other two tables, and the fallback is gone: NO id shape is read in the
+     * report layer. (A platform's own identity mapper may still read one — `slack-identity.ts`
+     * falls back to the `D` channel-id prefix — but that is upstream of the stamp, in the layer
+     * entitled to know what a Slack id looks like.) A NEW dataset must name its mode column here; a
+     * dataset that cannot classify its surfaces has no business publishing them, and the type is
+     * what says so.
+     */
+    readonly surfaceModeColumn: string;
+    /**
+     * The column carrying each row's TURN-ORIGIN tag, where the dataset has one (`usage` does). The
+     * mask reads it only as the legacy fallback for rows written before `surface_mode` existed, and
+     * only for its two conversation-bearing values — see spend/dm-mask.ts. It is named here, and
+     * forced into the grouping beside the mode, so one row cannot classify one way in `usage_report`
+     * and another way in `query_analytics`.
+     */
+    readonly surfaceKindColumn: string | null;
+    /** For audit only: the columns whose `p/w/s` join reconstructs a channel key (domain scope/fold). */
+    readonly surfaceParts: readonly string[] | null;
+    /** The acting-principal column (self scope + the `principal` dimension). Required, and every
+     *  registered dataset sets `principal_id` — `analytics-compile-test.ts` holds that census, so a
+     *  dataset without a per-person column reds there rather than compiling `"" = ?`. */
+    readonly principalColumn: string;
+    /**
+     * The PLATFORM column, when the dataset has one of its own (audit does). Null means the
+     * platform is only recoverable as the first segment of {@link surfaceColumn} — the compiler
+     * then scopes with a `surface_key LIKE '<platform>/%'` prefix instead of an equality.
+     *
+     * Why any dataset needs it (OPE-309 phase 0b): `principal_id` is a BARE vendor id in every one
+     * of these tables, so `principal_id = ?` alone matches that spelling on EVERY platform at once.
+     * A self-scope read is namespaced by pairing the principal conjunct with this one.
+     */
+    readonly platformColumn: string | null;
+    /** Default rows-mode ordering column (newest-first). */
+    readonly rowOrderColumn: string;
+}
+export declare const DATASETS: Readonly<Record<DatasetName, DatasetSpec>>;
+export declare const DATASET_NAMES: DatasetName[];
+/** The human-readable schema card the tool description + a `describe` mode serve — generated
+ *  from the registry so it can NEVER drift from what the compiler enforces. */
+export declare function schemaCard(): string;
+//# sourceMappingURL=registry.d.ts.map

package/dist/agent/analytics/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../agent/analytics/registry.ts"],"names":[],"mappings":"AAsBA,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAEtD;+FAC+F;AAC/F,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzD,6DAA6D;AAC7D,MAAM,MAAM,aAAa;AACvB,iFAAiF;AAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACtD,0FAA0F;GACxF;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAClD,+FAA+F;GAC7F;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEhC;uFACuF;AACvF,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEjC,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,GAAG,cAAc,CAAC;IAChE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IACzD;oFACgF;IAChF,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;+FAC2F;IAC3F,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,qGAAqG;IACrG,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAChD;;yFAEqF;IACrF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAiLD,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,CAAgD,CAAC;AAIjH,eAAO,MAAM,aAAa,EAA4B,WAAW,EAAE,CAAC;AAYpE;+EAC+E;AAC/E,wBAAgB,UAAU,IAAI,MAAM,CASnC"}

package/dist/agent/analytics/registry.js

@@ -0,0 +1,216 @@
+// The ANALYTICS SEMANTIC REGISTRY (OPE-66, nl-analytics-query-plan.md option (b)) — the
+// single, CI-pinned vocabulary the `query_analytics` grammar and the host-side compiler both
+// read, so a docs card and the enforcement can never drift (both are generated from HERE).
+//
+// This is the "constrained semantic layer": the model never writes SQL. It names a dataset,
+// dimensions, measures and filter dims from CLOSED enums; the compiler (analytics/compile.ts)
+// maps each name through the fixed fragment tables below to a parameterized query, injecting
+// the scope predicate host-side (analytics/compile.ts + access/analytics-scope.ts). A name the
+// registry doesn't list fails zod validation before any code runs — no model string ever
+// reaches SQL as an identifier.
+//
+// DUAL-ENGINE: every SQL fragment here is engine-IDENTICAL (SUM/COUNT(*)/COUNT(DISTINCT …),
+// substr(ts,…) — all standard, identical on node:sqlite and Postgres), so ONE registry
+// compiles for both backends (the store seam renders only the placeholder style). The
+// differential-oracle test (scripts/analytics-query-test.ts) pins that both engines return
+// the same rows for the same compiled query.
+//
+// COMPUTED, NOT COLUMNS: two things the SQL layer can't express are computed HOST-SIDE after
+// the query — `domain` (a config-as-code channel→domain fold, reusing memory/domain.ts) and
+// `est_usd` (spend/reporting.ts's honest per-row pricing). The registry marks them so the
+// compiler knows to add the underlying columns to the SQL grouping and fold in the tool.
+// --- the datasets --------------------------------------------------------------------------
+const AUDIT = {
+    table: "audit_entry",
+    dims: {
+        ts: { kind: "ts", column: "ts" },
+        platform: { kind: "column", column: "platform" },
+        workspace: { kind: "column", column: "workspace" },
+        surface: { kind: "column", column: "surface" },
+        action: { kind: "column", column: "action" },
+        principal: { kind: "column", column: "principal_id" },
+        domain: { kind: "domain" },
+    },
+    measures: {
+        rows: { kind: "sql", expr: "COUNT(*)" },
+    },
+    // OPE-1866: rows mode masks `surface` too, so the mode must be SELECTed beside it.
+    rowColumns: ["ts", "platform", "workspace", "surface", "surface_mode", "principal_id", "action"],
+    surfaceColumn: null,
+    surfaceModeColumn: "surface_mode",
+    surfaceKindColumn: null,
+    surfaceParts: ["platform", "workspace", "surface"],
+    principalColumn: "principal_id",
+    platformColumn: "platform",
+    rowOrderColumn: "ts",
+};
+const USAGE = {
+    table: "usage_events",
+    dims: {
+        ts: { kind: "ts", column: "ts" },
+        surface: { kind: "column", column: "surface_key" },
+        principal: { kind: "column", column: "principal_id" },
+        kind: { kind: "column", column: "kind" },
+        model: { kind: "column", column: "model" },
+        session: { kind: "column", column: "session_id" },
+        // OPE-145: WHICH routine, not just THAT a routine ran — the dimension per-routine cost
+        // ("what is my 03:00 digest costing me?") groups by. Null on every non-routine row.
+        routine: { kind: "column", column: "routine_id" },
+        // OPE-369. `depth` is a BAND, not a hop count: 0 = a root turn, 1 = a directly-delegated child,
+        // 2 = two or more hops (eve publishes the root and the immediate parent, never what is between
+        // — see operational/store.ts MAX_OBSERVABLE_DELEGATION_DEPTH). `root_session` is the top of the
+        // delegation chain and is set on EVERY row, which is what makes "one conversation tree's total
+        // cost, grandchildren included" a single grouped read — a grandchild's row files under its
+        // immediate parent, so grouping by `session` alone never reaches it.
+        depth: { kind: "column", column: "delegation_depth" },
+        root_session: { kind: "column", column: "root_session_id" },
+        // Which cost answer the row carried: "measured" (the gateway billed it) or "derived".
+        cost_source: { kind: "column", column: "cost_source" },
+        domain: { kind: "domain" },
+    },
+    measures: {
+        events: { kind: "sql", expr: "COUNT(*)" },
+        input_tokens: { kind: "sql", expr: "SUM(input_tokens)" },
+        output_tokens: { kind: "sql", expr: "SUM(output_tokens)" },
+        cache_read_tokens: { kind: "sql", expr: "SUM(cache_read_tokens)" },
+        cache_write_tokens: { kind: "sql", expr: "SUM(cache_write_tokens)" },
+        sessions: { kind: "sql", expr: "COUNT(DISTINCT session_id)" },
+        est_usd: { kind: "est_usd" },
+        // OPE-369: the GATEWAY's own billed $ for the rows that carried one — a plain SQL sum, NOT the
+        // host-priced `est_usd` kind, because it is already money and re-deriving it would be a second
+        // opinion about a measurement. COALESCE because the column is NULL on every pre-migration and
+        // unmeasured row, and a NULL must read as "nothing measured", never poison the sum.
+        measured_usd: { kind: "sql", expr: "SUM(COALESCE(usd_micros_measured, 0)) / 1000000.0" },
+        // OPE-1611 — the attribution dimensions AND their COVERAGE, because a token sum alone is the
+        // exact misreading this ticket retires. `SUM(cache_read_tokens)` reading 0 does not mean "no
+        // caching": the source may have published nothing, or published a zero over a call that was
+        // discounted. The two counts below are what let a query tell those apart.
+        // 🔴 `reasoning_tokens` is NULL for "unreported" here (unlike the ledger's NOT NULL column), so
+        // the sum COALESCEs and the coverage count is COUNT(col), which counts non-NULL only.
+        reasoning_tokens: { kind: "sql", expr: "SUM(COALESCE(reasoning_tokens, 0))" },
+        reasoning_reported_calls: { kind: "sql", expr: "COUNT(reasoning_tokens)" },
+        // 🔴 CASE, not `= 1` and not FILTER. The column is a real `boolean` on Postgres and 1/0 on
+        // sqlite: `= 1` is a type error on pg, and the sqlite engine avoids FILTER throughout.
+        cache_reported_calls: { kind: "sql", expr: "SUM(CASE WHEN cache_tokens_reported THEN 1 ELSE 0 END)" },
+    },
+    rowColumns: [
+        "ts",
+        "surface_key",
+        "principal_id",
+        "kind",
+        // OPE-1862: rows mode masks `surface_key` too, so the mode must be SELECTed beside it.
+        "surface_mode",
+        "routine_id",
+        "model",
+        "session_id",
+        "input_tokens",
+        "output_tokens",
+        "cache_read_tokens",
+        "cache_write_tokens",
+        "cache_tokens_reported",
+        "reasoning_tokens",
+        "usd_micros_measured",
+        "cost_source",
+        "delegation_depth",
+        "root_session_id",
+    ],
+    surfaceColumn: "surface_key",
+    surfaceModeColumn: "surface_mode",
+    surfaceKindColumn: "kind",
+    surfaceParts: null,
+    principalColumn: "principal_id",
+    platformColumn: null,
+    rowOrderColumn: "ts",
+};
+const SPEND = {
+    table: "spend_ledger",
+    dims: {
+        period: { kind: "column", column: "period" },
+        surface: { kind: "column", column: "surface_key" },
+        // OPE-265: the redesigned ledger is dimensioned — '' (not NULL) means unattributed on
+        // all three, so grouping never splits a NULL bucket from an empty one.
+        principal: { kind: "column", column: "principal_id" },
+        routine: { kind: "column", column: "routine_id" },
+        model: { kind: "column", column: "model" },
+        // OPE-369: part of the ledger's PRIMARY KEY, so a row is homogeneous — grouping by it splits
+        // the calls the gateway billed from the ones only our rate table costed, which is exactly the
+        // split the `usd` vs `measured_usd` comparison has to be read against.
+        cost_source: { kind: "column", column: "cost_source" },
+        domain: { kind: "domain" },
+    },
+    measures: {
+        input_tokens: { kind: "sql", expr: "SUM(input_tokens)" },
+        output_tokens: { kind: "sql", expr: "SUM(output_tokens)" },
+        cache_read_tokens: { kind: "sql", expr: "SUM(cache_read_tokens)" },
+        cache_write_tokens: { kind: "sql", expr: "SUM(cache_write_tokens)" },
+        calls: { kind: "sql", expr: "SUM(calls)" },
+        // The ledger's own write-time-priced $, as dollars — a plain SQL sum (engine-identical
+        // division), NOT the host-priced `est_usd` kind: usd_micros is already priced (incl.
+        // sandbox runtime, OPE-266), so re-pricing from token sums would be a second opinion.
+        // 🔴 THIS is the figure the caps enforce, measured rows included — see usd_measured below.
+        usd: { kind: "sql", expr: "SUM(usd_micros) / 1000000.0" },
+        // OPE-369: what the GATEWAY billed, over the rows it measured (0 on 'derived' rows). Pair it
+        // with `usd` FILTERED to cost_source='measured' for an apples-to-apples drift read; against
+        // the unfiltered `usd` it under-reads, because that also carries every unmeasured call.
+        usd_measured: { kind: "sql", expr: "SUM(usd_micros_measured) / 1000000.0" },
+        // OPE-1611: the reasoning dimension, summed like the other token columns. NOT COALESCEd,
+        // because the ledger's column is NOT NULL DEFAULT 0 on both engines — unlike usage_events,
+        // where "unreported" is a real NULL and has to be distinguished from a reported zero.
+        // 🔴 It is an ATTRIBUTION count and never money: `billableTokens` is input+output only, so
+        // nothing here feeds `usd` or a cap.
+        reasoning_tokens: { kind: "sql", expr: "SUM(reasoning_tokens)" },
+    },
+    rowColumns: [
+        "period",
+        "surface_key",
+        "principal_id",
+        // OPE-1862: rows mode masks `surface_key` too, so the mode must be SELECTed beside it.
+        "surface_mode",
+        "routine_id",
+        "model",
+        "cost_source",
+        "input_tokens",
+        "output_tokens",
+        "cache_read_tokens",
+        "cache_write_tokens",
+        "reasoning_tokens",
+        "usd_micros",
+        "usd_micros_measured",
+        "calls",
+    ],
+    surfaceColumn: "surface_key",
+    surfaceModeColumn: "surface_mode",
+    // The ledger has no turn-origin tag at all — it never had one, which is why its DM rows were the
+    // worst of the leak (OPE-1862). `surface_mode` is the whole answer here.
+    surfaceKindColumn: null,
+    surfaceParts: null,
+    // OPE-265: the ledger now carries the acting principal, so the `principal` dimension and
+    // the self grain are available (resolveAnalyticsScope/compile treat it like usage's).
+    principalColumn: "principal_id",
+    platformColumn: null,
+    rowOrderColumn: "period",
+};
+export const DATASETS = { audit: AUDIT, usage: USAGE, spend: SPEND };
+// --- vocab accessors (the zod enums + the schema card generate from these) ------------------
+export const DATASET_NAMES = Object.keys(DATASETS);
+/** Dimension names for a dataset (the zod enum + card). */
+function dimNames(dataset) {
+    return Object.keys(DATASETS[dataset].dims);
+}
+/** Measure names for a dataset (the zod enum + card). */
+function measureNames(dataset) {
+    return Object.keys(DATASETS[dataset].measures);
+}
+/** The human-readable schema card the tool description + a `describe` mode serve — generated
+ *  from the registry so it can NEVER drift from what the compiler enforces. */
+export function schemaCard() {
+    const lines = [];
+    for (const name of DATASET_NAMES) {
+        const spec = DATASETS[name];
+        lines.push(`dataset ${name} (table ${spec.table})`);
+        lines.push(`  dims:     ${dimNames(name).join(", ")}`);
+        lines.push(`  measures: ${measureNames(name).join(", ")}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=registry.js.map

package/dist/agent/analytics/registry.js.map

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

package/dist/agent/approvals/access-request.d.ts

@@ -0,0 +1,53 @@
+import { type AccessRequestsConfig } from "../access/config.js";
+import { type AccessDelta } from "../access/delta.js";
+import { GitHubContents, type CommitId } from "../scm/contents.js";
+import { createBranch, getBranchSha } from "../scm/refs.js";
+import { createOrUpdatePullRequest } from "../scm/pr.js";
+/** `delta` is the whole story: validated at propose time, frozen, and never re-derived. `requestId` names the PR branch, so a re-request of the same pending updates that branch and PR instead of scattering new ones. */
+export interface AccessRequestArgs {
+    readonly org: string;
+    readonly scopeKey: string;
+    readonly requestId: string;
+    readonly delta: AccessDelta;
+    readonly requestedBy: string;
+    readonly reason?: string;
+    readonly channelId: string;
+    readonly threadTs: string | null;
+    /** Best-effort permalink to the asking thread, frozen at propose. Absent is normal, and the body then names the channel and the scope instead. */
+    readonly permalink?: string;
+    /** Display-only: the config repo the card promises the PR against. */
+    readonly configRepo: string;
+    /** Code-rendered sentence naming the UNIVERSE a domain, personal or group grant lands in — every admitted room, whose DM, or how many members' DMs and whether that set can grow by itself. Frozen at propose, so the card the member tapped and the PR the admin merges say the same thing about reach even if the registry moves. */
+    readonly universe?: string;
+    /** Code-rendered sentences saying how far this widening reaches inside the requesting room's memory domain, and what the deployment cannot see. Frozen at propose; absent when the propose path could not compute it at all, and the card then reads as it did before, never as a false all-clear. */
+    readonly exposure?: readonly string[];
+}
+/** Injectable seams for execute() — every network edge and the config lookup, so the whole path is offline-testable with the live defaults used byte-for-byte in production. */
+export interface AccessRequestExecuteDeps {
+    readonly config?: AccessRequestsConfig;
+    readonly contents?: Pick<GitHubContents, "getFile" | "putFile">;
+    readonly getBranchSha?: typeof getBranchSha;
+    readonly createBranch?: typeof createBranch;
+    readonly createPr?: typeof createOrUpdatePullRequest;
+    readonly post?: (method: string, body: string) => Promise<Record<string, unknown> | undefined>;
+    /** The REQUESTING thread's note, dispatched on the asking surface's own platform. Separate from `post` because the two notes go to two different places on two possibly different platforms. */
+    readonly postThreadNote?: (platform: string, target: {
+        channelId: string;
+        text: string;
+        threadTs?: string | null;
+    }) => Promise<string | undefined>;
+    readonly resolveToken?: (repo: string) => Promise<string>;
+    readonly committer?: CommitId;
+}
+/** AccessRequestsConfig with the two fail-closed fields PROVEN present — what
+ *  requireAccessRequestsConfig narrows to, so the execute path never re-checks. */
+export type EnabledAccessRequestsConfig = AccessRequestsConfig & {
+    readonly adminChannel: string;
+    readonly configRepo: string;
+};
+/** The access-requests config, fail-closed: absent loader, missing admin channel, or
+ *  missing config repo all throw — a half-configured flow must refuse loudly, not open
+ *  PRs nobody will hear about. */
+export declare function requireAccessRequestsConfig(override?: AccessRequestsConfig): EnabledAccessRequestsConfig;
+export declare function executeAccessRequest(args: AccessRequestArgs, decidedBy: string, deps?: AccessRequestExecuteDeps): Promise<string>;
+//# sourceMappingURL=access-request.d.ts.map

package/dist/agent/approvals/access-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-request.d.ts","sourceRoot":"","sources":["../../../agent/approvals/access-request.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAA8B,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGlF,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAYzD,2NAA2N;AAC3N,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,kJAAkJ;IAClJ,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uUAAuU;IACvU,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sSAAsS;IACtS,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,gLAAgL;AAChL,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;IAC5C,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,yBAAyB,CAAC;IACrD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/F,gMAAgM;IAChM,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACnJ,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC;CAC/B;AAED;mFACmF;AACnF,MAAM,MAAM,2BAA2B,GAAG,oBAAoB,GAAG;IAC/D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF;;kCAEkC;AAClC,wBAAgB,2BAA2B,CAAC,QAAQ,CAAC,EAAE,oBAAoB,GAAG,2BAA2B,CASxG;AA0BD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,wBAA6B,GAAG,OAAO,CAAC,MAAM,CAAC,CAoI3I"}