cursedbelt-core 2.1.1 → 2.3.0

package/dist/config/appConfig.d.ts

@@ -1,7 +1,7 @@
 /**
  * `app-config.json` — the single schema the compiler AND the runtime import
  * (02-MASTER-ENGINES §2). Nothing else may re-declare this shape: a second copy
- * is how `privateMedia` without `guard` parsed as valid for a year (J2-1).
+ * is how a feature without the engine it needs parsed as valid for a year (J2-1).
  *
  * Two laws are encoded here rather than in prose:
  *
@@ -9,8 +9,8 @@
  *    `features` block — is a parse ERROR (`unknown-config-key`), never silently
  *    stripped. A typo'd flag that gets dropped reads as "the feature is off" at
  *    runtime, which is indistinguishable from a bug in the feature.
- * 2. `.superRefine()` cross-engine dependencies. `privateMedia` needs `guard`,
- *    `oralHistory` needs `asset`, `auth.enabled` needs `guard`, and the saas
+ * 2. `.superRefine()` cross-engine dependencies. `oralHistory` needs `asset`,
+ *    `auth.enabled` needs `guard`, and the saas
  *    profile needs `guard` + `rbac:true`. These are structural: the config
  *    references something that will not exist at runtime, so it dies at V0 —
  *    fail-closed on structure (04 §0).
@@ -41,7 +41,6 @@ export declare const AssetFeatures: z.ZodObject<{
     editor: z.ZodDefault<z.ZodBoolean>;
     fileBrowser: z.ZodDefault<z.ZodBoolean>;
     taggedFiles: z.ZodDefault<z.ZodBoolean>;
-    privateMedia: z.ZodDefault<z.ZodBoolean>;
     vaultSource: z.ZodDefault<z.ZodBoolean>;
     ocr: z.ZodDefault<z.ZodBoolean>;
     imageStudio: z.ZodDefault<z.ZodBoolean>;
@@ -127,7 +126,6 @@ export declare const FeaturesByEngine: {
         editor: z.ZodDefault<z.ZodBoolean>;
         fileBrowser: z.ZodDefault<z.ZodBoolean>;
         taggedFiles: z.ZodDefault<z.ZodBoolean>;
-        privateMedia: z.ZodDefault<z.ZodBoolean>;
         vaultSource: z.ZodDefault<z.ZodBoolean>;
         ocr: z.ZodDefault<z.ZodBoolean>;
         imageStudio: z.ZodDefault<z.ZodBoolean>;

package/dist/config/appConfig.js

@@ -1,7 +1,7 @@
 /**
  * `app-config.json` — the single schema the compiler AND the runtime import
  * (02-MASTER-ENGINES §2). Nothing else may re-declare this shape: a second copy
- * is how `privateMedia` without `guard` parsed as valid for a year (J2-1).
+ * is how a feature without the engine it needs parsed as valid for a year (J2-1).
  *
  * Two laws are encoded here rather than in prose:
  *
@@ -9,8 +9,8 @@
  *    `features` block — is a parse ERROR (`unknown-config-key`), never silently
  *    stripped. A typo'd flag that gets dropped reads as "the feature is off" at
  *    runtime, which is indistinguishable from a bug in the feature.
- * 2. `.superRefine()` cross-engine dependencies. `privateMedia` needs `guard`,
- *    `oralHistory` needs `asset`, `auth.enabled` needs `guard`, and the saas
+ * 2. `.superRefine()` cross-engine dependencies. `oralHistory` needs `asset`,
+ *    `auth.enabled` needs `guard`, and the saas
  *    profile needs `guard` + `rbac:true`. These are structural: the config
  *    references something that will not exist at runtime, so it dies at V0 —
  *    fail-closed on structure (04 §0).
@@ -31,7 +31,9 @@ export const AssetFeatures = z
     editor: z.boolean().default(false), // lazy chunk; joins bundleKey
     fileBrowser: z.boolean().default(false),
     taggedFiles: z.boolean().default(false),
-    privateMedia: z.boolean().default(false), // requires guard engine — enforced in superRefine
+    // `privateMedia` was here until 2.3.0 (task 330). Its server module and the `pfs/` keyspace
+    // were deleted from cursedbelt-server in 4.0.0, so the flag named a tier that no longer
+    // exists; `.strict()` now refuses it as `unknown-config-key`, which is the honest answer.
     vaultSource: z.boolean().default(false),
     ocr: z.boolean().default(false),
     imageStudio: z.boolean().default(false),
@@ -277,8 +279,6 @@ export const AppConfigSchema = z
         }
         const f = parsed.data;
         // (c) cross-engine dependencies — hard blocks, not comments (J2-1)
-        if (inst.engine === 'asset' && f.privateMedia === true && !engineSet.has('guard'))
-            issue(['instances', i, 'features', 'privateMedia'], `'privateMedia' requires the 'guard' engine in engines[] (engine-dependency-missing).`);
         if (inst.engine === 'knowledge' && f.oralHistory === true && !engineSet.has('asset'))
             issue(['instances', i, 'features', 'oralHistory'], `'oralHistory' requires the 'asset' engine for its media player tier (engine-dependency-missing).`);
     });

package/dist/core/offline/shellWorker.d.ts

@@ -0,0 +1,185 @@
+/**
+ * The app-shell service worker, once, for every app that serves its shell offline
+ * (task 2073, 2026-09-22).
+ *
+ * `apps/roms` wrote this by hand as plain JS in `public/sw.js`, with a TypeScript
+ * twin in `src/offline/swRouting.ts` held in step by a comment saying "keep the two
+ * in step". `apps/music` needed the same worker, and a third hand copy is how a fix
+ * lands in one app and not the others. This module is the one body; an app's
+ * `src/sw.ts` passes a config and adds whatever is genuinely its own (background
+ * sync, an outbox, a digest-keyed media cache) as further listeners beside it.
+ *
+ * What it does, and it is deliberately all it does:
+ *  - `install`  — precache the shell and the config's `precache` list, then `skipWaiting`.
+ *  - `activate` — delete every cache named `<cachePrefix>*` that is not this version's,
+ *                 then `clients.claim()`.
+ *  - `fetch`    — same-origin static ASSETS cache-first; document NAVIGATIONS
+ *                 network-first, falling back offline to the exact URL, then the same
+ *                 path ignoring the query, then the shell. Everything else is left on
+ *                 the network: `respondWith` is never called for it.
+ *
+ * 🔴 `/api/` is NEVER cached and NEVER served from a cache. It is auth-gated, and a
+ * browser whose session has since been revoked must not read yesterday's copy of a
+ * private response out of its own cache. That is not a default a config can switch
+ * off: `apiPrefixes` ADDS prefixes to `/api/`, it cannot remove it, a precache entry
+ * under an API prefix is refused when the worker is installed, and `shouldCache`
+ * refuses to store an `api` route even if a caller asks.
+ *
+ * 🔴 `noShellFallback` exists because of the 2026-08-12 frame incident in roms. A game
+ * boots by loading `/emulator-frame.html` into a sandboxed iframe — a NAVIGATION, so it
+ * went network-first, and offline with nothing cached under that path the fallback
+ * handed it the APP SHELL. The iframe rendered a second copy of the library where the
+ * game should be: no canvas, no error, no clue. Any document that is not the shell (an
+ * iframe, a popup, a print view) must be listed there, and must be in `precache` if it
+ * is meant to work offline at all — an offline miss on it then REJECTS, which is the
+ * honest answer, rather than resolving the wrong document.
+ *
+ * Imports nothing at runtime (`leafSubpathsImportNothing.spec.ts` holds it to that):
+ * it is bundled into a service worker, where every byte ships on every install.
+ * `scope` is typed structurally so this compiles without the WebWorker lib, is testable
+ * with a fake, and still accepts the real `self` — `shellWorker.webworker.spec.ts`
+ * typechecks exactly that against `lib.webworker.d.ts`.
+ */
+/** Where a request goes. */
+export type ShellRoute = 
+/** A document navigation — network-first, cached-document fallback offline. */
+'navigate'
+/** A same-origin static asset (JS/CSS/WASM/font/image/JSON) — cache-first. */
+ | 'asset'
+/** An auth-gated API call — never cached, never answered from a cache. */
+ | 'api'
+/** Everything else (non-GET, cross-origin, `passthroughPrefixes`) — untouched. */
+ | 'passthrough';
+/** The facts about a request that classification reads — nothing else. */
+export interface RequestFacts {
+    method: string;
+    /** Same origin as the worker (`new URL(request.url).origin === location.origin`). */
+    sameOrigin: boolean;
+    /** URL pathname, no query. */
+    pathname: string;
+    /** `request.mode === 'navigate'`. */
+    isNavigate: boolean;
+}
+export interface ShellWorkerConfig {
+    /**
+     * Every cache this worker owns is named `<cachePrefix><version>`, and `activate`
+     * deletes every OTHER cache starting with `cachePrefix`. So the prefix must be one
+     * nothing else in the app shares — `roms-shell-`, not `roms-`, or the app's own
+     * digest-keyed caches go with it.
+     */
+    cachePrefix: string;
+    /** Bump to evict the previous shell on the next activate. */
+    version: string;
+    /**
+     * Same-origin paths fetched into the cache at install. `shellPath` is always
+     * precached whether listed or not — a shell fallback with no shell is no fallback.
+     */
+    precache: readonly string[];
+    /**
+     * Extra API prefixes. `/api/` is ALWAYS one of them and cannot be removed — see the
+     * header. Default: `['/api/']`.
+     */
+    apiPrefixes?: readonly string[];
+    /**
+     * Same-origin prefixes the worker must leave alone even for GET assets — e.g. roms'
+     * `/_nes-roms/`, whose bytes the app caches itself under a content digest.
+     */
+    passthroughPrefixes?: readonly string[];
+    /**
+     * Exact pathnames that must NEVER be answered with the shell offline (roms'
+     * `/emulator-frame.html`). An offline miss on one rejects instead. See the header.
+     */
+    noShellFallback?: readonly string[];
+    /** Which same-origin pathnames count as static assets. Default: `DEFAULT_ASSET_EXT`. */
+    assetExtensions?: RegExp;
+    /** The app shell's path, the navigation fallback. Default: `'/'`. */
+    shellPath?: string;
+}
+/** A config with every default applied and every refusal already checked. */
+export interface ResolvedShellWorkerConfig {
+    cachePrefix: string;
+    version: string;
+    cacheName: string;
+    precache: readonly string[];
+    apiPrefixes: readonly string[];
+    passthroughPrefixes: readonly string[];
+    noShellFallback: readonly string[];
+    assetExtensions: RegExp;
+    shellPath: string;
+}
+/** roms' `ASSET_EXT`, verbatim. */
+export declare const DEFAULT_ASSET_EXT: RegExp;
+/** Always an API prefix, whatever the config says. */
+export declare const ALWAYS_API_PREFIX = "/api/";
+/**
+ * Classify a request. Order matters and is roms' order: non-GET and cross-origin
+ * first, then the API (so an API path that happens to end in `.json` is still `api`),
+ * then the app's own passthrough prefixes, then navigation, then assets.
+ */
+export declare function classifyRequest(facts: RequestFacts, config?: Pick<ShellWorkerConfig, 'apiPrefixes' | 'passthroughPrefixes' | 'assetExtensions'>): ShellRoute;
+/** Whether a response on this route may be written to the cache. Never `api`. */
+export declare function shouldCache(route: ShellRoute): boolean;
+/** May an offline miss on this navigation be answered with the shell? */
+export declare function mayFallBackToShell(pathname: string, config?: Pick<ShellWorkerConfig, 'noShellFallback'>): boolean;
+/**
+ * Apply defaults and refuse the configs that would break a promise in the header.
+ * `installShellWorker` calls this; it is exported so an app's own test can prove its
+ * config is accepted without standing up a worker.
+ */
+export declare function resolveShellWorkerConfig(config: ShellWorkerConfig): ResolvedShellWorkerConfig;
+export interface ShellWorkerRequest {
+    readonly url: string;
+    readonly method: string;
+    readonly mode: string;
+}
+/**
+ * The structural mirror of `RequestInfo | URL` — a request, a string, or a URL-like —
+ * which is what the real `fetch`, `Cache` and `CacheStorage` accept. It has to be the
+ * whole union: with `ShellWorkerRequest` alone the real `self` is refused, because a
+ * `URL` is not a request in either direction (measured by the webworker spec).
+ */
+export type ShellWorkerRequestInfo = ShellWorkerRequest | string | {
+    readonly href: string;
+};
+export interface ShellWorkerResponse {
+    readonly ok: boolean;
+    clone(): ShellWorkerResponse;
+}
+export interface ShellWorkerCache {
+    addAll(requests: string[]): Promise<void>;
+    put(request: ShellWorkerRequestInfo, response: ShellWorkerResponse): Promise<void>;
+}
+export interface ShellWorkerCacheStorage {
+    open(cacheName: string): Promise<ShellWorkerCache>;
+    keys(): Promise<string[]>;
+    delete(cacheName: string): Promise<boolean>;
+    match(request: ShellWorkerRequestInfo, options?: {
+        ignoreSearch?: boolean;
+    }): Promise<ShellWorkerResponse | undefined>;
+}
+export interface ShellExtendableEvent {
+    waitUntil(promise: Promise<unknown>): void;
+}
+export interface ShellFetchEvent extends ShellExtendableEvent {
+    readonly request: ShellWorkerRequest;
+    respondWith(response: Promise<ShellWorkerResponse>): void;
+}
+export interface ShellWorkerScope {
+    addEventListener(type: 'install', listener: (event: ShellExtendableEvent) => void): void;
+    addEventListener(type: 'activate', listener: (event: ShellExtendableEvent) => void): void;
+    addEventListener(type: 'fetch', listener: (event: ShellFetchEvent) => void): void;
+    readonly caches: ShellWorkerCacheStorage;
+    readonly clients: {
+        claim(): Promise<void>;
+    };
+    readonly location: {
+        readonly origin: string;
+    };
+    fetch(request: ShellWorkerRequestInfo): Promise<ShellWorkerResponse>;
+    skipWaiting(): Promise<void>;
+}
+/**
+ * Wire `install`, `activate` and `fetch` onto `scope` (the worker's `self`).
+ * Returns the resolved config, so an app can read `cacheName` for its own use.
+ */
+export declare function installShellWorker(scope: ShellWorkerScope, config: ShellWorkerConfig): ResolvedShellWorkerConfig;

