@sudobility/sider_lib 0.0.2

package/dist/composite.d.ts

@@ -0,0 +1,16 @@
+import type { ToolSpec } from "@sudobility/sider_types";
+export interface RunStepResult {
+    ok: boolean;
+    status?: number;
+    body?: unknown;
+    error?: string;
+    gate?: string;
+}
+/** Runs ONE tool by id with resolved args. The caller applies gates + fetch. */
+export type StepRunner = (toolId: string, args: Record<string, unknown>) => Promise<RunStepResult>;
+/** Reference, in a priorOutput binding, to the current element during a fan-out. */
+declare const ITEM_REF = "$item";
+export declare function executeComposite(tool: ToolSpec, ctx: {
+    args?: Record<string, unknown>;
+}, run: StepRunner): Promise<RunStepResult>;
+export { ITEM_REF };

package/dist/composite.js

@@ -0,0 +1,59 @@
+// Composite/fan-out tool execution. A ToolSpec whose recipe has `compose` steps
+// chains or fans out over other tools — e.g. "list sections → for each, fetch
+// seats". This is PURE orchestration: the caller injects `run` (which applies
+// the three gates + issues the actual request for one tool), and this threads
+// prior outputs, resolves bindings, and parallelizes fan-out.
+import { getByPath } from "./recipe";
+/** Reference, in a priorOutput binding, to the current element during a fan-out. */
+const ITEM_REF = "$item";
+export async function executeComposite(tool, ctx, run) {
+    const steps = tool.recipe.compose ?? [];
+    if (steps.length === 0)
+        return run(tool.id, ctx.args ?? {});
+    const priorOutputs = {};
+    let last;
+    for (const step of steps) {
+        if (step.forEachJsonPath) {
+            // Fan out: run the step once per element of the referenced array (parallel).
+            const arr = getByPath(priorOutputs, step.forEachJsonPath);
+            const items = Array.isArray(arr) ? arr : [];
+            const results = await Promise.all(items.map((item) => run(step.toolId, resolveArgs(step.argBindings, ctx, priorOutputs, item))));
+            priorOutputs[step.ref] = results.map((r) => r.body);
+            last = { ok: results.every((r) => r.ok), body: results.map((r) => r.body) };
+            if (!last.ok)
+                break; // don't thread a failed fan-out into later steps
+        }
+        else {
+            const r = await run(step.toolId, resolveArgs(step.argBindings, ctx, priorOutputs, undefined));
+            priorOutputs[step.ref] = r.body;
+            last = r;
+            if (!r.ok)
+                break; // stop the chain on the first failure
+        }
+    }
+    return last ?? { ok: false, error: "empty compose" };
+}
+function resolveArgs(bindings, ctx, priorOutputs, item) {
+    const out = {};
+    for (const [key, b] of Object.entries(bindings)) {
+        switch (b.kind) {
+            case "literal":
+                out[key] = b.value;
+                break;
+            case "arg":
+                out[key] = ctx.args?.[b.argName];
+                break;
+            case "priorOutput":
+                out[key] =
+                    b.stepRef === ITEM_REF ? getByPath(item, b.jsonPath) : getByPath(priorOutputs[b.stepRef], b.jsonPath);
+                break;
+            case "secret":
+                // Secrets belong to the sub-tool's own recipe (resolved at egress by
+                // the runner), never to compose-level args.
+                break;
+        }
+    }
+    return out;
+}
+// keep the fan-out sentinel discoverable to callers/authors of recipes.
+export { ITEM_REF };

package/dist/execute.d.ts

