@open-tomato/rafa 0.44.0 → 0.46.0

package/dist/ports/index.d.ts

@@ -0,0 +1,732 @@
+/**
+ * The package's ports: the seven interfaces core defines for an adapter
+ * to implement, declared as types with no implementation behind any of
+ * them.
+ *
+ * The spec's `exports` map names this module's build as the `./ports`
+ * subpath, declared in phase 0 and filled in phase 1. Phase 1 puts one
+ * adapter per port under `src/adapters/` and lets an add-on register
+ * more by name; core imports an add-on only from a `path` source the
+ * config's `allowList:` names (`src/modules/load.ts`). What those adapters
+ * implement is declared here first, so a service (the orchestrator's
+ * worker pool, a Drizzle-backed store) can type an implementation
+ * against the subpath without importing the CLI.
+ *
+ * ## Types, and nothing else
+ *
+ * The entry exports no runtime value, so importing it runs nothing and
+ * adds nothing to a service's bundle. Its imports are `import type`
+ * lines, which the bundler erases, so naming {@link GeneratedPlan}'s
+ * review type pulls `./spec-review.ts` into no bundle. That
+ * keeps three things a port could otherwise carry out of this module:
+ *
+ *   - The store's key projection, `EFFORT_KEY_PROJECTIONS`, which is a
+ *     value. It stays on `./store`, beside the backends that read it.
+ *   - The Tracker source's `as const` tuples. Each union they derived
+ *     is spelled out as a literal union instead, keeping the members and
+ *     dropping the tuple, so nothing here enumerates them at runtime.
+ *   - The number core compares a port version against. The modules spec
+ *     gives every port a version and has core refuse a module whose
+ *     version it no longer serves. Each version is declared here as a
+ *     number literal type, gathered in {@link PortVersions} under the
+ *     port types the adapter registry keys by. The number core compares
+ *     is `PORT_VERSIONS` in `packages/rafa/src/core/adapters/registry.ts`, held equal to
+ *     these literals there.
+ *
+ * ## Where each port comes from
+ *
+ *   - {@link Tracker}: copied from open-tomato's
+ *     `packages/shared/issue-tracker/src/port.ts` at commit
+ *     `45aaab563e5b4f4e6258e19ebf752b7cfeb67bf0` (2026-08-05). The phase
+ *     1 spec asks for a copy rather than a dependency, with its source
+ *     commit recorded, so the monorepo can later be pointed at this
+ *     export and the port does not live twice. Member types and their
+ *     TSDoc are carried over as written, so they speak of open-tomato's
+ *     OPT numbers, CLI and ledger, with three exceptions: {@link TrackerKind}
+ *     is opened, {@link IssueType} gains `epic` and `spec`, and the note on
+ *     `IssueRef.externalId` names the `local` adapter's issue number
+ *     where the source named a file path. Four members are rafa's own
+ *     and absent from the source, all optional: the `openIssues`
+ *     reading, with the {@link OpenIssue} it answers, the `filedIssues`
+ *     reading, with the {@link FiledIssue} it answers, and the `editable`
+ *     and `edit` pair `rafa issue edit` writes through, with the
+ *     {@link EditableIssue} and {@link IssueEdit} they take and answer. Left
+ *     out: `BOARD_COLUMNS`, `CLOSED_STATES` and `GITHUB_ISSUE_TYPES`,
+ *     which are values and the GitHub adapter's projections, and
+ *     `LedgerEntry`, the local ledger's line. rafa ports no OPT ledger,
+ *     so the degradation chain (`src/adapters/tracker/resolve.ts`)
+ *     arrived without it, and the `local` adapter records the reason the
+ *     chain hands it in each issue file instead.
+ *   - {@link Store}: the effort store port phase 0 already built, in
+ *     `packages/rafa/src/effort/store/types.ts`, re-exported under the port's name
+ *     rather than declared again. `Store` is `EffortStore`, and the rows
+ *     and results it is typed against come with it.
+ *   - {@link Learning}: `distributed-learning-library.md`, "rafa's
+ *     Learning port", with the records it passes taken from that spec's
+ *     package shape. {@link InstinctRecord}, {@link SyncPayload},
+ *     {@link BlessedBundle}, {@link MergeRule}, {@link MergeDecision} and
+ *     {@link MergeResult} are declared in `./learning.ts` and re-exported
+ *     here under the same names. The learning library declares its own
+ *     six in `src/learning/types.ts`, since neither side may import the
+ *     other, and `src/tests/learning-contract.test.ts` holds each pair
+ *     mutually assignable.
+ *   - {@link Output}: open-tomato's `packages/shared/cli-core`, the
+ *     events from `src/events.ts` at
+ *     `2b00895eaec9edcdce02839831429da97441c0f5` and the interface from
+ *     `src/output.ts` at `18f94c843fff1bce65ed2245f8712ed9b64a2d51`
+ *     (both 2026-06-25), where it is named `CliOutput`. The source's
+ *     `text` and `json` factories are the two adapters phase 1 ports.
+ *   - {@link Planner}: no spec gives it a signature. The phase 1 table
+ *     names its core adapter as today's `plan.ts`, so the request and the
+ *     answer are read off what `rafa plan` takes and leaves behind.
+ *   - {@link Sync}: issue #323, "choose how a project's effort store
+ *     travels". The spec gives its two directions, push (send the rows
+ *     this store wrote) and pull (merge the rows another device wrote),
+ *     and the five strategies `effort.sync` selects between. Every
+ *     adapter's pull runs `mergeStore` (`packages/rafa/src/effort/store/merge-store.ts`),
+ *     so {@link SyncPullResult} carries that merge's own result type,
+ *     imported as `StoreMergeResult` because the Learning port's
+ *     `MergeResult` already holds the name here. The request types are
+ *     read off what the `file` strategy needs: the directory
+ *     `rafa effort copy` writes into, and the `effort.sqlite` and
+ *     `--dry-run` that `rafa effort import` hands the merge.
+ *
+ * ## Property signatures
+ *
+ * Every function a port declares is a function-typed property, never a
+ * method, as the store port's already are. TypeScript compares a
+ * method's parameters bivariantly and a property's strictly, so an
+ * adapter accepting less than the port hands it, such as a `transition`
+ * taking only `done`, compiles against a method and is refused against a
+ * property. The Tracker source and the Learning spec both spell methods.
+ * This is the one change the Learning port makes to a member's type; the
+ * Tracker copy makes one more, opening {@link TrackerKind}.
+ *
+ * ## Left open for phase 1
+ *
+ *   - {@link MergeResult}: the spec names `discarded` and describes the
+ *     rest without naming it. `decisions`, {@link MergeDecision} and the
+ *     {@link MergeRule} names are the learning library's, one rule per
+ *     row of the spec's merge table plus the record no existing trigger
+ *     shares.
+ *   - {@link PlanRequest} and {@link GeneratedPlan} carry what `rafa
+ *     plan` has today. The webhook adapter phase 6 adds lands a plan on a
+ *     branch, which may widen the answer.
+ */
+import type { BlessedBundle, MergeResult, SyncPayload } from './learning.js';
+import type { LogLevel } from './log-level.js';
+import type { SpecReviewReading } from './spec-review.js';
+import type { MergeResult as StoreMergeResult } from '../effort/store/merge-store.js';
+export type { LogLevel } from './log-level.js';
+export type { BlessedBundle, InstinctRecord, MergeDecision, MergeResult, MergeRule, SyncPayload, } from './learning.js';
+export type { AppendResult, CommitEffortRow, EffortKeyProjections, EffortRow, EffortRowByKind, EffortRowKind, EffortStore as Store, SessionEffortRow, SessionMode, } from '../effort/store/types.js';
+/** The version of the {@link Tracker} port this entry declares. */
+export type TrackerPortVersion = 1;
+/** The version of the {@link Store} port this entry declares. */
+export type StorePortVersion = 1;
+/** The version of the {@link Learning} port this entry declares. */
+export type LearningPortVersion = 1;
+/** The version of the {@link Output} port this entry declares. */
+export type OutputPortVersion = 1;
+/** The version of the {@link Planner} port this entry declares. */
+export type PlannerPortVersion = 1;
+/** The version of the {@link Sync} port this entry declares. */
+export type SyncPortVersion = 1;
+/**
+ * Each port's version, under the port type the adapter registry keys its
+ * adapters by. An adapter states the version of its port it implements,
+ * and the registry refuses one core does not serve.
+ */
+export interface PortVersions {
+    tracker: TrackerPortVersion;
+    store: StorePortVersion;
+    learning: LearningPortVersion;
+    output: OutputPortVersion;
+    planner: PlannerPortVersion;
+    sync: SyncPortVersion;
+    logger: LoggerPortVersion;
+}
+/**
+ * The seven port types: `tracker`, `store`, `learning`, `output`,
+ * `planner`, `sync` and `logger`.
+ */
+export type PortType = keyof PortVersions;
+/**
+ * The platform a tracker adapter projects issues onto, named as the
+ * adapter registry keys it.
+ *
+ * The source closes this over `github`, `linear` and `local`. The copy
+ * keeps those three and admits any other name, because an add-on
+ * registers a tracker under a kind core has never heard of (`obsidian`
+ * in the phase 1 table), and the config accepts any kind name for
+ * `tracker.default` and `tracker.fallback`. Whether a kind has an
+ * adapter is the registry's answer, not this type's.
+ *
+ * `string & {}` is a string the checker does not merge with the three
+ * named members. Under `| string` the union reduces to `string`, and the
+ * three names are gone from the type.
+ */
+export type TrackerKind = 'github' | 'linear' | 'local' | (string & {});
+/**
+ * What an issue is for. `epic` and `spec` are rafa's own members, absent
+ * from the source: an issue labelled `type:epic` groups the issues
+ * carrying its `epic:<slug>` label, and one labelled `type:spec` holds a
+ * spec on the board.
+ */
+export type IssueType = 'code' | 'bug' | 'spike' | 'adr' | 'chore' | 'package-api' | 'epic' | 'spec';
+/** How urgent an issue is, once triage has set it. */
+export type IssuePriority = 'urgent' | 'high' | 'medium' | 'low';
+/**
+ * One state per board column, plus `cancelled`, spelled in lifecycle
+ * order.
+ */
+export type IssueState = 'backlog' | 'todo' | 'in-progress' | 'in-review' | 'done' | 'released' | 'cancelled';
+/** A resolved pointer to an issue on some tracker. */
+export interface IssueRef {
+    /** Internal OPT number — stable across trackers. */
+    opt: number;
+    kind: TrackerKind;
+    /**
+     * GitHub issue number as a string, Linear uuid, or the number the `local`
+     * adapter gave the issue under `.rafa/issues/`, as a string.
+     */
+    externalId: string;
+    url: string | null;
+    /**
+     * Module the issue belongs to, when the caller already knows it (e.g. from
+     * a ledger entry). `transition()` on the GitHub adapter needs this to
+     * resolve which project board an issue lives on; when it's absent, the
+     * adapter falls back to reading the `module:` label via `get()` — an extra
+     * `gh issue view` round trip that a caller who already has this for free
+     * (the CLI, reading the ledger) can skip by setting it here.
+     */
+    module?: string;
+    /**
+     * `owner/name` for github refs. Absent means the configured default repo
+     * (`github.repo`) — set only when the issue's module routes to a repo of
+     * its own (`modules.*.repo`), so the common case stays untagged.
+     */
+    repo?: string;
+    /**
+     * Set when the issue was filed but a follow-up step failed — today, Projects
+     * v2 board placement. The issue exists and MUST still be recorded in the
+     * ledger; the caller is responsible for surfacing this to the user.
+     */
+    warning?: string;
+}
+/** Everything needed to create an issue, before any platform is chosen. */
+export interface IssueDraft {
+    opt: number;
+    title: string;
+    body: string;
+    type: IssueType;
+    module: string;
+    /** null means triage has not set one yet — the adapter applies needs-triage. */
+    priority: IssuePriority | null;
+    /** Project/board name, or null when the tracker has no project concept. */
+    project: string | null;
+    /** OPT numbers this issue is blocked by. */
+    blockedBy: readonly number[];
+    /**
+     * rafa's own field, absent from the source: true when the issue waits
+     * on other issues of the board, which the `github` adapter files as
+     * the board's `spec:blocked` label (`SPEC_BLOCKED_LABEL` in
+     * `src/board/blocked.ts`) and the `local` adapter records in the issue
+     * file. Absent or false files no such mark. Not {@link blockedBy},
+     * which names OPT ledger numbers.
+     */
+    specBlocked?: boolean;
+    /**
+     * rafa's own field, absent from the source: the cause code a bug was
+     * filed with (`context/error-codes.md`). The `github` adapter files it
+     * as the label `cause:<code>` and the `local` adapter records it in the
+     * issue file. Absent files no such mark.
+     */
+    cause?: string;
+}
+/** An issue as a tracker holds it: the draft, where it lives, its state. */
+export interface Issue extends IssueDraft {
+    ref: IssueRef;
+    state: IssueState;
+}
+/** What `find` narrows by; an absent field narrows by nothing. */
+export interface IssueQuery {
+    module?: string;
+    text?: string;
+    type?: IssueType;
+    state?: IssueState;
+    limit?: number;
+}
+/**
+ * One open issue as `openIssues` answers it: where it lives, the title
+ * and body it holds, and when it was created, so a caller comparing
+ * issue text, or asking which issues were filed after a time, reads
+ * every open issue in one call rather than a `get` for each.
+ */
+export interface OpenIssue {
+    ref: IssueRef;
+    title: string;
+    body: string;
+    /**
+     * When the issue was created, as an ISO 8601 date and time with its
+     * offset, or null when the tracker does not say: it holds no creation
+     * time for the issue, or one that does not read as a time. {@link Issue}
+     * carries no such time.
+     */
+    createdAt: string | null;
+}
+/**
+ * One issue as `filedIssues` answers it: where it lives, the title and
+ * body it holds, and when it was filed. rafa's own type, absent from the
+ * source.
+ *
+ * Unlike {@link OpenIssue}, its creation time is never null: a listing
+ * by filing time cannot place an undated issue against its cut-off, so
+ * an adapter never answers one.
+ */
+export interface FiledIssue {
+    readonly ref: IssueRef;
+    readonly title: string;
+    /** The body as the tracker holds it, unnormalised. */
+    readonly body: string;
+    /**
+     * When the issue was created, as an ISO 8601 date and time with its
+     * offset.
+     */
+    readonly createdAt: string;
+}
+/**
+ * One issue as `editable` answers it: what `rafa issue edit` weighs
+ * before it writes, read in one call. rafa's own type, absent from the
+ * source.
+ *
+ * {@link Issue} carries neither labels nor an author, and the edit's
+ * gates read both: the author for whose issue it is, the labels for
+ * whether a plan or a loop is building from it.
+ */
+export interface EditableIssue {
+    readonly ref: IssueRef;
+    readonly title: string;
+    /** The body as the tracker holds it, unnormalised. */
+    readonly body: string;
+    /**
+     * False when the tracker holds the issue closed: `done`, `released`
+     * or `cancelled`, as `openIssues` reads them.
+     */
+    readonly open: boolean;
+    /**
+     * The issue's labels, by name, in the order the tracker answers them.
+     * Empty on a tracker that holds no labels.
+     */
+    readonly labels: readonly string[];
+    /**
+     * The login of the account that opened the issue, or the empty string
+     * on a tracker that holds no accounts, such as `local`.
+     */
+    readonly author: string;
+    /**
+     * The priority the tracker holds for the issue, or null when triage
+     * has set none, as `get` answers {@link IssueDraft.priority}. Absent on
+     * a tracker whose `edit` writes no priority: a caller reads it here
+     * before it hands {@link IssueEdit} a priority, and hands none to a
+     * tracker that answers none.
+     */
+    readonly priority?: IssuePriority | null;
+}
+/**
+ * What one `edit` writes: a new body, a new title, a new priority, or
+ * any of the three together. Whatever it leaves out stays as the
+ * tracker holds it. A body is written whole: an append is the caller's,
+ * which hands the old body with its update below it. A priority is
+ * written in place of the one the issue held, and takes the issue out
+ * of triage: after it the tracker holds that priority and no other, and
+ * no mark that triage has yet to set one. An edit never returns an
+ * issue to triage, so the member holds no null. The union holds an edit
+ * to at least one of the three.
+ */
+export type IssueEdit = {
+    readonly body: string;
+    readonly title?: string;
+    readonly priority?: IssuePriority;
+} | {
+    readonly body?: string;
+    readonly title: string;
+    readonly priority?: IssuePriority;
+} | {
+    readonly body?: string;
+    readonly title?: string;
+    readonly priority: IssuePriority;
+};
+/** What a tracker's platform supports beyond issues themselves. */
+export interface TrackerCapabilities {
+    /** Supports project/board grouping (GitHub Projects v2, Linear projects). */
+    projects: boolean;
+    /** Supports custom single-select fields (priority as a board field). */
+    customFields: boolean;
+    /** Supports native issue types (GitHub org issue types). */
+    issueTypes: boolean;
+}
+/** A preflight's answer: reachable, or the reason it is not. */
+export type PreflightResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Outcome of a `transition()` call. Mirrors `IssueRef.warning`'s convention
+ * rather than inventing a new shape: the transition's primary write (the
+ * tracker's own open/closed or workflow state) succeeded — otherwise
+ * `transition()` throws — but a secondary write (the GitHub adapter's board
+ * column) may not have landed. `warning` set means exactly that: the caller
+ * MUST NOT treat this as a full success, and — for callers that persist a
+ * state claim of their own (the ledger) — must not persist that claim when a
+ * board-shaped warning says the board never received it.
+ */
+export interface TransitionResult {
+    warning?: string;
+}
+/**
+ * An issue tracker: where `loop start` files what a task report's
+ * out-of-scope bugs name, through its triage (`start/triage.ts`, over
+ * `triage/triage.ts`). A report's blockers are written onto its task's
+ * tracker line instead.
+ */
+export interface Tracker {
+    readonly kind: TrackerKind;
+    capabilities: () => TrackerCapabilities;
+    /** Cheap reachability/auth probe. Must not throw — returns a reason instead. */
+    preflight: () => Promise<PreflightResult>;
+    find: (query: IssueQuery) => Promise<IssueRef[]>;
+    get: (ref: IssueRef) => Promise<Issue>;
+    create: (draft: IssueDraft) => Promise<IssueRef>;
+    comment: (ref: IssueRef, body: string) => Promise<void>;
+    transition: (ref: IssueRef, state: IssueState) => Promise<TransitionResult>;
+    /**
+     * The open issues of `type`, each with its title, its body and the
+     * time it was created, in the order the adapter lists them. Open is
+     * every state the tracker does not hold closed: `done`, `released`
+     * and `cancelled` are closed, the rest open. rafa's own member, absent
+     * from the source, and optional: a tracker without it reads no open
+     * issues, and a caller that needs them goes without.
+     */
+    openIssues?: (type: IssueType) => Promise<OpenIssue[]>;
+    /**
+     * The issues of `type` filed after `since`, in any state: one closed
+     * since it was filed is listed beside the open ones, so a caller asking
+     * what was filed after a time does not lose an issue closed before it
+     * asks. Each carries its title, its body and the time it was created,
+     * in the order the adapter lists them. An issue whose creation time the
+     * tracker does not hold, or holds unreadable, is never answered: a
+     * listing by filing time cannot place it against `since`. rafa's own
+     * member, absent from the source, and optional: a tracker without it
+     * reads no filed issues, and a caller that needs them goes without.
+     */
+    filedIssues?: (type: IssueType, since: Date) => Promise<FiledIssue[]>;
+    /**
+     * The issue's title, body, open state, labels and author, in one
+     * read, with its priority on a tracker whose `edit` writes one.
+     * Rejects for a ref the tracker does not hold. rafa's own member,
+     * absent from the source, and optional with {@link edit}: a tracker
+     * without the two cannot have a body edited, and `rafa issue edit`
+     * refuses with a line naming the tracker's kind.
+     */
+    editable?: (ref: IssueRef) => Promise<EditableIssue>;
+    /**
+     * Writes the body, the title and the priority that `change` names,
+     * leaving the rest of the issue as it was, so that `editable` and
+     * `get` read the written text and priority back unchanged. Rejects
+     * when the tracker refuses the write or does not hold the ref.
+     * Optional with {@link editable}.
+     */
+    edit?: (ref: IssueRef, change: IssueEdit) => Promise<void>;
+}
+/**
+ * The learning tunnel: findings go in as instincts, blessed instincts
+ * come out for dispatch to inject. The modules spec closes it to third
+ * parties; there is core's `local` adapter and a first-party `remote`
+ * one, never a second source of blessed instincts.
+ */
+export interface Learning {
+    /** Merges one source's instincts into what the adapter holds. */
+    push: (payload: SyncPayload) => Promise<MergeResult>;
+    /** The instincts currently blessed. */
+    pullBlessed: () => Promise<BlessedBundle>;
+    /** Flags one instinct by id, keeping it out of every later bundle. */
+    flag: (id: string, reason: string) => Promise<void>;
+}
+/** A command began. `ts` is an ISO 8601 timestamp on every event. */
+export interface CliEventStart {
+    type: 'start';
+    command: string;
+    ts: string;
+}
+/** A named step of the command began. */
+export interface CliEventStep {
+    type: 'step';
+    name: string;
+    ts: string;
+}
+/** One message at one level. */
+export interface CliEventLog {
+    type: 'log';
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    /** What a logger knew beyond the message: module, action, code, hint and the like. */
+    fields?: Readonly<Record<string, unknown>>;
+    ts: string;
+}
+/**
+ * The command's outcome: its data when it succeeded, its error when not.
+ *
+ * `error.code` is the dispatcher's own code (`command_exit`,
+ * `no_project`, …) and `error.message` the failure's words. The four
+ * optional members say what the failure was beside them (#952): `cause`
+ * is a `<family>:<leaf>` cause code on every failure the dispatcher
+ * writes; `hint` is a coded error's next step, when it has one; `module`
+ * and `action` name where a coded error was thrown, or the command that
+ * ran for an uncoded failure of one.
+ */
+export interface CliEventResult {
+    type: 'result';
+    ok: boolean;
+    data?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        cause?: string;
+        hint?: string;
+        module?: string;
+        action?: string;
+    };
+    ts: string;
+}
+/**
+ * One named event of a long-running command, such as a loop's task
+ * ending. `summary` is the one line the events output prints; `data`
+ * holds the same facts as fields for a reader of json.
+ */
+export interface CliEventNamed {
+    type: 'event';
+    name: string;
+    summary: string;
+    data: Readonly<Record<string, unknown>>;
+    ts: string;
+}
+/** Every event an output renders, closed over its five kinds. */
+export type CliEvent = CliEventStart | CliEventStep | CliEventLog | CliEventResult | CliEventNamed;
+/**
+ * Where a command's output goes: a terminal's text, or NDJSON events a
+ * service or the TUI reads. Phase 1 routes the sibling's `console.log`
+ * calls through it.
+ */
+export interface Output {
+    /** A message at `info`. */
+    info: (message: string) => void;
+    /** A message at `warn`. */
+    warn: (message: string) => void;
+    /** A message at `error`. */
+    error: (message: string) => void;
+    /** A message at `debug`. */
+    debug: (message: string) => void;
+    /** One event, rendered as the adapter renders its kind. */
+    emit: (event: CliEvent) => void;
+    /** The command's answer. */
+    result: (payload: unknown) => void;
+}
+/** One request to a service and what came back, as metadata only: never a body. */
+export interface ApiExchange {
+    /** The service called, such as `hub`. */
+    service: string;
+    /** The request method, such as `GET`. */
+    method: string;
+    /** The request URL; an adapter filters it before writing it. */
+    url: string;
+    /** The response status; absent when no response arrived. */
+    status?: number;
+    /** How long the exchange took, in milliseconds. */
+    durationMs?: number;
+    /** The size of the request body, in bytes. */
+    requestBytes?: number;
+    /** The size of the response body, in bytes. */
+    responseBytes?: number;
+    /** The id the service gave the request, when it gives one. */
+    requestId?: string;
+    /** Response headers; an adapter writes only the ones its allow-list names. */
+    headers?: Readonly<Record<string, string>>;
+}
+/** One diagnostic line, with what is known about where it comes from. */
+export interface LogEntry {
+    /** How loud the entry is, or `api`. */
+    level: LogLevel;
+    /** What happened, as one sentence. */
+    message: string;
+    /** The module writing it, as a child logger binds it. */
+    module?: string;
+    /** The action or step running. */
+    action?: string;
+    /** A cause code, `<family>:<leaf>` (`packages/rafa/src/errors/codes.ts`). */
+    code?: string;
+    /** The recommended next action. */
+    hint?: string;
+    /** Anything else worth keeping, for an adapter that stores fields. */
+    data?: Readonly<Record<string, unknown>>;
+    /** The error behind the entry, kept whole so its own stack survives. */
+    error?: unknown;
+    /** The exchange an `api` entry is about. */
+    api?: ApiExchange;
+}
+/** What a child logger adds to every entry it writes. */
+export interface LogBindings {
+    /** The module every entry of the child comes from. */
+    module?: string;
+    /** The action every entry of the child belongs to. */
+    action?: string;
+}
+/**
+ * Where diagnostics go: errors, warnings, debug lines and `api`
+ * exchanges, each with its module, cause code and hint when known. A
+ * command's own text and its result stay on {@link Output}.
+ */
+export interface Logger {
+    /** Writes `entry`, unless its level is off for its module. */
+    log: (entry: LogEntry) => void;
+    /** A logger adding `bindings` to every entry; an entry's own fields win. */
+    child: (bindings: LogBindings) => Logger;
+    /** Whether an entry at `level` from `module` would be written. */
+    enabled: (level: LogLevel, module?: string) => boolean;
+}
+/** The version of the {@link Logger} port this entry declares. */
+export type LoggerPortVersion = 1;
+/**
+ * One plan to generate, from one spec. The adapter is bound to a
+ * repository when it is made, as a store is opened on a root, so the
+ * paths here are that repository's.
+ */
+export interface PlanRequest {
+    /** The spec, as `--spec=` names it: repository-relative or absolute. */
+    specPath: string;
+    /** The plan's stub. `rafa plan` defaults it to the spec's basename. */
+    stub: string;
+}
+/**
+ * Where a planner left the plan it generated: repository-relative, or
+ * absolute when the directory it writes plans into is.
+ */
+export interface GeneratedPlan {
+    /** The plan: `PLAN-<stub>.md` in `plan.dir` under today's planner. */
+    planPath: string;
+    /**
+     * The setup steps the planner found no task could automate, or null
+     * when it wrote none: `PREREQUISITES-<stub>.md` in `plan.dir` today.
+     */
+    prerequisitesPath: string | null;
+    /**
+     * What the planner's own session said about the spec BEFORE it
+     * planned, read out of that session's output: the `rafa:spec-review`
+     * block of the readiness gate's check 3
+     * (`src/board/spec-review.ts`).
+     *
+     * Optional, because a planner that reads no session output has judged
+     * nothing and must still satisfy this port — the fixture planners the
+     * command's tests resolve, and the `webhook` adapter phase 6 adds.
+     * The `claude` adapter carries one on every plan it answers, `absent`
+     * when its session returned no block. Nothing here acts on it: the
+     * gate is `rafa plan`'s, which is what lets `--skip-review` weigh a
+     * verdict the planner still read.
+     */
+    review?: SpecReviewReading;
+}
+/**
+ * Generates a plan from a spec: core's `claude` adapter runs a Claude
+ * Code session, as `rafa plan` does, and phase 6's `webhook` adapter
+ * hands the spec to hyperloop's plan-to-branch.
+ */
+export interface Planner {
+    /**
+     * Generates the plan. Rejects when none was generated: the session
+     * failed, or it finished without writing the plan.
+     */
+    create: (request: PlanRequest) => Promise<GeneratedPlan>;
+}
+/**
+ * Where a push leaves this store's rows.
+ *
+ * `to` is the directory the `file` strategy copies the store into, as
+ * `rafa effort copy --to=<dir>` names it, and null for a strategy that
+ * sends the rows on by itself or sends none.
+ */
+export interface SyncPushRequest {
+    readonly to: string | null;
+}
+/**
+ * Where a pull reads another device's rows from, and whether it swaps
+ * the merge in.
+ */
+export interface SyncPullRequest {
+    /**
+     * The other device's store file the `file` strategy merges, the
+     * `effort.sqlite` a copy carried, and null for a strategy that fetches
+     * the rows by itself or fetches none.
+     */
+    readonly from: string | null;
+    /**
+     * Build and check the merged store, then delete it rather than swap it
+     * in, as `mergeStore`'s own `dryRun` does.
+     */
+    readonly dryRun: boolean;
+    /**
+     * The session id of the loop run pulling, which a strategy passes on as
+     * `mergeStore`'s `sessionId` so the live-loop guard passes the run's own
+     * record; absent or null for a pull no run makes.
+     */
+    readonly sessionId?: string | null;
+}
+/** What a push did. */
+export type SyncPushResult = 
+/** The strategy moves no rows: `local`. */
+{
+    readonly status: 'nothing-to-sync';
+}
+/**
+ * The rows were sent. `path` is the file the person carries to the
+ * other device, the copy's `effort.sqlite` under `file`, and null for
+ * a strategy that delivered the rows itself.
+ */
+ | {
+    readonly status: 'pushed';
+    readonly path: string | null;
+};
+/** What a pull did. */
+export type SyncPullResult = 
+/** The strategy moves no rows: `local`. */
+{
+    readonly status: 'nothing-to-sync';
+}
+/**
+ * The rows were merged by `mergeStore`, whose result says whether the
+ * merge was swapped in or, under `dryRun`, built and deleted.
+ */
+ | {
+    readonly status: 'pulled';
+    readonly merge: StoreMergeResult;
+};
+/**
+ * How a project's effort store travels between devices: the strategy
+ * `effort.sync` selects. `local` and `file` are core's strategies and
+ * `git`, `service` and `p2p` modules'; the adapter registry holds core's
+ * as `sync/local` (`src/effort/sync/select.ts`) and `sync/file`
+ * (`src/effort/sync/file.ts`). Push and pull are directions,
+ * not strategies: in every strategy a device pushes the rows it wrote
+ * and pulls the rows others wrote.
+ */
+export interface Sync {
+    readonly kind: 'local' | 'file' | 'git' | 'service' | 'p2p';
+    /** Sends the rows this store wrote. */
+    push: (request: SyncPushRequest) => Promise<SyncPushResult>;
+    /**
+     * Merges the rows another device wrote into this store. Rejects with
+     * the merge's own refusal when `mergeStore` refuses.
+     */
+    pull: (request: SyncPullRequest) => Promise<SyncPullResult>;
+}