package/dist/core/offline/shellWorker.js

@@ -0,0 +1,200 @@
+/**
+ * The app-shell service worker, once, for every app that serves its shell offline
+ * (task 2073, 2026-09-22).
+ *
+ * `apps/roms` wrote this by hand as plain JS in `public/sw.js`, with a TypeScript
+ * twin in `src/offline/swRouting.ts` held in step by a comment saying "keep the two
+ * in step". `apps/music` needed the same worker, and a third hand copy is how a fix
+ * lands in one app and not the others. This module is the one body; an app's
+ * `src/sw.ts` passes a config and adds whatever is genuinely its own (background
+ * sync, an outbox, a digest-keyed media cache) as further listeners beside it.
+ *
+ * What it does, and it is deliberately all it does:
+ *  - `install`  — precache the shell and the config's `precache` list, then `skipWaiting`.
+ *  - `activate` — delete every cache named `<cachePrefix>*` that is not this version's,
+ *                 then `clients.claim()`.
+ *  - `fetch`    — same-origin static ASSETS cache-first; document NAVIGATIONS
+ *                 network-first, falling back offline to the exact URL, then the same
+ *                 path ignoring the query, then the shell. Everything else is left on
+ *                 the network: `respondWith` is never called for it.
+ *
+ * 🔴 `/api/` is NEVER cached and NEVER served from a cache. It is auth-gated, and a
+ * browser whose session has since been revoked must not read yesterday's copy of a
+ * private response out of its own cache. That is not a default a config can switch
+ * off: `apiPrefixes` ADDS prefixes to `/api/`, it cannot remove it, a precache entry
+ * under an API prefix is refused when the worker is installed, and `shouldCache`
+ * refuses to store an `api` route even if a caller asks.
+ *
+ * 🔴 `noShellFallback` exists because of the 2026-08-12 frame incident in roms. A game
+ * boots by loading `/emulator-frame.html` into a sandboxed iframe — a NAVIGATION, so it
+ * went network-first, and offline with nothing cached under that path the fallback
+ * handed it the APP SHELL. The iframe rendered a second copy of the library where the
+ * game should be: no canvas, no error, no clue. Any document that is not the shell (an
+ * iframe, a popup, a print view) must be listed there, and must be in `precache` if it
+ * is meant to work offline at all — an offline miss on it then REJECTS, which is the
+ * honest answer, rather than resolving the wrong document.
+ *
+ * Imports nothing at runtime (`leafSubpathsImportNothing.spec.ts` holds it to that):
+ * it is bundled into a service worker, where every byte ships on every install.
+ * `scope` is typed structurally so this compiles without the WebWorker lib, is testable
+ * with a fake, and still accepts the real `self` — `shellWorker.webworker.spec.ts`
+ * typechecks exactly that against `lib.webworker.d.ts`.
+ */
+/** roms' `ASSET_EXT`, verbatim. */
+export const DEFAULT_ASSET_EXT = /\.(?:js|mjs|css|wasm|woff2?|ttf|png|jpe?g|webp|svg|ico|json)$/i;
+/** Always an API prefix, whatever the config says. */
+export const ALWAYS_API_PREFIX = '/api/';
+const apiPrefixesOf = (config) => {
+    const extra = config.apiPrefixes ?? [];
+    return extra.includes(ALWAYS_API_PREFIX) ? extra : [ALWAYS_API_PREFIX, ...extra];
+};
+const startsWithAny = (pathname, prefixes) => prefixes.some((prefix) => pathname.startsWith(prefix));
+/**
+ * Classify a request. Order matters and is roms' order: non-GET and cross-origin
+ * first, then the API (so an API path that happens to end in `.json` is still `api`),
+ * then the app's own passthrough prefixes, then navigation, then assets.
+ */
+export function classifyRequest(facts, config = {}) {
+    if (facts.method !== 'GET')
+        return 'passthrough';
+    if (!facts.sameOrigin)
+        return 'passthrough';
+    if (startsWithAny(facts.pathname, apiPrefixesOf(config)))
+        return 'api';
+    if (startsWithAny(facts.pathname, config.passthroughPrefixes ?? []))
+        return 'passthrough';
+    if (facts.isNavigate)
+        return 'navigate';
+    if ((config.assetExtensions ?? DEFAULT_ASSET_EXT).test(facts.pathname))
+        return 'asset';
+    return 'passthrough';
+}
+/** Whether a response on this route may be written to the cache. Never `api`. */
+export function shouldCache(route) {
+    return route === 'asset' || route === 'navigate';
+}
+/** May an offline miss on this navigation be answered with the shell? */
+export function mayFallBackToShell(pathname, config = {}) {
+    return !(config.noShellFallback ?? []).includes(pathname);
+}
+/**
+ * Apply defaults and refuse the configs that would break a promise in the header.
+ * `installShellWorker` calls this; it is exported so an app's own test can prove its
+ * config is accepted without standing up a worker.
+ */
+export function resolveShellWorkerConfig(config) {
+    if (config.cachePrefix.trim() === '') {
+        // An empty prefix makes EVERY cache on the origin "an old version of ours", and
+        // activate would delete the app's other caches with it.
+        throw new Error('shell worker: cachePrefix must not be empty — activate deletes every cache it prefixes');
+    }
+    if (config.version.trim() === '')
+        throw new Error('shell worker: version must not be empty');
+    const shellPath = config.shellPath ?? '/';
+    const apiPrefixes = apiPrefixesOf(config);
+    const precache = config.precache.includes(shellPath) ? [...config.precache] : [shellPath, ...config.precache];
+    for (const path of precache) {
+        if (!path.startsWith('/')) {
+            throw new Error(`shell worker: precache entry "${path}" must be a same-origin path starting with "/"`);
+        }
+        if (startsWithAny(path, apiPrefixes)) {
+            throw new Error(`shell worker: precache entry "${path}" is under an API prefix — the API is never cached`);
+        }
+    }
+    if (config.noShellFallback?.includes(shellPath)) {
+        throw new Error(`shell worker: the shell path "${shellPath}" cannot also be in noShellFallback`);
+    }
+    return {
+        cachePrefix: config.cachePrefix,
+        version: config.version,
+        cacheName: `${config.cachePrefix}${config.version}`,
+        precache,
+        apiPrefixes,
+        passthroughPrefixes: config.passthroughPrefixes ?? [],
+        noShellFallback: config.noShellFallback ?? [],
+        assetExtensions: config.assetExtensions ?? DEFAULT_ASSET_EXT,
+        shellPath,
+    };
+}
+/**
+ * Wire `install`, `activate` and `fetch` onto `scope` (the worker's `self`).
+ * Returns the resolved config, so an app can read `cacheName` for its own use.
+ */
+export function installShellWorker(scope, config) {
+    const resolved = resolveShellWorkerConfig(config);
+    const { caches } = scope;
+    // Written after the response is handed back, like roms' `cache.put` — but kept
+    // alive with `waitUntil` so the worker is not stopped mid-write, and swallowed on
+    // failure: a full quota must not turn a good network response into an error.
+    const store = (event, route, response) => {
+        if (!shouldCache(route) || !response.ok)
+            return;
+        const copy = response.clone();
+        event.waitUntil(caches
+            .open(resolved.cacheName)
+            .then((cache) => cache.put(event.request, copy))
+            .catch(() => undefined));
+    };
+    const cacheFirst = async (event) => {
+        const cached = await caches.match(event.request);
+        if (cached)
+            return cached;
+        const response = await scope.fetch(event.request);
+        store(event, 'asset', response);
+        return response;
+    };
+    const networkFirst = async (event) => {
+        const { request } = event;
+        try {
+            const response = await scope.fetch(request);
+            store(event, 'navigate', response);
+            return response;
+        }
+        catch (error) {
+            // Offline. The exact URL first, then the same path ignoring the query — roms'
+            // frame is `/emulator-frame.html?system=nes`, and one cached copy answers for
+            // every console.
+            const cached = (await caches.match(request)) ?? (await caches.match(request, { ignoreSearch: true }));
+            if (cached)
+                return cached;
+            if (mayFallBackToShell(new URL(request.url).pathname, resolved)) {
+                const shell = await caches.match(resolved.shellPath);
+                if (shell)
+                    return shell;
+            }
+            // Nothing honest to serve: reject, and the browser shows its own offline page
+            // rather than a document that is not the one asked for.
+            throw error;
+        }
+    };
+    scope.addEventListener('install', (event) => {
+        event.waitUntil(caches
+            .open(resolved.cacheName)
+            .then((cache) => cache.addAll([...resolved.precache]))
+            .then(() => scope.skipWaiting()));
+    });
+    scope.addEventListener('activate', (event) => {
+        event.waitUntil(caches
+            .keys()
+            .then((keys) => Promise.all(keys
+            .filter((key) => key.startsWith(resolved.cachePrefix) && key !== resolved.cacheName)
+            .map((key) => caches.delete(key))))
+            .then(() => scope.clients.claim()));
+    });
+    scope.addEventListener('fetch', (event) => {
+        const url = new URL(event.request.url);
+        const route = classifyRequest({
+            method: event.request.method,
+            sameOrigin: url.origin === scope.location.origin,
+            pathname: url.pathname,
+            isNavigate: event.request.mode === 'navigate',
+        }, resolved);
+        if (route === 'asset')
+            event.respondWith(cacheFirst(event));
+        else if (route === 'navigate')
+            event.respondWith(networkFirst(event));
+        // `api` and `passthrough`: no respondWith, so the browser goes to the network as
+        // if this worker did not exist. Never a cache read, never a cache write.
+    });
+    return resolved;
+}

