cursedbelt 0.0.0 → 2.3.0

package/dist/server/mixins/services.d.ts

@@ -0,0 +1,1317 @@
+/**
+ * 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;
+}
+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;
+}
+/**
+ * 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>;
+}
+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>;
+}
+/** 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;
+}
+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;
+    };
+}
+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>;
+}
+/** 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>;
+}
+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[]>;
+}
+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>;
+}
+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;
+}
+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>;
+}
+/**
+ * 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>;
+    /** 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;
+    }>;
+    /**
+     * 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>;
+}
+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;
+    }[]>;
+}
+export interface CalendarEventView {
+    id: string;
+    title: string;
+    startsAt: string;
+    endsAt?: string;
+}
+export interface NotificationView {
+    id: string;
+    title: string;
+    body?: string;
+    done: boolean;
+}
+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>;
+}
+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>;
+}
+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>;
+}
+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;
+}
+//# sourceMappingURL=services.d.ts.map