@@ -0,0 +1,27 @@
+import type { CompiledRequest, SecretSlot } from "@sudobility/sider_types";
+import type { ToolSpec } from "@sudobility/sider_types";
+import type { CompileContext } from "./recipe";
+import type { GateContext } from "./gates";
+export interface ResolvedRequest {
+    method: CompiledRequest["method"];
+    url: string;
+    headers: Record<string, string>;
+    body?: unknown;
+    credentials: "include";
+}
+/** Resolve a slot's current value from the caller's live session (never stored). */
+export type SecretResolver = (slotId: string) => string | undefined;
+export declare function detokenizeRequest(req: CompiledRequest, resolve: SecretResolver, slotsById: Record<string, SecretSlot>): ResolvedRequest;
+export type PrepareResult = {
+    ok: true;
+    request: ResolvedRequest;
+} | {
+    ok: false;
+    gate: "compile" | "same_origin" | "injection_location" | "safety";
+    reason: string;
+};
+/**
+ * compile → gate → detokenize, in one call. The browser executor should issue
+ * `result.request` only when `result.ok`.
+ */
+export declare function prepareRequest(tool: ToolSpec, compileCtx: CompileContext, gateCtx: GateContext, resolve: SecretResolver): PrepareResult;

package/dist/execute.js

@@ -0,0 +1,58 @@
+// Detokenization (the last mile, browser-side) + the single prepareRequest
+// entry point. Detokenization runs ONLY after the gates pass; it reads each
+// secret's current value from the caller's resolver (backed by the browser
+// TokenMap) and substitutes it into the sentinel positions the gates already
+// proved are confined to the declared location.
+import { compileRecipe, secretSentinel } from "./recipe";
+import { evaluateGates } from "./gates";
+export function detokenizeRequest(req, resolve, slotsById) {
+    let url = req.url;
+    const headers = { ...req.headers };
+    let bodyStr = req.body !== undefined ? JSON.stringify(req.body) : undefined;
+    for (const slotId of req.referencedSlotIds) {
+        const slot = slotsById[slotId];
+        // auto_cookie secrets are attached by the browser; never substituted.
+        if (slot && (slot.role === "auto_cookie" || slot.injectionLocation.at === "cookie"))
+            continue;
+        const value = resolve(slotId);
+        if (value === undefined)
+            throw new Error(`Unresolved secret slot at egress: ${slotId}`);
+        const sen = secretSentinel(slotId);
+        url = url.split(sen).join(value);
+        for (const k of Object.keys(headers))
+            headers[k] = headers[k].split(sen).join(value);
+        if (bodyStr !== undefined) {
+            const innerEscaped = JSON.stringify(value).slice(1, -1); // JSON-string-safe
+            bodyStr = bodyStr.split(sen).join(innerEscaped);
+        }
+    }
+    return {
+        method: req.method,
+        url,
+        headers,
+        body: bodyStr !== undefined ? JSON.parse(bodyStr) : undefined,
+        credentials: "include",
+    };
+}
+/**
+ * compile → gate → detokenize, in one call. The browser executor should issue
+ * `result.request` only when `result.ok`.
+ */
+export function prepareRequest(tool, compileCtx, gateCtx, resolve) {
+    let compiled;
+    try {
+        compiled = compileRecipe(tool, compileCtx);
+    }
+    catch (e) {
+        return { ok: false, gate: "compile", reason: e.message };
+    }
+    const gate = evaluateGates(compiled, gateCtx);
+    if (!gate.ok)
+        return gate;
+    try {
+        return { ok: true, request: detokenizeRequest(compiled, resolve, gateCtx.slotsById) };
+    }
+    catch (e) {
+        return { ok: false, gate: "injection_location", reason: e.message };
+    }
+}

package/dist/gates.d.ts

@@ -0,0 +1,12 @@
+import type { CompiledRequest, GateOutcome, SecretSlot } from "@sudobility/sider_types";
+export interface GateContext {
+    /** The site's origin. The request destination MUST equal this. */
+    siteOrigin: string;
+    /** Every secret slot the request may reference, keyed by slot id (placeholder). */
+    slotsById: Record<string, SecretSlot>;
+    /** True once the user has confirmed a write/financial step. */
+    confirmed?: boolean;
+    /** Site policy: whether mutations are permitted here at all. */
+    allowMutations?: boolean;
+}
+export declare function evaluateGates(req: CompiledRequest, ctx: GateContext): GateOutcome;