package/dist/core/passwordPolicy.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The one place a satellite's owner-password floor is decided.
+ *
+ * ── Why this is shared, and why the default is 9 ────────────────────────────
+ * Three apps had independently written a `MIN_PASSWORD_BYTES` constant into
+ * their own `scripts/owner.ts`, and they had already drifted (9, 14, 14) with
+ * a paragraph in each explaining itself against the others. A floor is a
+ * POLICY, and a policy copied three times is three policies.
+ *
+ * The default is {@link DEFAULT_MIN_PASSWORD_BYTES} = 9, which is the floor the
+ * owner wants for an ordinary satellite: long enough that it is not a PIN, short
+ * enough that it does not push the owner toward writing it down or reusing one.
+ * Argon2id — what every caller hashes with — is what actually carries the cost
+ * of a guess here; these apps have exactly ONE principal and no enumerable user
+ * list, so the marginal value of characters 10–14 is small and the friction is
+ * not.
+ *
+ * ── `cursedbelt-core/password-policy`, since 2.3.0 (task 321) ────────────────
+ * The floor that exists so it cannot drift was itself copied — `src/kit/passwordPolicy.ts`
+ * in `auth`, `patterns` and `vault`. It is here, in the isomorphic tier, because `vault`
+ * enforces it in the BROWSER (`src/crypto/vaultCipher.ts`) as well as on the server, and a
+ * floor checked in two runtimes must be one import in both. It imports nothing.
+ *
+ * ── Raising it is an APP's decision, and it is the only direction ───────────
+ * {@link resolveMinPasswordBytes} takes an optional override and **refuses to
+ * go below the default**. An app that genuinely runs at higher stakes says so
+ * at its own call site, in one visible argument, with a comment saying why.
+ * No app overrides it today — the retired orch companion app did (14, as the single
+ * internet-facing door into the host that runs `claude` in every repo) until
+ * the owner dropped it to the shared floor on 2026-07-26.
+ *
+ * The asymmetry is the whole point: a shared default can be raised locally
+ * where the risk is local, but nothing can quietly lower the floor for
+ * everyone — which is exactly the mistake a bare exported constant invites.
+ */
+/**
+ * The floor, in BYTES as typed (not codepoints — callers measure the raw bytes
+ * they read, so a multi-byte character counts as more than one, which is the
+ * conservative direction).
+ */
+export declare const DEFAULT_MIN_PASSWORD_BYTES = 9;
+/**
+ * The floor this app enforces: the default, or a higher one it asks for.
+ *
+ * Throws on an override below the default rather than silently clamping. A
+ * caller passing 6 believes it is enforcing 6; being handed 9 without a word is
+ * how a security floor becomes folklore.
+ */
+export declare function resolveMinPasswordBytes(override?: number): number;

