@descix/frqtl-node 0.6.0-p1.1 → 0.6.0

package/dist/shim/render-state/apply.js

@@ -5,7 +5,7 @@
  * that applies a renderState bag to a booted runner.
  *
  * A renderState bag (renderer/seed load-time selections + render rows + camera + backdrop
- * visibility + page controls) is replayed by every host: the GYM rung frame, STUDIO, the bundle's
+ * visibility) is replayed by every host: the GYM rung frame, STUDIO, the bundle's
  * `bootRecipe`, the hosted eyes. They all come through `RenderState.apply` — directly (the bundle,
  * which is its own page) or through the blank page's door `FrqtlPage.applyRenderState`
  * (lib/frqtl/experiments/empty/index.html). A host never restates the procedure.
@@ -37,8 +37,13 @@
  *                                          census LO marked `backdrop === true`, or null. STUDIO's
  *                                          save captures its visibility through it, so capture and
  *                                          replay read one fact.
- *   normalizeSavedRenderState(raw)       — tolerant normalizer for a LOADED bag; THROWS only on a bag
- *                                          that carries page controls (they are author code now).
+ *   RENDER_STATE_KEYS                    — THE key table of a bag, in the order the normalized bag is written;
+ *                                          each row normalizes its own value.
+ *   RENDER_STATE_VERSION                 — 1, the one version a bag may declare.
+ *   normalizeSavedRenderState(raw)       — a bag (or null: no boot bag) → the full bag off RENDER_STATE_KEYS.
+ *                                          THROWS on a key outside the table (naming it and the table), on
+ *                                          another version, on page controls (author code now), and on a
+ *                                          value that is neither a plain object nor null.
  *   pickCameraReplay(saved)              — pure decision: named preset over raw orbit.
  *   partitionRenderRows(rows, declared, known) — apply / retain / throw, before anything is written.
  *   renderRowsFromBag(bag)               — a { key: value } render-option bag as ordered rows.
@@ -70,13 +75,42 @@ function pickCameraReplay(saved) {
     return null;
 }
 