package/dist/gates.js

@@ -0,0 +1,106 @@
+// The three egress gates. This is the security core: tokenization is only safe
+// BECAUSE a secret cannot leave for the wrong destination (Gate A), cannot be
+// relocated out of its declared slot (Gate B), and cannot ride a mutation
+// without confirmation (Gate C). Run on a CompiledRequest whose secrets are
+// still sentinels — never on values.
+import { getByPath, secretSentinel } from "./recipe";
+export function evaluateGates(req, ctx) {
+    // --- Gate A: same-origin destination ------------------------------------
+    let originHost;
+    try {
+        originHost = new URL(req.url).origin;
+    }
+    catch {
+        return { ok: false, gate: "same_origin", reason: `invalid url: ${req.url}` };
+    }
+    if (originHost !== ctx.siteOrigin) {
+        return {
+            ok: false,
+            gate: "same_origin",
+            reason: `destination ${originHost} != site ${ctx.siteOrigin}`,
+        };
+    }
+    for (const slotId of req.referencedSlotIds) {
+        const slot = ctx.slotsById[slotId];
+        if (!slot) {
+            return { ok: false, gate: "injection_location", reason: `unknown secret slot ${slotId}` };
+        }
+        if (slot.allowedDestination !== originHost) {
+            return {
+                ok: false,
+                gate: "same_origin",
+                reason: `slot ${slotId} allows ${slot.allowedDestination}, not ${originHost}`,
+            };
+        }
+        if (slot.role === "auto_cookie" || slot.injectionLocation.at === "cookie") {
+            return {
+                ok: false,
+                gate: "injection_location",
+                reason: `slot ${slotId} is cookie-borne (auto-attached); it must not be injected`,
+            };
+        }
+        // --- Gate B: sentinel appears ONLY in its declared location ------------
+        const b = injectionCheck(req, slot);
+        if (!b.ok)
+            return b;
+    }
+    // --- Gate C: mutations require confirmation -----------------------------
+    // Bind to the HTTP method, not just the server-declared (and therefore
+    // untrusted) safetyClass — a recipe labeled "read" with a POST/PUT/PATCH/
+    // DELETE still mutates and must not run unconfirmed.
+    const idempotent = req.method === "GET" || req.method === "HEAD" || req.method === "OPTIONS";
+    if (req.safetyClass !== "read" || !idempotent) {
+        if (ctx.allowMutations === false) {
+            return { ok: false, gate: "safety", reason: `mutations disabled for ${ctx.siteOrigin}` };
+        }
+        if (!ctx.confirmed) {
+            return { ok: false, gate: "safety", reason: `mutating request requires confirmation` };
+        }
+    }
+    return { ok: true };
+}
+function injectionCheck(req, slot) {
+    const sen = secretSentinel(slot.id);
+    const bodyStr = req.body !== undefined ? JSON.stringify(req.body) : "";
+    const total = count(req.url, sen) +
+        Object.values(req.headers).reduce((n, v) => n + count(v, sen), 0) +
+        count(bodyStr, sen);
+    let allowed = 0;
+    const loc = slot.injectionLocation;
+    if (loc.at === "header") {
+        allowed = count(req.headers[loc.name] ?? "", sen);
+    }
+    else if (loc.at === "query") {
+        let qv = "";
+        try {
+            qv = new URL(req.url).searchParams.get(loc.param) ?? "";
+        }
+        catch {
+            /* invalid url already caught in Gate A */
+        }
+        allowed = count(qv, sen);
+    }
+    else if (loc.at === "body") {
+        allowed = count(String(getByPath(req.body, loc.jsonPath) ?? ""), sen);
+    }
+    if (allowed < 1) {
+        return {
+            ok: false,
+            gate: "injection_location",
+            reason: `slot ${slot.id} absent from its declared ${loc.at} location`,
+        };
+    }
+    if (total !== allowed) {
+        return {
+            ok: false,
+            gate: "injection_location",
+            reason: `slot ${slot.id} appears outside its declared ${loc.at} location`,
+        };
+    }
+    return { ok: true };
+}
+function count(hay, needle) {
+    if (!needle)
+        return 0;
+    return hay.split(needle).length - 1;
+}

