cursedbelt-core 1.0.0

package/package.json

@@ -0,0 +1,373 @@
+{
+	"name": "cursedbelt-core",
+	"version": "1.0.0",
+	"license": "ISC",
+	"type": "module",
+	"description": "Framework-agnostic core of the cursedbelt split \u2014 isomorphic domain logic. cwip below it, cursedbelt-server and cursedbelt (react) above it.",
+	"cursed": {
+		"schemaVersion": 1,
+		"app": {
+			"name": "cursedbelt-core",
+			"commands": {
+				"test": "test",
+				"typecheck": "typecheck",
+				"build": "build"
+			}
+		}
+	},
+	"scripts": {
+		"clean": "rm -rf dist",
+		"typecheck": "tsc -p tsconfig.build.json --noEmit",
+		"test": "NODE_ENV=development bun test src",
+		"build": "bun run clean && tsc -p tsconfig.build.json",
+		"paths": "bun ../../tools/check-paths.ts .",
+		"verify": "bun run paths && bun run typecheck && bun run build && bun run test",
+		"prepublishOnly": "bun run verify"
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"bun": "./src/index.ts",
+			"source": "./src/index.ts",
+			"import": "./dist/index.js"
+		},
+		"./activity": {
+			"types": "./dist/core/activity/index.d.ts",
+			"bun": "./src/core/activity/index.ts",
+			"source": "./src/core/activity/index.ts",
+			"import": "./dist/core/activity/index.js"
+		},
+		"./activity/model": {
+			"types": "./dist/core/activity/model.d.ts",
+			"bun": "./src/core/activity/model.ts",
+			"source": "./src/core/activity/model.ts",
+			"import": "./dist/core/activity/model.js"
+		},
+		"./analytics": {
+			"types": "./dist/core/analytics/index.d.ts",
+			"bun": "./src/core/analytics/index.ts",
+			"source": "./src/core/analytics/index.ts",
+			"import": "./dist/core/analytics/index.js"
+		},
+		"./analytics/range": {
+			"types": "./dist/core/analytics/range.d.ts",
+			"bun": "./src/core/analytics/range.ts",
+			"source": "./src/core/analytics/range.ts",
+			"import": "./dist/core/analytics/range.js"
+		},
+		"./analytics/schedule": {
+			"types": "./dist/core/analytics/schedule.d.ts",
+			"bun": "./src/core/analytics/schedule.ts",
+			"source": "./src/core/analytics/schedule.ts",
+			"import": "./dist/core/analytics/schedule.js"
+		},
+		"./app-config": {
+			"types": "./dist/config/appConfig.d.ts",
+			"bun": "./src/config/appConfig.ts",
+			"source": "./src/config/appConfig.ts",
+			"import": "./dist/config/appConfig.js"
+		},
+		"./category": {
+			"types": "./dist/core/category/index.d.ts",
+			"bun": "./src/core/category/index.ts",
+			"source": "./src/core/category/index.ts",
+			"import": "./dist/core/category/index.js"
+		},
+		"./color": {
+			"types": "./dist/core/color.d.ts",
+			"bun": "./src/core/color.ts",
+			"source": "./src/core/color.ts",
+			"import": "./dist/core/color.js"
+		},
+		"./color-scheme": {
+			"types": "./dist/core/colorScheme/index.d.ts",
+			"bun": "./src/core/colorScheme/index.ts",
+			"source": "./src/core/colorScheme/index.ts",
+			"import": "./dist/core/colorScheme/index.js"
+		},
+		"./ctgr": {
+			"types": "./dist/ctgr/index.d.ts",
+			"bun": "./src/ctgr/index.ts",
+			"source": "./src/ctgr/index.ts",
+			"import": "./dist/ctgr/index.js"
+		},
+		"./ctgr/chunk-store": {
+			"types": "./dist/ctgr/chunkStore.d.ts",
+			"bun": "./src/ctgr/chunkStore.ts",
+			"source": "./src/ctgr/chunkStore.ts",
+			"import": "./dist/ctgr/chunkStore.js"
+		},
+		"./ctgr/types": {
+			"types": "./dist/ctgr/types.d.ts",
+			"bun": "./src/ctgr/types.ts",
+			"source": "./src/ctgr/types.ts",
+			"import": "./dist/ctgr/types.js"
+		},
+		"./ctgr/v0compat": {
+			"types": "./dist/ctgr/v0compat.d.ts",
+			"bun": "./src/ctgr/v0compat.ts",
+			"source": "./src/ctgr/v0compat.ts",
+			"import": "./dist/ctgr/v0compat.js"
+		},
+		"./domain-owners": {
+			"types": "./dist/core/domainOwners.d.ts",
+			"bun": "./src/core/domainOwners.ts",
+			"source": "./src/core/domainOwners.ts",
+			"import": "./dist/core/domainOwners.js"
+		},
+		"./download": {
+			"types": "./dist/core/download.d.ts",
+			"bun": "./src/core/download.ts",
+			"source": "./src/core/download.ts",
+			"import": "./dist/core/download.js"
+		},
+		"./errors": {
+			"types": "./dist/shared/errors.d.ts",
+			"bun": "./src/shared/errors.ts",
+			"source": "./src/shared/errors.ts",
+			"import": "./dist/shared/errors.js"
+		},
+		"./events/cc-event-bus": {
+			"types": "./dist/core/events/ccEventBus.d.ts",
+			"bun": "./src/core/events/ccEventBus.ts",
+			"source": "./src/core/events/ccEventBus.ts",
+			"import": "./dist/core/events/ccEventBus.js"
+		},
+		"./file-tree/file-tree-model": {
+			"types": "./dist/core/file-tree/fileTreeModel.d.ts",
+			"bun": "./src/core/file-tree/fileTreeModel.ts",
+			"source": "./src/core/file-tree/fileTreeModel.ts",
+			"import": "./dist/core/file-tree/fileTreeModel.js"
+		},
+		"./folder-tree": {
+			"types": "./dist/core/folder-tree/index.d.ts",
+			"bun": "./src/core/folder-tree/index.ts",
+			"source": "./src/core/folder-tree/index.ts",
+			"import": "./dist/core/folder-tree/index.js"
+		},
+		"./folder-tree/actions": {
+			"types": "./dist/core/folder-tree/actions.d.ts",
+			"bun": "./src/core/folder-tree/actions.ts",
+			"source": "./src/core/folder-tree/actions.ts",
+			"import": "./dist/core/folder-tree/actions.js"
+		},
+		"./folder-tree/path": {
+			"types": "./dist/core/folder-tree/path.d.ts",
+			"bun": "./src/core/folder-tree/path.ts",
+			"source": "./src/core/folder-tree/path.ts",
+			"import": "./dist/core/folder-tree/path.js"
+		},
+		"./folder-tree/tree": {
+			"types": "./dist/core/folder-tree/tree.d.ts",
+			"bun": "./src/core/folder-tree/tree.ts",
+			"source": "./src/core/folder-tree/tree.ts",
+			"import": "./dist/core/folder-tree/tree.js"
+		},
+		"./layout": {
+			"types": "./dist/core/layout/index.d.ts",
+			"bun": "./src/core/layout/index.ts",
+			"source": "./src/core/layout/index.ts",
+			"import": "./dist/core/layout/index.js"
+		},
+		"./master-lock": {
+			"types": "./dist/core/master-lock/index.d.ts",
+			"bun": "./src/core/master-lock/index.ts",
+			"source": "./src/core/master-lock/index.ts",
+			"import": "./dist/core/master-lock/index.js"
+		},
+		"./master-lock/kdf": {
+			"types": "./dist/core/master-lock/kdf.d.ts",
+			"bun": "./src/core/master-lock/kdf.ts",
+			"source": "./src/core/master-lock/kdf.ts",
+			"import": "./dist/core/master-lock/kdf.js"
+		},
+		"./master-lock/policy": {
+			"types": "./dist/core/master-lock/policy.d.ts",
+			"bun": "./src/core/master-lock/policy.ts",
+			"source": "./src/core/master-lock/policy.ts",
+			"import": "./dist/core/master-lock/policy.js"
+		},
+		"./media": {
+			"types": "./dist/core/media/index.d.ts",
+			"bun": "./src/core/media/index.ts",
+			"source": "./src/core/media/index.ts",
+			"import": "./dist/core/media/index.js"
+		},
+		"./media/ffmpeg": {
+			"types": "./dist/core/media/ffmpeg.d.ts",
+			"bun": "./src/core/media/ffmpeg.ts",
+			"source": "./src/core/media/ffmpeg.ts",
+			"import": "./dist/core/media/ffmpeg.js"
+		},
+		"./media/render-plan": {
+			"types": "./dist/core/media/renderPlan.d.ts",
+			"bun": "./src/core/media/renderPlan.ts",
+			"source": "./src/core/media/renderPlan.ts",
+			"import": "./dist/core/media/renderPlan.js"
+		},
+		"./media/size": {
+			"types": "./dist/core/media/size.d.ts",
+			"bun": "./src/core/media/size.ts",
+			"source": "./src/core/media/size.ts",
+			"import": "./dist/core/media/size.js"
+		},
+		"./media/types": {
+			"types": "./dist/core/media/types.d.ts",
+			"bun": "./src/core/media/types.ts",
+			"source": "./src/core/media/types.ts",
+			"import": "./dist/core/media/types.js"
+		},
+		"./media/upload-limits": {
+			"types": "./dist/core/media/uploadLimits.d.ts",
+			"bun": "./src/core/media/uploadLimits.ts",
+			"source": "./src/core/media/uploadLimits.ts",
+			"import": "./dist/core/media/uploadLimits.js"
+		},
+		"./media/video-cuts": {
+			"types": "./dist/core/media/videoCuts.d.ts",
+			"bun": "./src/core/media/videoCuts.ts",
+			"source": "./src/core/media/videoCuts.ts",
+			"import": "./dist/core/media/videoCuts.js"
+		},
+		"./navigation": {
+			"types": "./dist/core/navigation/index.d.ts",
+			"bun": "./src/core/navigation/index.ts",
+			"source": "./src/core/navigation/index.ts",
+			"import": "./dist/core/navigation/index.js"
+		},
+		"./net/reconnect-schedule": {
+			"types": "./dist/core/net/reconnectSchedule.d.ts",
+			"bun": "./src/core/net/reconnectSchedule.ts",
+			"source": "./src/core/net/reconnectSchedule.ts",
+			"import": "./dist/core/net/reconnectSchedule.js"
+		},
+		"./palette": {
+			"types": "./dist/core/palette/index.d.ts",
+			"bun": "./src/core/palette/index.ts",
+			"source": "./src/core/palette/index.ts",
+			"import": "./dist/core/palette/index.js"
+		},
+		"./palette/fuzzy-rank": {
+			"types": "./dist/core/palette/fuzzyRank.d.ts",
+			"bun": "./src/core/palette/fuzzyRank.ts",
+			"source": "./src/core/palette/fuzzyRank.ts",
+			"import": "./dist/core/palette/fuzzyRank.js"
+		},
+		"./palette/hotkeys": {
+			"types": "./dist/core/palette/hotkeys.d.ts",
+			"bun": "./src/core/palette/hotkeys.ts",
+			"source": "./src/core/palette/hotkeys.ts",
+			"import": "./dist/core/palette/hotkeys.js"
+		},
+		"./palette/shortcut-registry": {
+			"types": "./dist/core/palette/ShortcutRegistry.d.ts",
+			"bun": "./src/core/palette/ShortcutRegistry.ts",
+			"source": "./src/core/palette/ShortcutRegistry.ts",
+			"import": "./dist/core/palette/ShortcutRegistry.js"
+		},
+		"./session/claims": {
+			"types": "./dist/core/session/claims.d.ts",
+			"bun": "./src/core/session/claims.ts",
+			"source": "./src/core/session/claims.ts",
+			"import": "./dist/core/session/claims.js"
+		},
+		"./sharing": {
+			"types": "./dist/core/sharing/index.d.ts",
+			"bun": "./src/core/sharing/index.ts",
+			"source": "./src/core/sharing/index.ts",
+			"import": "./dist/core/sharing/index.js"
+		},
+		"./sharing/model": {
+			"types": "./dist/core/sharing/model.d.ts",
+			"bun": "./src/core/sharing/model.ts",
+			"source": "./src/core/sharing/model.ts",
+			"import": "./dist/core/sharing/model.js"
+		},
+		"./site/site-copy": {
+			"types": "./dist/core/site/siteCopy.d.ts",
+			"bun": "./src/core/site/siteCopy.ts",
+			"source": "./src/core/site/siteCopy.ts",
+			"import": "./dist/core/site/siteCopy.js"
+		},
+		"./slots": {
+			"types": "./dist/core/slots.d.ts",
+			"bun": "./src/core/slots.ts",
+			"source": "./src/core/slots.ts",
+			"import": "./dist/core/slots.js"
+		},
+		"./styles/constructable-sheet": {
+			"types": "./dist/core/styles/constructableSheet.d.ts",
+			"bun": "./src/core/styles/constructableSheet.ts",
+			"source": "./src/core/styles/constructableSheet.ts",
+			"import": "./dist/core/styles/constructableSheet.js"
+		},
+		"./testing": {
+			"types": "./dist/testing/index.d.ts",
+			"bun": "./src/testing/index.ts",
+			"source": "./src/testing/index.ts",
+			"import": "./dist/testing/index.js"
+		},
+		"./testing/dom-inspect": {
+			"types": "./dist/testing/domInspect.d.ts",
+			"bun": "./src/testing/domInspect.ts",
+			"source": "./src/testing/domInspect.ts",
+			"import": "./dist/testing/domInspect.js"
+		},
+		"./tokens/registry": {
+			"types": "./dist/core/tokens/registry.d.ts",
+			"bun": "./src/core/tokens/registry.ts",
+			"source": "./src/core/tokens/registry.ts",
+			"import": "./dist/core/tokens/registry.js"
+		},
+		"./ui-scale": {
+			"types": "./dist/core/uiScale/index.d.ts",
+			"bun": "./src/core/uiScale/index.ts",
+			"source": "./src/core/uiScale/index.ts",
+			"import": "./dist/core/uiScale/index.js"
+		},
+		"./wire": {
+			"types": "./dist/core/wire/index.d.ts",
+			"bun": "./src/core/wire/index.ts",
+			"source": "./src/core/wire/index.ts",
+			"import": "./dist/core/wire/index.js"
+		},
+		"./wire/marshalling": {
+			"types": "./dist/core/wire/marshalling.d.ts",
+			"bun": "./src/core/wire/marshalling.ts",
+			"source": "./src/core/wire/marshalling.ts",
+			"import": "./dist/core/wire/marshalling.js"
+		},
+		"./wire/wire-hub": {
+			"types": "./dist/core/wire/wireHub.d.ts",
+			"bun": "./src/core/wire/wireHub.ts",
+			"source": "./src/core/wire/wireHub.ts",
+			"import": "./dist/core/wire/wireHub.js"
+		},
+		"./ws-wire": {
+			"types": "./dist/client/wsWire.d.ts",
+			"bun": "./src/client/wsWire.ts",
+			"source": "./src/client/wsWire.ts",
+			"import": "./dist/client/wsWire.js"
+		}
+	},
+	"dependencies": {
+		"@leeoniya/ufuzzy": "^1.0.19",
+		"cwip": "^3.0.2"
+	},
+	"peerDependencies": {
+		"zod": "^4.4.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.0",
+		"@types/bun": "^1.3.14",
+		"@types/node": "^24",
+		"typescript": "^6.0.3",
+		"zod": "4.4.3",
+		"@happy-dom/global-registrator": "^20.10.6",
+		"hono": "4.12.28"
+	}
+}