+/** The one version a renderState bag may declare (an absent version is this one). */
+var RENDER_STATE_VERSION = 1;
+
+/**
+ * THE key table of a renderState bag, in the order the normalized bag is written. Each row's `normalize(value)`
+ * takes the raw value (undefined when the key is absent) to the stored form; an absent or malformed value is the
+ * neutral one (null / []), which `apply` writes nothing for.
+ * @type {ReadonlyArray<{key: string, normalize: function(*): *}>}
+ */
+var RENDER_STATE_KEYS = Object.freeze([
+    { key: 'version', normalize: function (v) {
+        if (v === undefined || v === RENDER_STATE_VERSION) { return RENDER_STATE_VERSION; }
+        throw new Error('[render-state] renderState.version ' + JSON.stringify(v) + ' — this owner reads version ' +
+            RENDER_STATE_VERSION + ' only. (FAIL-LOUD.)');
+    } },
+    { key: 'renderer', normalize: function (v) { return (typeof v === 'string' && v.length > 0) ? v : null; } },
+    { key: 'engine', normalize: function (v) { return (typeof v === 'string' && v.length > 0) ? v : null; } },
+    { key: 'seed', normalize: function (v) { return (v !== undefined && v !== null && v !== '') ? String(v) : null; } },
+    { key: 'backdropVisible', normalize: function (v) { return (typeof v === 'boolean') ? v : null; } },
+    { key: 'camera', normalize: function (v) {
+        if (!_isPlainObject(v)) { return null; }
+        return { orbit: _isPlainObject(v.orbit) ? v.orbit : null, preset: (typeof v.preset === 'string') ? v.preset : null };
+    } },
+    { key: 'render', normalize: function (v) {
+        return Array.isArray(v) ? v.filter(function (row) {
+            return _isPlainObject(row) && typeof row.key === 'string' && row.key.length > 0;
+        }) : [];
+    } }
+].map(Object.freeze));
+
 /**
- * Tolerant normalizer for a saved module's `renderState` field — a stored record may be
- * `undefined` (a pre-S6 legacy module), `null`, or a shape from another `version` — NEVER throws;
- * every missing/malformed field degrades to a NEUTRAL default (empty array / null), one `apply`
- * writes nothing for.
+ * The full renderState bag of `raw`, built off RENDER_STATE_KEYS: a bag (a host's capture, a registry rung's, a
+ * stored folder row's, an export's boot bag) or `null` (no boot bag — the one-file Import) → every key, in table
+ * order. An owner refuses what is not in its contract: a silent drop would be a silent fallback.
  *
- * @param {*} raw
+ * @param {object|null} raw
  * @returns {{
  *   version: number,
  *   renderer: string|null,
@@ -86,34 +120,33 @@ function pickCameraReplay(saved) {
  *   camera: {orbit:object|null, preset:string|null}|null,
  *   render: {key:string, value:*}[]
  * }}
- * @throws {Error} a bag whose `pageControls` holds a row — page controls are declared in the sketch's own
- *   code, so a saved bag never carries them; migrate the project (move the controls into its sketch).
+ * @throws {Error} a key outside RENDER_STATE_KEYS (named, beside the table); a version other than
+ *   RENDER_STATE_VERSION; a bag carrying `pageControls` — page controls are declared in the sketch's own code, so a
+ *   saved bag never carries them (migrate the project: move the controls into its sketch); and a value that is
+ *   neither a plain object nor null (`undefined` included: a caller with no bag passes null).
  */
 function normalizeSavedRenderState(raw) {
-    var r = _isPlainObject(raw) ? raw : {};
-    if (Array.isArray(r.pageControls) && r.pageControls.length > 0) {
+    if (raw !== null && !_isPlainObject(raw)) {
+        throw new Error('[render-state] a renderState is a bag (a plain object) or null for none — got ' +
+            (raw === undefined ? 'undefined' : Array.isArray(raw) ? 'an array' : typeof raw) + '. (FAIL-LOUD.)');
+    }
+    var r = raw || {};
+    if (Object.prototype.hasOwnProperty.call(r, 'pageControls')) {
+        var rows = Array.isArray(r.pageControls) ? r.pageControls : [];
         throw new Error('[render-state] this saved project carries page controls (renderState.pageControls: ' +
-            r.pageControls.map(function (row) { return _isPlainObject(row) ? String(row.id) : '?'; }).join(', ') +
+            (rows.map(function (row) { return _isPlainObject(row) ? String(row.id) : '?'; }).join(', ') || 'an empty list') +
             ') — page controls are declared in the sketch\'s own code; move them into the sketch and save again. (FAIL-LOUD.)');
     }
-    var camera = null;
-    if (_isPlainObject(r.camera)) {
-        camera = {
-            orbit: _isPlainObject(r.camera.orbit) ? r.camera.orbit : null,
-            preset: (typeof r.camera.preset === 'string') ? r.camera.preset : null
-        };
-    }
-    return {
-        version: (typeof r.version === 'number') ? r.version : 1,
-        renderer: (typeof r.renderer === 'string' && r.renderer.length > 0) ? r.renderer : null,
-        engine: (typeof r.engine === 'string' && r.engine.length > 0) ? r.engine : null,
-        seed: (r.seed !== undefined && r.seed !== null && r.seed !== '') ? String(r.seed) : null,
-        backdropVisible: (typeof r.backdropVisible === 'boolean') ? r.backdropVisible : null,
-        camera: camera,
-        render: Array.isArray(r.render) ? r.render.filter(function (row) {
-            return _isPlainObject(row) && typeof row.key === 'string' && row.key.length > 0;
-        }) : []
-    };
+    var known = RENDER_STATE_KEYS.map(function (row) { return row.key; });
+    Object.keys(r).forEach(function (k) {
+        if (known.indexOf(k) === -1) {
+            throw new Error('[render-state] renderState has no key "' + k + '" — its keys (RENDER_STATE_KEYS): ' +
+                known.join(', ') + '. (FAIL-LOUD.)');
+        }
+    });
+    var out = {};
+    RENDER_STATE_KEYS.forEach(function (row) { out[row.key] = row.normalize(r[row.key]); });
+    return out;
 }
 
 /**
@@ -252,6 +285,8 @@ function apply(runner, bag, env) {
 export {
     apply,
     backdropOf,
+    RENDER_STATE_KEYS,
+    RENDER_STATE_VERSION,
     normalizeSavedRenderState,
     pickCameraReplay,
     partitionRenderRows,

package/dist/shim/render-state/index.js

@@ -11,7 +11,9 @@
  * ── Layer 1: API contract ────────────────────────────────────────────────────
  *
  *   RenderState                        — the owner object: RenderState.apply(runner, bag, env).
- *   normalizeSavedRenderState(raw)     — tolerant normalizer for a LOADED bag (never throws).
+ *   RENDER_STATE_KEYS, RENDER_STATE_VERSION — the bag's key table and its one version.
+ *   normalizeSavedRenderState(raw)     — a bag or null → the full bag; THROWS on a key outside the table, another
+ *                                        version, page controls, or a non-bag.
  *   pickCameraReplay(saved)            — pure decision: named preset over raw orbit.
  *   partitionRenderRows(rows, declared, known)
  *                                      — resolve render rows against the TARGET renderer.
@@ -29,7 +31,7 @@
 
 // The one owner of the renderState contract and its apply procedure.
 import * as RenderState from './apply.js';
-import { normalizeSavedRenderState, pickCameraReplay, partitionRenderRows, renderRowsFromBag } from './apply.js';
+import { RENDER_STATE_KEYS, RENDER_STATE_VERSION, normalizeSavedRenderState, pickCameraReplay, partitionRenderRows, renderRowsFromBag } from './apply.js';
 
 // ── applySavedUrlOverrides ───────────────────────────────────────────────────
 
@@ -65,6 +67,8 @@ function applySavedUrlOverrides(src, overrides) {
 // ── Export ────────────────────────────────────────────────────────────────────
 
 export {
+    RENDER_STATE_KEYS,
+    RENDER_STATE_VERSION,
     RenderState,
     normalizeSavedRenderState,
     pickCameraReplay,

package/dist/shim/runtime/index.js

@@ -133,7 +133,7 @@ var _renderObj = {
  * naming the global and the gate, rather than yielding undefined or null. A soft
  * return is exactly what turns a boot-ordering defect into an opaque
  * property-access TypeError one frame later ("Cannot read properties of null
- * (reading 'build')" — FRAQTL #73); the throw names what was unavailable instead.
+ * (reading 'build')"); the throw names what was unavailable instead.
  * That covers the constructor members (`FrqtlApp`, `RecipeContext`) and every getter generated from
  * the member table (CAPS_FRQTL_MEMBERS): there is no soft residual.
  *
@@ -441,7 +441,7 @@ function _runMath(code, fileId, sourceUrl) {
  * handle minted before the call is dead — a later use throws
  * `arena:stale-handle`. For `js-reference` it is a no-op.
  *
- * THE SCOPE RULE (FRAQTL issue #67): a math scope is one RUN, and the caller
+ * THE SCOPE RULE: a math scope is one RUN, and the caller
  * that knows what a run is owns the boundary. Two run units exist, each stated
  * once: the `run()` lane's unit is one code buffer (it calls this in its own
  * `finally`); a notebook's unit is one notebook run, so `NotebookKernel` calls
@@ -576,7 +576,7 @@ function _runMathModule(code, sdk, sourceUrl) {
  *   - _ensureMathSdk()                          (resolved SDK + backend select)
  *   - the stashed-console tee (the 7cc5520 lesson — observers never re-emit)
  *
- * It does NOT end the math scope: a cell is not a run (FRAQTL issue #67). Its
+ * It does NOT end the math scope: a cell is not a run. Its
  * declared outputs are committed into the caller's binding store and must stay
  * usable in later cells, so the scope boundary belongs to whoever owns that
  * store — see `resetMathScope()`.
@@ -839,7 +839,7 @@ function runCell(spec) {
             // NO math-scope reset here. A cell is not a run: the values this cell
             // just returned are about to be committed into the caller's binding
             // store, and draining the arena would make every one of them a stale
-            // handle before the next cell could read it (FRAQTL issue #67). The
+            // handle before the next cell could read it. The
             // scope boundary is the binding store's — see resetMathScope().
         });
     }).catch(function (e) {

package/dist/shim/storage/codec-chains.js

@@ -0,0 +1,88 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/storage/codec-chains.js — THE owner of a ROSETTA codec chain saved in browser storage.
+ *
+ * A codec chain is one module text (the codec page's `chainToModule` output) under a name. It is not a sketch
+ * project (frqtl.json is "kind": "scene"), so it has its own small store:
+ *
+ *   CODEC_CHAINS_NAMESPACE = 'codec-chains'
+ *   CODEC_CHAIN_KEYS       = ['name', 'source']   the stored row, keyed by `name`
+ *
+ *   saveChain(provider, row)              → name   Save: write under its own name (overwrites)
+ *   saveChainAs(provider, row, newName)   → newName Save As: REFUSED when newName is taken
+ *   loadChain(provider, name)             → row | null
+ *   listChains(provider)                  → [{ name }] ascending
+ *   deleteChain(provider, name)
+ *
+ * The name follows the storage seam's key rule (index.js checkStorageKey), as a project folder's does. The
+ * codec page's deep link `?module=<name>` is a key of this namespace.
+ *
+ * FAIL-LOUD. Layer 2 (physics): none.
+ */
+
+'use strict';
+
+import { checkStorageKey } from './index.js';
+
+export var CODEC_CHAINS_NAMESPACE = 'codec-chains';
+export var CODEC_CHAIN_KEYS = Object.freeze(['name', 'source']);
+
+function _fail(msg) {
+    throw new Error('[codec-chains] ' + msg + ' (FAIL-LOUD.)');
+}
+
+/** @returns {Readonly<{name: string, source: string}>} */
+export function normalizeChainRow(row) {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) {
+        _fail('a codec chain row is { ' + CODEC_CHAIN_KEYS.join(', ') + ' } (got ' + (row === null ? 'null' : typeof row) + ').');
+    }
+    var unknown = Object.keys(row).filter(function (k) { return CODEC_CHAIN_KEYS.indexOf(k) === -1; });
+    if (unknown.length) {
+        _fail('unknown key ' + unknown.map(function (k) { return JSON.stringify(k); }).join(', ') +
+            ' — a codec chain row holds exactly CODEC_CHAIN_KEYS: ' + CODEC_CHAIN_KEYS.join(', ') + '.');
+    }
+    checkStorageKey(row.name, 'a codec chain name');
+    if (typeof row.source !== 'string' || row.source.length === 0) {
+        _fail('"source" is the chain\'s module text, a non-empty string.');
+    }
+    return Object.freeze({ name: row.name, source: row.source });
+}
+
+export function saveChain(provider, row) {
+    var n = normalizeChainRow(row);
+    provider.put(CODEC_CHAINS_NAMESPACE, n.name, { name: n.name, source: n.source });
+    return n.name;
+}
+
+export function saveChainAs(provider, row, newName) {
+    checkStorageKey(newName, 'a codec chain name');
+    var n = normalizeChainRow(Object.assign({}, row, { name: newName }));
+    if (provider.get(CODEC_CHAINS_NAMESPACE, newName) !== null) {
+        _fail('a codec chain named "' + newName + '" is already saved — Save As takes a name no saved chain has.');
+    }
+    provider.put(CODEC_CHAINS_NAMESPACE, n.name, { name: n.name, source: n.source });
+    return n.name;
+}
+
+export function loadChain(provider, name) {
+    checkStorageKey(name, 'a codec chain name');
+    var raw = provider.get(CODEC_CHAINS_NAMESPACE, name);
+    if (raw === null || raw === undefined) { return null; }
+    var row;
+    try { row = normalizeChainRow(raw); }
+    catch (e) { _fail('the saved chain "' + name + '" is not a codec chain row: ' + ((e && e.message) || e)); }
+    if (row.name !== name) { _fail('the saved chain under "' + name + '" names itself "' + row.name + '".'); }
+    return row;
+}
+
+export function listChains(provider) {
+    return provider.list(CODEC_CHAINS_NAMESPACE).map(function (e) { return e.key; }).sort().map(function (k) {
+        return { name: k };
+    });
+}
+
+export function deleteChain(provider, name) {
+    checkStorageKey(name, 'a codec chain name');
+    provider['delete'](CODEC_CHAINS_NAMESPACE, name);
+}