package/dist/gates.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/gates.test.js

@@ -0,0 +1,88 @@
+import { test, expect } from "bun:test";
+import { evaluateGates } from "./gates";
+import { secretSentinel } from "./recipe";
+const ORIGIN = "https://resale.fifa.com";
+function slot(overrides = {}) {
+    return {
+        id: "slot:resale.fifa.com:auth_bearer",
+        siteId: "site1",
+        kind: "bearer",
+        role: "active_inject",
+        injectionLocation: { at: "header", name: "authorization" },
+        allowedDestination: ORIGIN,
+        resolverHints: [],
+        confidence: 1,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        updatedAt: "2026-01-01T00:00:00.000Z",
+        ...overrides,
+    };
+}
+function req(overrides = {}) {
+    const sen = secretSentinel("slot:resale.fifa.com:auth_bearer");
+    return {
+        method: "GET",
+        url: `${ORIGIN}/api/seats`,
+        headers: { authorization: `Bearer ${sen}` },
+        body: undefined,
+        credentials: "include",
+        referencedSlotIds: ["slot:resale.fifa.com:auth_bearer"],
+        safetyClass: "read",
+        ...overrides,
+    };
+}
+const ctx = (extra = {}) => ({
+    siteOrigin: ORIGIN,
+    slotsById: { "slot:resale.fifa.com:auth_bearer": slot() },
+    ...extra,
+});
+test("Gate A: passes a same-origin read with a confined header secret", () => {
+    expect(evaluateGates(req(), ctx())).toEqual({ ok: true });
+});
+test("Gate A: refuses a cross-origin destination", () => {
+    const out = evaluateGates(req({ url: "https://evil.com/api/seats" }), ctx());
+    expect(out.ok).toBe(false);
+    if (!out.ok)
+        expect(out.gate).toBe("same_origin");
+});
+test("Gate A: refuses when the slot's allowedDestination differs", () => {
+    const s = slot({ allowedDestination: "https://other.com" });
+    const out = evaluateGates(req(), ctx({ slotsById: { [s.id]: s } }));
+    expect(out.ok).toBe(false);
+    if (!out.ok)
+        expect(out.gate).toBe("same_origin");
+});
+test("Gate B: refuses a sentinel relocated into the URL", () => {
+    const sen = secretSentinel("slot:resale.fifa.com:auth_bearer");
+    const out = evaluateGates(req({ url: `${ORIGIN}/api/seats?t=${sen}`, headers: { authorization: `Bearer ${sen}` } }), ctx());
+    expect(out.ok).toBe(false);
+    if (!out.ok)
+        expect(out.gate).toBe("injection_location");
+});
+test("Gate B: refuses when the sentinel is absent from its declared location", () => {
+    const out = evaluateGates(req({ headers: { authorization: "Bearer plain" } }), ctx());
+    expect(out.ok).toBe(false);
+    if (!out.ok)
+        expect(out.gate).toBe("injection_location");
+});
+test("Gate C: a POST (method-bound) requires confirmation even if labeled read", () => {
+    const out = evaluateGates(req({ method: "POST", safetyClass: "read" }), ctx());
+    expect(out.ok).toBe(false);
+    if (!out.ok)
+        expect(out.gate).toBe("safety");
+});
+test("Gate C: a confirmed POST passes", () => {
+    expect(evaluateGates(req({ method: "POST" }), ctx({ confirmed: true }))).toEqual({ ok: true });
+});
+test("Gate C: allowMutations=false blocks a mutation outright", () => {
+    const out = evaluateGates(req({ method: "POST" }), ctx({ confirmed: true, allowMutations: false }));
+    expect(out.ok).toBe(false);
+    if (!out.ok)
+        expect(out.gate).toBe("safety");
+});
+test("cookie-borne slot is refused (must be auto-attached, never injected)", () => {
+    const s = slot({ role: "auto_cookie", injectionLocation: { at: "cookie", name: "sid" } });
+    const out = evaluateGates(req(), ctx({ slotsById: { [s.id]: s } }));
+    expect(out.ok).toBe(false);
+    if (!out.ok)
+        expect(out.gate).toBe("injection_location");
+});

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./templating";
+export * from "./tokenize";
+export * from "./recipe";
+export * from "./gates";
+export * from "./execute";
+export * from "./composite";

