@wenathlan/vault 2.0.94 → 2.0.118

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@wenathlan/vault",
-  "version": "2.0.94",
+  "version": "2.0.118",
   "description": "vault is the supabase clone of the wenathlan family: it owns the self-hosted database, auth and storage surface, and ships the documentation set and the tests directory as one package",
   "type": "module",
-  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wenathlan/devthink"
+  },
   "license": "GPL-3.0-only",
   "author": "Wenathlan",
   "sideEffects": false,
@@ -14,7 +17,22 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=26.8.1 <27"
+    "bare": "^1.18.0",
+    "bun": "^1.4.2",
+    "chrome": "^16.0.912",
+    "cnpm": "^9.4.0",
+    "corepack": "^0.35.0",
+    "deno": "^2.9.5",
+    "ecmascript": "^5.0.0",
+    "firefox": ">=0.8.0",
+    "iojs": "^1.0.0",
+    "node": "^26.8.2",
+    "npm": "^12.1.0",
+    "pnpm": "^12.6.0",
+    "teleport": ">=0.2.0",
+    "typescript": "^5.8.0",
+    "vscode": "^1.118.0",
+    "yarn": "^4.17.1"
   },
   "publishConfig": {
     "access": "public"
@@ -24,7 +42,12 @@
     "build": "vite build",
     "start": "vite preview --host",
     "preview": "vite preview --host",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"tests/*.test.ts\"",
+    "test:watch": "node --test --watch \"tests/*.test.ts\"",
+    "lint": "biome check .",
+    "restore:entry": "node -e \"const{readFileSync}=require('node:fs');const{execSync}=require('node:child_process');const script=/script[^>]*App\\.tsx/;const triad=/family=Inter[\\s\\S]*Geist\\+Mono/;const face=(h)=>script.test(h)&&triad.test(h);if(face(readFileSync('index.html','utf8'))){console.log('index.html already rides the source face');process.exit(0)}if(!face(execSync('git show HEAD:./index.html',{encoding:'utf8'}))){console.error('refusing: HEAD index.html is not the canonical source face yet (script App.tsx + the font triad) - land the source-face fix first; nothing was touched');process.exit(1)}execSync('git checkout -- index.html',{stdio:'inherit'});console.log('index.html restored from HEAD (the source face)')\""
   },
   "dependencies": {
     "@hono/node-server": "^2.1.3",
@@ -40,6 +63,7 @@
     "@capacitor/cli": "^8.5.2",
     "@capacitor/core": "^8.5.2",
     "@capacitor/ios": "^8.5.2",
+    "@fluentui/react-icons": "^2.0.344",
     "@hookform/resolvers": "^5.9.1",
     "@libsql/client": "^0.18.0",
     "@opencode-ai/sdk": "^1.18.34",

package/tests/buckets.test.ts

@@ -0,0 +1,127 @@
+// # buckets.test — the bucket shelf engine of the vault, runnable with the
+// node built-in runner (no dependencies, no install):
+//   node --test tests/buckets.test.ts
+// The shelf rolls the rehearsal ledger up per bucket: policy, rows, bytes,
+// lfs share — deterministic from the seed, honest about unknowns.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  type BucketRule,
+  bucketShelf,
+  bucketsInUse,
+  objectsOf,
+  retentionLabel,
+  ruleFor,
+  seedRules,
+  shelfBytes,
+  shelfOf,
+} from "../buckets.ts";
+import { VAULT_BUCKETS, seedVault } from "../objects.ts";
+
+describe("policies", () => {
+  const rules = seedRules(912731);
+
+  it("musters one policy per named bucket, in shelf order", () => {
+    assert.deepEqual(
+      rules.map((rule) => rule.bucket),
+      [...VAULT_BUCKETS],
+    );
+    for (const rule of rules) {
+      assert.ok(rule.days >= 0, "a policy never goes negative");
+      assert.ok(rule.note.length > 0, "every policy carries its honest why");
+    }
+  });
+
+  it("keeps the forever policy at zero and the finite ones positive", () => {
+    const forever = rules.find((rule) => rule.bucket === "family-state");
+    assert.ok(forever, "the family state bucket exists");
+    assert.equal(forever.days, 0, "the family state keeps forever");
+    for (const rule of rules) {
+      if (rule.bucket !== "family-state") assert.ok(rule.days > 0, `${rule.bucket} rides a finite window`);
+    }
+  });
+
+  it("answers the same shelf for the same seed", () => {
+    assert.deepEqual(seedRules(912731), rules);
+    assert.notDeepEqual(seedRules(912732), rules);
+  });
+
+  it("answers ruleFor and refuses unknown buckets", () => {
+    assert.equal(ruleFor(rules, "family-state")?.days, 0);
+    assert.equal(ruleFor(rules, "no-such-bucket"), undefined);
+  });
+});
+
+describe("shelf", () => {
+  const vault = seedVault(20260314);
+  const rules = seedRules(912731);
+  const shelf = shelfOf(vault, rules);
+
+  it("rolls every named bucket up, even empty ones", () => {
+    assert.equal(shelf.length, VAULT_BUCKETS.length);
+    for (const entry of shelf) {
+      assert.ok(entry.objects >= 0);
+      assert.ok(entry.bytes >= 0);
+      assert.ok(entry.lfsShare >= 0 && entry.lfsShare <= 1);
+    }
+  });
+
+  it("accounts every row and byte on the shelf", () => {
+    const rows = shelf.reduce((total, entry) => total + entry.objects, 0);
+    assert.equal(rows, vault.length, "no row is lost between the ledger and the shelf");
+    const bytes = shelfBytes(shelf);
+    const ledgerBytes = vault.reduce((total, object) => total + object.size, 0);
+    assert.equal(bytes, ledgerBytes, "the shelf byte total equals the ledger byte total");
+  });
+
+  it("keeps the lfs share honest per bucket", () => {
+    for (const entry of shelf) {
+      const mine = objectsOf(vault, entry.rule.bucket);
+      const lfsBytes = mine.filter((object) => object.lfs).reduce((total, object) => total + object.size, 0);
+      const expected = entry.bytes === 0 ? 0 : lfsBytes / entry.bytes;
+      assert.ok(Math.abs(entry.lfsShare - expected) < 1e-9);
+      assert.equal(entry.blobRows, mine.length - entry.lfsRows);
+    }
+  });
+
+  it("answers the biggest row of the shelf", () => {
+    for (const entry of shelf) {
+      const mine = objectsOf(vault, entry.rule.bucket);
+      if (mine.length === 0) {
+        assert.equal(entry.biggest, undefined);
+        continue;
+      }
+      const max = Math.max(...mine.map((object) => object.size));
+      assert.equal(entry.biggest!.size, max);
+    }
+  });
+
+  it("lists only the buckets the ledger actually touches", () => {
+    const inUse = bucketsInUse(vault);
+    assert.ok(inUse.length > 0);
+    assert.ok(inUse.length <= VAULT_BUCKETS.length);
+    for (const bucket of inUse) assert.ok(VAULT_BUCKETS.includes(bucket as (typeof VAULT_BUCKETS)[number]));
+    assert.deepEqual(bucketsInUse([]), []);
+  });
+
+  it("shelves a bucket the ledger never touches as an honest empty row", () => {
+    const rules2: BucketRule[] = [...rules, { bucket: "ghost-bucket", days: 12, note: "a policy without rows" }];
+    const entry = bucketShelf(vault, rules2, "ghost-bucket");
+    assert.equal(entry.objects, 0);
+    assert.equal(entry.bytes, 0);
+    assert.equal(entry.lfsShare, 0);
+    assert.equal(entry.biggest, undefined);
+  });
+});
+
+describe("retention labels", () => {
+  it("renders the honest human label of a window", () => {
+    assert.equal(retentionLabel(0), "sealed forever");
+    assert.equal(retentionLabel(1), "1 day");
+    assert.equal(retentionLabel(30), "1 month");
+    assert.equal(retentionLabel(60), "2 months");
+    assert.equal(retentionLabel(365), "1 year");
+    assert.equal(retentionLabel(730), "2 years");
+    assert.equal(retentionLabel(45), "45 days");
+  });
+});