package/dist/shim/storage/folders.js

@@ -0,0 +1,205 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/storage/folders.js — THE owner of a project saved in browser storage: one project = one folder.
+ *
+ * A project is a folder of files: `frqtl.json` (its owner is
+ * lib/shim/project/manifest.js), the entry sketch it names, and whatever else the author keeps beside them.
+ * The stored ROW is the folder plus the host's boot bag, and nothing else:
+ *
+ *   FOLDER_ROW_KEYS = ['files', 'renderState']
+ *     files        { path: text } — text only (a binary value is refused by name); every path through
+ *                  lib/shim/project/identity.js checkProjectPath, the one path rule; a root `index.html` is
+ *                  refused (EXPORT_PAGE: the Export writes it); `frqtl.json` is required and read by its owner.
+ *     renderState  the host's boot bag (STUDIO's capture, a rung's effectiveRenderState), normalized by its one
+ *                  owner (lib/shim/render-state normalizeSavedRenderState) and ferried — never re-listed here.
+ *                  Boot facts live beside the folder, never in frqtl.json.
+ *
+ * The key is the manifest `name`, in FOLDERS_NAMESPACE. Exports:
+ *
+ *   normalizeFolderRow(row)                    → the frozen row (the one validation every reader and writer uses)
+ *   folderNameOf(row)                          → its frqtl.json name
+ *   saveFolder(provider, row)                  → name   Save: write the folder under its own name (overwrites)
+ *   saveFolderAs(provider, row, newName)       → newName Save As: frqtl.json's name rewritten through
+ *                                                serializeManifest; REFUSED when newName is taken
+ *   copyFolder(provider, name, newName)        → newName a stored folder copied (saveFolderAs over loadFolder)
+ *   loadFolder(provider, name)                 → row | null
+ *   listFolders(provider)                      → [{ name }] in ascending name order
+ *   deleteFolder(provider, name)
+ *
+ * Retired saves (DESCIX IS NOT LIVE; there is no migration tool): the namespaces RETIRED_NAMESPACES (owned by
+ * the storage seam, index.js, which refuses a write into one) held the v4 module envelope and the design
+ * envelope. They are never read and never converted:
+ *
+ *   retiredSaves(provider)                     → [{ namespace, key }] — every key in a retired namespace
+ *   deleteRetiredSaves(provider, saves)        → the count deleted — EXACTLY the listed keys (each must be in a
+ *                                                retired namespace); nothing else is touched
+ *
+ * FAIL-LOUD: every refusal names the rule it applies. Layer 2 (physics): none — this stores text.
+ */
+
+'use strict';
+
+import { RETIRED_NAMESPACES, checkStorageKey } from './index.js';
+import { checkProjectPath } from '../project/identity.js';
+import { MANIFEST_FILE, parseManifest, serializeManifest } from '../project/manifest.js';
+import { normalizeSavedRenderState } from '../render-state/index.js';
+
+export { RETIRED_NAMESPACES };
+
+/** The storage namespace every project folder is saved under. */
+export var FOLDERS_NAMESPACE = 'project-folders';
+
+/** The stored row's keys — the folder and the host's boot bag. */
+export var FOLDER_ROW_KEYS = Object.freeze(['files', 'renderState']);
+
+/** The root page the Export generates (lib/shim/bundle) — reserved, so a folder never holds one. */
+export var EXPORT_PAGE = 'index.html';
+
+function _fail(msg) {
+    throw new Error('[folders] ' + msg + ' (FAIL-LOUD.)');
+}
+
+function _isPlainObject(v) { return !!v && typeof v === 'object' && !Array.isArray(v); }
+
+/**
+ * @param {{files: Object<string,string>, renderState?: object|null}} row
+ * @returns {Readonly<{files: Readonly<Object<string,string>>, renderState: object}>}
+ */
+export function normalizeFolderRow(row) {
+    if (!_isPlainObject(row)) {
+        _fail('a project folder row is { ' + FOLDER_ROW_KEYS.join(', ') + ' } (got ' +
+            (row === null ? 'null' : Array.isArray(row) ? 'an array' : typeof row) + ').');
+    }
+    var unknown = Object.keys(row).filter(function (k) { return FOLDER_ROW_KEYS.indexOf(k) === -1; });
+    if (unknown.length) {
+        _fail('unknown key ' + unknown.map(function (k) { return JSON.stringify(k); }).join(', ') +
+            ' — a project folder row holds exactly FOLDER_ROW_KEYS (lib/shim/storage/folders.js): ' +
+            FOLDER_ROW_KEYS.join(', ') + '.');
+    }
+    var files = row.files;
+    if (!_isPlainObject(files) || Object.keys(files).length === 0) {
+        _fail('"files" is the folder { path: text } with at least ' + MANIFEST_FILE + ' (got ' +
+            (_isPlainObject(files) ? 'an empty map' : typeof files) + ').');
+    }
+    var out = {};
+    Object.keys(files).forEach(function (p) {
+        checkProjectPath(p);
+        if (p === EXPORT_PAGE) {
+            _fail('"' + EXPORT_PAGE + '" at the folder root is reserved — the Export generates it (the host page ' +
+                'that carries the boot bag); a project folder never holds one.');
+        }
+        if (typeof files[p] !== 'string') {
+            _fail('"' + p + '" is not text (got ' + (files[p] instanceof Uint8Array ? 'bytes' : typeof files[p]) +
+                ') — a project folder holds text files only.');
+        }
+        out[p] = files[p];
+    });
+    if (typeof out[MANIFEST_FILE] !== 'string') {
+        _fail('the folder carries no ' + MANIFEST_FILE + ' — a project folder is named and entered by its manifest ' +
+            '(lib/shim/project/manifest.js manifestFor({ name, entry }) writes one).');
+    }
+    var name = parseManifest(out[MANIFEST_FILE]).name;
+    checkStorageKey(name, 'a project folder name (frqtl.json "name")');
+    return Object.freeze({ files: Object.freeze(out), renderState: normalizeSavedRenderState(row.renderState) });
+}
+
+/** @param {object} row @returns {string} the folder's frqtl.json name */
+export function folderNameOf(row) {
+    return parseManifest(normalizeFolderRow(row).files[MANIFEST_FILE]).name;
+}
+
+function _stored(row) {
+    return { files: Object.assign({}, row.files), renderState: row.renderState };
+}
+
+/**
+ * Save: write the folder under its own frqtl.json name, overwriting that name's folder.
+ * @returns {string} the name
+ */
+export function saveFolder(provider, row) {
+    var n = normalizeFolderRow(row);
+    var name = parseManifest(n.files[MANIFEST_FILE]).name;
+    provider.put(FOLDERS_NAMESPACE, name, _stored(n));
+    return name;
+}
+
+/**
+ * Save As: the folder under `newName` — frqtl.json's name rewritten through serializeManifest (the one writer).
+ * REFUSED when a folder named `newName` is already saved.
+ * @returns {string} newName
+ */
+export function saveFolderAs(provider, row, newName) {
+    checkStorageKey(newName, 'a project folder name');
+    var n = normalizeFolderRow(row);
+    if (provider.get(FOLDERS_NAMESPACE, newName) !== null) {
+        _fail('a project named "' + newName + '" is already saved — Save As takes a name no saved project has ' +
+            '(choose another, or delete the saved one first).');
+    }
+    var files = Object.assign({}, n.files);
+    files[MANIFEST_FILE] = serializeManifest(Object.assign({}, parseManifest(n.files[MANIFEST_FILE]), { name: newName }));
+    var renamed = normalizeFolderRow({ files: files, renderState: n.renderState });
+    provider.put(FOLDERS_NAMESPACE, newName, _stored(renamed));
+    return newName;
+}
+
+/** A stored folder copied under `newName` (frqtl.json's name rewritten); refuses a taken name or a missing source. */
+export function copyFolder(provider, name, newName) {
+    var row = loadFolder(provider, name);
+    if (!row) { _fail('no saved project named "' + name + '" to copy.'); }
+    return saveFolderAs(provider, row, newName);
+}
+
+/** @returns {Readonly<object>|null} the normalized row, or null when no folder has that name */
+export function loadFolder(provider, name) {
+    checkStorageKey(name, 'a project folder name');
+    var raw = provider.get(FOLDERS_NAMESPACE, name);
+    if (raw === null || raw === undefined) { return null; }
+    var row;
+    try { row = normalizeFolderRow(raw); }
+    catch (e) { _fail('the saved project "' + name + '" is not a project folder row: ' + ((e && e.message) || e)); }
+    var stored = parseManifest(row.files[MANIFEST_FILE]).name;
+    if (stored !== name) {
+        _fail('the saved project under "' + name + '" names itself "' + stored + '" in ' + MANIFEST_FILE +
+            ' — a folder is keyed by its manifest name.');
+    }
+    return row;
+}
+
+/** @returns {Array<{name: string}>} every saved folder, ascending by name */
+export function listFolders(provider) {
+    return provider.list(FOLDERS_NAMESPACE).map(function (e) { return e.key; }).sort().map(function (k) {
+        return { name: k };
+    });
+}
+
+export function deleteFolder(provider, name) {
+    checkStorageKey(name, 'a project folder name');
+    provider['delete'](FOLDERS_NAMESPACE, name);
+}
+
+/** @returns {Array<{namespace: string, key: string}>} every key in a retired namespace (never read) */
+export function retiredSaves(provider) {
+    var out = [];
+    RETIRED_NAMESPACES.forEach(function (ns) {
+        provider.list(ns).forEach(function (e) { out.push({ namespace: ns, key: e.key }); });
+    });
+    return out;
+}
+
+/**
+ * Delete exactly `saves` (retiredSaves' rows); a row outside a retired namespace is refused before anything
+ * is deleted.
+ * @returns {number} the count deleted
+ */
+export function deleteRetiredSaves(provider, saves) {
+    if (!Array.isArray(saves)) { _fail('deleteRetiredSaves(provider, saves): saves is retiredSaves(provider)\'s list.'); }
+    saves.forEach(function (s) {
+        if (!s || RETIRED_NAMESPACES.indexOf(s.namespace) === -1 || typeof s.key !== 'string') {
+            _fail('deleteRetiredSaves deletes only retired saves ({ namespace in [' + RETIRED_NAMESPACES.join(', ') +
+                '], key }) — got ' + JSON.stringify(s) + '.');
+        }
+    });
+    saves.forEach(function (s) { provider['delete'](s.namespace, s.key); });
+    return saves.length;
+}

