cursedbelt 2.7.0 → 3.0.0

package/src/server/ops/engineOps.ts

@@ -1,443 +0,0 @@
-/**
- * The production op handler table for `/api/instance/:id/ops/:op` (03 §3.2).
- *
- * `instanceMixin` ships with an empty handler map and `composeServer` takes the
- * table as an option, which was the right *shape* and the wrong *state*: the
- * only table that ever existed lived in the verify harness. `exec` was threaded
- * onto `DevMixinContext`, contained beautifully by the type system, and then
- * used by nobody — the jail guarded a door that was not installed (§4.1). This
- * module installs the door.
- *
- * Three rules the table encodes, none of which are optional:
- *
- *   1. **Every OS execution goes through `ExecutionDriver`.** An op never builds
- *      an argv, never sees a shell. It names a `commandId` that the driver
- *      resolves against `cc-manifest.json`'s whitelist; an unknown id is a typed
- *      `EXEC_COMMAND_NOT_WHITELISTED` (H-2, V7.14).
- *   2. **Long work goes through the `JobBroker`**, never a request held open and
- *      never a bare `setTimeout` (03 §7.3). Ops that start work return a
- *      `jobId`, and the completion is published on the server push hub so the
- *      client learns about it without polling.
- *   3. **`system:http-send` re-applies the outbound guard.** The route form of
- *      Request Builder's send is guarded (finding 4.2); an ops path that reached
- *      the same service without guarding would re-open the SSRF through a
- *      different door. The guard is applied HERE, at the boundary, for exactly
- *      that reason.
- *
- * Ops whose engine service is absent are simply not registered: `instanceMixin`
- * answers 501 for an unregistered handler, which is louder and more honest than
- * a handler that reports success without running.
- */
-import { z } from 'zod';
-import { AppError } from '../errors';
-import type { ExecutionDriver, JobBroker } from '../drivers';
-import type { OpHandler, OpInvocation } from '../mixins/instance.mixin';
-import type { EngineServices } from '../mixins/services';
-import { assertPublicOutboundUrl, type OutboundGuardOptions } from '../net/outboundGuard';
-import { publishJobCompletion, type ServerPushHub } from '../stream';
-
-/** Job kinds these ops enqueue. A host must register a handler for each kind it enables. */
-export const OP_JOB_KINDS = {
-  reindex: 'reindex',
-  transcode: 'transcode',
-  deploy: 'deploy',
-  import: 'import',
-} as const;
-
-/**
- * Manifest command ids the dev ops invoke. Defaults follow the
- * `<subject>:<verb>` convention; a host whose manifest names them differently
- * overrides here rather than forking the table.
- */
-export interface DevOpCommandIds {
-  /** Restart a registered app's server process. */
-  restartApp: string;
-}
-
-export const DEFAULT_DEV_OP_COMMANDS: DevOpCommandIds = { restartApp: 'app:restart' };
-
-/** A named, synchronous utility the `formatLab`/`lineFilter` features expose. */
-export type UtilityFn = (input: unknown) => unknown;
-
-export interface EngineOpsOptions {
-  services: EngineServices;
-  broker: JobBroker;
-  /**
-   * DevStudio ONLY (J3-4). Absent ⇒ the dev ops that execute commands are not
-   * registered at all, so they 501 rather than silently no-op.
-   */
-  exec?: ExecutionDriver;
-  commands?: Partial<DevOpCommandIds>;
-  /** Publishes job completions to the per-instance stream (03 §3.2). */
-  push?: ServerPushHub;
-  /** `system:run-utility` implementations, keyed by utility id. */
-  utilities?: Readonly<Record<string, UtilityFn>>;
-  /** Overrides for the outbound SSRF guard (test hosts, an allowlisted internal target). */
-  outboundGuard?: OutboundGuardOptions;
-}
-
-/* --------------------------------------------------------------- schemas */
-
-const runPipelineBody = z
-  .object({
-    commandId: z.string().min(1),
-    args: z.record(z.string(), z.string()).default({}),
-    cwd: z.string().optional(),
-  })
-  .strict();
-
-const restartAppBody = z.object({ appId: z.string().min(1) }).strict();
-const deployAppBody = z.object({ appId: z.string().min(1) }).strict();
-const writeConfigBody = z.object({ appId: z.string().min(1), patch: z.record(z.string(), z.string()) }).strict();
-const dbExportBody = z.object({ domain: z.string().min(1) }).strict();
-const idBody = z.object({ id: z.string().min(1) }).strict();
-const idsBody = z.object({ ids: z.array(z.string().min(1)).min(1) }).strict();
-const corpusBody = z.object({ corpus: z.string().min(1).default('default') }).strict();
-const importBody = z.object({ listId: z.string().min(1), rows: z.array(z.record(z.string(), z.unknown())) }).strict();
-const rotateSecretBody = z.object({ key: z.string().min(1) }).strict();
-const reorderColumnBody = z.object({ columnId: z.string().min(1), position: z.number().finite() }).strict();
-const moveCardBody = z
-  .object({ cardId: z.string().min(1), toColumnId: z.string().min(1), position: z.number().finite() })
-  .strict();
-const reorderAlbumMemberBody = z
-  .object({ albumId: z.string().min(1), assetId: z.string().min(1), position: z.number().finite() })
-  .strict();
-const occurrenceMarkBody = z
-  .object({ eventId: z.string().min(1), occurredOn: z.string().min(1), state: z.enum(['done', 'skipped']) })
-  .strict();
-const clearOccurrenceBody = z.object({ eventId: z.string().min(1), occurredOn: z.string().min(1) }).strict();
-const utilityBody = z.object({ utility: z.string().min(1), input: z.unknown() }).strict();
-const httpSendBody = z
-  .object({
-    url: z.string().min(1),
-    method: z.string().default('GET'),
-    headers: z.record(z.string(), z.string()).optional(),
-    body: z.string().optional(),
-  })
-  .strict();
-
-/**
- * Parse an op body, turning a Zod failure into a 400 that NAMES the violated
- * rule. Generic "Validation failed" strings are banned (03 §2.2).
- */
-const parseBody = <S extends z.ZodTypeAny>(schema: S, op: string, body: unknown): z.infer<S> => {
-  const result = schema.safeParse(body ?? {});
-  if (result.success) return result.data as z.infer<S>;
-  const issue = result.error.issues[0];
-  throw new AppError(`Op '${op}': ${issue?.path.join('.') || 'body'} ${issue?.message ?? 'is invalid'}.`, {
-    code: 'OP_BODY_INVALID',
-    status: 400,
-    context: { op, path: issue?.path.map(String) ?? [] },
-  });
-};
-
-export function createEngineOpHandlers(options: EngineOpsOptions): Record<string, OpHandler> {
-  const { services, broker } = options;
-  const commands: DevOpCommandIds = { ...DEFAULT_DEV_OP_COMMANDS, ...options.commands };
-  const handlers: Record<string, OpHandler> = {};
-
-  /** Enqueue and register the push notification in one place. */
-  const enqueue = async (
-    invocation: OpInvocation,
-    kind: string,
-    payload: Record<string, unknown>,
-  ): Promise<{ jobId: string }> => {
-    const jobId = await broker.enqueue({
-      kind,
-      tenantId: invocation.claims.tenantId,
-      instanceId: invocation.instanceId,
-      payload,
-    });
-    if (options.push)
-      publishJobCompletion(broker, {
-        hub: options.push,
-        jobId,
-        tenantId: invocation.claims.tenantId,
-        instanceId: invocation.instanceId,
-      });
-    return { jobId };
-  };
-
-  const scopeOf = (invocation: OpInvocation) => ({
-    claims: invocation.claims,
-    instanceId: invocation.instanceId,
-  });
-
-  /* ------------------------------------------------------------- asset */
-
-  const asset = services.asset;
-  if (asset) {
-    handlers['asset:reindex-media'] = (invocation) =>
-      enqueue(invocation, OP_JOB_KINDS.reindex, { corpus: 'media' });
-
-    handlers['asset:transcode'] = (invocation) => {
-      const { id } = parseBody(idBody, 'transcode', invocation.body);
-      return enqueue(invocation, OP_JOB_KINDS.transcode, { id, userId: invocation.claims.userId });
-    };
-
-    handlers['asset:ocr-extract'] = async (invocation) => {
-      const { id } = parseBody(idBody, 'ocr-extract', invocation.body);
-      // OCR already has a service seam (its output feeds `knowledge` via CDC),
-      // so this op delegates rather than enqueuing a second, parallel job path.
-      return await asset.requestOcr(scopeOf(invocation), id);
-    };
-
-    handlers['asset:delete'] = async (invocation) => {
-      const { id } = parseBody(idBody, 'delete', invocation.body);
-      // Soft-delete + negative storage credit live in the service (§2c). A
-      // false here is an unknown/foreign/already-trashed id → typed 404, which
-      // keeps the id's existence undisclosed (the same law `read` follows).
-      const deleted = await asset.remove(scopeOf(invocation), id);
-      if (!deleted)
-        throw new AppError(`No media item '${id}'.`, { code: 'MEDIA_NOT_FOUND', status: 404, context: { id } });
-      return { deleted: true };
-    };
-
-    // Ordered album membership reorder (§2a / §4) — the album-member analog of
-    // `move-card`: ONE `UPDATE … SET position`, guarded to the caller's album AND
-    // asset. `false` ⇒ a foreign album/asset → typed 404.
-    handlers['asset:reorder-album-member'] = async (invocation) => {
-      const { albumId, assetId, position } = parseBody(reorderAlbumMemberBody, 'reorder-album-member', invocation.body);
-      const ok = await asset.albums.reorderAsset(scopeOf(invocation), albumId, assetId, position);
-      if (!ok) throw opNotFound('album member', `${albumId}/${assetId}`);
-      return { reordered: true };
-    };
-  }
-
-  /* --------------------------------------------------------- knowledge */
-
-  const knowledge = services.knowledge;
-  if (knowledge) {
-    handlers['knowledge:reindex-corpus'] = (invocation) => {
-      const { corpus } = parseBody(corpusBody, 'reindex-corpus', invocation.body);
-      return enqueue(invocation, OP_JOB_KINDS.reindex, { corpus });
-    };
-
-    handlers['knowledge:organize-notes'] = async (invocation) => {
-      const { ids } = parseBody(idsBody, 'organize-notes', invocation.body);
-      // MUST go through `completeStructured` inside the service (03 §7.2) — a
-      // free-text model response can never become an instruction here.
-      return await knowledge.organize(scopeOf(invocation), ids);
-    };
-
-    handlers['knowledge:import-records'] = (invocation) => {
-      const body = parseBody(importBody, 'import-records', invocation.body);
-      // Imports project through `l_columns` metadata (02 §7.2). No user action
-      // ever generates DDL, so this is a data job, not a migration.
-      return enqueue(invocation, OP_JOB_KINDS.import, { listId: body.listId, rows: body.rows });
-    };
-
-    // The two O(1) kanban ordering ACTIONS (§1b / §4). They are ops, not page
-    // routes, because a drag-drop is an action on the board, not a resource. Each
-    // is ONE `UPDATE … SET position` in the repo; `false` (unknown/foreign id, or
-    // a cross-tenant target column on a move) becomes a typed 404 that keeps the
-    // id's existence undisclosed — the same law the read paths follow.
-    handlers['knowledge:reorder-column'] = async (invocation) => {
-      const { columnId, position } = parseBody(reorderColumnBody, 'reorder-column', invocation.body);
-      const ok = await knowledge.kanban.reorderColumn(scopeOf(invocation), columnId, position);
-      if (!ok) throw opNotFound('column', columnId);
-      return { reordered: true };
-    };
-
-    handlers['knowledge:move-card'] = async (invocation) => {
-      const { cardId, toColumnId, position } = parseBody(moveCardBody, 'move-card', invocation.body);
-      const ok = await knowledge.kanban.moveCard(scopeOf(invocation), cardId, toColumnId, position);
-      // false ⇒ the card OR the destination column is not the caller's — the repo
-      // guards both sides, so a card can never be flung into another tenant's board.
-      if (!ok) throw opNotFound('card', cardId);
-      return { moved: true };
-    };
-
-    // The Airtable-list column reorder ACTION (§1c / §4) — the list analog of
-    // `reorder-column`: ONE `UPDATE … SET position` in `l_columns`, tenant-guarded
-    // through its list. A separate op from the kanban reorder because it targets a
-    // different table; `false` (unknown/foreign column) becomes a typed 404.
-    handlers['knowledge:reorder-list-column'] = async (invocation) => {
-      const { columnId, position } = parseBody(reorderColumnBody, 'reorder-list-column', invocation.body);
-      const ok = await knowledge.lists.reorderColumn(scopeOf(invocation), columnId, position);
-      if (!ok) throw opNotFound('list column', columnId);
-      return { reordered: true };
-    };
-  }
-
-  /* --------------------------------------------------------------- dev */
-
-  const dev = services.dev;
-  const exec = options.exec;
-
-  if (dev && exec) {
-    /**
-     * The op probe 14 drives. `commandId` is caller-supplied ON PURPOSE — a
-     * pipeline names which whitelisted step to run — and the driver is what
-     * refuses anything not in `cc-manifest.json`. Validating the id here as
-     * well would be theater: the whitelist is the authority, and it is checked
-     * on the way in.
-     */
-    handlers['dev:run-pipeline'] = async (invocation) => {
-      const body = parseBody(runPipelineBody, 'run-pipeline', invocation.body);
-      const handle = await exec.run({
-        commandId: body.commandId,
-        args: body.args,
-        cwd: body.cwd,
-        tenantId: invocation.claims.tenantId,
-        instanceId: invocation.instanceId,
-      });
-      return { handleId: handle.handleId, pid: handle.pid, commandId: handle.commandId };
-    };
-
-    handlers['dev:restart-app'] = async (invocation) => {
-      const { appId } = parseBody(restartAppBody, 'restart-app', invocation.body);
-      const handle = await exec.run({
-        commandId: commands.restartApp,
-        args: { appId },
-        tenantId: invocation.claims.tenantId,
-        instanceId: invocation.instanceId,
-      });
-      return { handleId: handle.handleId, pid: handle.pid };
-    };
-  }
-
-  if (dev) {
-    handlers['dev:deploy-app'] = (invocation) => {
-      const { appId } = parseBody(deployAppBody, 'deploy-app', invocation.body);
-      return enqueue(invocation, OP_JOB_KINDS.deploy, { appId });
-    };
-
-    handlers['dev:write-config'] = async (invocation) => {
-      const body = parseBody(writeConfigBody, 'write-config', invocation.body);
-      await dev.writeConfig(scopeOf(invocation), body.appId, body.patch);
-      return { written: true };
-    };
-
-    handlers['dev:db-export'] = async (invocation) => {
-      const { domain } = parseBody(dbExportBody, 'db-export', invocation.body);
-      // `VACUUM INTO` a snapshot inside the service — never a copy of a live
-      // `.db` (01 §6.1).
-      return await dev.exportDatabase(scopeOf(invocation), domain);
-    };
-  }
-
-  /* ------------------------------------------------------------- guard */
-
-  const guard = services.guard;
-  if (guard) {
-    handlers['guard:lock'] = async (invocation) => {
-      await guard.lock(scopeOf(invocation));
-      // The lock is mandatory-broadcast: one tab locking locks all tabs
-      // (03 §6.5, V7.9). Publishing app-wide — not per instance — is the point;
-      // a lock concerns every surface, not the one that asked for it.
-      options.push?.publish({
-        event: 'lifecycle',
-        data: { type: 'VAULT_LOCKED' },
-        tenantId: invocation.claims.tenantId,
-      });
-      return { locked: true };
-    };
-
-    handlers['guard:rotate-secret'] = async (invocation) => {
-      const { key } = parseBody(rotateSecretBody, 'rotate-secret', invocation.body);
-      const summary = await guard.rotateSecret(scopeOf(invocation), key);
-      return { rotated: true, key: summary.key, updatedAt: summary.updatedAt };
-    };
-  }
-
-  /* ------------------------------------------------------------ system */
-
-  const system = services.system;
-  if (system) {
-    handlers['system:run-utility'] = (invocation) => {
-      const body = parseBody(utilityBody, 'run-utility', invocation.body);
-      const utility = options.utilities?.[body.utility];
-      if (!utility)
-        throw new AppError(`No utility '${body.utility}' is registered on this host.`, {
-          code: 'UTILITY_NOT_REGISTERED',
-          status: 404,
-          // The utility NAME the caller asked for, never the registered set —
-          // enumerating it back is free reconnaissance (§3.2).
-          context: { utility: body.utility },
-        });
-      return { output: utility(body.input) };
-    };
-
-    handlers['system:http-send'] = async (invocation) => {
-      const body = parseBody(httpSendBody, 'http-send', invocation.body);
-      // Fail-closed BEFORE the service runs. Same guard, same placement as the
-      // route (finding 4.2): an ops path that skipped it would re-open the SSRF
-      // through a second door.
-      assertPublicOutboundUrl(body.url, options.outboundGuard);
-      return await system.sendHttp(scopeOf(invocation), {
-        url: body.url,
-        method: body.method,
-        headers: body.headers,
-        body: body.body,
-      });
-    };
-
-    // Occurrence marking (§3 / §4) — toggling ONE recurrence occurrence
-    // done/skipped is an action on the series, not a resource, so it is an op.
-    // The mark feeds the pure `expandEvent` expander's completions/exdates sets;
-    // the repo re-earns tenancy through the FK chain to `cal_calendars`, so a
-    // foreign `eventId` marks nothing and returns null → typed 404.
-    handlers['system:mark-occurrence'] = async (invocation) => {
-      const { eventId, occurredOn, state } = parseBody(occurrenceMarkBody, 'mark-occurrence', invocation.body);
-      const mark = await system.calendar.setMark(scopeOf(invocation), eventId, occurredOn, state);
-      if (!mark) throw opNotFound('calendar event', eventId);
-      return { mark };
-    };
-
-    handlers['system:clear-occurrence'] = async (invocation) => {
-      const { eventId, occurredOn } = parseBody(clearOccurrenceBody, 'clear-occurrence', invocation.body);
-      const cleared = await system.calendar.clearMark(scopeOf(invocation), eventId, occurredOn);
-      if (!cleared) throw opNotFound('occurrence mark', `${eventId}@${occurredOn}`);
-      return { cleared: true };
-    };
-
-    // Time-off state machine (§3 / §4). A decision on a request is an ACTION, not
-    // a resource write, so it is an op. Approval debits the ledger EXACTLY ONCE in
-    // the repo's own transaction; a `null` (foreign, or not in the required source
-    // state) becomes a typed 404 that keeps the request's existence undisclosed.
-    handlers['system:approve-timeoff'] = async (invocation) => {
-      const { id } = parseBody(idBody, 'approve-timeoff', invocation.body);
-      const request = await system.timeOff.approveRequest(scopeOf(invocation), id);
-      if (!request) throw opNotFound('time-off request', id);
-      return { request };
-    };
-
-    handlers['system:deny-timeoff'] = async (invocation) => {
-      const { id } = parseBody(idBody, 'deny-timeoff', invocation.body);
-      const request = await system.timeOff.denyRequest(scopeOf(invocation), id);
-      if (!request) throw opNotFound('time-off request', id);
-      return { request };
-    };
-
-    handlers['system:cancel-timeoff'] = async (invocation) => {
-      const { id } = parseBody(idBody, 'cancel-timeoff', invocation.body);
-      const request = await system.timeOff.cancelRequest(scopeOf(invocation), id);
-      if (!request) throw opNotFound('time-off request', id);
-      return { request };
-    };
-
-    // Subscription cancel (§4) — idempotent: the repo stamps `cancelled_at`, and a
-    // second cancel returns `null` → typed 404, so a double-cancel is a safe no-op.
-    handlers['system:cancel-subscription'] = async (invocation) => {
-      const { id } = parseBody(idBody, 'cancel-subscription', invocation.body);
-      const subscription = await system.subscriptions.cancel(scopeOf(invocation), id);
-      if (!subscription) throw opNotFound('subscription', id);
-      return { subscription };
-    };
-  }
-
-  return handlers;
-}
-
-/**
- * A typed 404 for an op whose target resource does not exist for this caller.
- * The message names the KIND but the code is the generic `ENTITY_NOT_FOUND`, so
- * a cross-tenant probe cannot tell "no such id" from "not yours" (J3-2).
- */
-const opNotFound = (kind: string, id: string): AppError =>
-  new AppError(`No ${kind} '${id}' for this tenant.`, {
-    code: 'ENTITY_NOT_FOUND',
-    status: 404,
-    context: { id },
-  });

