@opus-magnum/rubedo 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { RubedoForge } from "./v1/RubedoForge";
+export { stableStringify, canonicalizeJson, type Json } from "./v1/canonical-json";
+export { RUBEDO_CONTRACT_V1 } from "./v1/contract";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { RubedoForge } from "./v1/RubedoForge";
+export { stableStringify, canonicalizeJson } from "./v1/canonical-json";
+export { RUBEDO_CONTRACT_V1 } from "./v1/contract";

package/dist/v1/RubedoForge.d.ts

@@ -0,0 +1,4 @@
+import type { IRubedoForge, RubedoArtifact, RubedoInput } from "../../../interfaces/RUBEDO/v1/IRubedoForge";
+export declare class RubedoForge implements IRubedoForge {
+    forge(input: RubedoInput): RubedoArtifact;
+}

package/dist/v1/RubedoForge.js

@@ -0,0 +1,19 @@
+import crypto from "node:crypto";
+import { stableStringify } from "./canonical-json";
+function sha256Hex(s) {
+    return crypto.createHash("sha256").update(s, "utf-8").digest("hex");
+}
+export class RubedoForge {
+    forge(input) {
+        const synopsis = [...input.synopsis].slice().sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        const payload = { synopsis };
+        const canonical = stableStringify(payload);
+        const fingerprint = sha256Hex(canonical);
+        return {
+            artifact_id: "RUBEDO::v1::" + fingerprint.slice(0, 12),
+            fingerprint,
+            payload,
+            stats: { count: input.synopsis.length }
+        };
+    }
+}

package/dist/v1/canonical-json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Canonical JSON helpers
+ * Goal: stable structural representation independent of input key order.
+ */
+export declare function canonicalizeJson(value: unknown): unknown;
+export declare function stableStringify(value: unknown): string;

package/dist/v1/canonical-json.js

@@ -0,0 +1,29 @@
+/**
+ * Canonical JSON helpers
+ * Goal: stable structural representation independent of input key order.
+ */
+export function canonicalizeJson(value) {
+    if (value === null)
+        return null;
+    const t = typeof value;
+    // primitives
+    if (t === "string" || t === "number" || t === "boolean")
+        return value;
+    // arrays
+    if (Array.isArray(value))
+        return value.map(v => canonicalizeJson(v));
+    // objects
+    if (t === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        const out = {};
+        for (const k of keys)
+            out[k] = canonicalizeJson(obj[k]);
+        return out;
+    }
+    // non-JSON types (undefined, bigint, function, symbol) — deterministic fallback
+    return null;
+}
+export function stableStringify(value) {
+    return JSON.stringify(canonicalizeJson(value));
+}

package/dist/v1/contract-test.d.ts

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

package/dist/v1/contract-test.js

@@ -0,0 +1,25 @@
+import { RUBEDO_CONTRACT_V1 } from "./contract.js";
+import { RubedoForge } from "./RubedoForge.js";
+function assertEq(a, b, msg) {
+    if (a !== b)
+        throw new Error(msg + `: ${String(a)} !== ${String(b)}`);
+}
+console.log(`[RUBEDO_CONTRACT] version=${RUBEDO_CONTRACT_V1.version}`);
+const f = new RubedoForge();
+const fpOf = (synopsis) => f.forge({ synopsis }).fingerprint;
+// Key order independence (value object different key order must be same fingerprint)
+const s1 = [{ id: "key:a", kind: "KEY", value: { a: 1, b: 2, c: { y: 9, z: 0 } } }];
+const s2 = [{ id: "key:a", kind: "KEY", value: { b: 2, a: 1, c: { z: 0, y: 9 } } }];
+assertEq(fpOf(s1), fpOf(s2), "KEY_ORDER_INDEPENDENCE");
+// Synopsis order independence
+const t1 = [
+    { id: "k:1", kind: "KEY", value: 1 },
+    { id: "k:2", kind: "KEY", value: 2 }
+];
+const t2 = [
+    { id: "k:2", kind: "KEY", value: 2 },
+    { id: "k:1", kind: "KEY", value: 1 }
+];
+assertEq(fpOf(t1), fpOf(t2), "SYNOPSIS_ORDER_INDEPENDENCE");
+console.log("[PASS] RUBEDO package contract invariants satisfied");
+process.exit(0);

package/dist/v1/contract.d.ts

@@ -0,0 +1,22 @@
+/**
+ * RUBEDO CONTRACT v1
+ * Immutable invariants for fingerprint generation.
+ */
+export declare const RUBEDO_CONTRACT_V1: {
+    readonly version: 1;
+    readonly fingerprint: {
+        readonly algorithm: "sha256";
+        readonly encoding: "hex";
+        readonly source: "canonical-json";
+        readonly deterministic: true;
+        readonly orderIndependent: true;
+    };
+    readonly payload: {
+        readonly fields: readonly ["synopsis"];
+        readonly synopsis: {
+            readonly required: true;
+            readonly orderedBy: "id";
+        };
+    };
+    readonly invariants: readonly ["Same semantic input MUST produce identical fingerprint", "Key order MUST NOT affect fingerprint", "Synopsis order MUST NOT affect fingerprint", "Fingerprint MUST be reproducible offline"];
+};

package/dist/v1/contract.js