package/dist/index.js

@@ -0,0 +1,16 @@
+// @sudobility/sider_lib — pure Sider business logic.
+//
+//   templating  — cluster raw observations into endpoint templates
+//   tokenize    — replace known secret values with placeholders (browser-side)
+//   recipe      — compile a ToolSpec + args into a CompiledRequest (secrets = sentinels)
+//   gates       — the three egress gates (same-origin / injection-location / safety)
+//   execute     — detokenize after gates pass; prepareRequest = compile→gate→detokenize
+//
+// No Chrome/DOM/server dependencies — safe to import from sider_api,
+// sider_extension, and sider_app alike.
+export * from "./templating";
+export * from "./tokenize";
+export * from "./recipe";
+export * from "./gates";
+export * from "./execute";
+export * from "./composite";

package/dist/recipe.d.ts

@@ -0,0 +1,18 @@
+import type { CompiledRequest, InvocationRecipe, ToolSpec } from "@sudobility/sider_types";
+export declare function secretSentinel(slotId: string): string;
+export declare class RecipeCompileError extends Error {
+}
+export interface CompileContext {
+    /** Origin the recipe runs against (path templates are relative to it). */
+    siteOrigin: string;
+    /** User/LLM-supplied tool arguments. */
+    args?: Record<string, unknown>;
+    /** Prior tool results this run, keyed by ComposeStep.ref (for priorOutput bindings). */
+    priorOutputs?: Record<string, unknown>;
+}
+export declare function compileRecipe(tool: ToolSpec, ctx: CompileContext): CompiledRequest;
+/** Read a dotted/bracketed path from an object: "data.sections[0].id". */
+export declare function getByPath(obj: unknown, path: string): unknown;
+/** Stable stringify (sorted keys) so two users' equivalent recipes hash equal. */
+export declare function canonicalizeRecipe(recipe: InvocationRecipe): string;
+export declare function hashRecipe(recipe: InvocationRecipe): string;

package/dist/recipe.js

