sneakoscope 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,10 @@
-# Sneakoscope Codex
+<p align="center">
+  <img src="docs/assets/sneakoscope-codex-logo.svg" alt="Sneakoscope Codex logo" width="180">
+</p>
 
-Sneakoscope Codex is a zero-runtime-dependency Node.js harness for running Codex CLI in a more controlled project workflow. It adds mandatory clarification before autonomous work, a Ralph no-question execution loop, H-Proof completion gates, conservative database safety checks, bounded logs/storage, and optional GPT Image 2 visual cartridges.
+<h1 align="center">Sneakoscope Codex</h1>
+
+Sneakoscope Codex is a zero-runtime-dependency Node.js harness for running Codex CLI in a more controlled project workflow. It adds mandatory clarification before autonomous work, a Ralph no-question execution loop, H-Proof completion gates, conservative database safety checks, bounded logs/storage, and deterministic GX visual context cartridges.
 
 ```bash
 npm i -g sneakoscope
@@ -55,7 +59,7 @@ sks ralph run latest --mock
 - **Database guard**: destructive DB operations, production writes, unsafe Supabase MCP configuration, and direct live SQL mutations are blocked or warned on.
 - **H-Proof done gate**: completion requires supported critical claims, reviewed DB safety state, acceptable visual/wiki drift, and required test evidence.
 - **Bounded runtime state**: child process output is tailed, logs are rotated/compacted, and old mission artifacts can be pruned.
-- **Visual cartridges**: `gx` creates metadata-first visual cartridges where `vgraph.json` remains the source of truth and image generation is delegated to Codex/GPT Image 2.
+- **Visual cartridges**: `gx` creates deterministic SVG/HTML visual context from `vgraph.json` and `beta.json`; no generated-image service is required.
 
 ## Ralph Workflow
 
@@ -82,7 +86,7 @@ Core invariants:
 3. New ambiguity during `run` is resolved by the sealed decision ladder.
 4. Hooks help enforce the policy, but the Sneakoscope Codex supervisor and mission files remain the source of truth.
 5. Database destructive operations are never allowed.
-6. Generated images are not authoritative; `vgraph.json` is.
+6. Rendered GX files are reproducible context artifacts; `vgraph.json` is authoritative.
 7. Unsupported critical claims block completion.
 
 ## Commands
@@ -108,7 +112,10 @@ sks db check --file ./migration.sql
 
 sks hproof check [mission-id|latest]
 sks gx init [name]
-sks gx render|validate|drift
+sks gx render [name] [--format svg|html|all]
+sks gx validate [name]
+sks gx drift [name]
+sks gx snapshot [name]
 sks profile show
 sks profile set <model>
 sks gc [--dry-run] [--json]
@@ -217,20 +224,26 @@ This creates:
 ```text
 .sneakoscope/gx/cartridges/<name>/vgraph.json
 .sneakoscope/gx/cartridges/<name>/beta.json
-.sneakoscope/gx/cartridges/<name>/image-prompt.md
+.sneakoscope/gx/cartridges/<name>/render.svg
+.sneakoscope/gx/cartridges/<name>/render.html
+.sneakoscope/gx/cartridges/<name>/validation.json
+.sneakoscope/gx/cartridges/<name>/drift.json
 ```
 
-The intended flow is metadata first:
+The intended flow is source first and deterministic:
 
 ```text
 vgraph.json
-  -> image-prompt.md
-  -> Codex $imagegen / GPT Image 2
-  -> sheet.png
-  -> vision parse.json
-  -> validate against vgraph.json
+  + beta.json
+  -> sks gx render
+  -> render.svg / render.html
+  -> sks gx validate
+  -> sks gx drift
+  -> sks gx snapshot
 ```
 
+`render.svg` embeds the normalized `vgraph.json` hash. `sks gx drift` fails when the render is missing, stale, or structurally invalid.
+
 ## TriWiki Context Compression
 
 TriWiki is a harness-level context selection strategy, not a model-internal modification. It scores claims and memory entries by geometric distance, authority, freshness, risk, and token cost, then builds small context capsules for the current mission.
@@ -251,6 +264,7 @@ Q0 raw logs only when necessary
 bin/sks.mjs              CLI executable
 src/cli/main.mjs            command router and Ralph loop
 src/core/db-safety.mjs      SQL, CLI, and MCP payload classifier
+src/core/gx-renderer.mjs    deterministic SVG/HTML visual context renderer
 src/core/hproof.mjs         done-gate evaluator
 src/core/init.mjs           project bootstrap and hook/skill installation
 src/core/retention.mjs      storage report and garbage collection policy
@@ -266,7 +280,10 @@ The published npm package is allowlisted to `bin`, `src`, `docs`, `README.md`, a
 ```bash
 npm run packcheck
 npm run selftest