package/src/client/wsWire.ts

@@ -0,0 +1,83 @@
+/**
+ * The WS hub's WIRE, with no socket attached.
+ *
+ * ── Why this is a module of its own ─────────────────────────────────────────
+ * `./ws` imports `partysocket/ws` at the top of the file to build the
+ * auto-reconnecting socket. `partysocket` is an OPTIONAL peer of cursedbelt, so
+ * a consumer that brings its own socket — because it already has a reconnect
+ * strategy, or because its entry chunk is measured to the byte and it will not
+ * spend it on a reconnect library — could not touch the URL builder or the
+ * envelope helpers without pulling the library in. They are twenty lines of pure
+ * string handling and they were only ever in that file because they were written
+ * on the same afternoon.
+ *
+ * So: the WIRE lives here and is free of dependencies, and `./ws` re-exports it
+ * beside the socket factory. Nothing moved for the callers that already had it —
+ * `cursedbelt-cc/client` still exports all of it from one place — and the split is
+ * what makes `cursedbelt-core/ws-wire` a thing an app can import.
+ *
+ * 🔴 The contract is that the envelope has ONE definition. An app that hand-rolls
+ * `JSON.stringify({ event, data })` is an app whose frames drift from the hub's
+ * the day the envelope gains a field, and the drift presents as a message the
+ * server silently ignores — `createWsHub` returns from `message` rather than
+ * throwing, on purpose. Take the helpers.
+ *
+ * `apps/family` (cursed-satellites) is the first consumer of this subpath.
+ */
+
+/** The minimal shape of `window.location` {@link buildChannelSocketUrl} needs. Injectable
+ * so the URL builder is pure + testable (no `window` at module scope). */
+export interface WsLocation {
+  protocol: string;
+  host: string;
+}
+
+/** The hub's wire envelope, mirroring `cursedbelt-server`'s `WsMessage`. Re-declared here
+ * (not imported) because the server module is Bun-typed and must not leak into the browser
+ * surface. */
+export interface WsMessage<T = unknown> {
+  event: string;
+  data: T;
+}
+
+/** Build the `ws(s)://host/ws/<channel>[?room=<roomId>]` URL the hub upgrades. `wss` is
+ * chosen iff the page is `https`. Pure — pass `loc` in tests. */
+export function buildChannelSocketUrl(
+  channel: string,
+  roomId: string | undefined,
+  loc: WsLocation,
+): string {
+  const scheme = loc.protocol === 'https:' ? 'wss' : 'ws';
+  const base = `${scheme}://${loc.host}/ws/${encodeURIComponent(channel)}`;
+  return roomId ? `${base}?room=${encodeURIComponent(roomId)}` : base;
+}
+
+/** Send a `{ event, data }` frame the hub understands. */
+export function sendWsMessage(
+  socket: { send(data: string): void },
+  event: string,
+  data: unknown,
+): void {
+  socket.send(JSON.stringify({ event, data }));
+}
+
+/** Parse an inbound frame into a `{ event, data }` envelope, or `null` if it isn't valid
+ * JSON of that shape (so a stray non-envelope frame can't throw in a message handler). */
+export function parseWsMessage<T = unknown>(raw: unknown): WsMessage<T> | null {
+  if (typeof raw !== 'string') return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (
+    parsed &&
+    typeof parsed === 'object' &&
+    'event' in parsed &&
+    typeof parsed.event === 'string'
+  ) {
+    return parsed as WsMessage<T>;
+  }
+  return null;
+}