package/src/server/ops/engineOpsCatalog.spec.ts

@@ -1,141 +0,0 @@
-/**
- * The op-catalog coverage gate — every registered op handler MUST have a matching
- * declared op in `ENGINE_CATALOG`, and vice versa.
- *
- * Why this exists: an instance's ops allowlist is materialized in V2 PURELY from
- * `engine.ops` (the descriptor) filtered by effective features — the app config
- * has no `ops` field (`InstanceSchema` is `.strict()`). So a handler registered in
- * `engineOps.ts` with NO descriptor entry is uncallable in every generated app:
- * `instanceMixin` looks the op up in `instance.ops`, does not find it, and returns
- * a 404 `op-disabled-by-config` — even though the handler exists. That gap is
- * invisible to the round-trip suites, which hand-build `EffectiveInstance.ops`
- * directly and thus bypass V2. This test closes it by pinning the two sets equal,
- * so adding a handler without its descriptor op (or a descriptor op without its
- * handler) fails here rather than silently shipping a dead action surface.
- *
- * Registration only inspects service/exec PRESENCE (never calls a method), so
- * empty cast stubs are enough to enumerate every handler the fully-wired host gets.
- */
-import { describe, expect, it } from 'bun:test';
-import { type EngineId, featureKeysOf } from '../../config/appConfig';
-import { ENGINE_CATALOG } from '../../verify/engines';
-import { verifyAppConfig } from '../../verify/pipeline';
-import type { ExecutionDriver, JobBroker } from '../drivers';
-import type { EngineServices } from '../mixins/services';
-import { createEngineOpHandlers } from './engineOps';
-
-// All five engine services present + an ExecutionDriver, so EVERY conditional
-// handler block registers. The bodies are never invoked here.
-const fullyWired = {
-  services: { asset: {}, knowledge: {}, guard: {}, dev: {}, system: {} } as unknown as EngineServices,
-  broker: {} as unknown as JobBroker,
-  exec: {} as unknown as ExecutionDriver,
-};
-
-const handlerKeys = (): string[] => Object.keys(createEngineOpHandlers(fullyWired)).sort();
-const descriptorKeys = (): string[] =>
-  ENGINE_CATALOG.flatMap((engine) => engine.ops.map((op) => `${engine.id}:${op.id}`)).sort();
-
-describe('engine op catalog coverage', () => {
-  it('every registered op handler is declared in ENGINE_CATALOG (else it 404s in a generated app)', () => {
-    const declared = new Set(descriptorKeys());
-    const undeclared = handlerKeys().filter((key) => !declared.has(key));
-    // A handler with no descriptor op can never reach a generated app's allowlist.
-    expect(undeclared).toEqual([]);
-  });
-
-  it('every declared op has a registered handler (else it 501s at call time)', () => {
-    const handled = new Set(handlerKeys());
-    const unhandled = descriptorKeys().filter((key) => !handled.has(key));
-    // A descriptor op with no handler is a 501 `OP_NOT_IMPLEMENTED` waiting to happen.
-    expect(unhandled).toEqual([]);
-  });
-
-  it('the two sets are exactly equal', () => {
-    expect(handlerKeys()).toEqual(descriptorKeys());
-  });
-});
-
-/**
- * The `requiredFeature` parity gate (06 §1, L6).
- *
- * The id-set gate above proves every op has BOTH a handler and a descriptor — but
- * says nothing about whether each descriptor op's `requiredFeature` is CORRECT. A
- * `move-card` op mistagged `requiredFeature: 'notes'` instead of `'kanban'` still has
- * a matching id on both sides, so the id-set gate stays green, yet V2 would strand the
- * op (feature-off) or leak it onto instances that never claimed the feature. Only ONE
- * `requiredFeature` pair was exercised anywhere before this gate (`pipeline.spec.ts`,
- * `transcode ← hls`); the other ~30 were unguarded.
- *
- * This closes the class by DERIVING the ops allowlist through the REAL pipeline
- * (`verifyAppConfig` → V2), not a hand-built manifest (Law #4). For each descriptor op
- * with a `requiredFeature`: the feature must be a real feature of its engine, and a
- * manifest with exactly that feature ON must materialize the op into `instance.ops`
- * while the same feature OFF must not.
- *
- * What it catches: a `requiredFeature` naming a non-existent feature (the first
- * assertion), and a tag V2 does not actually honor for materialization (the second).
- * What it does NOT catch: a tag pointing at a different *real* feature of the same
- * engine (`move-card` → `notes` instead of `kanban`) — toggling `notes` still flips the
- * op, so structure alone cannot distinguish it. There is no machine-readable
- * handler↔feature map to anchor that; §3's positive `pipeline → ops → success` smoke and
- * the studio's own review are the backstop for semantic mistags. This gate is the
- * structural half the id-set gate left open.
- */
-
-/** Every capability any feature depends on, all present — so a feature-ON config is
- * never silently downgraded to OFF by a missing host capability (V2 `effective(f) =
- * features[f] ∧ capabilities[dep(f)]`). Mirrors `pipeline.spec.ts`'s `FULL`. */
-const FULL_CAPS = {
-  ffmpeg: true,
-  wasm: true,
-  shell: true,
-  aiProvider: true,
-  diskIndex: true,
-  network: true,
-  ocrRuntime: true,
-  git: true,
-} as const;
-
-/** A minimal one-instance app-config (raw — V0 parses it) for `engine` with the given
- * feature overrides. No routes/wires, so no view or required-port references to satisfy. */
-const singleInstanceConfig = (engine: EngineId, features: Record<string, boolean>) => ({
-  configVersion: 1,
-  app: { id: `parity-${engine}`, title: `parity ${engine}` },
-  engines: [engine],
-  instances: [{ engine, id: 'probe', features }],
-});
-
-/** The op-ids V2 materializes onto the single probe instance for these features. */
-const materializedOps = async (engine: EngineId, features: Record<string, boolean>): Promise<string[]> => {
-  const result = await verifyAppConfig({ config: singleInstanceConfig(engine, features), moment: 'ci', capabilities: FULL_CAPS });
-  const instance = result.manifest?.instances.find((i) => i.id === 'probe');
-  return (instance?.ops ?? []).map((op) => op.id);
-};
-
-describe('descriptor op requiredFeature parity through the real pipeline (06 §1)', () => {
-  for (const engine of ENGINE_CATALOG) {
-    for (const op of engine.ops) {
-      const key = `${engine.id}:${op.id}`;
-      const feature = op.requiredFeature;
-
-      if (feature === undefined) {
-        // A baseline (no-feature-override) op must always materialize — its presence is
-        // not gated, so removing it from the allowlist would be a silent action loss.
-        it(`${key} (no requiredFeature) materializes on a baseline instance`, async () => {
-          expect(await materializedOps(engine.id, {})).toContain(op.id);
-        });
-        continue;
-      }
-
-      it(`${key} requiredFeature '${feature}' names a real feature of engine '${engine.id}'`, () => {
-        expect(featureKeysOf(engine.id)).toContain(feature);
-      });
-
-      it(`${key} materializes iff '${feature}' is effective-on (feature-on ⇒ present, off ⇒ absent)`, async () => {
-        expect(await materializedOps(engine.id, { [feature]: true })).toContain(op.id);
-        expect(await materializedOps(engine.id, { [feature]: false })).not.toContain(op.id);
-      });
-    }
-  }
-});