@@ -0,0 +1,115 @@
+// Recipe compiler: ToolSpec + args → CompiledRequest (secrets still placeholders).
+//
+// Secrets are compiled to an internal SENTINEL (a Private-Use-Area delimited
+// token that cannot occur in real data), NOT to their values. The sentinel
+// survives through the egress gates and is only replaced with a real value at
+// detokenization (see execute.ts), after all three gates pass.
+const S = ""; // sentinel delimiter (PUA)
+export function secretSentinel(slotId) {
+    return `${S}${slotId}${S}`;
+}
+export class RecipeCompileError extends Error {
+}
+export function compileRecipe(tool, ctx) {
+    const recipe = tool.recipe;
+    const referenced = new Set();
+    const resolveKey = (key) => {
+        const b = recipe.bindings[key];
+        if (!b)
+            throw new RecipeCompileError(`Unbound placeholder {${key}} in tool "${tool.name}"`);
+        return resolveBinding(key, b, ctx, referenced);
+    };
+    const path = fillTemplate(recipe.urlTemplate, resolveKey);
+    const url = joinOrigin(ctx.siteOrigin, path);
+    const headers = {};
+    for (const h of recipe.headers)
+        headers[h.name] = fillTemplate(h.valueTemplate, resolveKey);
+    const body = recipe.bodyTemplate !== undefined ? resolveDeep(recipe.bodyTemplate, resolveKey) : undefined;
+    return {
+        method: recipe.method,
+        url,
+        headers,
+        body,
+        credentials: "include",
+        referencedSlotIds: [...referenced],
+        safetyClass: tool.safetyClass,
+    };
+}
+function resolveBinding(key, b, ctx, referenced) {
+    switch (b.kind) {
+        case "literal":
+            return b.value;
+        case "arg": {
+            const v = ctx.args?.[b.argName];
+            if (v === undefined)
+                throw new RecipeCompileError(`Missing arg "${b.argName}" for {${key}}`);
+            return String(v);
+        }
+        case "secret":
+            referenced.add(b.slotId);
+            return secretSentinel(b.slotId);
+        case "priorOutput": {
+            const v = getByPath(ctx.priorOutputs?.[b.stepRef], b.jsonPath);
+            if (v === undefined) {
+                throw new RecipeCompileError(`priorOutput ${b.stepRef}.${b.jsonPath} unresolved for {${key}}`);
+            }
+            return String(v);
+        }
+    }
+}
+function fillTemplate(tmpl, resolve) {
+    return tmpl.replace(/\{([^{}]+)\}/g, (_m, key) => resolve(key));
+}
+function resolveDeep(node, resolve) {
+    if (typeof node === "string")
+        return fillTemplate(node, resolve);
+    if (Array.isArray(node))
+        return node.map((n) => resolveDeep(n, resolve));
+    if (node && typeof node === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(node))
+            out[k] = resolveDeep(v, resolve);
+        return out;
+    }
+    return node;
+}
+function joinOrigin(origin, path) {
+    if (/^https?:\/\//i.test(path))
+        return path; // absolute (still same-origin-gated)
+    return `${origin.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+}
+/** Read a dotted/bracketed path from an object: "data.sections[0].id". */
+export function getByPath(obj, path) {
+    const parts = path
+        .replace(/\[(\d+)\]/g, ".$1")
+        .split(".")
+        .filter(Boolean);
+    let cur = obj;
+    for (const p of parts) {
+        if (cur == null || typeof cur !== "object")
+            return undefined;
+        cur = cur[p];
+    }
+    return cur;
+}
+// --- Recipe canonicalization for corroboration hashing --------------------
+/** Stable stringify (sorted keys) so two users' equivalent recipes hash equal. */
+export function canonicalizeRecipe(recipe) {
+    return stableStringify(recipe);
+}
+export function hashRecipe(recipe) {
+    const s = canonicalizeRecipe(recipe);
+    let h = 0;
+    for (let i = 0; i < s.length; i++)
+        h = (Math.imul(31, h) + s.charCodeAt(i)) | 0;
+    return (h >>> 0).toString(16);
+}
+function stableStringify(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v) ?? "null";
+    if (Array.isArray(v))
+        return `[${v.map(stableStringify).join(",")}]`;
+    const obj = v;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
+}

package/dist/templating.d.ts

@@ -0,0 +1,13 @@
+import type { Observation } from "@sudobility/sider_types";
+/** Replace id-like path segments with `{id}`: /sections/120/seats → /sections/{id}/seats */
+export declare function templatePath(rawUrl: string): string;
+/**
+ * GraphQL keying: one URL serves many operations, so cluster on operation name,
+ * not path. Returns undefined for non-GraphQL requests.
+ */
+export declare function graphqlOperationOf(url: string, body: unknown): string | undefined;
+type Clusterable = Pick<Observation, "method" | "url" | "requestBody">;
+/** Stable key identifying the endpoint template an observation belongs to. */
+export declare function endpointKey(o: Clusterable): string;
+export declare function clusterObservations<T extends Clusterable>(observations: T[]): Map<string, T[]>;
+export {};

package/dist/templating.js

@@ -0,0 +1,66 @@
+// Deterministic clustering & path templating. Runs BEFORE any AI: groups raw
+// observations into endpoint templates so the brain infers semantics once per
+// endpoint, not once per request. (This is the logic distill.ts inlined.)
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const LONGHEX_RE = /^[0-9a-f]{16,}$/i;
+/** Replace id-like path segments with `{id}`: /sections/120/seats → /sections/{id}/seats */
+export function templatePath(rawUrl) {
+    let pathname = rawUrl;
+    try {
+        pathname = new URL(rawUrl, "http://sider.local").pathname;
+    }
+    catch {
+        /* keep raw */
+    }
+    return pathname
+        .split("/")
+        .map((seg) => {
+        if (seg === "")
+            return seg;
+        if (/^\d+$/.test(seg))
+            return "{id}";
+        if (UUID_RE.test(seg))
+            return "{id}";
+        if (LONGHEX_RE.test(seg))
+            return "{id}";
+        return seg;
+    })
+        .join("/");
+}
+/**
+ * GraphQL keying: one URL serves many operations, so cluster on operation name,
+ * not path. Returns undefined for non-GraphQL requests.
+ */
+export function graphqlOperationOf(url, body) {
+    if (body && typeof body === "object") {
+        const b = body;
+        if (typeof b["operationName"] === "string" && b["operationName"]) {
+            return b["operationName"];
+        }
+        if (typeof b["query"] === "string") {
+            const m = /\b(query|mutation|subscription)\s+([A-Za-z0-9_]+)/.exec(b["query"]);
+            if (m && m[2])
+                return m[2];
+        }
+    }
+    if (/\/graphql\b/i.test(url))
+        return "anonymous";
+    return undefined;
+}
+/** Stable key identifying the endpoint template an observation belongs to. */
+export function endpointKey(o) {
+    const op = graphqlOperationOf(o.url, o.requestBody);
+    return `${o.method} ${templatePath(o.url)}${op ? ` #${op}` : ""}`;
+}
+export function clusterObservations(observations) {
+    const groups = new Map();
+    for (const o of observations) {
+        const key = endpointKey(o);
+        const g = groups.get(key);
+        if (g)
+            g.push(o);
+        else
+            groups.set(key, [o]);
+    }
+    return groups;
+}

package/dist/tokenize.d.ts

@@ -0,0 +1,27 @@
+import type { HttpMethod, Observation, RequestContext, ResolverHint, SecretKind, SecretRole, SecretSlot } from "@sudobility/sider_types";
+export interface RawObservation {
+    method: HttpMethod;
+    url: string;
+    requestHeaders: Record<string, string>;
+    requestBody?: unknown;
+    status: number;
+    responseBody?: unknown;
+    timingMs: number;
+    context: RequestContext;
+}
+/** A secret value the browser found in THIS user's session (value stays local). */
+export interface KnownSecret {
+    value: string;
+    slotId: string;
+    kind: SecretKind;
+    role: SecretRole;
+    resolverHint: ResolverHint;
+}
+export type SecretSlotProposal = Omit<SecretSlot, "siteId" | "createdAt" | "updatedAt">;
+export type TokenizedObservation = Omit<Observation, "id" | "batchId" | "createdAt">;
+export interface TokenizeResult {
+    observation: TokenizedObservation;
+    slots: SecretSlotProposal[];
+}
+export declare function samplePlaceholder(slotId: string): string;
+export declare function tokenizeObservation(raw: RawObservation, known: KnownSecret[]): TokenizeResult;