@@ -0,0 +1,27 @@
+/**
+ * RUBEDO CONTRACT v1
+ * Immutable invariants for fingerprint generation.
+ */
+export const RUBEDO_CONTRACT_V1 = {
+    version: 1,
+    fingerprint: {
+        algorithm: "sha256",
+        encoding: "hex",
+        source: "canonical-json",
+        deterministic: true,
+        orderIndependent: true
+    },
+    payload: {
+        fields: ["synopsis"],
+        synopsis: {
+            required: true,
+            orderedBy: "id"
+        }
+    },
+    invariants: [
+        "Same semantic input MUST produce identical fingerprint",
+        "Key order MUST NOT affect fingerprint",
+        "Synopsis order MUST NOT affect fingerprint",
+        "Fingerprint MUST be reproducible offline"
+    ]
+};

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@opus-magnum/rubedo",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "npx tsc -p tsconfig.build.json",
+    "test:contract": "npm run -s build >/dev/null && node dist/v1/contract-test.js"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^22.19.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { RubedoForge } from "./v1/RubedoForge";
+export { stableStringify, canonicalizeJson, type Json } from "./v1/canonical-json";
+export { RUBEDO_CONTRACT_V1 } from "./v1/contract";

package/src/v1/RubedoForge.ts

@@ -0,0 +1,26 @@
+import crypto from "node:crypto";
+import type { IRubedoForge, RubedoArtifact, RubedoInput } from "../../../interfaces/RUBEDO/v1/IRubedoForge";
+import { stableStringify } from "./canonical-json";
+
+function sha256Hex(s: string): string {
+  return crypto.createHash("sha256").update(s, "utf-8").digest("hex");
+}
+
+export class RubedoForge implements IRubedoForge {
+  
+forge(input: RubedoInput): RubedoArtifact {
+    const synopsis = [...input.synopsis].slice().sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const payload = { synopsis };
+
+    const canonical = stableStringify(payload);
+
+    const fingerprint = sha256Hex(canonical);
+
+    return {
+      artifact_id: "RUBEDO::v1::" + fingerprint.slice(0, 12),
+      fingerprint,
+      payload,
+      stats: { count: input.synopsis.length }
+    };
+  }
+}

package/src/v1/canonical-json.ts

@@ -0,0 +1,32 @@
+/**
+ * Canonical JSON helpers
+ * Goal: stable structural representation independent of input key order.
+ */
+
+export function canonicalizeJson(value: unknown): unknown {
+  if (value === null) return null;
+
+  const t = typeof value;
+
+  // primitives
+  if (t === "string" || t === "number" || t === "boolean") return value;
+
+  // arrays
+  if (Array.isArray(value)) return value.map(v => canonicalizeJson(v));
+
+  // objects
+  if (t === "object") {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const out: Record<string, unknown> = {};
+    for (const k of keys) out[k] = canonicalizeJson(obj[k]);
+    return out;
+  }
+
+  // non-JSON types (undefined, bigint, function, symbol) — deterministic fallback
+  return null;
+}
+
+export function stableStringify(value: unknown): string {
+  return JSON.stringify(canonicalizeJson(value));
+}

package/src/v1/contract-test.ts

@@ -0,0 +1,30 @@
+import { RUBEDO_CONTRACT_V1 } from "./contract.js";
+import { RubedoForge } from "./RubedoForge.js";
+
+function assertEq(a: any, b: any, msg: string) {
+  if (a !== b) throw new Error(msg + `: ${String(a)} !== ${String(b)}`);
+}
+
+console.log(`[RUBEDO_CONTRACT] version=${RUBEDO_CONTRACT_V1.version}`);
+
+const f = new RubedoForge();
+const fpOf = (synopsis: any[]) => f.forge({ synopsis }).fingerprint;
+
+// Key order independence (value object different key order must be same fingerprint)
+const s1 = [{ id: "key:a", kind: "KEY", value: { a: 1, b: 2, c: { y: 9, z: 0 } } }];
+const s2 = [{ id: "key:a", kind: "KEY", value: { b: 2, a: 1, c: { z: 0, y: 9 } } }];
+assertEq(fpOf(s1), fpOf(s2), "KEY_ORDER_INDEPENDENCE");
+
+// Synopsis order independence
+const t1 = [
+  { id: "k:1", kind: "KEY", value: 1 },
+  { id: "k:2", kind: "KEY", value: 2 }
+];
+const t2 = [
+  { id: "k:2", kind: "KEY", value: 2 },
+  { id: "k:1", kind: "KEY", value: 1 }
+];
+assertEq(fpOf(t1), fpOf(t2), "SYNOPSIS_ORDER_INDEPENDENCE");
+
+console.log("[PASS] RUBEDO package contract invariants satisfied");
+process.exit(0);

package/src/v1/contract.ts

@@ -0,0 +1,31 @@
+/**
+ * RUBEDO CONTRACT v1
+ * Immutable invariants for fingerprint generation.
+ */
+
+export const RUBEDO_CONTRACT_V1 = {
+  version: 1 as const,
+
+  fingerprint: {
+    algorithm: "sha256",
+    encoding: "hex",
+    source: "canonical-json",
+    deterministic: true,
+    orderIndependent: true
+  },
+
+  payload: {
+    fields: ["synopsis"],
+    synopsis: {
+      required: true,
+      orderedBy: "id"
+    }
+  },
+
+  invariants: [
+    "Same semantic input MUST produce identical fingerprint",
+    "Key order MUST NOT affect fingerprint",
+    "Synopsis order MUST NOT affect fingerprint",
+    "Fingerprint MUST be reproducible offline"
+  ]
+} as const;

package/tsconfig.build.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}