package/tests/design.test.ts

@@ -0,0 +1,163 @@
+// # design.test — the design contract of the vault surface, runnable with
+// the node built-in runner (no dependencies, no install):
+//   node --test tests/design.test.ts
+// The file reads the shipped sources (css, entry face, brand mark, app
+// identity) and pins the family laws of the reform wave: no banned hue, no
+// pill, no transition:all, the trylle type triad, the source-face entry,
+// the gelo identity under the windows hands and the honest page set of the
+// application identity.
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { describe, it } from "node:test";
+
+function read(path: string): string {
+  return readFileSync(new URL(path, import.meta.url), "utf8");
+}
+
+const CSS = read("../Sol/sol.css");
+const ENTRY = read("../index.html");
+const MARK = read("../Sol/shell/BrandMark.tsx");
+const SHELL = read("../Sol/shell/Shell.tsx");
+const TOML = read("../devthink.toml");
+const SOL = read("../Sol/Sol.tsx");
+
+const BANNED = [/3b82f6/i, /2563eb/i, /f97316/i];
+
+/** strips the windows pin keyframe — the one sanctioned scale(0) entrance —
+ * so the floor law can be asserted on everything else. */
+function cssWithoutPinIntro(source: string): string {
+  return source.replace(/@keyframes dtPopIntro \{.*\} \}/, "");
+}
+
+describe("design contract", () => {
+  it("ships no banned hue in the stylesheet, the entry or the mark", () => {
+    for (const source of [CSS, ENTRY, MARK]) {
+      for (const banned of BANNED) {
+        assert.ok(!banned.test(source), `banned hue ${banned} found`);
+      }
+    }
+  });
+
+  it("keeps the gelo identity and the windows accent in their lanes", () => {
+    assert.match(CSS, /--sol-primary: #a3d7e6/, "the gelo identity token stands");
+    assert.match(CSS, /--win-accent: #4cc2ff/, "the windows accent governs focus and the bar cta");
+    assert.match(CSS, /--win-accent: #0067c0/, "the light theme follows the windows light law");
+    assert.match(MARK, /#a3d7e6/, "the mark rides the gelo");
+  });
+
+  it("retires the gold lamplight and the green ghost from the identity", () => {
+    assert.ok(!/3ecf8e/i.test(CSS + ENTRY), "the green ghost is gone");
+    const gold = CSS.lastIndexOf("#eab308");
+    const ice = CSS.lastIndexOf("#a3d7e6");
+    assert.ok(ice > gold, "the gelo retint must restate the identity after the gold era");
+  });
+
+  it("wears the gelo identity on the icons and the manifest", () => {
+    const FAVICON = read("../favicon.svg");
+    const ICON = read("../icon.svg");
+    const MANIFEST = read("../manifest.webmanifest");
+    assert.match(FAVICON, /#a3d7e6/, "the favicon rides the gelo");
+    assert.match(ICON, /#5b93a6|#c9e9f2/, "the icon rides the gelo family");
+    assert.match(MANIFEST, /"theme_color": "#a3d7e6"/, "the manifest theme color is the gelo");
+    assert.match(MANIFEST, /"background_color": "#0a0d10"/, "the manifest background is the abyss base");
+    assert.match(ENTRY, /theme-color" content="#0a0d10"/, "the entry theme color is the abyss base");
+  });
+
+  it("keeps the pill out of the stylesheet (no 999px, no stadium radius)", () => {
+    assert.ok(!CSS.includes("999px"), "the pill radius is retired");
+    assert.ok(!CSS.includes("--r-pill"), "no pill token survives");
+  });
+
+  it("never ships transition: all", () => {
+    assert.ok(!/transition:\s*all/.test(CSS), "transition: all is a reprovação");
+  });
+
+  it("never enters from scale(0) outside the windows pin law", () => {
+    // the ONE sanctioned scale(0) entrance is the dtPopIntro pin bounce —
+    // the windows recipe (0 → 1.125 → 0.725 → 1); everything else floors
+    assert.ok(/@keyframes dtPopIntro/.test(CSS), "the windows pin entrance stands");
+    assert.ok(!/scale\(0\)/.test(cssWithoutPinIntro(CSS)), "scale(0) outside dtPopIntro is a reprovação");
+  });
+
+  it("declares the trylle type triad (Inter Variable surfaces, Geist Mono numbers)", () => {
+    assert.match(CSS, /"Inter Variable"/);
+    assert.match(CSS, /"Geist Mono Variable"/);
+    assert.match(ENTRY, /family=Inter/);
+    assert.match(ENTRY, /Geist\+Mono/);
+  });
+
+  it("keeps the entry on the source face (./App.tsx, no hashed ghosts)", () => {
+    assert.match(ENTRY, /script[^>]*\.\/App\.tsx/);
+    assert.ok(!/-[0-9a-f]{8}\.(js|css)/.test(ENTRY), "no hashed bundle rides the entry");
+    assert.match(ENTRY, /href="\.\/favicon\.svg"/);
+  });
+
+  it("guards the reduced-motion stop on every layer", () => {
+    const blocks = CSS.match(/@media \(prefers-reduced-motion: reduce\)/g) ?? [];
+    assert.ok(blocks.length >= 4, `expected the hard stop on every layer, found ${blocks.length}`);
+  });
+
+  it("wears the windows hands on the shell (press law, pin entrance, resize, inactive)", () => {
+    assert.match(CSS, /dtPopIntro/, "the pin entrance keyframe stands");
+    assert.match(SHELL, /RESIZE_EDGES/, "the eight resize handles mount");
+    assert.match(CSS, /win-rz\[data-edge="se"\]/, "the resize handles ride the frame edges");
+    assert.match(CSS, /grayscale\(80%\)/, "the inactive window law stands");
+    assert.match(CSS, /rgb\(232 17 35\)/, "the close caption wears the windows red");
+  });
+
+  it("declares the honest page set (home, objects, buckets, retention, notfound)", () => {
+    assert.match(TOML, /pages = \["home", "objects", "buckets", "retention", "notfound"\]/);
+    for (const route of ['"/objects"', '"/buckets"', '"/retention"', '"/404"']) {
+      assert.ok(SOL.includes(`path=${route}`), `route ${route} must mount`);
+    }
+  });
+
+  it("mounts the flow law (the entry gate on /, intro and onboarding in the chain)", () => {
+    const GATE = read("../Sol/home/entrygate.tsx");
+    const HOME = read("../Sol/home/home.tsx");
+    const INTRO = read("../Sol/intro/intro.tsx");
+    const ONBOARDING = read("../Sol/onboarding/onboarding.tsx");
+    assert.match(GATE, /navigate\("\/intro"/, "an unseen intro navigates to the splash");
+    assert.match(GATE, /navigate\("\/onboarding"/, "an unseen onboarding navigates to the walk");
+    assert.match(HOME, /EntryGate/, "the home anchor consults the gate");
+    assert.match(INTRO, /markOnboardingStage\("intro"\)/, "the intro marks introseen");
+    assert.match(INTRO, /\/onboarding/, "the intro hands DIRECTLY to the walk");
+    assert.match(ONBOARDING, /markOnboardingStage\("onboarding"\)/, "the onboarding marks onboardingseen");
+  });
+
+  it("catalogues the seen state on the database, not just the browser", () => {
+    const PRISMA = read("../schema.prisma");
+    const DB = read("../db.ts");
+    const STATE = read("../onboardingstate.ts");
+    assert.match(PRISMA, /model OnboardingState \{/, "the prisma model stands");
+    assert.match(PRISMA, /introseen\s+Boolean/);
+    assert.match(PRISMA, /onboardingseen\s+Boolean/);
+    assert.match(DB, /onboarding_states/, "the sqlite mirror exists");
+    assert.match(DB, /getOnboardingState/, "the reader accessor exists");
+    assert.match(DB, /setOnboardingStage/, "the writer accessor exists");
+    assert.doesNotMatch(DB, /["']\s*\+\s*(visitor|stage)\b/, "no concatenated sql rides the accessors");
+    assert.match(STATE, /vault\.onboarding\.seen/, "the localStorage cache mirrors the db");
+    assert.match(STATE, /\/api\/v1\/onboarding/, "the accessor rides the platform route");
+  });
+
+  it("keeps tabular numerals on the platform numbers", () => {
+    assert.match(CSS, /font-variant-numeric:\s*tabular-nums/);
+  });
+
+  it("rests the title-bar mark on the landing (logo discipline)", () => {
+    assert.match(CSS, /data-landing/);
+    assert.ok(SHELL.includes("data-landing"), "the shell carries the landing attribute");
+  });
+
+  it("runs the family flow signature inside the mark strokes", () => {
+    assert.match(MARK, /vtMarkFlow/, "the flow layer exists on the vault mark");
+    assert.match(MARK, /vtm-flow/, "the flow gradient is declared");
+    assert.match(MARK, /prefers-reduced-motion: reduce[\s\S]*\.vtMarkFlow \{ opacity: 0/, "the flow hard-stops on reduced motion");
+  });
+
+  it("links the family row from the one table (zero drift between chrome and landing)", () => {
+    assert.match(SHELL, /from "\.\.\/\.\.\/family"/, "the shell reads family.ts");
+    const HOME = read("../Sol/home/home.tsx");
+    assert.match(HOME, /familyrow/, "the landing footer reads the same table");
+  });
+});

package/tests/family.test.ts

@@ -0,0 +1,105 @@
+// # family.test — the family table the chrome rides, runnable with the node
+// built-in runner (no dependencies, no install):
+//   node --test tests/family.test.ts
+// Every test watches the promise the row makes: the nine siblings beside
+// vault are listed once, every slug resolves through the familyurl contract
+// into a climb-one-level url, every member carries the spec §12 accent with
+// its own dot ink, and no accent ever collides with the banned palette.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { FAMILY_ACCENTS, FAMILY_SLUGS, familyAccentOf, familyrow } from "../family.ts";
+import { familyurl } from "../familyurl.ts";
+
+const BANNED = new Set(["#3b82f6", "#2563eb", "#f97316"]);
+
+describe("family table", () => {
+  it("lists the nine siblings beside vault, never vault itself", () => {
+    assert.deepEqual(FAMILY_SLUGS, [
+      "devthink",
+      "cadria",
+      "stealthhead",
+      "debonair",
+      "argan",
+      "saddle",
+      "forge",
+      "foundry",
+      "getry",
+    ]);
+    assert.ok(!FAMILY_SLUGS.includes("vault"));
+  });
+
+  it("answers an accent for every listed sibling", () => {
+    for (const slug of FAMILY_SLUGS) {
+      const member = FAMILY_ACCENTS[slug];
+      assert.ok(member, `${slug} must carry an accent`);
+      assert.equal(member.slug, slug);
+      assert.match(member.accent, /^#[0-9a-fA-F]{6}$/);
+      assert.match(member.dotInk, /^#[0-9a-fA-F]{6}$/);
+    }
+    // the table holds exactly the ten deploy units — no orphan accents
+    assert.deepEqual(Object.keys(FAMILY_ACCENTS).sort(), [
+      "argan",
+      "cadria",
+      "debonair",
+      "devthink",
+      "forge",
+      "foundry",
+      "getry",
+      "saddle",
+      "stealthhead",
+      "vault",
+    ]);
+  });
+
+  it("keeps the spec §12 accents stable, verbatim", () => {
+    assert.equal(FAMILY_ACCENTS.devthink.accent, "#F59E0B");
+    assert.equal(FAMILY_ACCENTS.argan.accent, "#34d8a8");
+    assert.equal(FAMILY_ACCENTS.cadria.accent, "#f472b6");
+    assert.equal(FAMILY_ACCENTS.debonair.accent, "#d9962e");
+    assert.equal(FAMILY_ACCENTS.forge.accent, "#a2cb3a");
+    assert.equal(FAMILY_ACCENTS.foundry.accent, "#2fb8b5");
+    assert.equal(FAMILY_ACCENTS.getry.accent, "#8b5cf6");
+    assert.equal(FAMILY_ACCENTS.saddle.accent, "#e86f2d");
+    assert.equal(FAMILY_ACCENTS.stealthhead.accent, "#e8563f");
+    assert.equal(FAMILY_ACCENTS.vault.accent, "#a3d7e6");
+  });
+
+  it("keeps the spec accent-ink column stable", () => {
+    assert.equal(FAMILY_ACCENTS.forge.dotInk, "#161d03");
+    assert.equal(FAMILY_ACCENTS.foundry.dotInk, "#03211f");
+    assert.equal(FAMILY_ACCENTS.vault.dotInk, "#072330");
+  });
+
+  it("resolves every member through the familyurl contract", () => {
+    for (const slug of FAMILY_SLUGS) {
+      assert.equal(familyurl(slug), `../${slug}/`);
+    }
+  });
+
+  it("never ships a banned hue in the row or the table", () => {
+    for (const member of [...familyrow(), ...Object.values(FAMILY_ACCENTS)]) {
+      assert.ok(!BANNED.has(member.accent.toLowerCase()), `${member.slug} rides a banned accent`);
+    }
+  });
+
+  it("builds the rail row in slug order without gaps", () => {
+    const row = familyrow();
+    assert.equal(row.length, FAMILY_SLUGS.length);
+    assert.deepEqual(
+      row.map((member) => member.slug),
+      [...FAMILY_SLUGS],
+    );
+  });
+
+  it("answers familyAccentOf for the house and falls back for unknowns", () => {
+    assert.equal(familyAccentOf("vault")?.accent, "#a3d7e6");
+    assert.equal(familyAccentOf("forge")?.accent, "#a2cb3a");
+    assert.equal(familyAccentOf("nope"), undefined);
+  });
+
+  it("keeps the familyurl contract on the verbatim climb-one-level shape", () => {
+    assert.equal(familyurl("cadria"), "../cadria/");
+    assert.equal(familyurl("/cadria/"), "../cadria/");
+    assert.equal(familyurl("cadria"), familyurl("  cadria ".trim()));
+  });
+});

package/tests/objects.test.ts

@@ -0,0 +1,164 @@
+// # objects.test — the object ledger engine of the vault, runnable with the
+// node built-in runner (no dependencies, no install):
+//   node --test tests/objects.test.ts
+// The engine rides the REAL storage contract (storage.ts): the channel
+// comes from storageModeFor, the digest validates through digestValid, the
+// record passes storageRecordValid — and the rehearsal is deterministic
+// from the seed (the same seed always seals the same vault).
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  VAULT_BUCKETS,
+  type VaultObject,
+  channelPreview,
+  digestFor,
+  digestShort,
+  fnv1a,
+  fnv1aHex,
+  formatBytes,
+  pointerTextOf,
+  sealObject,
+  seedVault,
+  vaultCensus,
+  verifyObject,
+} from "../objects.ts";
+import { digestValid, storageModeFor, storageRecordValid } from "../storage.ts";
+
+describe("seal engine", () => {
+  it("splits the channels at the real 1,000,000-byte threshold", () => {
+    assert.equal(storageModeFor(1_000_000, "text/plain"), "blob");
+    assert.equal(storageModeFor(1_000_001, "text/plain"), "lfs");
+    assert.equal(storageModeFor(4, "image/png"), "lfs");
+    assert.equal(storageModeFor(4, "video/mp4"), "lfs");
+    assert.equal(storageModeFor(4, "model/onnx"), "lfs");
+    assert.equal(storageModeFor(4, "application/octet-stream"), "lfs");
+    assert.equal(storageModeFor(2_000_000, "text/markdown"), "lfs");
+  });
+
+  it("derives digests in the exact shape the contract demands", () => {
+    const lfs = digestFor("identity · lfs", true);
+    const blob = digestFor("identity · blob", false);
+    assert.equal(lfs.length, 64, "lfs rides the sha-256 width");
+    assert.equal(blob.length, 40, "blob rides the sha-1 width");
+    assert.match(lfs, /^[0-9a-f]{64}$/);
+    assert.match(blob, /^[0-9a-f]{40}$/);
+    assert.ok(digestValid(lfs, true));
+    assert.ok(digestValid(blob, false));
+    assert.equal(digestFor("identity · lfs", true), lfs, "the digest is deterministic");
+  });
+
+  it("seals a deposit through the real record gate", () => {
+    const sealed = sealObject("family-state", "/sites/state.db", "application/x-sqlite3", 48_211_046, 0);
+    assert.equal(sealed.refusal, undefined);
+    const record = {
+      id: sealed.object.id,
+      path: sealed.object.path,
+      mime: sealed.object.mime,
+      size: sealed.object.size,
+      lfs: sealed.object.lfs,
+      digest: sealed.object.digest,
+    };
+    assert.ok(storageRecordValid(record), "the sealed record must pass the five checks");
+    assert.equal(sealed.object.lfs, true, "a 48 MB row rides lfs");
+  });
+
+  it("refuses a deposit the contract rejects — and says why", () => {
+    const sealed = sealObject("family-state", "relative/path", "text/plain", 12, 0);
+    assert.ok(sealed.refusal, "a relative path is refused");
+    assert.match(sealed.refusal!, /refuses the deposit/);
+  });
+
+  it("never issues a banned or guessed digest", () => {
+    const sealed = sealObject("site-assets", "/media/cover.png", "image/png", 2_244_880, 3);
+    assert.ok(digestValid(sealed.object.digest, sealed.object.lfs));
+    assert.equal(verifyObject(sealed.object), true, "re-sealing is byte-equal");
+  });
+
+  it("verifies a tampered object as broken", () => {
+    const sealed = sealObject("run-evidence", "/runs/421337.log", "text/plain", 12_800, 9);
+    const tampered: VaultObject = { ...sealed.object, size: sealed.object.size + 1 };
+    assert.equal(verifyObject(tampered), false, "a moved byte breaks the seal");
+  });
+
+  it("renders the three-line lfs pointer from the real writer", () => {
+    const sealed = sealObject("backups", "/backups/ledger.tzst", "application/x-tzst", 220_118_016, 0);
+    const pointer = pointerTextOf(sealed.object);
+    const lines = pointer.split("\n");
+    assert.equal(lines[0], "version https://git-lfs.github.com/spec/v1");
+    assert.equal(lines[1], `oid sha256:${sealed.object.digest}`);
+    assert.equal(lines[2], `size ${sealed.object.size}`);
+  });
+});
+
+describe("rehearsal vault", () => {
+  const vault = seedVault(20260314);
+
+  it("musters the same rows for the same seed, byte for byte", () => {
+    const again = seedVault(20260314);
+    assert.deepEqual(again, vault);
+    const other = seedVault(20260315);
+    assert.notDeepEqual(other, vault);
+  });
+
+  it("rides only the named buckets and every row is sealed and verified", () => {
+    for (const object of vault) {
+      assert.ok(VAULT_BUCKETS.includes(object.bucket as (typeof VAULT_BUCKETS)[number]), `${object.path} rides a named bucket`);
+      assert.equal(verifyObject(object), true, `${object.path} is sealed intact`);
+      assert.ok(object.size >= 0);
+      assert.ok(object.path.startsWith("/"));
+    }
+  });
+
+  it("carries both channels across the rehearsal", () => {
+    const census = vaultCensus(vault);
+    assert.ok(census.lfsRows > 0, "the lfs channel is exercised");
+    assert.ok(census.blobRows > 0, "the blob channel is exercised");
+    assert.equal(census.lfsRows + census.blobRows, census.total);
+    assert.equal(census.lfsBytes + census.blobBytes, census.bytes);
+  });
+
+  it("answers the census with the biggest row on top", () => {
+    const census = vaultCensus(vault);
+    assert.equal(census.total, vault.length);
+    assert.ok(census.biggest, "the biggest row exists");
+    for (const object of vault) {
+      assert.ok(census.biggest!.size >= object.size);
+    }
+    assert.equal(vaultCensus([]).total, 0);
+    assert.equal(vaultCensus([]).biggest, undefined);
+  });
+});
+
+describe("ledger render", () => {
+  it("formats bytes with one unit and tabular intent", () => {
+    assert.equal(formatBytes(0), "0 B");
+    assert.equal(formatBytes(512), "512 B");
+    assert.equal(formatBytes(1024), "1.0 KB");
+    assert.equal(formatBytes(1_572_864), "1.5 MB");
+    assert.equal(formatBytes(1_073_741_824), "1.0 GB");
+    assert.equal(formatBytes(2_244_880), "2.1 MB");
+  });
+
+  it("shortens a digest without inventing characters", () => {
+    const long = "a".repeat(64);
+    assert.equal(digestShort(long), "aaaaaaaa…aaaa");
+    assert.equal(digestShort("abcd1234"), "abcd1234");
+  });
+
+  it("keeps the family fnv-1a byte-exact", () => {
+    assert.equal(fnv1a(""), 0x811c9dc5);
+    assert.equal(fnv1a("a"), 0xe40c292c);
+    assert.equal(fnv1aHex("hello"), fnv1a("hello").toString(16).padStart(8, "0"));
+    assert.match(fnv1aHex("hello"), /^[0-9a-f]{8}$/);
+  });
+
+  it("previews the channel answer before anything is sealed", () => {
+    const lfs = channelPreview("video/mp4", 12);
+    assert.equal(lfs.channel, "lfs");
+    assert.match(lfs.why, /binary master or over the threshold|binary master/);
+    assert.match(lfs.digestShape, /sha-256/);
+    const blob = channelPreview("text/markdown", 1200);
+    assert.equal(blob.channel, "blob");
+    assert.match(blob.digestShape, /sha-1/);
+  });
+});

package/tests/onboardingstate.test.ts

@@ -0,0 +1,64 @@
+// # onboardingstate.test — the pure contract of the seen flags: the host
+//   validation of the platform base (https only, public hosts only) and the
+//   seen-wins stage merge the accessor and the pages share. runnable with
+//   the node built-in runner (no dependencies, no install):
+//   node --test tests/onboardingstate.test.ts
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { hostallowed, mergeStage } from "../onboardingstate.ts";
+
+describe("onboarding state", () => {
+  it("accepts public https bases", () => {
+    assert.equal(hostallowed("https://gateway.wenathlan.dev"), true);
+    assert.equal(hostallowed("https://gateway.wenathlan.dev/"), true);
+    assert.equal(hostallowed("https://vault.example.com:8443"), true);
+  });
+
+  it("refuses plaintext, localhost, loopback and every private or reserved range", () => {
+    const refused = [
+      "http://gateway.wenathlan.dev",
+      "https://localhost",
+      "https://localhost:8787",
+      "https://app.localhost",
+      "https://box.local",
+      "https://service.internal",
+      "https://127.0.0.1",
+      "https://0.0.0.0",
+      "https://10.0.0.9",
+      "https://172.16.0.1",
+      "https://172.31.255.255",
+      "https://192.168.1.4",
+      "https://169.254.10.10",
+      "https://100.64.0.1",
+      "https://192.0.2.7",
+      "https://198.51.100.7",
+      "https://203.0.113.9",
+      "https://[::1]",
+      "https://[::ffff:127.0.0.1]",
+      "https://[::ffff:10.0.0.1]",
+      "https://[fd00::1]",
+      "https://[fe80::1]",
+      "not a url",
+      "",
+    ];
+    for (const base of refused) assert.equal(hostallowed(base), false, base);
+  });
+
+  it("merges stages seen-wins — a stage never unsees", () => {
+    const fresh = { introseen: false, onboardingseen: false };
+    assert.deepEqual(mergeStage(fresh, "intro"), { introseen: true, onboardingseen: false });
+    assert.deepEqual(mergeStage(fresh, "onboarding"), { introseen: false, onboardingseen: true });
+    const half = { introseen: true, onboardingseen: false };
+    assert.deepEqual(mergeStage(half, "onboarding"), { introseen: true, onboardingseen: true });
+    assert.deepEqual(mergeStage(mergeStage(half, "onboarding"), "intro"), {
+      introseen: true,
+      onboardingseen: true,
+    });
+  });
+
+  it("never mutates the state it merges", () => {
+    const state = { introseen: false, onboardingseen: false };
+    mergeStage(state, "intro");
+    assert.deepEqual(state, { introseen: false, onboardingseen: false });
+  });
+});

package/tests/retention.test.ts

@@ -0,0 +1,133 @@
+// # retention.test — the clock engine of the vault, runnable with the node
+// built-in runner (no dependencies, no install):
+//   node --test tests/retention.test.ts
+// The clock is rehearsal time: one tick is one day, the sweep is a PLAN
+// (pure — nothing is deleted), and the same ledger, rules and tick always
+// answer the same verdicts.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { seedRules } from "../buckets.ts";
+import { sealObject, seedVault } from "../objects.ts";
+import {
+  ROLL_STEP,
+  firstDueTick,
+  horizonTick,
+  retentionVerdicts,
+  sweepPlan,
+  tickLabel,
+  verdictOf,
+} from "../retention.ts";
+
+const rules = seedRules(912731);
+const vault = seedVault(20260314);
+
+describe("verdicts", () => {
+  it("answers protected for the forever policy, whatever the age", () => {
+    const familyRow = vault.find((object) => object.bucket === "family-state");
+    assert.ok(familyRow, "the rehearsal rides the family-state bucket");
+    const verdict = verdictOf(familyRow, rules, 10_000);
+    assert.equal(verdict.state, "protected");
+    assert.match(verdict.why, /keeps forever/);
+  });
+
+  it("answers sealed inside the window and due past it", () => {
+    const object = sealObject("backups", "/backups/ledger.tzst", "application/x-tzst", 220_118_016, 0).object;
+    const backupRule = rules.find((rule) => rule.bucket === "backups")!;
+    assert.ok(backupRule.days > 0, "the backups window is finite in this rehearsal");
+    assert.equal(verdictOf(object, rules, backupRule.days).state, "sealed", "the last day is still sealed");
+    assert.equal(verdictOf(object, rules, backupRule.days + 1).state, "due", "one day past the window, the row is due");
+    assert.equal(verdictOf(object, rules, 0).state, "sealed");
+  });
+
+  it("keeps the age non-negative and the why honest", () => {
+    const object = vault[0];
+    for (const now of [0, object.sealedAt, object.sealedAt + 100]) {
+      const verdict = verdictOf(object, rules, now);
+      assert.ok(verdict.ageDays >= 0);
+      assert.ok(verdict.why.length > 0);
+    }
+  });
+
+  it("answers every row of the ledger, in ledger order", () => {
+    const verdicts = retentionVerdicts(vault, rules, 0);
+    assert.equal(verdicts.length, vault.length);
+    for (let index = 0; index < verdicts.length; index++) {
+      assert.equal(verdicts[index].object.id, vault[index].id);
+    }
+  });
+
+  it("is pure: the same inputs answer the same verdicts", () => {
+    const once = retentionVerdicts(vault, rules, 400);
+    const twice = retentionVerdicts(vault, rules, 400);
+    assert.deepEqual(twice, once);
+  });
+});
+
+describe("sweep plan", () => {
+  it("collects only due rows and never mutates the ledger", () => {
+    const before = JSON.stringify(vault);
+    const plan = sweepPlan(vault, rules, 400);
+    assert.equal(JSON.stringify(vault), before, "the plan is pure");
+    for (const verdict of plan.due) {
+      assert.equal(verdict.state, "due");
+    }
+    const planBytes = plan.due.reduce((total, verdict) => total + verdict.object.size, 0);
+    assert.equal(plan.bytes, planBytes);
+  });
+
+  it("accounts the plan bytes per bucket", () => {
+    const plan = sweepPlan(vault, rules, 400);
+    let bucketTotal = 0;
+    for (const bytes of Object.values(plan.byBucket)) bucketTotal += bytes;
+    assert.equal(bucketTotal, plan.bytes);
+    const buckets = new Set(plan.due.map((verdict) => verdict.object.bucket));
+    assert.deepEqual(Object.keys(plan.byBucket).sort(), [...buckets].sort());
+  });
+
+  it("answers an empty plan before any window can expire", () => {
+    const plan = sweepPlan(vault, rules, 0);
+    assert.equal(plan.due.length, 0);
+    assert.equal(plan.bytes, 0);
+    assert.deepEqual(plan.byBucket, {});
+  });
+});
+
+describe("the clock", () => {
+  it("binds the first due tick to the earliest seal plus window", () => {
+    const first = firstDueTick(vault, rules);
+    assert.ok(Number.isFinite(first));
+    let expected = Number.POSITIVE_INFINITY;
+    for (const object of vault) {
+      const rule = rules.find((entry) => entry.bucket === object.bucket);
+      if (!rule || rule.days === 0) continue;
+      expected = Math.min(expected, object.sealedAt + rule.days);
+    }
+    assert.equal(first, expected);
+  });
+
+  it("binds the horizon to the far end of the finite windows", () => {
+    const horizon = horizonTick(vault, rules);
+    let expected = 0;
+    for (const object of vault) {
+      const rule = rules.find((entry) => entry.bucket === object.bucket);
+      if (!rule || rule.days === 0) continue;
+      expected = Math.max(expected, object.sealedAt + rule.days);
+    }
+    assert.equal(horizon, expected);
+    assert.ok(horizon >= firstDueTick(vault, rules));
+  });
+
+  it("answers never for a shelf that only keeps forever", () => {
+    const foreverVault = vault.filter((object) => object.bucket === "family-state");
+    assert.ok(foreverVault.length > 0);
+    assert.equal(firstDueTick(foreverVault, rules), Number.POSITIVE_INFINITY);
+    assert.equal(horizonTick(foreverVault, rules), 0);
+  });
+
+  it("rolls in deterministic steps and labels the days", () => {
+    assert.equal(ROLL_STEP, 7);
+    assert.equal(tickLabel(0), "day 0");
+    assert.equal(tickLabel(1), "day 1");
+    assert.equal(tickLabel(28), "day 28");
+  });
+});