@sudobility/sider_types 0.0.2 → 0.0.3

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.3",
   "description": "Shared domain types for Sider — AI assistance for generic web apps.",
   "license": "BUSL-1.1",
   "publishConfig": {

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;
+}