@sudobility/sider_types 0.0.2 → 0.0.5

package/dist/api.d.ts

@@ -1,5 +1,6 @@
-import type { EndpointGraphEdge, SafetyClass, SecretSlot, Site, ToolSpec, UXRecipe } from "./registry";
-import type { Observation, StepKind } from "./runtime";
+import type { IsoTimestamp, JSONSchema } from "./common";
+import type { EndpointGraphEdge, InvocationRecipe, SafetyClass, SecretSlot, Site, ToolSpec, ToolStatus, UXRecipe } from "./registry";
+import type { CaptureBatch, Contributor, Observation, StepKind } from "./runtime";
 /** A planner decision (mirror of the ShapeShyft plan-next-step output). */
 export interface PlannerStep {
     kind: StepKind;
@@ -52,3 +53,68 @@ export interface StatsResponse {
     trustedToolCount: number;
     contributorCount: number;
 }
+/** GET /api/v1/me — the signed-in contributor + aggregate counts. */
+export interface MeResponse {
+    contributor: Contributor;
+    batchCount: number;
+    observationCount: number;
+    /** Tools this user has corroborated (cast a recipe vote on). */
+    toolsContributed: number;
+    /** Of those, how many are currently `trusted`. */
+    trustedToolsContributed: number;
+}
+/** One row of GET /api/v1/me/capture-batches. */
+export interface MyCaptureBatchSummary extends CaptureBatch {
+    siteOrigin: string;
+    siteName: string;
+}
+/** GET /api/v1/me/capture-batches/:id — a batch plus its observations. */
+export interface MyCaptureBatchDetail {
+    batch: MyCaptureBatchSummary;
+    observations: Observation[];
+}
+/** One row of GET /api/v1/me/tools — a tool this user corroborated. */
+export interface MyToolEntry {
+    toolId: string;
+    siteId: string;
+    name: string;
+    status: ToolStatus;
+    safetyClass: SafetyClass;
+    version: number;
+    corroboratingUserCount: number;
+    /** Hash of MY independently-derived recipe. */
+    myRecipeHash: string;
+    /** Hash of the recipe currently stored on the tool. */
+    currentRecipeHash: string;
+    /** Whether my vote agrees with the stored recipe. */
+    agreesWithCurrent: boolean;
+    votedAt: IsoTimestamp;
+}
+/** GET /api/v1/tools/:id — full tool detail for the registry inspector. */
+export interface ToolDetailResponse {
+    /** The tools table row (recipe, schema, safety, status, counts). */
+    tool: {
+        id: string;
+        siteId: string;
+        name: string;
+        description: string;
+        capabilityLabel: string;
+        inputSchema: JSONSchema;
+        safetyClass: SafetyClass;
+        directCallAvailable: boolean;
+        recipe: InvocationRecipe;
+        status: ToolStatus;
+        version: number;
+        observationCount: number;
+        corroboratingUserCount: number;
+        confidence: number;
+        createdAt: IsoTimestamp;
+        updatedAt: IsoTimestamp;
+    };
+    /** Anonymized corroboration breakdown: recipe hash → distinct-user count. */
+    corroboration: {
+        distinctUsers: number;
+        hashCounts: Record<string, number>;
+        trustThreshold: number;
+    };
+}

package/dist/index.d.ts

@@ -4,3 +4,5 @@ export * from "./runtime";
 export * from "./local";
 export * from "./api";
 export * from "./actions";
+export * from "./templating";
+export * from "./recipe-hash";

package/dist/index.js

@@ -10,3 +10,5 @@ export * from "./runtime";
 export * from "./local";
 export * from "./api";
 export * from "./actions";
+export * from "./templating";
+export * from "./recipe-hash";

package/dist/recipe-hash.d.ts

@@ -0,0 +1,4 @@
+import type { InvocationRecipe } from "./registry";
+/** 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-hash.js

@@ -0,0 +1,23 @@
+// Recipe canonicalization + corroboration hashing. Pure domain logic shared by
+// the backend (trust engine: distinct-recipe-hash quorum) and the frontend. A
+// stable sorted-key stringify makes two users' equivalent recipes hash equal.
+/** 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 "./runtime";
+/** 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,67 @@
+// Deterministic clustering & path templating. Pure domain logic shared by the
+// backend (distillation) and the frontend security lib — groups raw observations
+// into endpoint templates so the brain infers semantics once per endpoint, not
+// once per request. No runtime dependencies.
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudobility/sider_types",
-  "version": "0.0.2",
+  "version": "0.0.5",
   "description": "Shared domain types for Sider — AI assistance for generic web apps.",
   "license": "BUSL-1.1",
   "publishConfig": {

package/src/api.ts

@@ -2,15 +2,18 @@
 // (to type its handlers) and sider_client (to type its calls). Keeping these
 // here is the single source of truth that stops the two sides from drifting.
 
+import type { IsoTimestamp, JSONSchema } from "./common";
 import type {
   EndpointGraphEdge,
+  InvocationRecipe,
   SafetyClass,
   SecretSlot,
   Site,
   ToolSpec,
+  ToolStatus,
   UXRecipe,
 } from "./registry";
-import type { Observation, StepKind } from "./runtime";
+import type { CaptureBatch, Contributor, Observation, StepKind } from "./runtime";
 
 /** A planner decision (mirror of the ShapeShyft plan-next-step output). */
 export interface PlannerStep {
@@ -66,3 +69,77 @@ export interface StatsResponse {
   trustedToolCount: number;
   contributorCount: number;
 }
+
+// ---------------------------------------------------------------------------
+// Dashboard DTOs (per-user + registry inspection). Spec 2026-07-20 §3.
+// ---------------------------------------------------------------------------
+
+/** GET /api/v1/me — the signed-in contributor + aggregate counts. */
+export interface MeResponse {
+  contributor: Contributor;
+  batchCount: number;
+  observationCount: number;
+  /** Tools this user has corroborated (cast a recipe vote on). */
+  toolsContributed: number;
+  /** Of those, how many are currently `trusted`. */
+  trustedToolsContributed: number;
+}
+
+/** One row of GET /api/v1/me/capture-batches. */
+export interface MyCaptureBatchSummary extends CaptureBatch {
+  siteOrigin: string;
+  siteName: string;
+}
+
+/** GET /api/v1/me/capture-batches/:id — a batch plus its observations. */
+export interface MyCaptureBatchDetail {
+  batch: MyCaptureBatchSummary;
+  observations: Observation[];
+}
+
+/** One row of GET /api/v1/me/tools — a tool this user corroborated. */
+export interface MyToolEntry {
+  toolId: string;
+  siteId: string;
+  name: string;
+  status: ToolStatus;
+  safetyClass: SafetyClass;
+  version: number;
+  corroboratingUserCount: number;
+  /** Hash of MY independently-derived recipe. */
+  myRecipeHash: string;
+  /** Hash of the recipe currently stored on the tool. */
+  currentRecipeHash: string;
+  /** Whether my vote agrees with the stored recipe. */
+  agreesWithCurrent: boolean;
+  votedAt: IsoTimestamp;
+}
+
+/** GET /api/v1/tools/:id — full tool detail for the registry inspector. */
+export interface ToolDetailResponse {
+  /** The tools table row (recipe, schema, safety, status, counts). */
+  tool: {
+    id: string;
+    siteId: string;
+    name: string;
+    description: string;
+    capabilityLabel: string;
+    inputSchema: JSONSchema;
+    safetyClass: SafetyClass;
+    directCallAvailable: boolean;
+    recipe: InvocationRecipe;
+    status: ToolStatus;
+    version: number;
+    observationCount: number;
+    corroboratingUserCount: number;
+    confidence: number;
+    createdAt: IsoTimestamp;
+    updatedAt: IsoTimestamp;
+  };
+  /** Anonymized corroboration breakdown: recipe hash → distinct-user count. */
+  corroboration: {
+    distinctUsers: number;
+    hashCounts: Record<string, number>;
+    trustThreshold: number;
+  };
+}

package/src/index.ts

@@ -11,3 +11,5 @@ export * from "./runtime";
 export * from "./local";
 export * from "./api";
 export * from "./actions";
+export * from "./templating";
+export * from "./recipe-hash";

package/src/recipe-hash.ts

@@ -0,0 +1,25 @@
+// Recipe canonicalization + corroboration hashing. Pure domain logic shared by
+// the backend (trust engine: distinct-recipe-hash quorum) and the frontend. A
+// stable sorted-key stringify makes two users' equivalent recipes hash equal.
+
+import type { InvocationRecipe } from "./registry";
+
+/** Stable stringify (sorted keys) so two users' equivalent recipes hash equal. */
+export function canonicalizeRecipe(recipe: InvocationRecipe): string {
+  return stableStringify(recipe);
+}
+
+export function hashRecipe(recipe: InvocationRecipe): string {
+  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: unknown): string {
+  if (v === null || typeof v !== "object") return JSON.stringify(v) ?? "null";
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`;
+  const obj = v as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
+}

package/src/templating.ts

@@ -0,0 +1,70 @@
+// Deterministic clustering & path templating. Pure domain logic shared by the
+// backend (distillation) and the frontend security lib — groups raw observations
+// into endpoint templates so the brain infers semantics once per endpoint, not
+// once per request. No runtime dependencies.
+
+import type { Observation } from "./runtime";
+
+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: string): string {
+  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: string, body: unknown): string | undefined {
+  if (body && typeof body === "object") {
+    const b = body as Record<string, unknown>;
+    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;
+}
+
+type Clusterable = Pick<Observation, "method" | "url" | "requestBody">;
+
+/** Stable key identifying the endpoint template an observation belongs to. */
+export function endpointKey(o: Clusterable): string {
+  const op = graphqlOperationOf(o.url, o.requestBody);
+  return `${o.method} ${templatePath(o.url)}${op ? ` #${op}` : ""}`;
+}
+
+export function clusterObservations<T extends Clusterable>(
+  observations: T[],
+): Map<string, T[]> {
+  const groups = new Map<string, T[]>();
+  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;
+}