cursedbelt 2.7.0 → 3.0.0

package/src/server/mixins/services.ts

@@ -1,1314 +0,0 @@
-/**
- * Engine service seams — what each master engine's route block calls into.
- *
- * The mixins own **composition and enforcement**: which routes exist for which
- * effective features, which sub-blocks are behind `guardVerify`, which ops
- * require `infra:write`. They deliberately do NOT own SQL. 01 §2.5 puts that
- * behind repositories built on `StorageProvider` ("engines import repositories
- * only"), and cursedbelt is a library — hardcoding a `SELECT` here would make
- * every generated app share one schema forever.
- *
- * So each engine declares the operations its declared route block needs, and the
- * generated app injects an implementation over its own repositories. The
- * interfaces are narrow on purpose: a route that does not exist in 03 §1 has no
- * method here, which keeps the server surface derivable from the spec rather
- * than from whatever a service happened to expose.
- */
-import type { CCRole, CCUserClaims } from '../../core/session/claims';
-
-/** Every service call carries the caller's verified identity. Never optional. */
-export interface CallScope {
-  claims: CCUserClaims;
-  /** The instance whose effective config governs this call (03 §3.2). */
-  instanceId?: string;
-}
-
-export interface Page<T> {
-  items: readonly T[];
-  /** Opaque continuation token; absent when the page is the last one. */
-  cursor?: string;
-}
-
-/* ------------------------------------------------------------------ asset */
-
-export interface MediaItemView {
-  id: string;
-  kind: 'video' | 'photo' | 'file';
-  title?: string;
-  /** Progressive playback URL. Always present; HLS is the optional upgrade. */
-  streamUrl?: string;
-  /** Present only when this item has an HLS rendition AND `hls` is effective-on. */
-  hlsUrl?: string;
-  private?: boolean;
-}
-
-/* ---- vault sources (asset sub-domain, `mv_sources`, §2a / §4) ---- */
-
-/**
- * A configured vault source — the ROWS that replaced the old
- * `mediaSources: [...]` config block.
- *
- * `rootKey` is the security boundary and it is read-only after creation: a source
- * is root-bounded, everything reachable through it lives under that key, and the
- * entire reason this moved out of config is that a config file can be edited to
- * re-point a source at `/`. Re-rooting is delete-and-recreate, which the CDC
- * stream records as exactly what it is.
- */
-export interface SourceView {
-  id: string;
-  /** `vault` (content-addressed) or `folder` (a filesystem root). */
-  kind: string;
-  title: string;
-  rootKey: string;
-  readOnly: boolean;
-}
-
-/**
- * Vault source CRUD (`mv_sources`), mounted behind the `vaultSource` feature.
- *
- * `update` takes a title and a read-only flag and NOTHING else — see
- * {@link SourceView.rootKey}.
- */
-export interface SourceService {
-  list(scope: CallScope): Promise<readonly SourceView[]>;
-  get(scope: CallScope, id: string): Promise<SourceView | null>;
-  create(scope: CallScope, input: { kind: string; title: string; rootKey: string; readOnly?: boolean }): Promise<SourceView>;
-  update(scope: CallScope, id: string, patch: { title?: string; readOnly?: boolean }): Promise<SourceView | null>;
-  remove(scope: CallScope, id: string): Promise<boolean>;
-}
-
-/* ---- albums (asset sub-domain, vault `mv_*`, §2a / §4) ---- */
-
-export interface AlbumView {
-  id: string;
-  title: string;
-  coverId?: string;
-  createdAt: string;
-}
-export interface AlbumAssetView {
-  id: string;
-  title?: string;
-  mimeType: string;
-  byteSize: number;
-}
-
-/**
- * Album CRUD + ordered membership over the vault (`mv_albums`,
- * `mv_album_members`), mounted behind the `gallery` feature (§4). Membership
- * reorder is ONE `UPDATE … SET position` in the repo (the album-member analog
- * of the kanban reorder law). Every membership mutation is guarded to the
- * caller's album AND asset in SQL — a foreign id writes nothing and returns
- * `false`.
- */
-export interface AlbumService {
-  list(scope: CallScope): Promise<readonly AlbumView[]>;
-  get(scope: CallScope, id: string): Promise<AlbumView | null>;
-  create(scope: CallScope, input: { title: string }): Promise<AlbumView>;
-  update(scope: CallScope, id: string, patch: { title?: string; coverId?: string | null }): Promise<AlbumView | null>;
-  remove(scope: CallScope, id: string): Promise<boolean>;
-  listAssets(scope: CallScope, albumId: string): Promise<readonly AlbumAssetView[]>;
-  addAsset(scope: CallScope, albumId: string, assetId: string, position: number): Promise<boolean>;
-  reorderAsset(scope: CallScope, albumId: string, assetId: string, position: number): Promise<boolean>;
-  removeAsset(scope: CallScope, albumId: string, assetId: string): Promise<boolean>;
-}
-
-/* ---- vault upload staging (asset sub-domain, `mv_uploads` → `mv_assets`, §2a / §4) ---- */
-
-/** A content-addressed vault asset as the upload route yields it. */
-export interface VaultAssetView {
-  id: string;
-  title?: string;
-  mimeType: string;
-  byteSize: number;
-  /** The content hash the vault is keyed on — identical bytes share one asset. */
-  checksum: string;
-  createdAt: string;
-}
-
-/**
- * The result of promoting a staged upload. `deduped` is `true` when these exact
- * bytes were already vaulted — a content-addressed store answers "I already have
- * this" as a success, and the caller stored zero NEW bytes (so it posts no
- * storage meter event and reclaims the redundant object).
- */
-export interface VaultUploadResultView {
-  uploadId: string;
-  asset: VaultAssetView;
-  deduped: boolean;
-}
-
-/** The state of a staging row — what the poll route reads back. */
-export interface VaultUploadStatusView {
-  id: string;
-  fileName: string;
-  mimeType: string;
-  byteSize: number;
-  received: number;
-  status: 'pending' | 'processing' | 'ready' | 'failed';
-  checksum?: string;
-  completedAt?: string;
-}
-
-export interface AssetService {
-  /**
-   * List media. `revealPrivate` is decided by the SERVER from the verified
-   * session, never by a client flag — a public listing must contain zero
-   * private items while locked (V7 probe 2).
-   */
-  list(scope: CallScope, opts: { revealPrivate: boolean; cursor?: string }): Promise<Page<MediaItemView>>;
-  /**
-   * ONE public item's metadata — the detail read the `video-detail` view rides
-   * (03 §1e). It is NOT derivable from `list`: the listing is a keyset page, so
-   * an item deep in the union is simply not on the page a detail route is asked
-   * about, and paging the whole catalogue to find one row is a scan.
-   *
-   * `null` for unknown, foreign AND private ids — the same single answer the
-   * bytes route gives, so this route is not an oracle for which ids are sealed.
-   */
-  get(scope: CallScope, id: string): Promise<MediaItemView | null>;
-  /**
-   * Bytes for a PUBLIC item. This route sits behind a plain session with no
-   * private-scope requirement, so it MUST fail-closed on a private id: return
-   * `null` (which the mixin turns into a typed 404), never the bytes. Private
-   * items are reachable only via {@link AssetService.readPrivate} behind
-   * `requirePrivateScope` — the mixin cannot tell a private id from a public one,
-   * so this method is the enforcement point (V7 probe 2, §4.3).
-   */
-  read(scope: CallScope, id: string): Promise<ReadableStream<Uint8Array> | null>;
-  /** Bytes for a private item — only reached behind `requirePrivateScope`. */
-  readPrivate(scope: CallScope, id: string): Promise<ReadableStream<Uint8Array> | null>;
-  /** HLS master playlist; mounted only when `hls` is effective-on. */
-  hlsPlaylist(scope: CallScope, id: string): Promise<string | null>;
-  /** Chunked multipart upload — streams straight to the ObjectStore (01 §2.5). */
-  upload(scope: CallScope, request: Request): Promise<{ id: string }>;
-  /**
-   * Soft-delete a catalogued file (§6.3 — never a hard destroy) and post the
-   * negative `storage.bytes` credit so the meter nets (§2c). Returns `false` for
-   * an unknown/foreign/already-trashed id — the mixin turns that into a typed 404,
-   * so the id's existence stays undisclosed and a double-delete is a safe no-op.
-   */
-  remove(scope: CallScope, id: string): Promise<boolean>;
-  /** Queue an OCR extraction; output feeds `knowledge` via CDC. */
-  requestOcr(scope: CallScope, id: string): Promise<{ jobId: string }>;
-  /**
-   * Serve bytes for a URL the LOCAL ObjectStore signed (08 §1a).
-   *
-   * Present only when the host wired a signed-url verifier — i.e. under the
-   * local profile, where `signedUrl` hands back an app-served path instead of a
-   * bucket presign. The mixin mounts `/api/asset/objects/*` iff this method
-   * exists, so under saas the route does not exist at all rather than existing
-   * and refusing: the bytes leave through the CDN there, and a route that
-   * cannot serve should not answer.
-   *
-   * Returns `null` for an unknown key AND for a bad/expired signature — the two
-   * are indistinguishable to the caller on purpose, so the endpoint is not an
-   * oracle for which keys exist.
-   */
-  readSignedObject?(claim: {
-    key: string;
-    expiresAt: number;
-    signature: string;
-  }): Promise<{ body: ReadableStream<Uint8Array>; contentType?: string } | null>;
-  /**
-   * Stage and promote a content-addressed vault upload (§2a / §4) — mounted
-   * behind the `vaultSource` feature. Bytes stream straight to the ObjectStore
-   * while a SHA-256 is computed WHILE streaming (never a whole-file RAM buffer,
-   * 01 §2.5); the settled checksum keys the `mv_assets` row, so a re-upload of
-   * identical bytes dedupes onto the existing asset. The actual streamed byte
-   * count — not the client's declared `Content-Length` — is what gets metered and
-   * stored, so the delete credit (§2c) reconciles the storage meter to net bytes.
-   */
-  vaultUpload(scope: CallScope, request: Request): Promise<VaultUploadResultView>;
-  /** Poll a staging row's state; `null` (⇒ typed 404) for an unknown/foreign id. */
-  vaultUploadStatus(scope: CallScope, id: string): Promise<VaultUploadStatusView | null>;
-  /**
-   * Reclaim staging rows stuck in `processing` past `olderThanMs` — the reaper
-   * the vault shipped without (05 §A2).
-   *
-   * NOT a route: this is a maintenance sweep the runtime drives on a timer
-   * (`createVaultUploadReaper`). It exists on the service rather than beside the
-   * repository because reclaiming a stranded upload is TWO stores — delete the
-   * orphaned object, then mark the row `failed` — and only the service holds
-   * both. Object first, so a crash between them leaves a `processing` row the
-   * next pass retries rather than a `failed` row whose bytes nobody will ever
-   * look for again.
-   */
-  reapStaleUploads(
-    scope: CallScope,
-    options?: { olderThanMs?: number; limit?: number },
-  ): Promise<{ reaped: number; objectsDeleted: number }>;
-  /** Vault albums — mounted behind the `gallery` feature (§4). */
-  albums: AlbumService;
-  /** Configured vault sources — mounted behind the `vaultSource` feature (§2a). */
-  sources: SourceService;
-}
-
-/* -------------------------------------------------------------- knowledge */
-
-export interface RecordView {
-  id: string;
-  type: string;
-  title: string;
-  tenantId: string;
-  updatedAt: string;
-}
-
-/**
- * ONE record with the parts a LISTING deliberately omits: its body and whichever
- * satellite its type owns (01 §2.1 — satellite tables, not an attribute bag).
- *
- * It is a superset of {@link RecordView}, so every existing consumer of the
- * entity route keeps working; what changes is that the `note` detail view
- * (03 §1e) can finally render a note's text. Before this, `k_items.body_md` and
- * the five `k_*` satellite tables were written by the repository, joined by
- * `getRecordFull`, and then dropped on the floor by the service's projection —
- * a far side with no near side, one `SELECT` away from being reachable.
- *
- * Every satellite field is OPTIONAL and absent rather than defaulted: a
- * `{ done: false }` invented for a record that has no todo satellite renders a
- * confidently wrong checkbox, which is worse than rendering nothing.
- */
-export interface RecordDetailView extends RecordView {
-  /** Markdown body. Absent ⇒ the record has none, not "empty string". */
-  bodyMd?: string;
-  pinned: boolean;
-  archived: boolean;
-  todo?: { status: 'open' | 'done'; priority: number; dueAt?: string; position: number };
-  bookmark?: { url: string; tags: readonly string[] };
-  worklog?: { loggedOn: string; minutes?: number };
-  article?: { status: 'draft' | 'review' | 'published'; sourceUrl?: string };
-  habit?: { cadence: 'daily' | 'weekly' | 'monthly'; streak: number };
-}
-
-/* ------- kanban (knowledge sub-domain, §1b / §4) ------- */
-
-export interface KanbanBoardView {
-  id: string;
-  title: string;
-  createdAt: string;
-}
-export interface KanbanColumnView {
-  id: string;
-  boardId: string;
-  title: string;
-  position: number;
-  wipLimit?: number;
-}
-export interface KanbanCardView {
-  id: string;
-  columnId: string;
-  title: string;
-  bodyMd?: string;
-  labels: readonly string[];
-  position: number;
-  /** Set when this card projects a `k_items` todo. */
-  kItemId?: string;
-}
-
-/**
- * The board→column→card CRUD plus the two O(1) ordering ops (§1b, §4). Every
- * child mutation reaches the tenant through its parent chain in the repository —
- * a foreign `boardId`/`columnId`/`cardId` writes zero rows and returns
- * `null`/`false`, which the mixin turns into a typed 404. `reorderColumn` and
- * `moveCard` are ONE `UPDATE … SET position` each in the repo; the whole reason
- * the DDL has a real `position` column is that a rewrite loop would be a defect.
- */
-export interface KanbanService {
-  listBoards(scope: CallScope): Promise<readonly KanbanBoardView[]>;
-  getBoard(scope: CallScope, id: string): Promise<KanbanBoardView | null>;
-  createBoard(scope: CallScope, input: { title: string }): Promise<KanbanBoardView>;
-  updateBoard(scope: CallScope, id: string, patch: { title?: string }): Promise<KanbanBoardView | null>;
-  removeBoard(scope: CallScope, id: string): Promise<boolean>;
-  listColumns(scope: CallScope, boardId: string): Promise<readonly KanbanColumnView[]>;
-  createColumn(
-    scope: CallScope,
-    boardId: string,
-    input: { title: string; position: number; wipLimit?: number },
-  ): Promise<KanbanColumnView | null>;
-  updateColumn(
-    scope: CallScope,
-    columnId: string,
-    patch: { title?: string; wipLimit?: number | null },
-  ): Promise<KanbanColumnView | null>;
-  /** ONE `UPDATE … SET position` (§1b). `false` ⇒ unknown/foreign column. */
-  reorderColumn(scope: CallScope, columnId: string, position: number): Promise<boolean>;
-  removeColumn(scope: CallScope, columnId: string): Promise<boolean>;
-  listCards(scope: CallScope, columnId: string): Promise<readonly KanbanCardView[]>;
-  /**
-   * Every card on a board, across all its columns — the read a BOARD renders.
-   * The per-column read forces one request per column, which grows with someone
-   * else's column count and never yields a coherent snapshot.
-   */
-  listBoardCards(scope: CallScope, boardId: string): Promise<readonly KanbanCardView[]>;
-  createCard(
-    scope: CallScope,
-    columnId: string,
-    input: { title: string; bodyMd?: string; labels?: readonly string[]; position: number },
-  ): Promise<KanbanCardView | null>;
-  updateCard(
-    scope: CallScope,
-    cardId: string,
-    patch: { title?: string; bodyMd?: string | null; labels?: readonly string[] },
-  ): Promise<KanbanCardView | null>;
-  /** ONE `UPDATE` guarding BOTH source and target column by tenant (§1b). */
-  moveCard(scope: CallScope, cardId: string, toColumnId: string, position: number): Promise<boolean>;
-  removeCard(scope: CallScope, cardId: string): Promise<boolean>;
-}
-
-/* ------- lists (knowledge sub-domain, `l_*`, §1c / §4) ------- */
-
-/** A cell value before it is routed to its typed storage column (`v_*`). */
-export type ListCellValue = string | number | boolean | null;
-/** The six storage classes an `l_columns` column may declare. */
-export type ListColumnType = 'text' | 'select' | 'number' | 'bool' | 'date' | 'json';
-
-export interface ListView {
-  id: string;
-  title: string;
-}
-export interface ListColumnView {
-  id: string;
-  listId: string;
-  name: string;
-  colType: ListColumnType;
-  position: number;
-  options: Record<string, unknown>;
-}
-export interface ListRowView {
-  id: string;
-  listId: string;
-  position: number;
-}
-/** A row paired with one column's typed value, in that column's native sort order. */
-export interface SortedListRowView extends ListRowView {
-  value: ListCellValue;
-}
-/** One stored cell, decoded from whichever typed column its class lives in. */
-export interface ListCellView {
-  rowId: string;
-  columnId: string;
-  value: ListCellValue;
-}
-
-/**
- * Airtable-style lists (`l_lists`/`l_columns`/`l_rows`/`l_values`), mounted
- * behind the `airtableStyleLists` feature (§4). The defining law is the TYPED
- * cell writer: `setCell` routes a value to its declared storage class and
- * refuses a class mismatch (`LIST_VALUE_TYPE_MISMATCH`), which is what keeps
- * `sortedRows` correct. Only `l_lists` carries `tenant_id`; columns, rows and
- * cells re-earn it through the FK chain, so a foreign `listId`/`columnId`/`rowId`
- * writes nothing and returns `null`/`false` → typed 404. `reorderColumn` is the
- * `knowledge:reorder-list-column` OP (an ordering action), not a route.
- */
-export interface ListService {
-  list(scope: CallScope): Promise<readonly ListView[]>;
-  get(scope: CallScope, id: string): Promise<ListView | null>;
-  create(scope: CallScope, input: { title: string }): Promise<ListView>;
-  remove(scope: CallScope, id: string): Promise<boolean>;
-  listColumns(scope: CallScope, listId: string): Promise<readonly ListColumnView[]>;
-  createColumn(
-    scope: CallScope,
-    listId: string,
-    input: { name: string; colType: ListColumnType; position: number; options?: Record<string, unknown> },
-  ): Promise<ListColumnView | null>;
-  removeColumn(scope: CallScope, columnId: string): Promise<boolean>;
-  /** ONE `UPDATE … SET position` (the O(1) reorder law); `false` ⇒ foreign column. */
-  reorderColumn(scope: CallScope, columnId: string, position: number): Promise<boolean>;
-  listRows(scope: CallScope, listId: string): Promise<readonly ListRowView[]>;
-  /**
-   * Every stored cell of a list, decoded to its declared class — the read a grid
-   * needs. The sorted read answers ONE column; without this a client would issue
-   * one sorted request per column and join them by row id. Unset cells are
-   * absent; a foreign list folds to zero rows (never a 403).
-   */
-  listCells(scope: CallScope, listId: string): Promise<readonly ListCellView[]>;
-  createRow(scope: CallScope, listId: string, input: { position: number }): Promise<ListRowView | null>;
-  removeRow(scope: CallScope, rowId: string): Promise<boolean>;
-  /** Write one typed cell; `false` ⇒ foreign row/column, throws on a class mismatch. */
-  setCell(scope: CallScope, rowId: string, columnId: string, value: ListCellValue): Promise<boolean>;
-  /** Rows ordered by ONE column's typed value; `null` ⇒ foreign list/column. */
-  sortedRows(
-    scope: CallScope,
-    listId: string,
-    columnId: string,
-    opts: { descending?: boolean },
-  ): Promise<readonly SortedListRowView[] | null>;
-}
-
-/* ------- contacts (knowledge sub-domain, `c_contacts`, §1a / §4) ------- */
-
-export interface ContactView {
-  id: string;
-  displayName: string;
-  vcardUid?: string;
-  fields: Record<string, unknown>;
-  birthday?: string;
-}
-
-/**
- * Contacts CRUD, mounted behind the `contacts` feature (§4). A vCard-UID
- * collision surfaces as a typed 409 (`CONTACT_VCARD_DUPLICATE`) rather than a
- * raw 500 — the global unique index on `c_contacts.vcard_uid` is the hard
- * backstop. `birthdays` folds the repo's yearly-recurring MM-DD window query.
- */
-export interface ContactService {
-  list(scope: CallScope): Promise<readonly ContactView[]>;
-  get(scope: CallScope, id: string): Promise<ContactView | null>;
-  create(
-    scope: CallScope,
-    input: { displayName: string; vcardUid?: string; fields?: Record<string, unknown>; birthday?: string },
-  ): Promise<ContactView>;
-  update(
-    scope: CallScope,
-    id: string,
-    patch: { displayName?: string; birthday?: string | null; fields?: Record<string, unknown> },
-  ): Promise<ContactView | null>;
-  remove(scope: CallScope, id: string): Promise<boolean>;
-  /** Contacts whose birthday's MM-DD falls in `[from, to]`; a wrapping window spans the year end. */
-  birthdays(scope: CallScope, from: string, to: string): Promise<readonly ContactView[]>;
-}
-
-/* ------- family (knowledge sub-domain, `f_*`, §1a / §4) ------- */
-
-export interface PersonView {
-  id: string;
-  displayName: string;
-  given?: string;
-  family?: string;
-  sex?: string;
-  birth?: string;
-  death?: string;
-  fields: Record<string, unknown>;
-}
-export interface PartnershipView {
-  id: string;
-  aId: string;
-  bId: string;
-  kind?: string;
-  span?: string;
-}
-export interface FamilyEventView {
-  id: string;
-  personId?: string;
-  kind: string;
-  at?: string;
-  place?: string;
-  note?: string;
-}
-export interface FamilySubgraphView {
-  people: readonly PersonView[];
-  partnerships: readonly PartnershipView[];
-}
-
-/**
- * The family tree (`f_people`/`f_partnerships`/`f_events`), mounted behind the
- * `family` feature (§4). Every table carries `tenant_id`, and a partnership/
- * person-attached-event write guards BOTH referenced people in SQL, so a foreign
- * person id writes nothing and returns `null` → typed 404. `subgraph` is the
- * tenant-scoped BFS the hourglass canvas renders (depth clamped in the repo).
- */
-export interface FamilyService {
-  listPeople(scope: CallScope): Promise<readonly PersonView[]>;
-  getPerson(scope: CallScope, id: string): Promise<PersonView | null>;
-  createPerson(
-    scope: CallScope,
-    input: {
-      displayName: string;
-      given?: string;
-      family?: string;
-      sex?: string;
-      birth?: string;
-      death?: string;
-      fields?: Record<string, unknown>;
-    },
-  ): Promise<PersonView>;
-  updatePerson(
-    scope: CallScope,
-    id: string,
-    patch: {
-      displayName?: string;
-      given?: string;
-      family?: string;
-      sex?: string;
-      birth?: string;
-      death?: string;
-      fields?: Record<string, unknown>;
-    },
-  ): Promise<PersonView | null>;
-  removePerson(scope: CallScope, id: string): Promise<boolean>;
-  listPartnerships(scope: CallScope, personId?: string): Promise<readonly PartnershipView[]>;
-  createPartnership(
-    scope: CallScope,
-    input: { aId: string; bId: string; kind?: string; span?: string },
-  ): Promise<PartnershipView | null>;
-  removePartnership(scope: CallScope, id: string): Promise<boolean>;
-  listEvents(scope: CallScope, personId: string): Promise<readonly FamilyEventView[]>;
-  createEvent(
-    scope: CallScope,
-    input: { personId?: string; kind: string; at?: string; place?: string; note?: string },
-  ): Promise<FamilyEventView | null>;
-  removeEvent(scope: CallScope, id: string): Promise<boolean>;
-  subgraph(scope: CallScope, rootId: string, depth: number): Promise<FamilySubgraphView>;
-}
-
-/* ------- oral history (knowledge sub-domain, `oh_*`, §1a / §4) ------- */
-
-export interface RecordingView {
-  id: string;
-  title: string;
-  /** A `cc://asset/<id>` ref into the asset engine, when audio/video is attached. */
-  mediaFileId?: string;
-  questionPack?: string;
-  recordedAt?: string;
-}
-export interface SegmentView {
-  id: string;
-  recordingId: string;
-  seq: number;
-  startMs: number;
-  endMs: number;
-  transcript: string;
-}
-
-/**
- * Oral-history recordings + transcript segments (`oh_recordings`/`oh_segments`),
- * mounted behind the `oralHistory` feature (§4). A segment re-earns tenancy
- * through its recording's FK chain, so a foreign `recordingId`/`segmentId` writes
- * nothing and returns `null` → typed 404. `mediaFileId` is a cross-engine
- * `cc://asset/<id>` string ref, not a DB FK.
- */
-export interface OralHistoryService {
-  list(scope: CallScope): Promise<readonly RecordingView[]>;
-  get(scope: CallScope, id: string): Promise<RecordingView | null>;
-  create(
-    scope: CallScope,
-    input: { title: string; mediaFileId?: string; questionPack?: string; recordedAt?: string },
-  ): Promise<RecordingView>;
-  update(
-    scope: CallScope,
-    id: string,
-    patch: { title?: string; mediaFileId?: string | null; questionPack?: string | null; recordedAt?: string | null },
-  ): Promise<RecordingView | null>;
-  remove(scope: CallScope, id: string): Promise<boolean>;
-  listSegments(scope: CallScope, recordingId: string): Promise<readonly SegmentView[]>;
-  addSegment(
-    scope: CallScope,
-    recordingId: string,
-    input: { seq: number; startMs: number; endMs: number; transcript: string },
-  ): Promise<SegmentView | null>;
-  updateSegment(
-    scope: CallScope,
-    segmentId: string,
-    patch: { transcript?: string; startMs?: number; endMs?: number; seq?: number },
-  ): Promise<SegmentView | null>;
-  removeSegment(scope: CallScope, segmentId: string): Promise<boolean>;
-}
-
-export interface KnowledgeService {
-  list(scope: CallScope, opts: { type?: string; cursor?: string }): Promise<Page<RecordView>>;
-  /**
-   * Fetch one entity, WITH its body and satellite (03 §1e). MUST return null for
-   * a row belonging to another tenant — the route turns that into a typed 404,
-   * because a 403 would disclose that the id exists (J3-2).
-   */
-  get(scope: CallScope, id: string): Promise<RecordDetailView | null>;
-  create(scope: CallScope, input: { type: string; title: string; bodyMd?: string }): Promise<RecordView>;
-  update(scope: CallScope, id: string, patch: Record<string, unknown>): Promise<RecordView | null>;
-  remove(scope: CallScope, id: string): Promise<boolean>;
-  /** Corpus search; mounted only when `ragChat` is effective-on. */
-  search(scope: CallScope, query: string, opts: { corpus?: readonly string[] }): Promise<Page<RecordView>>;
-  /** AI organize pass — MUST go through `completeStructured` (03 §7.2). */
-  organize(scope: CallScope, ids: readonly string[]): Promise<{ jobId: string }>;
-  /** Kanban boards — the `b_*` sub-domain, mounted behind the `kanban` feature. */
-  kanban: KanbanService;
-  /** Airtable-style lists — the `l_*` sub-domain, behind `airtableStyleLists`. */
-  lists: ListService;
-  /** Contacts — the `c_contacts` sub-domain, behind `contacts`. */
-  contacts: ContactService;
-  /** Family tree — the `f_*` sub-domain, behind `family`. */
-  family: FamilyService;
-  /** Oral history — the `oh_*` sub-domain, behind `oralHistory`. */
-  oralHistory: OralHistoryService;
-}
-
-/* ------------------------------------------------------------------ guard */
-
-export interface UnlockResult {
-  token: string;
-  claims: CCUserClaims;
-}
-
-export interface SecretSummary {
-  key: string;
-  updatedAt: string;
-}
-
-/**
- * One audit-trail row as `GET /api/guard/audit` serves it (05 §B2, D25).
- *
- * Declared HERE, structurally, rather than re-exported from `cwip`'s
- * `AuditTrailEntry`: this file is reachable from the CLIENT type graph, and a
- * `cwip/storage` import drags the whole server storage tier into a DOM-typed
- * compile (the demo gate catches it). The shape is the wire contract, which is
- * the thing a client is entitled to depend on anyway.
- */
-export interface AuditEntryView {
-  /**
-   * The entry's opaque row id — its stable identity. Two entries of one
-   * transaction share a timestamp (the database stamps them at transaction
-   * start), so `at` alone does not identify a row.
-   */
-  id?: string;
-  /** The dotted `RepoOp.name`, e.g. `knowledge.createNote`. */
-  action: string;
-  domain: string;
-  profile: string;
-  tenantId: string;
-  /** The acting user id, or `system` for a write with no request behind it. */
-  actor: string;
-  /** The row the op touched, when it could be determined. */
-  targetId?: string;
-  /** ISO-8601 UTC, stamped by the DATABASE clock. */
-  at?: string;
-  inTransaction: boolean;
-}
-
-export interface GuardService {
-  /**
-   * Verify the passphrase and mint a session. The passphrase arrives as bytes
-   * from the request stream and is zeroized immediately after the KDF (01 §3.4)
-   * — it must never become a JS string on the way here.
-   */
-  unlock(request: Request): Promise<UnlockResult>;
-  /** Revoke the session, zeroize key buffers, broadcast the lock to every tab. */
-  lock(scope: CallScope): Promise<void>;
-  /** Secret KEYS and timestamps only — never envelopes, never plaintext. */
-  listSecrets(scope: CallScope): Promise<readonly SecretSummary[]>;
-  putSecret(scope: CallScope, key: string, request: Request): Promise<SecretSummary>;
-  rotateSecret(scope: CallScope, key: string): Promise<SecretSummary>;
-}
-
-/* ------------------------------------------------------------------ account */
-
-/**
- * What a successful passphrase check (or login) grants — resolved by the host's
- * `AccountService`, not guessed. Defined here (client-light) rather than in
- * `services/guardService.ts` so `EngineServices.account` can name the account
- * surface without dragging the server driver tier into the client type graph.
- */
-export interface UnlockedIdentity {
-  tenantId: string;
-  userId: string;
-  role: CCRole;
-  permissions: readonly string[];
-}
-
-/** The public view of an account after signup — no secret material rides it. */
-export interface AccountView {
-  userId: string;
-  email?: string;
-  tenantId: string;
-  role: CCRole;
-}
-
-/** A signup: an email + password (consumed), creating a user + tenant + membership. */
-export interface SignupRequest {
-  email: string;
-  /** Owned bytes; consumed (zeroized) by `signup`. */
-  password: Uint8Array;
-  /** saas only: the new tenant's title. Defaults to the email. */
-  tenantTitle?: string;
-  /** The membership role. Defaults: saas ⇒ OWNER (the tenant creator), local ⇒ MEMBER. */
-  role?: CCRole;
-  /**
-   * An invitation token (02 §3). Present ⇒ the new account JOINS the inviting
-   * tenant with the role the invitation named, instead of creating its own
-   * tenant (saas) or joining the machine tenant (local) — and `role`/
-   * `tenantTitle` are ignored, because the inviter decided both. The token must
-   * be unexpired, unaccepted, and issued to this exact email.
-   */
-  inviteToken?: string;
-}
-
-/** A tenant as an administrator sees it (02 §3). */
-export interface TenantView {
-  tenantId: string;
-  title: string;
-  status: 'active' | 'suspended' | 'deleted';
-  planId: string;
-}
-
-/** One row of the members panel — the EFFECTIVE grant, not just the stored one. */
-export interface MemberView {
-  tenantId: string;
-  userId: string;
-  email?: string;
-  role: CCRole;
-  /** The explicit per-membership grants (what an admin edits). */
-  grants: readonly string[];
-  /** `role` ∪ `grants` — what a session minted for this member would carry. */
-  permissions: readonly string[];
-  status: string;
-}
-
-/** An issued invitation. The raw `token` is returned ONCE and never stored. */
-export interface InvitationView {
-  tenantId: string;
-  email: string;
-  role: CCRole;
-  expiresAt: string;
-  /**
-   * The single-use secret the invitee presents. Only the request that CREATED
-   * the invitation ever sees it — the store keeps a SHA-256 of it, so a stolen
-   * registry file yields no usable invite (the same reason `secrets.summaries`
-   * never yields an envelope). Deliver it out of band (a `Notifier`).
-   */
-  token: string;
-}
-
-/** The patch an OWNER/ADMIN applies to one membership (02 §3). */
-export interface MemberPatch {
-  role?: CCRole;
-  /** Explicit grants BEYOND the role's own. Replaces the stored list. */
-  grants?: readonly string[];
-  /** `active` | `suspended` — a suspended membership resolves to no identity. */
-  status?: string;
-}
-
-/** A login: an email + password (consumed), minting a session on success. */
-export interface LoginRequest {
-  email: string;
-  /** Owned bytes; consumed (zeroized) by `login`. */
-  password: Uint8Array;
-  /**
-   * What this device calls itself, for the sessions panel (02 §4). Display
-   * metadata only — it is recorded beside the jti, never signed into the token
-   * (the claims schema is `.strict()`, and a client-supplied string inside the
-   * signed payload is attacker-controlled text every verifier would parse).
-   */
-  deviceLabel?: string;
-}
-
-/**
- * One live session of the calling account (02 §4) — a row of "your devices".
- * Carries no token: a session list that hands back credentials is a credential
- * list. The only thing a caller may do with another row is end it.
- */
-export interface SessionView {
-  jti: string;
-  tenantId: string;
-  deviceLabel?: string;
-  /** ISO timestamps, derived from the signer's epoch-second record. */
-  issuedAt: string;
-  expiresAt: string;
-  /** True for the session that made this request. */
-  current: boolean;
-}
-
-/** A password change: the new password, plus the current one when the caller is self. */
-export interface PasswordChangeRequest {
-  /** The caller's current password — REQUIRED for a self-change, ignored for an admin reset. Consumed. */
-  current?: Uint8Array;
-  /** The new password. Consumed. */
-  next: Uint8Array;
-}
-
-/**
- * The account surface backing the guard mixin's auth routes (02 §2), and the
- * concrete `resolveIdentity` the guard service consumes (02 §1). Every method is
- * mounted behind a route so nothing is an orphan seam (Law #1); every password
- * rides the ONE argon2id KDF seam (Law #7) and is CONSUMED (zeroized) as bytes.
- */
-export interface AccountService {
-  /** The concrete `resolveIdentity` `createGuardService` calls. */
-  resolveIdentity(): Promise<UnlockedIdentity | null>;
-  /** Create a user + tenant + membership with a password. Consumes `req.password`. */
-  signup(req: SignupRequest): Promise<AccountView>;
-  /** Verify a password and mint a session carrying the user's membership role. Consumes `req.password`. */
-  login(req: LoginRequest): Promise<{ token: string; claims: CCUserClaims }>;
-  /** Re-seal a user's password. Consumes `req.current` (if present) and `req.next`. */
-  changePassword(scope: CallScope, userId: string, req: PasswordChangeRequest): Promise<void>;
-
-  /* ---- session concurrency & lifecycle, multi-device (02 §4) ------------- */
-  /** The caller's own live sessions, newest first. Never another account's. */
-  listSessions(scope: CallScope): Promise<readonly SessionView[]>;
-  /**
-   * Re-mint the CALLING session: the presented (already verified) token is
-   * exchanged for a fresh one carrying the membership as the store holds it NOW,
-   * and the old jti is revoked so exactly one token per device stays live.
-   *
-   * A revoked or role-changed session cannot refresh, because a grant change
-   * revokes the target's sessions (§3) and `guardVerify` refuses a revoked token
-   * before this is ever reached — the denylist wins, which is the point.
-   */
-  refreshSession(scope: CallScope): Promise<{ token: string; claims: CCUserClaims }>;
-  /** End one of the caller's OWN sessions by jti (log out this device). */
-  endSession(scope: CallScope, jti: string): Promise<boolean>;
-  /** "Log out everywhere" — revoke every live session of the calling account. */
-  logoutEverywhere(scope: CallScope): Promise<{ revoked: number }>;
-
-  /* ---- tenant lifecycle & RBAC administration (02 §3) ------------------- */
-  /**
-   * Every verb below decides authorization SERVER-SIDE from the caller's
-   * membership as the store holds it NOW — never from the role frozen into the
-   * token — and refuses privilege escalation: you cannot assign a role above
-   * your own, only an OWNER assigns OWNER, and you cannot act on a member who
-   * outranks you. A grant change revokes the target's live sessions, because
-   * routes authorize from the token's claims: leaving the old token alive is a
-   * grant change that did not happen.
-   */
-  /** The tenant, for its own members. */
-  getTenant(scope: CallScope, tenantId: string): Promise<TenantView | null>;
-  /** Rename (ADMIN+) or suspend/restore/soft-delete (OWNER only). */
-  updateTenant(scope: CallScope, tenantId: string, patch: { title?: string; status?: TenantView['status'] }): Promise<TenantView>;
-  /**
-   * Assign the tenant's PLAN (P2 — the entitlement anchor). Deliberately NOT
-   * part of `updateTenant`: that verb's authorization is tenant-internal
-   * (ADMIN/OWNER of the tenant), and a tenant assigning its own plan is a
-   * customer picking their price. Who may call this is the ROUTE's platform
-   * check (the store-anchored platform tenant, same rule as site copy); the
-   * service validates the id's shape and the tenant's existence, and is
-   * billing-shaped — a future subscription webhook lands on this same verb.
-   */
-  setTenantPlan(scope: CallScope, tenantId: string, planId: string): Promise<TenantView>;
-  /** The members panel (ADMIN+). */
-  listMembers(scope: CallScope, tenantId: string): Promise<readonly MemberView[]>;
-  /** Issue a single-use invitation (ADMIN+, never above your own role). */
-  inviteMember(
-    scope: CallScope,
-    tenantId: string,
-    input: { email: string; role: CCRole; ttlMinutes?: number },
-  ): Promise<InvitationView>;
-  /** Accept an invitation as the AUTHENTICATED caller (their email must match). */
-  acceptInvitation(scope: CallScope, token: string): Promise<MemberView>;
-  /** Change a member's role/grants/status (ADMIN+). Revokes the target's sessions. */
-  updateMember(scope: CallScope, tenantId: string, userId: string, patch: MemberPatch): Promise<MemberView>;
-  /** Remove a membership (ADMIN+). Revokes the target's sessions. */
-  removeMember(scope: CallScope, tenantId: string, userId: string): Promise<boolean>;
-}
-
-/* -------------------------------------------------------------------- dev */
-
-export interface AppSummary {
-  appId: string;
-  title: string;
-  running: boolean;
-  port?: number;
-}
-
-/**
- * One registered app, in full — the `app-detail` view's subject (03 §1e).
- *
- * Everything here is a registry fact: the `apps` row, the app's `ports` claims,
- * the aliases pointing at it, and whatever its recorded manifest declares. It is
- * deliberately NOT a superset of `AppSummary` with a config blob bolted on:
- * plaintext env values are `configEditor`'s privileged surface (J2-2), and a
- * detail read that quietly included them would route around that gate.
- */
-export interface AppDetailView extends AppSummary {
-  kind: string;
-  localPath: string;
-  /** The recorded live pid, present only while `running`. */
-  pid?: number;
-  lastBooted?: string;
-  /** EVERY port claimed by this app — `AppSummary.port` is only the lowest. */
-  ports: readonly number[];
-  aliases: readonly { name: string; command: string }[];
-  /** `cursed.app.commands` from the app's recorded manifest, if it declared any. */
-  commands: Readonly<Record<string, string>>;
-  /** `cursed.app.docs` — the doc paths the `docs` surface may read for this app. */
-  docs: readonly string[];
-}
-
-/** A doc an app declares, as the `docs` surface lists it. */
-export interface DocEntryView {
-  appId: string;
-  appTitle: string;
-  /** App-relative path, exactly as the manifest declared it. */
-  path: string;
-}
-
-/** A doc's contents. `text` is raw markdown; rendering is the client's job. */
-export interface DocContentView extends DocEntryView {
-  text: string;
-}
-
-/** A runnable pipeline — the whitelisted command as a UI sees it (03 §1e). */
-export interface PipelineView {
-  id: string;
-  params: readonly string[];
-  timeoutMs?: number;
-}
-
-/** One dispatched pipeline run. */
-export interface PipelineRunView {
-  handleId: string;
-  commandId: string;
-  state: 'running' | 'exited' | 'killed' | 'failed';
-  exitCode: number | null;
-  startedAt: number;
-  endedAt: number | null;
-}
-
-/** A captured screenshot, as the `screenshots` surface lists it. */
-export interface ScreenshotView {
-  /** Source-relative name — also the path segment the bytes route takes. */
-  name: string;
-  bytes: number;
-  /** ISO-8601 UTC capture (or file-modification) time. */
-  capturedAt: string;
-  contentType: string;
-}
-
-/** A terminal job outcome, as the `orchestration` surface lists it. */
-export interface JobRunView {
-  jobId: string;
-  ok: boolean;
-  error?: string;
-  at: string;
-  instanceId?: string;
-}
-
-export interface DevService {
-  listApps(scope: CallScope): Promise<readonly AppSummary[]>;
-  /** One registered app in full (03 §1e). Typed 404 for an unregistered id. */
-  appDetail(scope: CallScope, appId: string): Promise<AppDetailView>;
-  fleet(scope: CallScope): Promise<readonly AppSummary[]>;
-  deploy(scope: CallScope, appId: string): Promise<{ jobId: string }>;
-  /** Every doc every registered app declares. */
-  listDocs(scope: CallScope): Promise<readonly DocEntryView[]>;
-  /** One declared doc's text. Refuses a path the app's manifest does not declare. */
-  readDoc(scope: CallScope, appId: string, docPath: string): Promise<DocContentView>;
-  /** The runnable whitelist and the runs dispatched from it. */
-  pipelines(scope: CallScope): Promise<readonly PipelineView[]>;
-  pipelineRuns(scope: CallScope): Promise<readonly PipelineRunView[]>;
-  /** Captured screenshots, and one screenshot's bytes. */
-  screenshots(scope: CallScope): Promise<readonly ScreenshotView[]>;
-  readScreenshot(scope: CallScope, name: string): Promise<{ bytes: Uint8Array; contentType: string }>;
-  /** Recent terminal job outcomes for the caller's tenant, newest first. */
-  jobs(scope: CallScope): Promise<readonly JobRunView[]>;
-  /** Read config — `infra:write` gated at the route (02 §4.4). */
-  readConfig(scope: CallScope, appId: string): Promise<Record<string, string>>;
-  writeConfig(scope: CallScope, appId: string, patch: Record<string, string>): Promise<void>;
-  /** Export a domain DB via `VACUUM INTO` — never a live-file copy (01 §6). */
-  exportDatabase(scope: CallScope, domain: string): Promise<{ snapshotPath: string }>;
-  diskUsage(scope: CallScope): Promise<{ path: string; bytes: number }[]>;
-}
-
-/* ----------------------------------------------------------------- system */
-
-export interface CalendarEventView {
-  id: string;
-  title: string;
-  startsAt: string;
-  endsAt?: string;
-}
-
-export interface NotificationView {
-  id: string;
-  title: string;
-  body?: string;
-  done: boolean;
-}
-
-/* ------- calendar (system sub-domain, `cal_*`, §3 / §4) ------- */
-
-export interface CalendarView {
-  id: string;
-  title: string;
-  color?: string;
-  visible: boolean;
-}
-export interface CalendarEventDetailView {
-  id: string;
-  calendarId: string;
-  title: string;
-  bodyMd?: string;
-  location?: string;
-  startsAt: string;
-  endsAt?: string;
-  allDay: boolean;
-  /** RFC-5545 recurrence rule; expanded by the pure `core/calendar` fn, not here. */
-  rrule?: string;
-  kItemId?: string;
-}
-export interface OccurrenceMarkView {
-  eventId: string;
-  occurredOn: string;
-  state: 'done' | 'skipped';
-}
-
-/**
- * Calendar CRUD + occurrence marks (§3 / §4). `cal_events`/`cal_done_marks`
- * carry no `tenant_id`; every write re-earns tenancy through the FK chain to
- * `cal_calendars` in the repository, so a foreign `calendarId`/`eventId` writes
- * nothing and returns `null`/`false`. Recurrence EXPANSION stays the pure
- * `core/calendar` `expandEvent(rule, window)` function — never re-implemented in
- * this service.
- */
-export interface CalendarService {
-  listCalendars(scope: CallScope): Promise<readonly CalendarView[]>;
-  createCalendar(
-    scope: CallScope,
-    input: { title: string; color?: string; visible?: boolean },
-  ): Promise<CalendarView>;
-  updateCalendar(
-    scope: CallScope,
-    id: string,
-    patch: { title?: string; color?: string | null; visible?: boolean },
-  ): Promise<CalendarView | null>;
-  removeCalendar(scope: CallScope, id: string): Promise<boolean>;
-  getEvent(scope: CallScope, id: string): Promise<CalendarEventDetailView | null>;
-  createEvent(
-    scope: CallScope,
-    input: {
-      calendarId: string;
-      title: string;
-      startsAt: string;
-      endsAt?: string;
-      allDay?: boolean;
-      bodyMd?: string;
-      location?: string;
-      rrule?: string;
-    },
-  ): Promise<CalendarEventDetailView | null>;
-  updateEvent(
-    scope: CallScope,
-    id: string,
-    patch: {
-      title?: string;
-      bodyMd?: string | null;
-      location?: string | null;
-      startsAt?: string;
-      endsAt?: string | null;
-      allDay?: boolean;
-      rrule?: string | null;
-    },
-  ): Promise<CalendarEventDetailView | null>;
-  removeEvent(scope: CallScope, id: string): Promise<boolean>;
-  listMarks(scope: CallScope, calendarId: string): Promise<readonly OccurrenceMarkView[]>;
-  /** Toggle a single occurrence `done`/`skipped` — a guarded idempotent upsert. */
-  setMark(
-    scope: CallScope,
-    eventId: string,
-    occurredOn: string,
-    state: 'done' | 'skipped',
-  ): Promise<OccurrenceMarkView | null>;
-  clearMark(scope: CallScope, eventId: string, occurredOn: string): Promise<boolean>;
-}
-
-/* ------- time off (system sub-domain, `to_*`, §3 / §4) ------- */
-
-export type TimeOffRequestStatus = 'pending' | 'approved' | 'denied' | 'cancelled';
-
-export interface TimeOffPolicyView {
-  id: string;
-  title: string;
-  accrualDays: number;
-  carryoverMax?: number;
-}
-export interface TimeOffRequestView {
-  id: string;
-  userId: string;
-  policyId?: string;
-  startsOn: string;
-  endsOn: string;
-  days: number;
-  status: TimeOffRequestStatus;
-  note?: string;
-  createdAt: string;
-  decidedAt?: string;
-}
-export interface TimeOffLedgerView {
-  id: string;
-  userId: string;
-  policyId?: string;
-  requestId?: string;
-  deltaDays: number;
-  reason: string;
-  at: string;
-}
-
-/**
- * Time-off policies, requests and the append-only ledger (`to_policies`/
- * `to_requests`/`to_ledger`), mounted behind the `timeOff` feature (§4). The
- * page-backed CRUD lives on routes; the state-machine ACTIONS
- * (approve/deny/cancel) are instance ops (§4) because a decision on a request is
- * an action, not a resource write. Approval debits the ledger EXACTLY ONCE — the
- * repo flips `pending → approved` with a status-guarded `UPDATE` so a double
- * approve changes zero rows and writes no second debit — and `balance` folds the
- * ledger, so the two stay reconciled. A foreign/not-pending id returns `null`,
- * which the op turns into a typed 404.
- */
-export interface TimeOffService {
-  listPolicies(scope: CallScope): Promise<readonly TimeOffPolicyView[]>;
-  createPolicy(
-    scope: CallScope,
-    input: { title: string; accrualDays?: number; carryoverMax?: number },
-  ): Promise<TimeOffPolicyView>;
-  updatePolicy(
-    scope: CallScope,
-    id: string,
-    patch: { title?: string; accrualDays?: number; carryoverMax?: number | null },
-  ): Promise<TimeOffPolicyView | null>;
-  removePolicy(scope: CallScope, id: string): Promise<boolean>;
-  listRequests(scope: CallScope, opts: { status?: TimeOffRequestStatus }): Promise<readonly TimeOffRequestView[]>;
-  getRequest(scope: CallScope, id: string): Promise<TimeOffRequestView | null>;
-  createRequest(
-    scope: CallScope,
-    input: { policyId?: string; startsOn: string; endsOn: string; days: number; note?: string },
-  ): Promise<TimeOffRequestView>;
-  /** pending→approved, debiting the ledger exactly once; `null` ⇒ foreign/not-pending. */
-  approveRequest(scope: CallScope, id: string): Promise<TimeOffRequestView | null>;
-  /** pending→denied, no ledger movement; `null` ⇒ foreign/not-pending. */
-  denyRequest(scope: CallScope, id: string): Promise<TimeOffRequestView | null>;
-  /** approved/pending→cancelled, crediting an approved request's days back once; `null` ⇒ foreign/terminal. */
-  cancelRequest(scope: CallScope, id: string): Promise<TimeOffRequestView | null>;
-  listLedger(scope: CallScope, opts: { policyId?: string }): Promise<readonly TimeOffLedgerView[]>;
-  /** The folded balance of the append-only ledger (negative ⇒ net debited). */
-  balance(scope: CallScope, policyId?: string): Promise<number>;
-}
-
-/* ------- budgets (system sub-domain, `bg_*`, §3 / §4) ------- */
-
-export type BudgetPeriod = 'weekly' | 'monthly' | 'yearly';
-
-export interface BudgetView {
-  id: string;
-  title: string;
-  period: BudgetPeriod;
-  amountCents: number;
-  currency: string;
-}
-export interface BudgetEntryView {
-  id: string;
-  budgetId: string;
-  occurredOn: string;
-  amountCents: number;
-  category?: string;
-  note?: string;
-}
-
-/**
- * Budgets and their entries (`bg_budgets`/`bg_entries`), mounted behind the
- * `budgets` feature (§4). Entries re-earn tenancy through the FK chain to
- * `bg_budgets`, so a foreign `budgetId` writes nothing and returns `null` → typed
- * 404. `spend` folds the entries in a window — the read the budget UI compares
- * against `amountCents`. Money is integer cents everywhere; no float ever touches
- * a currency amount.
- */
-export interface BudgetService {
-  list(scope: CallScope): Promise<readonly BudgetView[]>;
-  create(
-    scope: CallScope,
-    input: { title: string; period?: BudgetPeriod; amountCents?: number; currency?: string },
-  ): Promise<BudgetView>;
-  update(
-    scope: CallScope,
-    id: string,
-    patch: { title?: string; period?: BudgetPeriod; amountCents?: number; currency?: string },
-  ): Promise<BudgetView | null>;
-  remove(scope: CallScope, id: string): Promise<boolean>;
-  listEntries(scope: CallScope, budgetId: string, window: { from?: string; to?: string }): Promise<readonly BudgetEntryView[]>;
-  createEntry(
-    scope: CallScope,
-    budgetId: string,
-    input: { occurredOn: string; amountCents: number; category?: string; note?: string },
-  ): Promise<BudgetEntryView | null>;
-  removeEntry(scope: CallScope, id: string): Promise<boolean>;
-  /** Summed spend over `[from, to]` (integer cents); a foreign budget folds to 0. */
-  spend(scope: CallScope, budgetId: string, window: { from?: string; to?: string }): Promise<number>;
-}
-
-/* ------- subscriptions (system sub-domain, `sub_*`, §3 / §4) ------- */
-
-export type SubscriptionCadence = 'weekly' | 'monthly' | 'yearly';
-
-export interface SubscriptionView {
-  id: string;
-  title: string;
-  amountCents: number;
-  currency: string;
-  cadence: SubscriptionCadence;
-  nextDueOn?: string;
-  cancelledAt?: string;
-}
-
-/**
- * Recurring subscriptions (`sub_subscriptions`), mounted behind the
- * `subscriptions` feature (§4). Living in `budgetsRepo` beside budgets — there is
- * no separate subscriptions repo. Cancel is an instance OP (a state action), and
- * is idempotent: it stamps `cancelled_at`, and a second cancel returns `null`,
- * which the op turns into a typed 404 so a double-cancel is a safe non-event.
- */
-export interface SubscriptionService {
-  list(scope: CallScope, opts: { includeCancelled?: boolean }): Promise<readonly SubscriptionView[]>;
-  create(
-    scope: CallScope,
-    input: { title: string; amountCents?: number; currency?: string; cadence?: SubscriptionCadence; nextDueOn?: string },
-  ): Promise<SubscriptionView>;
-  update(
-    scope: CallScope,
-    id: string,
-    patch: {
-      title?: string;
-      amountCents?: number;
-      currency?: string;
-      cadence?: SubscriptionCadence;
-      nextDueOn?: string | null;
-    },
-  ): Promise<SubscriptionView | null>;
-  /** Idempotent cancel — stamps `cancelled_at`; `null` ⇒ foreign/already-cancelled. */
-  cancel(scope: CallScope, id: string): Promise<SubscriptionView | null>;
-}
-
-export interface SystemService {
-  listEvents(scope: CallScope, range: { from: string; to: string }): Promise<readonly CalendarEventView[]>;
-  listNotifications(scope: CallScope): Promise<readonly NotificationView[]>;
-  markNotificationDone(scope: CallScope, id: string): Promise<boolean>;
-  /** Calendar CRUD + marks — mounted behind the `calendar` feature (§4). */
-  calendar: CalendarService;
-  /** Time-off policies/requests/ledger — mounted behind the `timeOff` feature (§4). */
-  timeOff: TimeOffService;
-  /** Budgets + entries — mounted behind the `budgets` feature (§4). */
-  budgets: BudgetService;
-  /** Recurring subscriptions — mounted behind the `subscriptions` feature (§4). */
-  subscriptions: SubscriptionService;
-  /**
-   * Request Builder's send. Server-side by design (02 §1.5): the pinned CSP
-   * would block a browser-side call to an arbitrary host, and doing it here is
-   * what keeps `httpClient` working without widening `connect-src`.
-   *
-   * SSRF contract: the `url` reaching this method has already passed the
-   * framework's fail-closed {@link assertPublicOutboundUrl} guard at the route,
-   * so a private/loopback/link-local/reserved target is rejected before an impl
-   * runs. An impl that follows redirects, or resolves a hostname itself, MUST
-   * re-guard each resulting target (use `assertResolvedPublicUrl`) — the SaaS
-   * profile must additionally enforce network-layer egress. Never treat `url` as
-   * pre-sanitized beyond the single hop the route validated.
-   */
-  sendHttp(
-    scope: CallScope,
-    spec: { url: string; method: string; headers?: Record<string, string>; body?: string },
-  ): Promise<{ status: number; headers: Record<string, string>; body: string }>;
-}
-
-/**
- * The service bag handed to `composeServer`. Every engine named in `engines[]`
- * must have its service present — `composeServer` throws at boot otherwise,
- * which is a startup failure rather than a 500 on the first request that
- * happens to touch the missing one.
- */
-export interface EngineServices {
-  asset?: AssetService;
-  knowledge?: KnowledgeService;
-  guard?: GuardService;
-  /**
-   * The account surface backing the guard mixin's auth routes (02 §2). Present
-   * iff the guard engine is active AND an identity store was wired; the mixin
-   * mounts `/api/guard/login`/`accounts` only when it is.
-   */
-  account?: AccountService;
-  dev?: DevService;
-  system?: SystemService;
-}