package/dist/core/passwordPolicy.js

@@ -0,0 +1,60 @@
+/**
+ * The one place a satellite's owner-password floor is decided.
+ *
+ * ── Why this is shared, and why the default is 9 ────────────────────────────
+ * Three apps had independently written a `MIN_PASSWORD_BYTES` constant into
+ * their own `scripts/owner.ts`, and they had already drifted (9, 14, 14) with
+ * a paragraph in each explaining itself against the others. A floor is a
+ * POLICY, and a policy copied three times is three policies.
+ *
+ * The default is {@link DEFAULT_MIN_PASSWORD_BYTES} = 9, which is the floor the
+ * owner wants for an ordinary satellite: long enough that it is not a PIN, short
+ * enough that it does not push the owner toward writing it down or reusing one.
+ * Argon2id — what every caller hashes with — is what actually carries the cost
+ * of a guess here; these apps have exactly ONE principal and no enumerable user
+ * list, so the marginal value of characters 10–14 is small and the friction is
+ * not.
+ *
+ * ── `cursedbelt-core/password-policy`, since 2.3.0 (task 321) ────────────────
+ * The floor that exists so it cannot drift was itself copied — `src/kit/passwordPolicy.ts`
+ * in `auth`, `patterns` and `vault`. It is here, in the isomorphic tier, because `vault`
+ * enforces it in the BROWSER (`src/crypto/vaultCipher.ts`) as well as on the server, and a
+ * floor checked in two runtimes must be one import in both. It imports nothing.
+ *
+ * ── Raising it is an APP's decision, and it is the only direction ───────────
+ * {@link resolveMinPasswordBytes} takes an optional override and **refuses to
+ * go below the default**. An app that genuinely runs at higher stakes says so
+ * at its own call site, in one visible argument, with a comment saying why.
+ * No app overrides it today — the retired orch companion app did (14, as the single
+ * internet-facing door into the host that runs `claude` in every repo) until
+ * the owner dropped it to the shared floor on 2026-07-26.
+ *
+ * The asymmetry is the whole point: a shared default can be raised locally
+ * where the risk is local, but nothing can quietly lower the floor for
+ * everyone — which is exactly the mistake a bare exported constant invites.
+ */
+/**
+ * The floor, in BYTES as typed (not codepoints — callers measure the raw bytes
+ * they read, so a multi-byte character counts as more than one, which is the
+ * conservative direction).
+ */
+export const DEFAULT_MIN_PASSWORD_BYTES = 9;
+/**
+ * The floor this app enforces: the default, or a higher one it asks for.
+ *
+ * Throws on an override below the default rather than silently clamping. A
+ * caller passing 6 believes it is enforcing 6; being handed 9 without a word is
+ * how a security floor becomes folklore.
+ */
+export function resolveMinPasswordBytes(override) {
+    if (override === undefined)
+        return DEFAULT_MIN_PASSWORD_BYTES;
+    if (!Number.isInteger(override)) {
+        throw new Error(`minPasswordBytes must be an integer, got ${override}`);
+    }
+    if (override < DEFAULT_MIN_PASSWORD_BYTES) {
+        throw new Error(`minPasswordBytes may only be RAISED above the shared default of ` +
+            `${DEFAULT_MIN_PASSWORD_BYTES}; refusing ${override}`);
+    }
+    return override;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-core",
-	"version": "2.1.1",
+	"version": "2.3.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "Framework-agnostic core of the cursedbelt split — isomorphic domain logic. cwip below it, cursedbelt-server and cursedbelt (react) above it.",
@@ -251,6 +251,12 @@
 			"source": "./src/core/net/reconnectSchedule.ts",
 			"import": "./dist/core/net/reconnectSchedule.js"
 		},
