light-plan 0.0.0-stage → 0.1.0

package/dist/remote/periods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"periods.js","sourceRoot":"","sources":["../../src/remote/periods.ts"],"names":[],"mappings":"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"}

package/dist/remote/plan.d.ts

@@ -0,0 +1,671 @@
+/**
+ * The push and pull planners — pure functions from a board to a plan.
+ *
+ *   planPush(board, links, remote) → PushPlan             (LP-280, this file)
+ *   planPull(board, links, remote, options) → PullPlan    (LP-281, this file)
+ *
+ * Both take a `BoardView` DTO rather than a `LoadedBoard`, so neither needs a
+ * filesystem handle and the plan is a plain data structure a dry-run can render
+ * and an executor can walk.  Neither touches the disk or the network: the push
+ * plan is handed to the executor (`LP-490`), the pull plan to `applyChanges`
+ * from `src/sync`.
+ *
+ * ## Why a push plan exists at all
+ *
+ * A push is a list of *remote operations*, not a batch write.  The remote is a
+ * separate system with its own ids, its own workflow and its own idea of a
+ * parent, so the plan has to say, in order:
+ *
+ *   1. what to create, parents before children (a parent must exist before its
+ *      children are filed under it);
+ *   2. what to update / transition / close, for documents that already have a
+ *      twin;
+ *   3. what to link and unlink, after every endpoint exists.
+ *
+ * Two rules make the order load-bearing.  A `create` op carries no remote id —
+ * it is referenced by a **placeholder** (`new:1`) until the executor resolves
+ * it against the response — and an edge (`link` / `unlink`) is emitted only
+ * once both endpoints exist, so a document created in this same push can be an
+ * endpoint.  That is the held-back-link trick `src/sync/patch.ts` uses for
+ * `depends_on`, expressed here as a rule about op order rather than a deferred
+ * patch: every edge is placed after every create and update, and it references
+ * its endpoints through a `RemoteRef` that is either a recorded twin or a
+ * placeholder.
+ *
+ * ## What this file deliberately does not do
+ *
+ * - **Conflict detection on the push side** (both sides edited a field) is
+ *   `LP-257`'s; `planPush` diffs a document against its base and pushes what
+ *   changed locally — it never consults the remote side for a pushed field.
+ *   The pull planner *does* detect a both-sides edit: a field both sides
+ *   changed is reported in `PullPlan.fieldConflicts` rather than written.
+ * - **Existence and shape** (the twin was deleted, moved or converted) is
+ *   `LP-361`'s; `remote.issues` is part of the input so that story and the pull
+ *   planner can read it, but this planner does not yet act on it.
+ * - **The mapping** is the translator's job at execution time.  The planner
+ *   decides *what* changed against the base snapshot and *in what order* it is
+ *   pushed; it never turns a board status into a remote state.
+ * - **`relates_to`** is a non-gating edge: it is linked / unlinked natively
+ *   only where the provider declares a native relate edge (Jira, LP-325), and
+ *   rides the managed block everywhere else (LP-314).
+ */
+import type { RemoteDirection, RemoteOnDelete } from '../core/model/types.js';
+import type { RemoteCommentsMode } from '../core/model/types.js';
+import type { Change } from '../shared/changes.js';
+import type { BoardView } from '../shared/plans/reading.js';
+import type { ResolvedHierarchy } from './hierarchy.js';
+import type { LinkStore } from './links.js';
+import type { ManagedBlockEntry, ManagedBlockLinks } from './managed-block.js';
+import { type LocalComment } from './comments.js';
+import type { BoardFields, BoardFieldsPatch, LinkKind, RemoteComment, RemoteRecord } from './provider.js';
+/**
+ * The remote as a planner sees it: how it is declared to sync, plus the
+ * remote-side issue state the executor captured before planning.
+ *
+ * `direction` and `scope` come from the remote's declaration; `issues` is the
+ * live listing (remote id → raw record).  The push planner reads the first two
+ * and leaves `issues` to the pull planner and the lifecycle/conflict stories;
+ * it is carried here so one snapshot serves both directions.
+ */
+export interface RemoteSnapshot {
+    /** The remote's declared direction; a pull-only remote plans nothing. */
+    direction: RemoteDirection;
+    /** The scope root id; absent means the whole board is in scope. */
+    scope?: string;
+    /**
+     * Act on only these documents this run (`lpm remote push LP-12`), leaving
+     * every other document exactly as it stands.
+     *
+     * **Selection is not scope, and the difference is load-bearing.** Scope says
+     * which documents this remote *owns*, so a linked document outside it has
+     * left the mirror and the `on_delete` policy applies — a decouple, a close,
+     * a delete. Selection says which documents this run is *about*. Narrowing
+     * the scope to say "just push this one" would tell the planner that every
+     * other twin on the board had gone away, and a selective push would file one
+     * story and decouple the other two hundred. So `only` filters what is
+     * created, updated, reparented, edged and commented, and the gone pass never
+     * consults it. Absent means the whole scope.
+     *
+     * Reference resolution (`refOf`) does not consult it either: a selected
+     * child whose parent is already linked still names that parent, which is
+     * what lets a plan be filed a piece at a time and still come out the right
+     * shape.
+     */
+    only?: ReadonlySet<string>;
+    /**
+     * Documents another remote already mirrors (`src/remote/ledger.ts`), local
+     * id → the key they hold there. A document is mirrored by one remote at a
+     * time, so these are never created a second time: they are reported in
+     * `skipped` with the reason `owned_elsewhere`, the same channel a
+     * deliberately decoupled document is reported through.
+     */
+    ownedElsewhere?: ReadonlyMap<string, string>;
+    /** Remote issues keyed by remote id, as the provider returned them. */
+    issues: ReadonlyMap<string, RemoteRecord>;
+    /**
+     * The listing is **not exhaustive** — it is one issue somebody named
+     * (`lpm remote pull PAY-31`), not everything the remote holds. The pull
+     * planner then never infers a deletion from absence: a twin missing from a
+     * partial listing was not looked for, and answering that with the
+     * `on_delete` policy would close or delete the rest of the board's twins on
+     * every targeted pull.
+     */
+    partial?: boolean;
+    /** What to do when a linked twin is absent from `issues`. Defaults to `unlink`. */
+    onDelete?: RemoteOnDelete;
+    /**
+     * Set by the caller (LP-364) when the remote could not be seen this run —
+     * the reachability probe failed, or the bulk guard tripped. The pull
+     * planner then plans **nothing**, so an expired credential can never become
+     * a wave of deletions. The caller derives it from
+     * `resolveLifecycle(...).runUnreachable`.
+     */
+    unreachable?: boolean;
+    /**
+     * The resolved hierarchy encoding (LP-309), computed by the caller from the
+     * resolved capability table (`resolveHierarchyEncoding`). Absent means the
+     * planners fall back to the pre-encoding behaviour: every parent is carried
+     * natively. Present, a document whose parent is beyond the native depth has
+     * its parent carried in the managed block instead (`blockParent`).
+     */
+    hierarchy?: ResolvedHierarchy;
+    /**
+     * Which dependency edge kinds the remote holds natively (LP-314, LP-325).
+     * Absent defaults to "native `depends_on`, no native `relates_to`" — the
+     * pre-edge-carrier behaviour, so a snapshot that does not know its
+     * capabilities still plans `link` / `unlink` ops.  A provider with no native
+     * blocking edge carries `depends_on` in the managed block instead (an
+     * `edges` op); `relates_to` rides the block unless `relatesTo` is true, in
+     * which case it is linked and unlinked natively.
+     */
+    edges?: {
+        dependsOn: boolean;
+        relatesTo: boolean;
+    };
+    /**
+     * How user comments sync (LP-316): `push` (the default) or `both`.  The push
+     * planner posts unsynced local comments whenever it runs; the pull planner
+     * appends remote comments only when this is `both`.  Absent means `push`.
+     */
+    commentsMode?: RemoteCommentsMode;
+    /**
+     * Remote comments per remote issue id, fetched by the caller before planning
+     * (LP-316).  The pull planner reads this map and emits append ops for every
+     * comment not already recorded in the link store.  Absent means no comments
+     * were fetched, which is the caller's way of saying comment pull is
+     * unavailable this run.
+     */
+    remoteComments?: ReadonlyMap<string, readonly RemoteComment[]>;
+    /**
+     * A board body as it will read after a round trip through the remote's own
+     * body format (`Translator.normalizeBody`), for a provider whose bodies are
+     * not markdown.
+     *
+     * The base records the body the remote echoed back, so the comparison is
+     * only honest if the board's body is put through the same conversion first.
+     * Jira's ADF has no source line breaks, so without this every hard-wrapped
+     * document is permanently ahead and each push rewrites the lot. Absent for a
+     * provider whose bodies are markdown already, where the round trip is the
+     * identity.
+     */
+    normalizeBody?: (markdown: string) => string;
+}
+/** A document that already has a twin on the remote. */
+export interface LinkedRef {
+    kind: 'linked';
+    localId: string;
+    remoteId: string;
+}
+/** A document this same plan creates, referenced by its placeholder. */
+export interface CreatedRef {
+    kind: 'created';
+    localId: string;
+    /** The `create` op's placeholder, resolved by the executor when it lands. */
+    placeholder: string;
+}
+/**
+ * A remote issue an op points at.  Either a twin that already exists, or a
+ * document the plan creates — which has no remote id yet, so it is referenced
+ * by its placeholder until execution resolves it.
+ */
+export type RemoteRef = LinkedRef | CreatedRef;
+/** File a new remote issue for a local document with no twin. */
+export interface RemoteCreateOp {
+    kind: 'create';
+    /** Placeholder the executor resolves to a remote id when this create lands. */
+    placeholder: string;
+    localId: string;
+    /** The issue's fields in board vocabulary (the translator's input). */
+    fields: BoardFields;
+    /** The created issue's native parent, when it is in scope; absent = remote root. */
+    parent?: RemoteRef;
+    /** The created issue's degraded parent (LP-309): carried in the managed block, never a native edge. */
+    blockParent?: RemoteRef;
+}
+/** Change non-status fields of an existing twin. */
+export interface RemoteUpdateOp {
+    kind: 'update';
+    localId: string;
+    ref: LinkedRef;
+    /** Only the fields that changed since the base snapshot. */
+    fields: Partial<BoardFields>;
+    /**
+     * The degraded parent (LP-314): carried in the managed block when the
+     * document nests beyond the native depth.  The executor re-applies it
+     * whenever it rewrites the body, so a prose edit never strips the block.
+     */
+    blockParent?: RemoteRef;
+}
+/** Move an existing twin to a non-terminal status. */
+export interface RemoteTransitionOp {
+    kind: 'transition';
+    localId: string;
+    ref: LinkedRef;
+    /** The new board status id; the translator maps it to a remote state. */
+    status: string;
+}
+/**
+ * Move an existing twin's parent, in place (LP-493). Covers both a local
+ * reparent (`lpm move` on a linked document) and a hierarchy-encoding switch,
+ * which moves the *same* parent between the two carriers. Exactly one of
+ * `parent` / `blockParent` is set while the new parent sits within / beyond
+ * the native depth; both are absent when the document moves to the root. The
+ * twin keeps its remote id — it is never re-created.
+ */
+export interface RemoteReparentOp {
+    kind: 'reparent';
+    localId: string;
+    ref: LinkedRef;
+    /** The twin's native parent (the sub-issues edge), within the native depth. */
+    parent?: RemoteRef;
+    /** The twin's degraded parent (the block's `parent` row), beyond it. */
+    blockParent?: RemoteRef;
+}
+/** Close an existing twin (a terminal status reached). */
+export interface RemoteCloseOp {
+    kind: 'close';
+    localId: string;
+    ref: LinkedRef;
+    /**
+     * A comment to post on the twin before closing, explaining why (the
+     * push-side `on_delete: close` policy). Only ever set when the close is a
+     * policy close for a document that went away — never for a terminal status
+     * the board reached on its own, which needs no explanation.
+     */
+    note?: string;
+}
+/**
+ * Delete an existing twin (`on_delete: delete`, LP-351).
+ *
+ * The connector decides what delete means on its platform — Jira and Linear
+ * hard-delete (or trash), GitHub cannot hard-delete and closes instead, which
+ * its adapter documents. The op carries only the twin to remove; the executor
+ * drops the link (or decouples, when the local document still exists) after
+ * the delete lands, so a failed delete leaves the link in place and the next
+ * sync retries it.
+ */
+export interface RemoteDeleteOp {
+    kind: 'delete';
+    localId: string;
+    ref: LinkedRef;
+}
+/** Add an edge between two in-scope issues. */
+export interface RemoteLinkOp {
+    kind: 'link';
+    /**
+     * The edge kind: `depends` (the gating `depends_on` edge, the default) or
+     * `relates` (the non-gating `relates_to` edge, LP-325). For `depends`,
+     * `dependent` waits on `dependency`; for `relates` the two are
+     * interchangeable.
+     */
+    linkKind: LinkKind;
+    /** The issue that waits (or, for relates, the local side of the edge). */
+    dependent: RemoteRef;
+    /** The issue it waits on (or, for relates, the other side of the edge). */
+    dependency: RemoteRef;
+}
+/** Remove an edge that no longer exists locally. */
+export interface RemoteUnlinkOp {
+    kind: 'unlink';
+    /** The edge kind, exactly as `RemoteLinkOp.linkKind`. */
+    linkKind: LinkKind;
+    dependent: LinkedRef;
+    dependency: LinkedRef;
+}
+/**
+ * Write the dependency / relate edges into the managed block of a twin whose
+ * remote holds no native edge (LP-314).
+ *
+ * The block is authoritative: the op carries the **complete** current set of
+ * edges, not a diff, so the executor rewrites the block idempotently.  A
+ * dependency referenced by a create that did not land is simply omitted (the
+ * executor cannot resolve its remote id), and the next push re-plans it — a
+ * reference is never written as a dangling local id (AC #2).
+ */
+export interface RemoteEdgesOp {
+    kind: 'edges';
+    localId: string;
+    /** The twin carrying the block — an existing twin, or the create this same push files. */
+    ref: RemoteRef;
+    /** The degraded parent (block carrier), when the document nests beyond the native depth. */
+    parent?: RemoteRef;
+    /** The issues this document waits on, resolved to remote ids by the executor. */
+    dependsOn: RemoteRef[];
+    /** The issues this document is related to, resolved to remote ids by the executor. */
+    relatesTo: RemoteRef[];
+}
+/**
+ * Post a local work-log comment upstream (LP-316).  Carries the comment's
+ * 1-based index so the executor can record `commentIds[index] = remote id`
+ * once it lands — which is what makes re-posting impossible.  `body` is the
+ * rendered comment (`renderCommentForRemote`), already naming the local author
+ * for a platform that cannot set the comment author itself.
+ */
+export interface RemoteCommentOp {
+    kind: 'comment';
+    /** The twin the comment hangs off — an existing twin, or the create this same push files. */
+    ref: RemoteRef;
+    /** 1-based index of the local comment in `_comments.md`. */
+    index: number;
+    /** The local author, for the report. */
+    author: string;
+    /** The rendered comment body posted upstream. */
+    body: string;
+}
+/**
+ * Write (or update) the managed comment holding a twin's degraded fields.
+ *
+ * The op carries the *entries* rather than a rendered body, so the executor
+ * renders them through the codec (byte-stable, sorted) and can tell "nothing
+ * to write" from "something to write" — the former removes the comment.  The
+ * executor derives the id links from the link store; `links` is the pure
+ * override a test or a dry-run supplies when there is no store to read.
+ */
+export interface RemoteManagedCommentOp {
+    kind: 'managedComment';
+    localId: string;
+    ref: LinkedRef;
+    /** The degraded fields the comment carries, as block entries. */
+    entries: readonly ManagedBlockEntry[];
+    /** Local id → remote URL, for rendering id cells as clickable links. */
+    links?: ManagedBlockLinks;
+}
+/** Detach a local document from its twin without touching the remote. */
+export interface RemoteUnlinkLocalOp {
+    kind: 'unlinkLocal';
+    localId: string;
+}
+/**
+ * Decouple a local document from its twin, recording a tombstone so no later
+ * sync re-files it (LP-366).  Unlike `unlinkLocal`, which just drops the link,
+ * a decouple *remembers*: the last known remote key, the reason, and when it
+ * happened.  The remote twin is left alone — decoupling never deletes or closes
+ * anything upstream.
+ */
+export interface RemoteDecoupleOp {
+    kind: 'decouple';
+    localId: string;
+    /** Why the link was dropped: `manual` (a human) or `out_of_scope`. */
+    reason: string;
+}
+/**
+ * Re-file a vanished twin upstream (`on_delete: restore`, LP-365).
+ *
+ * A restore is a push of a document that already has history: the remote issue
+ * was deleted, so this re-creates it from local state under a **new** remote id
+ * and the link is repointed at that id, the base snapshot rewritten from the
+ * response.  It is deliberately not a `create` — a `create` says "this
+ * document has no twin", a restore says "the twin is gone and we are filing a
+ * replacement", and the report must say so rather than imply a true undelete.
+ */
+export interface RemoteRestoreOp {
+    kind: 'restore';
+    /** Placeholder the executor resolves to the new remote id when this lands. */
+    placeholder: string;
+    localId: string;
+    /** The remote id that vanished — carried for the report, not the request. */
+    oldRemoteId: string;
+    /** The issue's fields in board vocabulary (the translator's input). */
+    fields: BoardFields;
+    /** The re-filed issue's native parent, when it is in scope; absent = remote root. */
+    parent?: RemoteRef;
+    /** The re-filed issue's degraded parent (LP-309): carried in the managed block. */
+    blockParent?: RemoteRef;
+}
+/**
+ * The push plan.  Mirrors `Change` (`create` / `update` / `delete` there;
+ * `create` / `update` / `transition` / `link` / `unlink` / `comment` / `close`
+ * / `unlinkLocal` here).  Providers implement the operations; they never see a
+ * `LoadedBoard`.
+ */
+export type RemoteOp = RemoteCreateOp | RemoteUpdateOp | RemoteTransitionOp | RemoteReparentOp | RemoteCloseOp | RemoteDeleteOp | RemoteLinkOp | RemoteUnlinkOp | RemoteEdgesOp | RemoteCommentOp | RemoteManagedCommentOp | RemoteUnlinkLocalOp | RemoteDecoupleOp | RemoteRestoreOp;
+/**
+ * A document a push deliberately left out, with why.  A decoupled document is
+ * skipped — never created — and the reason names the tombstone's own reason
+ * plus the last known remote key, so the operator can tell "deliberately
+ * dropped" from "never pushed".
+ */
+export interface PushSkip {
+    localId: string;
+    /** The tombstone's reason: `manual`, `out_of_scope`, or a policy reason. */
+    reason: string;
+    /** The last known remote key, kept by the tombstone; empty when none. */
+    remoteKey: string;
+}
+/** A push, planned: the operations to run, plus what was deliberately left out. */
+export interface PushPlan {
+    ops: RemoteOp[];
+    skipped: PushSkip[];
+}
+/**
+ * One correspondence effect a pull performs on the link store, *alongside* the
+ * `Change[]` that lands on the board.
+ *
+ * The pull plan is two lists on purpose. `Change` is the board-document
+ * protocol (`create` / `update` / `delete`) and it has no word for a link
+ * store entry, which is the remote layer's own state — so the correspondence
+ * moves are carried here and applied by `applyPull` as the changes land.
+ */
+export type PullLinkOp = 
+/** After a `create` lands, record its twin (real id → remote id). */
+{
+    kind: 'record';
+    tempId: string;
+    remoteId: string;
+}
+/** The twin is gone upstream; drop the correspondence for this local id. */
+ | {
+    kind: 'unlink';
+    localId: string;
+}
+/** Drop the link and record a tombstone, so the next push never re-files it. */
+ | {
+    kind: 'decouple';
+    localId: string;
+    reason: string;
+};
+/**
+ * A pull-side existence decision left for a human (LP-365).  Neither side has
+ * moved: `on_delete: manual` leaves a vanished twin unresolved, and a
+ * `delete` that would orphan a linked child is refused.  The sync reports each
+ * one and exits non-zero; `lpm remote resolve` (LP-287) settles it.
+ */
+export interface PullConflict {
+    localId: string;
+    /** The remote id that vanished. */
+    remoteId: string;
+    /** Why neither side moved — the policy, or the child a delete would orphan. */
+    reason: string;
+    /** The linked child a delete would have orphaned, when that was the refusal. */
+    childId?: string;
+}
+/**
+ * Append one remote comment to a document's `_comments.md` (LP-316).  Carried
+ * separately from `Change[]` because a comment is not board state and is
+ * written straight through, exactly the way the web app writes one.  `targetId`
+ * is the local document — its temporary id when the issue is also new in this
+ * pull, its real id otherwise — so `applyPull` resolves it the same way it
+ * resolves a `record` link op.
+ */
+export interface PullCommentOp {
+    kind: 'append';
+    /** Temp id (new create) or real local id (twin) of the target document. */
+    targetId: string;
+    /** The remote comment id, recorded so the next pull never appends it twice. */
+    remoteId: string;
+    /** The remote author's name, written into the `_comments.md` heading. */
+    author: string;
+    /** The remote timestamp, written into the `_comments.md` heading. */
+    at: string;
+    /** The comment body text. */
+    body: string;
+}
+/**
+ * A field-level conflict on a linked twin still present on both sides (LP-257
+ * AC #2).  Both sides edited the same field since the base snapshot, so
+ * neither value is derived from the other: the field is left untouched on both
+ * sides and reported — a question, not an operation, exactly like an
+ * existence conflict.
+ */
+export interface PullFieldConflict {
+    localId: string;
+    remoteId: string;
+    /** The board field that diverged: `title`, `body`, `status`, `assignee`, `period`, or an attribute name. */
+    field: string;
+    /** The local (board) value. Body is the raw text. */
+    local: unknown;
+    /** The remote value, translated back to board vocabulary. Body is the raw text. */
+    remote: unknown;
+}
+/**
+ * A reference a managed block carried that the pull could not resolve to a
+ * local document (LP-314).  Reported, never silently dropped: a cross-repo
+ * reference is out of scope, an unknown token is a human edit or a mangled
+ * row.
+ */
+export interface PullEdgeWarning {
+    /** The remote id of the record whose block carried the reference. */
+    remoteId: string;
+    /** `depends_on` or `relates_to` — the row the reference came from. */
+    field: 'depends_on' | 'relates_to';
+    /** The raw reference: `owner/repo#12`, a bare local id, or free text. */
+    reference: string;
+    /** `cross_repo` (out of scope), `unknown` (unresolvable) or `cycle` (refused). */
+    kind: 'cross_repo' | 'unknown' | 'cycle';
+    /** The cycle the edge would close, named member → member → member (kind: `cycle` only). */
+    cycle?: string;
+}
+/**
+ * The edge references a record's managed block carries (LP-314), split by
+ * resolvability.  Same-repo references come back as bare remote ids and are
+ * resolved through the link store exactly like a native edge; cross-repo and
+ * unknown references are reported by the planner rather than resolved.
+ */
+export interface BlockEdges {
+    dependsOn: string[];
+    relatesTo: string[];
+    /** Cross-repo references (`owner/repo#12`) — out of scope, never resolved. */
+    crossRepo: Array<{
+        field: 'depends_on' | 'relates_to';
+        reference: string;
+    }>;
+    /** References that are neither a `#ref` nor a cross-repo reference. */
+    unknown: Array<{
+        field: 'depends_on' | 'relates_to';
+        reference: string;
+    }>;
+}
+/**
+ * A pull, planned: the board-document changes to apply, plus the link-store
+ * effects that travel with them.
+ *
+ * `changes` is a plain `Change[]` from `src/shared/changes.ts`, handed to
+ * `applyChanges` from `src/sync` — the one applier every front end shares.  A
+ * create carries a temporary id from a fresh counter (never one derived from a
+ * view's pending list), and its parent is referenced by the same temporary id
+ * when the parent is also new, which is exactly what `applyChanges`'s
+ * hold-back-and-replay handles: the reference decides the order, not the plan.
+ *
+ * `restore` carries the push-side operations for `on_delete: restore` — a pull
+ * discovers the deletion, but the remedy is a re-file upstream, so the plan
+ * holds `RemoteOp[]` rather than `Change[]`.  `conflicts` carries the documents
+ * a policy left for a human.  Both are absent when empty, so an up-to-date pull
+ * is still exactly `{ changes: [], links: [] }`.
+ */
+export interface PullPlan {
+    changes: Change[];
+    links: PullLinkOp[];
+    /** Remote comments to append to `_comments.md`, absent when there are none. */
+    comments?: PullCommentOp[];
+    restore?: RemoteRestoreOp[];
+    conflicts?: PullConflict[];
+    /** Field conflicts on twins still present on both sides, absent when empty. */
+    fieldConflicts?: PullFieldConflict[];
+    /** Edge references a managed block carried that could not be resolved, absent when empty. */
+    edgeWarnings?: PullEdgeWarning[];
+}
+/**
+ * The translation seams `planPull` needs, which are pure by construction so the
+ * planner stays browser-compatible and free of the disk and the network.
+ *
+ * `toPatch` turns one remote record into the board fields a `create` writes; it
+ * receives the issue's hierarchy depth so the type can be resolved exactly as
+ * `mapTypeFromRemote` wants it.  It is a callback rather than a `Translator`
+ * plus mapping so the planner never learns a provider's vocabulary.  When it
+ * returns no `type`, the create falls back to the deepest declared issue type
+ * (LP-315) — a triaged remote issue with no mapped label still becomes a
+ * document rather than a failure when it is applied.
+ *
+ * `parentIdOf` reads the remote id of a record's parent, for providers that
+ * hold a native hierarchy.  Omit it for a flat remote (GitHub) and the pull
+ * files every issue at the top level.
+ *
+ * `dependsOnOf` reads the remote ids a record waits on, for providers that
+ * hold dependency edges.  Each id is resolved to the local document it names —
+ * the dependency's temporary id when it is also new in this pull, its twin
+ * otherwise — exactly as `parentIdOf` is.  A dependency naming a remote id
+ * with neither a twin nor a pending create is dropped, because there is no
+ * local document for the edge to point at.  Omit it for a remote with no
+ * edges and every create is filed with no `depends_on`.
+ *
+ * `relatesToOf` reads the remote ids a record relates to, for providers that
+ * hold a native relate edge (LP-325).  Resolved exactly as `dependsOnOf`'s
+ * are, and written onto `patch.relatesTo`.
+ *
+ * `blockEdgesOf` reads the dependency / relate references a record's managed
+ * block carries (LP-314), for providers with no native edge.  Same-repo
+ * references are returned as bare remote ids and resolved exactly as
+ * `dependsOnOf`'s are; cross-repo and unknown references are reported in
+ * `PullPlan.edgeWarnings` rather than resolved.  Omit it for a remote that
+ * never writes a managed block.
+ */
+export interface PullOptions {
+    toPatch: (record: RemoteRecord, depth: number) => BoardFieldsPatch;
+    /**
+     * Where a remote issue with no parent of its own lands on the board.
+     *
+     * A tracker's issues are a flat list; a board's are a tree with rules about
+     * what may sit at which level, so an issue pulled in on its own has nowhere
+     * to go and the create is refused ("user_story needs a parent issue"). This
+     * is the caller's answer to that — `lpm remote pull PAY-31 --parent LP-3` —
+     * and it applies only where nothing else does: an issue whose remote parent
+     * is already mirrored is filed under that twin, whatever this says.
+     */
+    underParent?: string;
+    parentIdOf?: (record: RemoteRecord) => string | undefined;
+    dependsOnOf?: (record: RemoteRecord) => string[];
+    relatesToOf?: (record: RemoteRecord) => string[];
+    blockEdgesOf?: (record: RemoteRecord) => BlockEdges;
+}
+/**
+ * Plan a push: the remote operations needed to bring the remote's in-scope
+ * issues onto the board's current state, ordered so every reference resolves.
+ *
+ * Returns an empty `{ ops: [], skipped: [] }` when nothing changed, when the
+ * remote is pull-only, or when the scope holds no documents.  The order inside
+ * a non-empty plan is:
+ *
+ *   1. `create` ops, parents before children (by depth);
+ *   2. `update` / `transition` / `close` ops for changed twins;
+ *   3. `link` / `unlink` ops, after every endpoint exists;
+ *   4. the `on_delete` resolution for linked twins whose local document went
+ *      away (deleted, or left the scope subtree): `unlink` / `close` / `delete`.
+ *
+ * In-scope documents carrying a tombstone are never created; they are
+ * reported in `skipped` rather than silently omitted (LP-366).
+ *
+ * A `create` carries no remote id: it is referenced by a `new:` placeholder,
+ * which the executor resolves against each create's response before it reaches
+ * any op that points at it.
+ */
+export declare function planPush(board: BoardView, links: LinkStore, remote: RemoteSnapshot, localComments?: ReadonlyMap<string, readonly LocalComment[]>): PushPlan;
+/**
+ * Plan a pull: the `Change[]` needed to bring the board's in-scope issues into
+ * agreement with the remote listing, plus the link-store effects that travel
+ * with it.
+ *
+ * The pull is an *existence* reconciliation, plus a field diff.  A remote
+ * issue with no twin is planned as a `create` — carrying its hierarchy parent
+ * and its dependency edges, both referenced by temporary ids when the other
+ * endpoint is also new in this pull, so the existing hold-back-and-replay
+ * wires them.  A linked twin absent from the listing is resolved by the
+ * remote's `on_delete` policy (`unlink`, `close`, `delete`, `restore` or
+ * `manual`), one document at a time (LP-365).  A linked twin still present on
+ * both sides is merged field by field against its base snapshot (LP-284): a
+ * field the remote alone changed becomes an `update` pulling the remote value
+ * onto the board, a field both sides changed is reported in `fieldConflicts`
+ * and left untouched on both sides (LP-257 AC #2), and a field the board alone
+ * changed is left for the push planner to carry upstream.
+ *
+ * The plan is applied by `applyChanges` from `src/sync` — the same applier the
+ * web app and the CLI push a view through — so the pull inherits partial
+ * application, temporary-id remapping and the hold-back-and-replay of a create
+ * whose parent is created later in the same push.  (Naming note: `PushSession`
+ * inside `src/sync` is named for pushing a *view* onto the board, which is the
+ * same direction a remote **pull** moves — remote → board.)
+ *
+ * Returns an empty plan for a `direction: push` remote (it never pulls), for a
+ * scope that names no documents, and when the listing agrees with the link
+ * store.  Pure: no disk, no network.
+ */
+export declare function planPull(board: BoardView, links: LinkStore, remote: RemoteSnapshot, options: PullOptions): PullPlan;