+npm run sizecheck
 npm run doctor
 ```
 
+`npm run sizecheck` blocks accidental package bloat before `npm pack` or `npm publish`. Defaults: packed tarball `<=96 KiB`, unpacked package `<=320 KiB`, package files `<=40`, and each tracked file `<=256 KiB`. Override only for an intentional release with `SKS_MAX_PACK_BYTES`, `SKS_MAX_UNPACKED_BYTES`, `SKS_MAX_PACK_FILES`, or `SKS_MAX_TRACKED_FILE_BYTES`.
+
 `npm run selftest` uses the mock path and does not call a model. Live Ralph runs require a working Codex CLI installation and authentication.

package/docs/PERFORMANCE.md

@@ -1,12 +1,13 @@
 # Sneakoscope Codex performance and leak policy
 
-Sneakoscope Codex v0.2 is designed to keep runtime, package size, RAM, and storage bounded.
+Sneakoscope Codex v0.4 is designed to keep runtime, package size, RAM, and storage bounded.
 
 ## Speed
 
 - `codex exec` output is streamed to files and only a bounded tail is retained in memory.
 - Ralph cycles run under a timeout and bounded max cycles.
 - TriWiki claim selection uses bounded top-K selection instead of sorting unbounded context into prompts.
+- GX visual context renders deterministic SVG/HTML from JSON sources, avoiding external image-generation latency, cost, and nondeterminism.
 - `sks gc` runs after Ralph cycles by default.
 
 ## Package size
@@ -14,6 +15,8 @@ Sneakoscope Codex v0.2 is designed to keep runtime, package size, RAM, and stora
 - The npm package has zero runtime dependencies.
 - `@openai/codex` is no longer bundled. Users install Codex separately or set `SKS_CODEX_BIN`.
 - Optional Rust source is in `crates/` for the Git repo, but is excluded from the npm package by the `files` allowlist.
+- GX rendering uses only built-in Node.js APIs and ships as source in the npm package.
+- `npm run sizecheck` enforces package limits before pack/publish: `<=96 KiB` packed, `<=320 KiB` unpacked, `<=40` package files, and `<=256 KiB` per tracked file by default.
 
 ## Memory leaks
 
@@ -37,3 +40,9 @@ Rust is useful for CPU-heavy long-running kernels, but not for the default npm p
 Sneakoscope Codex v0.3 adds a DB Safety Guard without adding runtime dependencies. It scans hook payloads and CLI commands with bounded string traversal and blocks high-risk database operations before Codex can execute them.
 
 Blocked classes include destructive SQL, direct remote SQL mutation, `supabase db reset`, `supabase db push`, migration history repair/squash, and project/branch destructive commands. The guard is intentionally conservative: when unsure, it blocks or warns rather than allowing a potentially destructive database operation.
+
+## GX visual context policy
+
+Sneakoscope Codex v0.4 replaces model-rendered visual cartridges with deterministic code-rendered context sheets. `vgraph.json` and `beta.json` are the inputs, `render.svg` and `render.html` are reproducible outputs, and `drift.json` records whether the rendered source hash still matches the current graph.
+
+This keeps visual context cheap to regenerate, diffable in normal tooling, and safe to validate during npm packaging without network calls or model access.

package/docs/assets/sneakoscope-codex-logo.svg

@@ -0,0 +1,51 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-labelledby="title desc">
+  <title id="title">Sneakoscope Codex logo</title>
+  <desc id="desc">A brass magical danger-sensing lens with a red core, orbiting rings, and SKS initials.</desc>
+  <defs>
+    <radialGradient id="lens" cx="50%" cy="42%" r="58%">
+      <stop offset="0%" stop-color="#fff4c2"/>
+      <stop offset="42%" stop-color="#f0b54f"/>
+      <stop offset="100%" stop-color="#7b241f"/>
+    </radialGradient>
+    <linearGradient id="brass" x1="92" x2="420" y1="80" y2="432">
+      <stop offset="0%" stop-color="#ffe28a"/>
+      <stop offset="46%" stop-color="#c9872e"/>
+      <stop offset="100%" stop-color="#6c3218"/>
+    </linearGradient>
+    <linearGradient id="ink" x1="160" x2="352" y1="154" y2="358">
+      <stop offset="0%" stop-color="#311018"/>
+      <stop offset="100%" stop-color="#15070b"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="16" stdDeviation="18" flood-color="#12070a" flood-opacity=".28"/>
+    </filter>
+  </defs>
+
+  <rect width="512" height="512" rx="108" fill="#16080d"/>
+  <path fill="#241016" d="M64 346c61 66 122 96 193 96 72 0 138-34 197-101v106c0 21-17 38-38 38H102c-21 0-38-17-38-38V346Z" opacity=".65"/>
+
+  <g filter="url(#shadow)">
+    <path fill="none" stroke="url(#brass)" stroke-width="16" stroke-linecap="round" d="M99 256c41-82 95-123 158-123 62 0 115 41 156 123-41 82-94 123-156 123-63 0-117-41-158-123Z"/>
+    <path fill="none" stroke="#f4c56a" stroke-width="5" stroke-linecap="round" d="M126 256c34-61 78-92 131-92 52 0 96 31 130 92-34 61-78 92-130 92-53 0-97-31-131-92Z" opacity=".86"/>
+
+    <circle cx="256" cy="256" r="93" fill="url(#brass)"/>
+    <circle cx="256" cy="256" r="74" fill="url(#ink)"/>
+    <circle cx="256" cy="256" r="56" fill="url(#lens)"/>
+    <circle cx="237" cy="236" r="16" fill="#fff8d8" opacity=".82"/>
+    <circle cx="283" cy="282" r="9" fill="#5b1017" opacity=".75"/>
+
+    <path fill="#fff0a4" d="M256 176l14 57 55-18-42 39 43 38-56-16-14 57-14-57-56 16 43-38-42-39 55 18 14-57Z"/>
+    <circle cx="256" cy="256" r="17" fill="#7b0f17"/>
+
+    <path fill="none" stroke="#f6d37c" stroke-width="11" stroke-linecap="round" d="M256 75v36M256 401v36M75 256h36M401 256h36"/>
+    <path fill="none" stroke="#b86232" stroke-width="8" stroke-linecap="round" d="M133 132l26 26M353 354l26 26M379 132l-26 26M159 354l-26 26"/>
+
+    <g fill="#fff0bc">
+      <circle cx="127" cy="113" r="7"/>
+      <circle cx="385" cy="113" r="7"/>
+      <circle cx="127" cy="399" r="7"/>
+      <circle cx="385" cy="399" r="7"/>
+    </g>
+  </g>
+
+</svg>

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "sneakoscope",
   "displayName": "Sneakoscope Codex",
-  "version": "0.3.0",
-  "description": "Sneakoscope Codex: database-safe, performance-bounded Codex CLI harness with Ralph no-question loop, H-Proof gates, GPT Image 2 workflow, and TriWiki compression.",
+  "version": "0.4.0",
+  "description": "Sneakoscope Codex: database-safe, performance-bounded Codex CLI harness with Ralph no-question loop, H-Proof gates, deterministic GX visual context, and TriWiki compression.",
   "type": "module",
   "bin": {
     "sks": "bin/sks.mjs"
@@ -20,18 +20,24 @@
   "scripts": {
     "selftest": "node ./bin/sks.mjs selftest --mock",
     "doctor": "node ./bin/sks.mjs doctor",
-    "packcheck": "find bin src -name '*.mjs' -print0 | xargs -0 -n1 node --check",
-    "prepack": "npm run packcheck && npm run selftest",
-    "prepublishOnly": "npm run packcheck && npm run selftest"
+    "packcheck": "find bin src scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check",
+    "sizecheck": "node ./scripts/sizecheck.mjs",
+    "prepack": "npm run packcheck && npm run selftest && npm run sizecheck",
+    "prepublishOnly": "npm run packcheck && npm run selftest && npm run sizecheck"
   },
   "keywords": [
+    "sneakoscope",
     "codex",
     "sks",
+    "cli",
     "ai-agent",
     "harness",
     "ralph",
     "llm-wiki",
-    "gpt-image-2",
+    "gx",
+    "svg",
+    "deterministic",
+    "visual-context",
     "resource-safe",
     "database-safe",
     "supabase-mcp",

package/src/cli/main.mjs

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import fsp from 'node:fs/promises';
-import { projectRoot, readJson, writeJsonAtomic, writeTextAtomic, appendJsonlBounded, nowIso, exists, tmpdir, packageRoot, dirSize, formatBytes } from '../core/fsx.mjs';
+import { projectRoot, readJson, writeJsonAtomic, appendJsonlBounded, nowIso, exists, tmpdir, packageRoot, dirSize, formatBytes } from '../core/fsx.mjs';
 import { initProject } from '../core/init.mjs';
 import { getCodexInfo, runCodexExec } from '../core/codex-adapter.mjs';
 import { createMission, loadMission, findLatestMission, setCurrent, stateFile } from '../core/mission.mjs';
@@ -12,6 +12,7 @@ import { emitHook } from '../core/hooks-runtime.mjs';
 import { storageReport, enforceRetention } from '../core/retention.mjs';
 import { classifySql, classifyCommand, loadDbSafetyPolicy, safeSupabaseMcpConfig, checkSqlFile, checkDbOperation, scanDbSafety } from '../core/db-safety.mjs';
 import { rustInfo } from '../core/rust-accelerator.mjs';
+import { renderCartridge, validateCartridge, driftCartridge, snapshotCartridge } from '../core/gx-renderer.mjs';
 
 const flag = (args, name) => args.includes(name);
 const promptOf = (args) => args.filter((x) => !String(x).startsWith('--')).join(' ').trim();
@@ -38,7 +39,29 @@ export async function main(args) {
 }
 
 function help() {
-  console.log(`Sneakoscope Codex\n\nUsage:\n  sks doctor [--fix] [--json]\n  sks init\n  sks selftest [--mock]\n  sks ralph prepare "task"\n  sks ralph answer <mission-id|latest> <answers.json>\n  sks ralph run <mission-id|latest> [--mock] [--max-cycles N]\n  sks ralph status <mission-id|latest>\n  sks db policy\n  sks db scan [--migrations] [--json]\n  sks db mcp-config --project-ref <ref>\n  sks db check --sql "DROP TABLE users"\n  sks db check --command "supabase db reset"\n  sks gc [--dry-run] [--json]\n  sks stats [--json]\n`);
+  console.log(`Sneakoscope Codex
+
+Usage:
+  sks doctor [--fix] [--json]
+  sks init
+  sks selftest [--mock]
+  sks ralph prepare "task"
+  sks ralph answer <mission-id|latest> <answers.json>
+  sks ralph run <mission-id|latest> [--mock] [--max-cycles N]
+  sks ralph status <mission-id|latest>
+  sks db policy
+  sks db scan [--migrations] [--json]
+  sks db mcp-config --project-ref <ref>
+  sks db check --sql "DROP TABLE users"
+  sks db check --command "supabase db reset"
+  sks gx init [name]
+  sks gx render [name] [--format svg|html|all]
+  sks gx validate [name]
+  sks gx drift [name]
+  sks gx snapshot [name]
+  sks gc [--dry-run] [--json]
+  sks stats [--json]
+`);
 }
 
 async function doctor(args) {
@@ -241,6 +264,17 @@ async function selftest() {
   await writeJsonAtomic(path.join(dir, 'done-gate.json'), { passed: true, unsupported_critical_claims: 0, database_safety_violation: false, database_safety_reviewed: true, visual_drift: 'low', wiki_drift: 'low', tests_required: false });
   const gate = await evaluateDoneGate(tmp, id);
   if (!gate.passed) throw new Error('selftest failed: done gate');
+  const gxDir = path.join(tmp, '.sneakoscope', 'gx', 'cartridges', 'selftest');
+  await writeJsonAtomic(path.join(gxDir, 'vgraph.json'), defaultVGraph('selftest'));
+  await writeJsonAtomic(path.join(gxDir, 'beta.json'), defaultBeta('selftest'));
+  const render = await renderCartridge(gxDir, { format: 'all' });
+  if (!render.outputs.includes('render.svg')) throw new Error('selftest failed: gx svg not rendered');
+  const validation = await validateCartridge(gxDir);
+  if (!validation.ok) throw new Error('selftest failed: gx validation rejected');
+  const drift = await driftCartridge(gxDir);
+  if (drift.status !== 'low') throw new Error('selftest failed: gx drift is high');
+  const snapshot = await snapshotCartridge(gxDir);
+  if (!snapshot.files.svg || !snapshot.files.html) throw new Error('selftest failed: gx snapshot incomplete');
   const gc = await enforceRetention(tmp, { dryRun: true });
   if (!gc.report.exists) throw new Error('selftest failed: storage report');
   console.log('Sneakoscope Codex selftest passed.');
@@ -286,19 +320,114 @@ async function stats(args) {
   for (const [name, sec] of Object.entries(report.sections || {})) console.log(`- ${name}: ${sec.human}`);
 }
 
+function positionalArgs(args = []) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = String(args[i]);
+    if (arg === '--format') {
+      i++;
+      continue;
+    }
+    if (!arg.startsWith('--')) out.push(arg);
+  }
+  return out;
+}
+
+function readFlagValue(args, name, fallback) {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+}
+
+function cartridgeName(args, fallback = 'architecture-atlas') {
+  const raw = positionalArgs(args)[0] || fallback;
+  return String(raw).trim().replace(/[\\/]+/g, '-').replace(/[^A-Za-z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '') || fallback;
+}
+
+function cartridgeDir(root, name) {
+  return path.join(root, '.sneakoscope', 'gx', 'cartridges', name);
+}
+
+function defaultVGraph(name) {
+  return {
+    id: name,
+    title: 'Sneakoscope Context Map',
+    version: 1,
+    nodes: [
+      { id: 'source', label: 'vgraph source', kind: 'source', layer: 'input', status: 'safe' },
+      { id: 'contract', label: 'decision contract', kind: 'guard', layer: 'policy', status: 'safe' },
+      { id: 'proof', label: 'H-Proof gate', kind: 'guard', layer: 'verification', status: 'safe' }
+    ],
+    edges: [
+      { from: 'source', to: 'contract', label: 'constrains' },
+      { from: 'contract', to: 'proof', label: 'verifies' }
+    ],
+    invariants: [
+      'vgraph.json remains the source of truth',
+      'rendered SVG hash must match source hash'
+    ],
+    tests: [
+      'sks gx validate',
+      'sks gx drift'
+    ],
+    risks: []
+  };
+}
+
+function defaultBeta(name) {
+  return {
+    id: name,
+    version: 1,
+    read_order: ['title', 'layers', 'nodes', 'edges', 'invariants', 'tests'],
+    renderer: 'sneakoscope-codex-deterministic-svg'
+  };
+}
+
 async function gx(sub, args) {
   const root = await projectRoot();
+  const name = cartridgeName(args);
+  const dir = cartridgeDir(root, name);
   if (sub === 'init') {
-    const name = args[0] || 'architecture-atlas';
-    const dir = path.join(root, '.sneakoscope', 'gx', 'cartridges', name);
-    await writeJsonAtomic(path.join(dir, 'vgraph.json'), { id: name, version: 1, nodes: [], edges: [], invariants: [], tests: [] });
-    await writeJsonAtomic(path.join(dir, 'beta.json'), { id: name, version: 1, read_order: ['grid', 'layers', 'nodes', 'edges', 'tests'] });
-    await writeTextAtomic(path.join(dir, 'image-prompt.md'), 'Create a clean technical architecture sheet from vgraph.json. Use GPT Image 2 only.');
-    console.log(`GX cartridge initialized: ${path.relative(root, dir)}`);
+    const vgraphPath = path.join(dir, 'vgraph.json');
+    const betaPath = path.join(dir, 'beta.json');
+    const created = [];
+    if (!(await exists(vgraphPath)) || flag(args, '--force')) {
+      await writeJsonAtomic(vgraphPath, defaultVGraph(name));
+      created.push('vgraph.json');
+    }
+    if (!(await exists(betaPath)) || flag(args, '--force')) {
+      await writeJsonAtomic(betaPath, defaultBeta(name));
+      created.push('beta.json');
+    }
+    const render = await renderCartridge(dir, { format: 'all' });
+    const validation = await validateCartridge(dir);
+    const drift = await driftCartridge(dir);
+    console.log(JSON.stringify({ cartridge: path.relative(root, dir), created, render, validation: validation.ok, drift: drift.status }, null, 2));
+    return;
+  }
+  if (sub === 'render') {
+    const format = readFlagValue(args, '--format', 'all');
+    console.log(JSON.stringify(await renderCartridge(dir, { format }), null, 2));
     return;
   }
-  if (['render', 'validate', 'drift'].includes(sub)) return console.log(`GX ${sub}: metadata only; image generation is performed by Codex $imagegen in live mode.`);
-  console.error('Usage: sks gx init|render|validate|drift');
+  if (sub === 'validate') {
+    const validation = await validateCartridge(dir);
+    console.log(JSON.stringify(validation, null, 2));
+    process.exitCode = validation.ok ? 0 : 2;
+    return;
+  }
+  if (sub === 'drift') {
+    const drift = await driftCartridge(dir);
+    console.log(JSON.stringify(drift, null, 2));
+    process.exitCode = drift.status === 'low' ? 0 : 2;
+    return;
+  }
+  if (sub === 'snapshot') {
+    await renderCartridge(dir, { format: 'all' });
+    console.log(JSON.stringify(await snapshotCartridge(dir), null, 2));
+    return;
+  }
+  console.error('Usage: sks gx init|render|validate|drift|snapshot');
+  process.exitCode = 1;
 }
 
 async function team(args) {

package/src/core/decision-contract.mjs

@@ -41,7 +41,7 @@ export function buildDecisionContract({ mission, schema, answers }) {
     if_e2e_unavailable: 'run_unit_or_integration_and_record_e2e_not_executed',
     if_dependency_needed: 'avoid_new_dependency_unless_allowed_by_contract',
     if_existing_behavior_conflict: 'preserve_existing_public_behavior',
-    if_visual_cartridge_conflict: 'vgraph_json_wins_over_sheet_png',
+    if_visual_cartridge_conflict: 'vgraph_json_wins_over_rendered_gx_artifact',
     if_wiki_conflict: 'current_code_wins_over_wiki',
     if_low_confidence_claim: 'read_source_do_not_ask_user',
     if_unresolvable_optional_scope: 'defer_optional_subtask_and_complete_core_acceptance_criteria',

package/src/core/fsx.mjs

@@ -5,7 +5,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 
-export const PACKAGE_VERSION = '0.3.0';
+export const PACKAGE_VERSION = '0.4.0';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 

package/src/core/gx-renderer.mjs

@@ -0,0 +1,352 @@
+import path from 'node:path';
+import { exists, nowIso, readJson, readText, sha256, writeJsonAtomic, writeTextAtomic } from './fsx.mjs';
+
+const SVG_WIDTH = 1280;
+const SVG_HEIGHT = 820;
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function escapeXml(value = '') {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function slug(value = '') {
+  return String(value || 'item').trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'item';
+}
+
+function shortText(value = '', max = 64) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  return text.length > max ? `${text.slice(0, max - 1)}...` : text;
+}
+
+function splitLabel(value = '', maxLine = 24, maxLines = 3) {
+  const words = String(value || '').replace(/\s+/g, ' ').trim().split(' ').filter(Boolean);
+  const lines = [];
+  let current = '';
+  for (const word of words.length ? words : ['Untitled']) {
+    if (!current) current = word;
+    else if (`${current} ${word}`.length <= maxLine) current = `${current} ${word}`;
+    else {
+      lines.push(current);
+      current = word;
+    }
+    if (lines.length === maxLines) break;
+  }
+  if (current && lines.length < maxLines) lines.push(current);
+  return lines.slice(0, maxLines);
+}
+
+function normalizeNode(node, index) {
+  const id = slug(node?.id || `node-${index + 1}`);
+  return {
+    ...node,
+    id,
+    label: node?.label || node?.title || id,
+    kind: node?.kind || node?.type || 'component',
+    layer: node?.layer || node?.group || 'default',
+    risk: node?.risk || 'normal',
+    status: node?.status || 'unknown'
+  };
+}
+
+function normalizeEdge(edge, index) {
+  return {
+    ...edge,
+    id: slug(edge?.id || `edge-${index + 1}`),
+    from: slug(edge?.from || edge?.source || ''),
+    to: slug(edge?.to || edge?.target || ''),
+    label: edge?.label || edge?.kind || ''
+  };
+}
+
+export function normalizeVGraph(vgraph = {}) {
+  const nodes = Array.isArray(vgraph.nodes) ? vgraph.nodes.map(normalizeNode) : [];
+  const edges = Array.isArray(vgraph.edges) ? vgraph.edges.map(normalizeEdge) : [];
+  return {
+    id: slug(vgraph.id || vgraph.name || 'architecture-atlas'),
+    title: vgraph.title || vgraph.name || vgraph.id || 'Architecture Atlas',
+    version: vgraph.version || 1,
+    nodes,
+    edges,
+    invariants: Array.isArray(vgraph.invariants) ? vgraph.invariants : [],
+    tests: Array.isArray(vgraph.tests) ? vgraph.tests : [],
+    risks: Array.isArray(vgraph.risks) ? vgraph.risks : []
+  };
+}
+
+export function vgraphHash(vgraph = {}) {
+  return sha256(stableJson(normalizeVGraph(vgraph)));
+}
+
+function nodePalette(node) {
+  if (node.risk === 'critical' || node.status === 'blocked') return { fill: '#fee2e2', stroke: '#b91c1c', text: '#3b0a0a' };
+  if (node.risk === 'high' || node.status === 'warn') return { fill: '#ffedd5', stroke: '#c2410c', text: '#431407' };
+  if (node.status === 'passed' || node.status === 'safe') return { fill: '#dcfce7', stroke: '#15803d', text: '#052e16' };
+  if (node.kind === 'guard' || node.kind === 'policy') return { fill: '#e0f2fe', stroke: '#0369a1', text: '#082f49' };
+  return { fill: '#f8fafc', stroke: '#475569', text: '#0f172a' };
+}
+
+function layoutNodes(nodes) {
+  if (!nodes.length) return new Map();
+  const layers = [...new Set(nodes.map((node) => node.layer))].sort();
+  const byLayer = new Map(layers.map((layer) => [layer, nodes.filter((node) => node.layer === layer).sort((a, b) => a.id.localeCompare(b.id))]));
+  const positions = new Map();
+  const top = 170;
+  const bottom = 530;
+  const left = 92;
+  const right = 1188;
+  const layerGap = layers.length > 1 ? (bottom - top) / (layers.length - 1) : 0;
+  for (let li = 0; li < layers.length; li++) {
+    const layer = layers[li];
+    const row = byLayer.get(layer);
+    const y = layers.length > 1 ? top + li * layerGap : 300;
+    const gap = row.length > 1 ? (right - left) / (row.length - 1) : 0;
+    for (let i = 0; i < row.length; i++) {
+      const node = row[i];
+      const x = row.length > 1 ? left + i * gap : SVG_WIDTH / 2;
+      positions.set(node.id, { x, y, w: 196, h: 82, layer });
+    }
+  }
+  return positions;
+}
+
+function renderList(items, x, y, title) {
+  const lines = [`<text x="${x}" y="${y}" class="section-title">${escapeXml(title)}</text>`];
+  if (!items.length) {
+    lines.push(`<text x="${x}" y="${y + 34}" class="muted">No entries</text>`);
+    return lines.join('\n');
+  }
+  for (let i = 0; i < Math.min(items.length, 5); i++) {
+    const item = items[i];
+    const label = typeof item === 'string' ? item : (item.label || item.id || item.title || JSON.stringify(item));
+    lines.push(`<text x="${x}" y="${y + 34 + i * 28}" class="list-item">- ${escapeXml(shortText(label, 72))}</text>`);
+  }
+  if (items.length > 5) lines.push(`<text x="${x}" y="${y + 34 + 5 * 28}" class="muted">+ ${items.length - 5} more</text>`);
+  return lines.join('\n');
+}
+
+export function renderVGraphSvg(vgraph = {}, beta = {}) {
+  const graph = normalizeVGraph(vgraph);
+  const hash = vgraphHash(graph);
+  const positions = layoutNodes(graph.nodes);
+  const layers = [...new Set(graph.nodes.map((node) => node.layer))].sort();
+  const generatedAt = nowIso();
+  const edgeLines = graph.edges.map((edge) => {
+    const from = positions.get(edge.from);
+    const to = positions.get(edge.to);
+    if (!from || !to) return '';
+    const x1 = from.x;
+    const y1 = from.y + from.h / 2;
+    const x2 = to.x;
+    const y2 = to.y - to.h / 2;
+    const midX = (x1 + x2) / 2;
+    const midY = (y1 + y2) / 2;
+    return `<g class="edge">
+      <line x1="${x1}" y1="${y1}" x2="${x2}" y2="${y2}" marker-end="url(#arrow)"/>
+      ${edge.label ? `<text x="${midX}" y="${midY - 8}" class="edge-label">${escapeXml(shortText(edge.label, 28))}</text>` : ''}
+    </g>`;
+  }).join('\n');
+  const layerBands = layers.map((layer, index) => {
+    const y = layers.length > 1 ? 132 + index * (398 / Math.max(1, layers.length - 1)) : 250;
+    return `<text x="40" y="${y}" class="layer-label">${escapeXml(layer)}</text>`;
+  }).join('\n');
+  const nodeCards = graph.nodes.map((node) => {
+    const pos = positions.get(node.id);
+    const palette = nodePalette(node);
+    const labelLines = splitLabel(node.label);
+    const tag = `${node.kind} / ${node.status}`;
+    return `<g class="node" transform="translate(${pos.x - pos.w / 2} ${pos.y - pos.h / 2})">
+      <rect width="${pos.w}" height="${pos.h}" rx="14" fill="${palette.fill}" stroke="${palette.stroke}" stroke-width="3"/>
+      <text x="18" y="27" class="node-title" fill="${palette.text}">${escapeXml(labelLines[0])}</text>
+      ${labelLines.slice(1).map((line, i) => `<text x="18" y="${49 + i * 18}" class="node-title small" fill="${palette.text}">${escapeXml(line)}</text>`).join('\n')}
+      <text x="18" y="${pos.h - 14}" class="node-meta" fill="${palette.text}">${escapeXml(shortText(tag, 34))}</text>
+    </g>`;
+  }).join('\n');
+  const emptyState = graph.nodes.length ? '' : `<g class="empty">
+    <rect x="332" y="214" width="616" height="178" rx="18"/>
+    <text x="640" y="291" text-anchor="middle" class="empty-title">No graph nodes defined</text>
+    <text x="640" y="329" text-anchor="middle" class="muted">Edit vgraph.json, then run sks gx render ${escapeXml(graph.id)}</text>
+  </g>`;
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="${SVG_WIDTH}" height="${SVG_HEIGHT}" viewBox="0 0 ${SVG_WIDTH} ${SVG_HEIGHT}" role="img" aria-labelledby="title desc" data-generator="sneakoscope-codex" data-vgraph-id="${escapeXml(graph.id)}" data-vgraph-hash="${hash}" data-generated-at="${generatedAt}">
+  <title id="title">${escapeXml(graph.title)}</title>
+  <desc id="desc">Deterministic visual context sheet generated from vgraph.json.</desc>
+  <defs>
+    <marker id="arrow" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto" markerUnits="strokeWidth">
+      <path d="M2,2 L10,6 L2,10 Z" fill="#475569"/>
+    </marker>
+    <style>
+      .title { font: 800 38px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #111827; }
+      .subtitle, .muted { font: 500 18px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #64748b; }
+      .section-title { font: 800 24px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #111827; }
+      .list-item { font: 500 18px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #334155; }
+      .layer-label { font: 800 17px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #94a3b8; text-transform: uppercase; }
+      .node-title { font: 800 17px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      .node-title.small { font-size: 15px; font-weight: 700; }
+      .node-meta { font: 700 12px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; opacity: .72; text-transform: uppercase; }
+      .edge line { stroke: #475569; stroke-width: 2.5; }
+      .edge-label { font: 700 13px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #475569; paint-order: stroke; stroke: #f8fafc; stroke-width: 5px; }
+      .empty rect { fill: #f8fafc; stroke: #cbd5e1; stroke-width: 2; }
+      .empty-title { font: 800 26px ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #334155; }
+    </style>
+  </defs>
+  <rect width="${SVG_WIDTH}" height="${SVG_HEIGHT}" fill="#ffffff"/>
+  <rect x="0" y="0" width="${SVG_WIDTH}" height="108" fill="#f8fafc"/>
+  <text x="42" y="56" class="title">${escapeXml(graph.title)}</text>
+  <text x="42" y="86" class="subtitle">vgraph:${escapeXml(graph.id)} hash:${hash.slice(0, 12)} nodes:${graph.nodes.length} edges:${graph.edges.length} generated:${generatedAt}</text>
+  ${layerBands}
+  ${edgeLines}
+  ${nodeCards}
+  ${emptyState}
+  <line x1="42" y1="590" x2="1238" y2="590" stroke="#e2e8f0" stroke-width="2"/>
+  ${renderList(graph.invariants, 52, 638, 'Invariants')}
+  ${renderList(graph.tests, 690, 638, 'Tests')}
+  <text x="52" y="784" class="muted">Source: vgraph.json. Layout/read-order: ${escapeXml(beta?.id || graph.id)}. Renderer: Sneakoscope Codex deterministic GX.</text>
+</svg>
+`;
+}
+
+export function renderVGraphHtml(vgraph = {}, beta = {}, svg = renderVGraphSvg(vgraph, beta)) {
+  const graph = normalizeVGraph(vgraph);
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeXml(graph.title)} - Sneakoscope Codex</title>
+  <style>
+    body { margin: 0; font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #f1f5f9; color: #0f172a; }
+    main { max-width: 1320px; margin: 0 auto; padding: 24px; }
+    .sheet { background: white; border: 1px solid #cbd5e1; overflow: auto; }
+    svg { display: block; width: 100%; height: auto; }
+    pre { padding: 16px; background: #0f172a; color: #e2e8f0; overflow: auto; }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="sheet">${svg.replace(/^<\?xml[^>]*>\s*/, '')}</div>
+    <h2>Context Packet</h2>
+    <pre>${escapeXml(JSON.stringify({ vgraph: normalizeVGraph(vgraph), beta }, null, 2))}</pre>
+  </main>
+</body>
+</html>
+`;
+}
+
+export function validateVGraph(vgraph = {}, beta = {}) {
+  const graph = normalizeVGraph(vgraph);
+  const issues = [];
+  const warnings = [];
+  const ids = new Set();
+  if (!graph.id) issues.push({ id: 'missing_graph_id', severity: 'error', reason: 'vgraph.id is required.' });
+  for (const node of graph.nodes) {
+    if (ids.has(node.id)) issues.push({ id: 'duplicate_node_id', severity: 'error', node: node.id, reason: 'Node ids must be unique.' });
+    ids.add(node.id);
+    if (!node.label) warnings.push({ id: 'missing_node_label', severity: 'warning', node: node.id, reason: 'Node has no label.' });
+  }
+  for (const edge of graph.edges) {
+    if (!ids.has(edge.from)) issues.push({ id: 'missing_edge_source', severity: 'error', edge: edge.id, from: edge.from });
+    if (!ids.has(edge.to)) issues.push({ id: 'missing_edge_target', severity: 'error', edge: edge.id, to: edge.to });
+  }
+  if (beta?.read_order && !Array.isArray(beta.read_order)) issues.push({ id: 'invalid_read_order', severity: 'error', reason: 'beta.read_order must be an array when present.' });
+  if (!graph.nodes.length) warnings.push({ id: 'empty_graph', severity: 'warning', reason: 'vgraph contains no nodes.' });
+  return {
+    checked_at: nowIso(),
+    ok: issues.length === 0,
+    graph_id: graph.id,
+    source_hash: vgraphHash(graph),
+    counts: { nodes: graph.nodes.length, edges: graph.edges.length, invariants: graph.invariants.length, tests: graph.tests.length },
+    issues,
+    warnings
+  };
+}
+
+function extractRenderHash(text = '') {
+  const match = String(text).match(/\bdata-vgraph-hash="([^"]+)"/);
+  return match ? match[1] : null;
+}
+
+export async function renderCartridge(dir, { format = 'all' } = {}) {
+  const vgraph = await readJson(path.join(dir, 'vgraph.json'));
+  const beta = await readJson(path.join(dir, 'beta.json'), {});
+  const svg = renderVGraphSvg(vgraph, beta);
+  const outputs = [];
+  if (format === 'all' || format === 'svg') {
+    await writeTextAtomic(path.join(dir, 'render.svg'), svg);
+    outputs.push('render.svg');
+  }
+  if (format === 'all' || format === 'html') {
+    await writeTextAtomic(path.join(dir, 'render.html'), renderVGraphHtml(vgraph, beta, svg));
+    outputs.push('render.html');
+  }
+  if (!outputs.length) throw new Error('Unsupported GX render format. Use svg, html, or all.');
+  return { graph_id: normalizeVGraph(vgraph).id, source_hash: vgraphHash(vgraph), outputs };
+}
+
+export async function validateCartridge(dir) {
+  const vgraph = await readJson(path.join(dir, 'vgraph.json'));
+  const beta = await readJson(path.join(dir, 'beta.json'), {});
+  const validation = validateVGraph(vgraph, beta);
+  await writeJsonAtomic(path.join(dir, 'validation.json'), validation);
+  return validation;
+}
+
+export async function driftCartridge(dir) {
+  const vgraph = await readJson(path.join(dir, 'vgraph.json'));
+  const sourceHash = vgraphHash(vgraph);
+  const renderPath = path.join(dir, 'render.svg');
+  const renderText = await readText(renderPath, '');
+  const renderHash = renderText ? extractRenderHash(renderText) : null;
+  const validation = validateVGraph(vgraph, await readJson(path.join(dir, 'beta.json'), {}));
+  const reasons = [];
+  if (!renderText) reasons.push('render_svg_missing');
+  if (renderText && !renderHash) reasons.push('render_svg_missing_vgraph_hash');
+  if (renderHash && renderHash !== sourceHash) reasons.push('render_svg_stale');
+  for (const issue of validation.issues) reasons.push(`validation:${issue.id}`);
+  const drift = {
+    checked_at: nowIso(),
+    status: reasons.length ? 'high' : 'low',
+    source_hash: sourceHash,
+    render_hash: renderHash,
+    reasons,
+    validation
+  };
+  await writeJsonAtomic(path.join(dir, 'drift.json'), drift);
+  return drift;
+}
+
+export async function snapshotCartridge(dir) {
+  const vgraph = await readJson(path.join(dir, 'vgraph.json'));
+  const beta = await readJson(path.join(dir, 'beta.json'), {});
+  const validation = await validateCartridge(dir);
+  const drift = await driftCartridge(dir);
+  const snapshot = {
+    created_at: nowIso(),
+    graph_id: normalizeVGraph(vgraph).id,
+    source_hash: vgraphHash(vgraph),
+    files: {
+      vgraph: 'vgraph.json',
+      beta: 'beta.json',
+      svg: await exists(path.join(dir, 'render.svg')) ? 'render.svg' : null,
+      html: await exists(path.join(dir, 'render.html')) ? 'render.html' : null
+    },
+    validation,
+    drift,
+    vgraph: normalizeVGraph(vgraph),
+    beta
+  };
+  await writeJsonAtomic(path.join(dir, 'snapshot.json'), snapshot);
+  return snapshot;
+}

package/src/core/init.mjs

@@ -22,8 +22,8 @@ Sneakoscope Codex keeps runtime state bounded. Do not write large raw logs into
 2. decision-contract.json
 3. vgraph.json
 4. beta.json
-5. LLM Wiki
-6. visual parse
+5. GX render/snapshot metadata
+6. LLM Wiki
 7. model knowledge only if explicitly allowed
 
 ## Database Safety
@@ -50,7 +50,8 @@ export async function initProject(root, opts = {}) {
     no_external_tools: true,
     codex_required: true,
     native_runtime_dependencies: 0,
-    database_safety: 'destructive_db_operations_denied_always'
+    database_safety: 'destructive_db_operations_denied_always',
+    gx_renderer: 'deterministic_svg_html'
   });
   created.push('.sneakoscope/manifest.json');
 
@@ -82,6 +83,11 @@ export async function initProject(root, opts = {}) {
         live_database_mode: 'read_only',
         destructive_operations_allowed: false,
         mcp_write_tools_allowed: false
+      },
+      gx: {
+        renderer: 'deterministic_svg_html',
+        source_of_truth: 'vgraph.json',
+        external_image_generation: false
       }
     });
     created.push('.sneakoscope/policy.json');
@@ -120,11 +126,11 @@ async function installSkills(root) {
     'ralph-supervisor': `---\nname: ralph-supervisor\ndescription: Run the Ralph no-question loop after a decision contract is sealed.\n---\n\nYou are the Ralph Supervisor.\n\nRules:\n- Never ask the user during Ralph run.\n- Use decision-contract.json and the decision ladder.\n- Continue until done-gate.json passes or safe scope is completed with explicit limitation.\n- Keep outputs bounded. Write raw logs to files and summarize only tails.\n- Database destructive operations are never allowed.\n- Write progress to .sneakoscope mission files.\n`,
     'ralph-resolver': `---\nname: ralph-resolver\ndescription: Resolve newly discovered ambiguity during Ralph using the sealed decision ladder, without asking the user.\n---\n\nResolve ambiguity in this order: seed contract, explicit answers, approved defaults, AGENTS.md, current code/tests, smallest reversible change, defer optional scope. Never ask the user. If database risk is involved, prefer read-only, no-op, local-only migration file, or safe limitation; never run destructive SQL.\n`,
     'hproof-claim-ledger': `---\nname: hproof-claim-ledger\ndescription: Extract atomic claims and classify support status.\n---\n\nEvery factual statement must become an atomic claim. Unsupported critical claims cannot be used for implementation or final answer. Database claims require DB safety evidence.\n`,
-    'hproof-evidence-bind': `---\nname: hproof-evidence-bind\ndescription: Bind claims to code, tests, decision contract, vgraph, beta, wiki, or visual parse evidence.\n---\n\nEvidence priority: current code/tests, decision-contract.json, vgraph.json, beta.json, wiki, visual parse, user prompt. Database claims must respect .sneakoscope/db-safety.json.\n`,
+    'hproof-evidence-bind': `---\nname: hproof-evidence-bind\ndescription: Bind claims to code, tests, decision contract, vgraph, beta, wiki, or GX render evidence.\n---\n\nEvidence priority: current code/tests, decision-contract.json, vgraph.json, beta.json, GX snapshot/render metadata, wiki, user prompt. Database claims must respect .sneakoscope/db-safety.json.\n`,
     'db-safety-guard': `---\nname: db-safety-guard\ndescription: Enforce Sneakoscope Codex database safety before using SQL, Supabase MCP, Postgres, Prisma, Drizzle, Knex, or migration commands.\n---\n\nRules:\n- Never run DROP, TRUNCATE, mass DELETE/UPDATE, db reset, db push, project deletion, branch reset/merge/delete, or RLS-disabling operations.\n- Supabase MCP must be read-only and project-scoped by default.\n- Live writes through execute_sql are blocked; use migration files and only local/preview branches if explicitly allowed.\n- Production writes are forbidden.\n- If unsure, read-only only.\n`,
-    'gx-visual-generate': `---\nname: gx-visual-generate\ndescription: Generate a visual sheet using GPT Image 2 from vgraph.json and beta.json.\n---\n\nUse built-in GPT Image 2 / $imagegen only. Do not use external diagram tools. vgraph.json is source of truth.\n`,
-    'gx-visual-read': `---\nname: gx-visual-read\ndescription: Read a Sneakoscope Codex visual sheet and produce parse.json.\n---\n\nExtract nodes, edges, invariants, tests, risks, and uncertainties. Do not infer hidden nodes.\n`,
-    'gx-visual-validate': `---\nname: gx-visual-validate\ndescription: Validate visual parse against vgraph.json and beta.json.\n---\n\nIf critical nodes, edges, or invariants are missing, mark validation failed.\n`,
+    'gx-visual-generate': `---\nname: gx-visual-generate\ndescription: Render a deterministic SVG/HTML visual sheet from vgraph.json and beta.json.\n---\n\nUse sks gx render. Do not use external image generation. vgraph.json is the source of truth and the SVG embeds its source hash.\n`,
+    'gx-visual-read': `---\nname: gx-visual-read\ndescription: Read a Sneakoscope Codex deterministic visual sheet and produce context notes.\n---\n\nExtract nodes, edges, invariants, tests, risks, and uncertainties from vgraph.json, beta.json, render.svg, or snapshot.json. Do not infer hidden nodes.\n`,
+    'gx-visual-validate': `---\nname: gx-visual-validate\ndescription: Validate render metadata against vgraph.json and beta.json.\n---\n\nRun sks gx validate and sks gx drift. If critical nodes, edges, or invariants are missing or the render hash is stale, mark validation failed.\n`,
     'turbo-context-pack': `---\nname: turbo-context-pack\ndescription: Build ultra-low-token context packet with Q4 bits, Q3 tags, top-K claims, and minimal evidence.\n---\n\nDefault to Q4/Q3 only. Add Q2 or Q1 only when needed for support or verification.\n`
   };
   for (const [name, content] of Object.entries(skills)) {