+		"./offline/shell-worker": {
+			"types": "./dist/core/offline/shellWorker.d.ts",
+			"bun": "./src/core/offline/shellWorker.ts",
+			"source": "./src/core/offline/shellWorker.ts",
+			"import": "./dist/core/offline/shellWorker.js"
+		},
 		"./palette": {
 			"types": "./dist/core/palette/index.d.ts",
 			"bun": "./src/core/palette/index.ts",
@@ -275,6 +281,12 @@
 			"source": "./src/core/palette/ShortcutRegistry.ts",
 			"import": "./dist/core/palette/ShortcutRegistry.js"
 		},
+		"./password-policy": {
+			"types": "./dist/core/passwordPolicy.d.ts",
+			"bun": "./src/core/passwordPolicy.ts",
+			"source": "./src/core/passwordPolicy.ts",
+			"import": "./dist/core/passwordPolicy.js"
+		},
 		"./session/claims": {
 			"types": "./dist/core/session/claims.d.ts",
 			"bun": "./src/core/session/claims.ts",

package/src/config/appConfig.spec.ts

@@ -51,13 +51,11 @@ describe('strictness (02 §2.2)', () => {
 });
 
 describe('cross-engine dependencies are code, not comments (J2-1)', () => {
-  it('blocks privateMedia without the guard engine', () => {
-    const config = base({ instances: [{ engine: 'asset', id: 'gallery', features: { privateMedia: true } }] });
-    expect(parse(config).success).toBe(false);
-    expect(messages(config).join(' ')).toContain("'privateMedia' requires the 'guard' engine");
-  });
-
-  it('allows privateMedia once guard is activated', () => {
+  // 🔴 `privateMedia` was the other half of this mechanism's proof until 2.3.0 (task 330). The
+  // flag is gone, so `oralHistory` → `asset` is now the ONE feature-to-engine dependency, and it
+  // is proven both ways below — blocked without its engine, allowed with it — so the
+  // `engine-dependency-missing` diagnostic keeps a failure path AND a pass path.
+  it('refuses the retired privateMedia flag as an unknown key, never silently ignores it', () => {
     const config = base({
       engines: ['asset', 'guard'],
       instances: [
@@ -65,6 +63,20 @@ describe('cross-engine dependencies are code, not comments (J2-1)', () => {
         { engine: 'guard', id: 'guard-main' },
       ],
     });
+    expect(parse(config).success).toBe(false);
+    expect(parse(config).error?.issues.map((issue) => issue.path.join('.'))).toContain(
+      'instances.0.features.privateMedia',
+    );
+  });
+
+  it('allows oralHistory once the asset engine is activated', () => {
+    const config = base({
+      engines: ['knowledge', 'asset'],
+      instances: [
+        { engine: 'knowledge', id: 'stories', features: { oralHistory: true } },
+        { engine: 'asset', id: 'player' },
+      ],
+    });
     expect(parse(config).success).toBe(true);
   });