package/src/server/ops/index.ts

@@ -1,4 +0,0 @@
-// The production op handler table for `/api/instance/:id/ops/:op` (03 §3.2) —
-// the wiring that turns the contained `ExecutionDriver` into DevStudio's actual
-// server power (§4.1).
-export * from './engineOps';

package/src/server/paths/appDataHome.spec.ts

@@ -1,87 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { APP_DATA_HOME_ENV, resolveAppDataHome, XDG_DATA_HOME_ENV } from "./appDataHome";
-
-/**
- * The published-library defect this file is the gate for: a resolver that knows
- * the name of a directory in one person's home. Every assertion below is either
- * "the caller decides" or "the OS decides"; there is no third source.
- */
-describe("the app-data home", () => {
-	it("takes an explicit argument over everything else", () => {
-		expect(
-			resolveAppDataHome({
-				override: "/srv/data",
-				env: { [APP_DATA_HOME_ENV]: "/env/data", [XDG_DATA_HOME_ENV]: "/xdg", HOME: "/home/x" },
-			}),
-		).toBe("/srv/data");
-	});
-
-	it("reads APP_DATA_HOME — the one env var — before any convention", () => {
-		expect(
-			resolveAppDataHome({
-				env: { [APP_DATA_HOME_ENV]: "/env/data", [XDG_DATA_HOME_ENV]: "/xdg", HOME: "/home/x" },
-			}),
-		).toBe("/env/data");
-	});
-
-	it("honors XDG_DATA_HOME on every platform, macOS included", () => {
-		for (const platform of ["darwin", "linux"]) {
-			expect(resolveAppDataHome({ env: { [XDG_DATA_HOME_ENV]: "/xdg", HOME: "/home/x" }, platform })).toBe("/xdg");
-		}
-	});
-
-	it("falls back to the macOS convention, not to anybody's dotfolder", () => {
-		const resolved = resolveAppDataHome({ env: { HOME: "/home/x" }, platform: "darwin" });
-		expect(resolved).toBe(join("/home/x", "Library", "Application Support"));
-	});
-
-	it("falls back to the XDG default path elsewhere", () => {
-		expect(resolveAppDataHome({ env: { HOME: "/home/x" }, platform: "linux" })).toBe(
-			join("/home/x", ".local", "share"),
-		);
-	});
-
-	// Whitespace is how an env var gets "set" by a shell script that meant to unset
-	// it; treating it as configuration points every app at the filesystem root.
-	it("treats a blank setting as no setting", () => {
-		expect(
-			resolveAppDataHome({
-				override: "  ",
-				env: { [APP_DATA_HOME_ENV]: " ", [XDG_DATA_HOME_ENV]: "", HOME: "/home/x" },
-				platform: "linux",
-			}),
-		).toBe(join("/home/x", ".local", "share"));
-	});
-
-	it("falls back to the process's own home when the env names none", () => {
-		expect(resolveAppDataHome({ env: {}, platform: "linux" })).toBe(join(homedir(), ".local", "share"));
-	});
-
-	/**
-	 * 🔴 The assertion this module exists for. It is deliberately a property of the
-	 * OUTPUT rather than of the source text, so it still holds if somebody
-	 * reintroduces the old folder through a variable, a `join`, or a constant.
-	 */
-	it("never resolves a previous generation's private directory", () => {
-		const envs: Array<Record<string, string | undefined>> = [
-			{},
-			{ HOME: "/home/x" },
-			{ HOME: "/home/x", [APP_DATA_HOME_ENV]: "/srv/data" },
-			{ HOME: "/home/x", [XDG_DATA_HOME_ENV]: "/xdg" },
-			// The previous generation's own env var must no longer steer anything: the
-			// value below is deliberately unlike any convention, so a resolver that
-			// still read this var could not produce a passing answer by accident.
-			{ HOME: "/home/x", APP_MANAGED_HOME: "/nowhere/inherited" },
-		];
-		for (const env of envs) {
-			for (const platform of ["darwin", "linux"]) {
-				const resolved = resolveAppDataHome({ env, platform });
-				expect(resolved).not.toContain("app-managed");
-				expect(resolved).not.toContain("code-retiring");
-				expect(resolved).not.toContain("Master-Docs");
-			}
-		}
-	});
-});