package/dist/shim/storage/index.js

@@ -45,16 +45,27 @@
  *   // Then anywhere in the IDE:
  *   import { getProvider } from 'lib/shim/storage';
  *   const storage = getProvider();
- *   storage.put('projects', 'abc123', { name: 'My project' });
- *   const saved = storage.get('projects', 'abc123');
- *   const all   = storage.list('projects');
- *   storage.delete('projects', 'abc123');
+ *   storage.put('explainers', 'gym', { seen: true });
+ *   const saved = storage.get('explainers', 'gym');
+ *   const all   = storage.list('explainers');
+ *   storage.delete('explainers', 'gym');
  *
  * ── Contract validation ─────────────────────────────────────────────────────
  *
  *   validateProvider(provider) — throws if provider does not implement the
  *     contract.  Called by setActiveProvider; consumers may also call it.
  *
+ * ── Retired namespaces ──────────────────────────────────────────────────────
+ *
+ *   RETIRED_NAMESPACES — the namespaces of the retired save formats ('files': the v4 module
+ *     envelope STUDIO and ROSETTA wrote; 'projects': the opaque design envelope). The project
+ *     folder (folders.js) and the codec chain (codec-chains.js) replaced them. The active provider
+ *     (getProvider) REFUSES a write into one, naming the replacement; reads, lists and deletes go
+ *     through, so the retired-saves strip can name them and delete exactly them (folders.js
+ *     retiredSaves / deleteRetiredSaves). Nothing reads or converts their rows.
+ *   checkStorageKey(key, what) — THE key rule of a store keyed by a name (a project folder's
+ *     frqtl.json name, a codec chain's name): a non-empty string with no "/" (reserved).
+ *
  * ── Server-side seam ───────────────────────────────────────────────────────
  *
  *   The matching server routes are defined in lib/server/mounts.js under
@@ -69,6 +80,49 @@
 
 /** @type {StorageProvider|null} */
 var _activeProvider = null;
+/** @type {StorageProvider|null} the active provider behind the retired-namespace write guard */
+var _activeGuard = null;
+
+/** The namespaces of the retired save formats — written by nothing (see the header). */
+export var RETIRED_NAMESPACES = Object.freeze(['files', 'projects']);
+
+var _RETIRED_BY = Object.freeze({
+  files:    'the project folder (lib/shim/storage/folders.js, namespace "project-folders") for a STUDIO save, ' +
+            'the codec chain (lib/shim/storage/codec-chains.js, namespace "codec-chains") for a ROSETTA save',
+  projects: 'the project folder (lib/shim/storage/folders.js, namespace "project-folders")'
+});
+
+/**
+ * THE key rule of a store keyed by a name: a non-empty string with no "/" (reserved by the contract).
+ * @param {*} key
+ * @param {string} what — the store's noun, for the message (e.g. 'a project folder name')
+ * @throws {Error}
+ */
+export function checkStorageKey(key, what) {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new Error('[StorageProvider] ' + what + ' is a non-empty string (got ' + JSON.stringify(key) + '). (FAIL-LOUD.)');
+  }
+  if (key.indexOf('/') !== -1) {
+    throw new Error('[StorageProvider] ' + what + ' ' + JSON.stringify(key) + ' contains "/" — "/" is reserved ' +
+      'in a storage key; name it without one. (FAIL-LOUD.)');
+  }
+}
+
+function _guarded(provider) {
+  return Object.freeze({
+    get: function (namespace, key) { return provider.get(namespace, key); },
+    put: function (namespace, key, value) {
+      if (RETIRED_NAMESPACES.indexOf(namespace) !== -1) {
+        throw new Error('[StorageProvider] a write into the retired namespace "' + namespace + '" (key ' +
+          JSON.stringify(key) + ') is refused — that save format is retired; ' + _RETIRED_BY[namespace] +
+          ' replaced it. (FAIL-LOUD.)');
+      }
+      return provider.put(namespace, key, value);
+    },
+    'delete': function (namespace, key) { return provider['delete'](namespace, key); },
+    list: function (namespace) { return provider.list(namespace); }
+  });
+}
 
 // ── Contract typedefs ──────────────────────────────────────────────────────
 