package/src/config/appConfig.spec.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it } from 'bun:test';
+import { AppConfigSchema, effectiveSignupMode, featureKeysOf, resolveInstanceFeatures, ROUTE_PATH_RE } from './appConfig';
+
+const base = (over: Record<string, unknown> = {}) => ({
+  configVersion: 1,
+  app: { id: 'demo', title: 'Demo' },
+  engines: ['asset'],
+  instances: [{ engine: 'asset', id: 'gallery' }],
+  ...over,
+});
+
+const parse = (config: unknown) => AppConfigSchema.safeParse(config);
+const messages = (config: unknown) => parse(config).error?.issues.map((i) => i.message) ?? [];
+
+describe('strictness (02 §2.2)', () => {
+  it('accepts a minimal config and fills every default', () => {
+    const result = parse(base());
+    expect(result.success).toBe(true);
+    expect(result.data?.profile).toBe('local');
+    expect(result.data?.connections).toEqual([]);
+    expect(result.data?.instances[0]?.cssIsolation).toBe('none');
+    expect(result.data?.deployTarget.capabilities).toEqual({});
+  });
+
+  it('refuses an unknown top-level key rather than stripping it', () => {
+    const result = parse(base({ theeme: {} }));
+    expect(result.success).toBe(false);
+    expect(result.error?.issues[0]?.code).toBe('unrecognized_keys');
+  });
+
+  it('refuses an unknown key inside a per-engine features block', () => {
+    const result = parse(base({ instances: [{ engine: 'asset', id: 'gallery', features: { alowVideoHLS: true } }] }));
+    expect(result.success).toBe(false);
+    expect(messages(base({ instances: [{ engine: 'asset', id: 'gallery', features: { alowVideoHLS: true } }] })).join(' ')).toContain(
+      'alowVideoHLS',
+    );
+  });
+
+  it('refuses an unknown configVersion instead of guessing', () => {
+    expect(parse(base({ configVersion: 2 })).success).toBe(false);
+  });
+
+  it('refuses an instance id that is not kebab-case', () => {
+    expect(parse(base({ instances: [{ engine: 'asset', id: 'Gallery Main' }] })).success).toBe(false);
+  });
+
+  it('refuses a port outside the unprivileged range', () => {
+    expect(parse(base({ app: { id: 'demo', title: 'Demo', port: 80 } })).success).toBe(false);
+    expect(parse(base({ app: { id: 'demo', title: 'Demo', port: 4747 } })).success).toBe(true);
+  });
+});
+
+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', () => {
+    const config = base({
+      engines: ['asset', 'guard'],
+      instances: [
+        { engine: 'asset', id: 'gallery', features: { privateMedia: true } },
+        { engine: 'guard', id: 'guard-main' },
+      ],
+    });
+    expect(parse(config).success).toBe(true);
+  });
+
+  it('blocks oralHistory without the asset engine', () => {
+    const config = base({ engines: ['knowledge'], instances: [{ engine: 'knowledge', id: 'stories', features: { oralHistory: true } }] });
+    expect(messages(config).join(' ')).toContain("'oralHistory' requires the 'asset' engine");
+  });
+
+  it('blocks auth.enabled without the guard engine', () => {
+    const config = base({ auth: { enabled: true } });
+    expect(messages(config).join(' ')).toContain("auth.enabled requires the 'guard' engine");
+  });
+
+  it('blocks an instance whose engine is absent from engines[]', () => {
+    const config = base({ engines: ['asset'], instances: [{ engine: 'knowledge', id: 'notes' }] });
+    expect(messages(config).join(' ')).toContain("absent from engines[]");
+  });
+
+  it('forces guard + rbac in the saas profile', () => {
+    const noGuard = base({ profile: 'saas', engines: ['knowledge'], instances: [{ engine: 'knowledge', id: 'notes' }] });
+    expect(messages(noGuard).join(' ')).toContain("structurally requires the 'guard' engine");
+
+    const noRbac = base({
+      profile: 'saas',
+      engines: ['guard', 'knowledge'],
+      instances: [
+        { engine: 'guard', id: 'guard-main' },
+        { engine: 'knowledge', id: 'notes' },
+      ],
+    });
+    expect(messages(noRbac).join(' ')).toContain("'features.rbac: true'");
+
+    const ok = base({
+      profile: 'saas',
+      engines: ['guard', 'knowledge'],
+      instances: [
+        { engine: 'guard', id: 'guard-main', features: { rbac: true } },
+        { engine: 'knowledge', id: 'notes' },
+      ],
+    });
+    expect(parse(ok).success).toBe(true);
+  });
+});
+
+describe('route paths (03 §3)', () => {
+  it('accepts kebab segments with camelCase params', () => {
+    for (const path of ['/', '/chat', '/chat/:conversationId', '/apps/:appId/logs']) expect(ROUTE_PATH_RE.test(path)).toBe(true);
+  });
+
+  it('rejects capitalized literal segments, trailing slashes and query strings', () => {
+    for (const path of ['/Chat', '/chat/', '/chat?x=1', 'chat']) expect(ROUTE_PATH_RE.test(path)).toBe(false);
+  });
+});
+
+describe('feature resolution', () => {
+  it('resolves declared features through the FULL engine schema (the V0 preview)', () => {
+    const effective = resolveInstanceFeatures('asset', { video: false });
+    expect(effective.video).toBe(false);
+    expect(effective.hls).toBe(true); // untouched default, present rather than undefined
+    expect(effective.galleryLayouts).toEqual(['rows']);
+  });
+
+  it('exposes every declared feature key for the V1 requiredFeatures check', () => {
+    expect(featureKeysOf('guard')).toContain('rbac');
+    expect(featureKeysOf('guard')).not.toContain('video');
+  });
+
+  it('defaults signupMode to open (the pre-D33 behavior, and every existing config)', () => {
+    expect(resolveInstanceFeatures('guard', {}).signupMode).toBe('open');
+  });
+});
+
+describe('effectiveSignupMode — the launch gate (D33)', () => {
+  const guard = (signupMode?: string): { engine: string; effective: Record<string, string> } => ({
+    engine: 'guard',
+    effective: signupMode === undefined ? {} : { signupMode },
+  });
+
+  it('is open for no guard instance, and for a manifest predating the field', () => {
+    expect(effectiveSignupMode([])).toBe('open');
+    expect(effectiveSignupMode([{ engine: 'asset', effective: { signupMode: 'closed' } }])).toBe('open');
+    expect(effectiveSignupMode([guard()])).toBe('open');
+  });
+
+  it('the STRICTEST configured value wins across guard instances', () => {
+    // A second, more open instance must never reopen a closed door.
+    expect(effectiveSignupMode([guard('open'), guard('invite')])).toBe('invite');
+    expect(effectiveSignupMode([guard('invite'), guard('closed')])).toBe('closed');
+    expect(effectiveSignupMode([guard('closed'), guard('open')])).toBe('closed');
+  });
+});