@@ -129,10 +183,11 @@ export function validateProvider(provider) {
 export function setActiveProvider(provider) {
   validateProvider(provider);
   _activeProvider = provider;
+  _activeGuard = _guarded(provider);
 }
 
 /**
- * Retrieve the active storage driver.
+ * Retrieve the active storage driver, behind the retired-namespace write guard (RETIRED_NAMESPACES).
  * FAIL-LOUD: throws if no provider has been registered.
  *
  * @returns {StorageProvider}
@@ -146,18 +201,18 @@ export function getProvider() {
       'for a non-browser driver.'
     );
   }
-  return _activeProvider;
+  return _activeGuard;
 }
 
 /**
- * Return the active provider, or null if none has been registered.
+ * Return the active provider (behind the same guard), or null if none has been registered.
  * Use this instead of getProvider() when a nil-safe check is appropriate
  * (e.g. during test setup before a provider is wired).
  *
  * @returns {StorageProvider|null}
  */
 export function peekProvider() {
-  return _activeProvider;
+  return _activeGuard;
 }
 
 /**
@@ -166,4 +221,5 @@ export function peekProvider() {
  */
 export function resetProvider() {
   _activeProvider = null;
+  _activeGuard = null;
 }

package/dist/shim/storage/make-namespace-store.js

@@ -3,9 +3,9 @@
 /**
  * lib/shim/storage/make-namespace-store.js — Generic namespace-CRUD factory.
  *
- * Factors out the byte-identical pattern shared by modules.js, projects.js,
- * and lib/shim/notebook/store.js.  Each of those files is a thin config call
- * over this factory; the public-API exports they expose are unchanged.
+ * The id-keyed record store lib/shim/notebook/store.js is a thin config call
+ * over. (A project folder and a codec chain are keyed by NAME and have their
+ * own owners: folders.js, codec-chains.js.)
  *
  * ── Signature ──────────────────────────────────────────────────────────────
  *
@@ -13,12 +13,12 @@
  *
  * ── Config ─────────────────────────────────────────────────────────────────
  *
- *   namespace      {string}    — StorageProvider namespace key (e.g. 'files').
+ *   namespace      {string}    — StorageProvider namespace key (e.g. 'notebooks').
  *   schemaVersion  {number}    — Current schema version integer (stamped on save
  *                                by callers; used here only in the returned
  *                                constant — actual stamping is the caller's job,
  *                                as in the originals).
- *   idPrefix       {string}    — Prefix for generated ids (e.g. 'mod_').
+ *   idPrefix       {string}    — Prefix for generated ids (e.g. 'nb_').
  *   validate       {function}  — validate(record): throws on invalid envelope.
  *   summaryFields  {function}  — summaryFields(record) → summary object, or
  *                                returns null to silently skip the record.