@issuegraph/editor 0.1.0

package/dist/create/placement.js

@@ -0,0 +1,76 @@
+/**
+ * Where the canvas path draws its type picker.
+ *
+ * §17b puts the picker "at the drop point", and the kit's implementation note
+ * fixes how that coordinate is arrived at: *"Hand-authoring these coordinates
+ * against remembered positions is the failure mode; compute them from layout."*
+ * So this takes MEASURED bounds — the container's, and the picker's own — and
+ * derives a position from them. It holds no constants about how big anything is.
+ *
+ * ## The one thing it adds to "at the drop point"
+ *
+ * A drop near the right or bottom edge would put a picker anchored there partly
+ * outside the canvas, where the reader cannot reach the options. So the picker
+ * FLIPS to the other side of the drop point rather than being nudged: a flip
+ * keeps the drop point on a corner of the picker, so the picker still visibly
+ * belongs to the gesture that opened it, while a nudge slides it off the point
+ * and reads as landing somewhere arbitrary.
+ *
+ * A flip is reported rather than only applied ({@link AxisPlacement.flipped}),
+ * because the side the picker opens on decides which corner its callout points
+ * from — and a host that had to re-derive that from the coordinates would be
+ * recomputing a decision already made here.
+ *
+ * ## It is geometry, so it is not in the draft
+ *
+ * The canvas is the only path with a drop point: the inspector opens its picker
+ * in a panel and the keyboard never has a pointer position at all. That is the
+ * whole of what distinguishes the three, and keeping it here — rather than as a
+ * field on {@link ./draft.ts CreateDraft} — is what stops "which path started
+ * this" from becoming state the rest of the create logic could branch on.
+ *
+ * Pure arithmetic on numbers, so it runs under the purity test like everything
+ * else here: it never measures anything itself. Measuring is the shell's, from
+ * `getBoundingClientRect` or its own layout output; both arrive as plain data.
+ */
+/**
+ * Place one axis: open forward from the drop, flip if that overflows, then clamp.
+ *
+ * ONE RULE APPLIED TWICE rather than written out for x and for y. The two axes
+ * differ only in which measurements they read, and a second copy is a second
+ * place for the arithmetic to drift — which on this surface would show up as a
+ * picker correct horizontally and off-canvas vertically.
+ *
+ * The clamp is last and is not redundant with the flip. A picker LARGER than
+ * its container overflows whichever way it opens, so the flip cannot save it and
+ * something has to decide what it does instead: it pins to the container's start
+ * edge, which keeps the options that exist reachable. `Math.min` before
+ * `Math.max` is what produces that — with the picker oversized the inner term
+ * lands before the start edge, and the outer `max` pulls it back — so the order
+ * is load-bearing rather than stylistic.
+ */
+function place(drop, extent, start, span) {
+    const end = start + span;
+    const flipped = drop + extent > end;
+    const anchored = flipped ? drop - extent : drop;
+    return { position: Math.max(start, Math.min(anchored, end - extent)), flipped };
+}
+/**
+ * The picker's top-left corner for a drop at `drop`, inside `container`.
+ *
+ * Every input is measured by the caller; nothing here assumes a size, a margin
+ * or a viewport. `container` is the canvas's own measured bounds rather than the
+ * window's, because the canvas is the surface the drop happened on and a picker
+ * escaping it would sit over the order rail beside it.
+ */
+export function pickerPlacement(drop, picker, container) {
+    const horizontal = place(drop.x, picker.width, container.x, container.width);
+    const vertical = place(drop.y, picker.height, container.y, container.height);
+    return {
+        x: horizontal.position,
+        y: vertical.position,
+        flippedX: horizontal.flipped,
+        flippedY: vertical.flipped,
+    };
+}
+//# sourceMappingURL=placement.js.map

package/dist/create/placement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../../src/create/placement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAkDH;;;;;;;;;;;;;;;GAeG;AACH,SAAS,KAAK,CAAC,IAAY,EAAE,MAAc,EAAE,KAAa,EAAE,IAAY;IACtE,MAAM,GAAG,GAAG,KAAK,GAAG,IAAI,CAAC;IACzB,MAAM,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,GAAG,CAAC;IACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IAChD,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,GAAG,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;AAClF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,IAAW,EAAE,MAAY,EAAE,SAAiB;IAC1E,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IAC7E,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAC7E,OAAO;QACL,CAAC,EAAE,UAAU,CAAC,QAAQ;QACtB,CAAC,EAAE,QAAQ,CAAC,QAAQ;QACpB,QAAQ,EAAE,UAAU,CAAC,OAAO;QAC5B,QAAQ,EAAE,QAAQ,CAAC,OAAO;KAC3B,CAAC;AACJ,CAAC"}

package/dist/firstpass/batch.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Multi-select: the other bulk path, for structure the owner already knows.
+ *
+ * The queue is for structure the owner has to be SHOWN. This is for the case
+ * §17e names beside it — the owner already knows these six issues are one
+ * serialized group, and answering six questions about a fact they arrived
+ * holding is worse than stating it once.
+ *
+ * §17e fixes three things about it, and each is load-bearing here:
+ *
+ *   "symmetric types apply to a whole selection at once; directed types need
+ *    one pick. N issues = N writes; the confirm states the count and the batch
+ *    is resumable if some fail."
+ *
+ * ## Directedness is read from the FORMAT, never listed here
+ *
+ * `isSymmetricEdgeField` in `@issuegraph/core` owns the split, for the reason
+ * `picker/view.ts` and `create/keys.ts` both record: a local list out here is
+ * the drifting second implementation the package family removes everywhere it
+ * appears, and a sixth field added to the format would leave it silently wrong
+ * with nothing failing to say so. A new symmetric field applies to a whole
+ * selection here the day core learns about it, with no edit to this file.
+ *
+ * ## Why a STAR, and why the anchor is stated rather than inferred
+ *
+ * N selected issues do not name N-1 edges on their own; some shape has to be
+ * chosen, and the choice is an opinion whichever way it goes. A clique is
+ * N(N-1)/2 writes for a fact the owner stated once — quadratic in the thing
+ * §17e is trying to make cheap. A chain is N-1 writes but imposes an ORDER the
+ * selection never carried, and for a symmetric field an invented order is
+ * exactly the wrong kind of invention.
+ *
+ * A star is N-1 writes and imposes one fact: which issue is the anchor. So that
+ * fact is TAKEN rather than guessed — {@link BatchRequest.anchor} — and it is
+ * the owner's pick, which is what makes the shape honest instead of arbitrary.
+ * For a symmetric kind the star still describes the whole component core means
+ * by these fields: every member is connected, which is the property, and the
+ * anchor is not privileged by the format afterwards.
+ *
+ * ## The "one pick" a directed type needs is DIRECTION, not the anchor
+ *
+ * Both kinds take an anchor, so that is not the thing that distinguishes them.
+ * What a directed kind additionally needs is which way the edges point — an
+ * anchor that BLOCKS the others and one that is BLOCKED BY them are opposite
+ * facts about the same six issues, and nothing about the selection implies
+ * either. So {@link BatchRequest.direction} is required for a directed kind and
+ * REFUSED for a symmetric one, rather than accepted and ignored: a host that
+ * sends one for `together-with` has misunderstood something, and silently
+ * dropping it would let a UI grow a direction control that does nothing.
+ *
+ * ## A refusal is a value, not a throw
+ *
+ * The same call `structuralRefusal` makes in the store, and for the same
+ * reason: these are things a person can do, so they get a surface to be drawn
+ * on rather than an exception to be caught. Nothing here adjudicates whether
+ * the resulting EDGES are legal — self-edges, duplicates and unknown issues are
+ * `structuralRefusal`'s, and a second validity rule out here is a second place
+ * for the answer to drift. This module refuses only what it alone can see:
+ * whether the REQUEST names a batch at all.
+ */
+import type { EdgeKind, IssueRef, Proposal } from '@issuegraph/store';
+/**
+ * Which way a directed batch points, relative to the anchor.
+ *
+ * Named for the anchor rather than for a field's own phrasing (`blocks` /
+ * `blocked-by`) because it has to read the same for all three directed fields,
+ * and only the anchor is common to them.
+ */
+export type BatchDirection = 'from-anchor' | 'to-anchor';
+/** What the owner selected and asked for. */
+export interface BatchRequest {
+    /**
+     * The anchor. Every edge in the batch touches it.
+     *
+     * It is not required to be a member of {@link members}, and deliberately so:
+     * "these five all block the release issue" is the ordinary shape, and the
+     * release issue is not one of the five.
+     */
+    readonly anchor: IssueRef;
+    /** The rest of the selection. Each one gets an edge to or from the anchor. */
+    readonly members: readonly IssueRef[];
+    readonly kind: EdgeKind;
+    /**
+     * Required for a directed kind, and refused for a symmetric one. See the
+     * module header — this is the "one pick", and it is not the anchor.
+     */
+    readonly direction?: BatchDirection | undefined;
+}
+/**
+ * Why a request does not name a batch.
+ *
+ * A closed union rather than a message, so a host words it — the same reason
+ * `reevaluate/words.ts` gives — and so a test asserts the reason rather than
+ * matching prose.
+ */
+export type BatchRefusal = 
+/** Fewer than one member: there is no edge to write. */
+{
+    readonly reason: 'no-members';
+}
+/** A directed kind arrived without its direction pick. */
+ | {
+    readonly reason: 'direction-required';
+    readonly kind: EdgeKind;
+}
+/** A symmetric kind arrived with a direction, which means something is wrong. */
+ | {
+    readonly reason: 'direction-not-applicable';
+    readonly kind: EdgeKind;
+};
+/**
+ * THERE IS NO `unknown-kind` REFUSAL, and its absence is deliberate.
+ *
+ * An earlier revision carried one, guarding `isSymmetricEdgeField` — which
+ * takes an `EdgeField` rather than a bare string precisely so it is never asked
+ * about a typo. But {@link BatchRequest.kind} is already `EdgeKind`, the closed
+ * union, so the case the guard answered cannot be constructed: the compiler
+ * rejected the very test written to exercise it.
+ *
+ * That is the shape `create/draft.ts` records a mutation control catching in
+ * this package once already — a branch asserting its own necessity that no test
+ * can reach. Deleting it is also what the family's validity rule says to do
+ * anyway: `structuralRefusal` owns whether an edge is legal, and a second
+ * validity rule out here is a second place for the answer to drift.
+ */
+/**
+ * A batch ready to confirm.
+ *
+ * `count` is `proposals.length` and exists so the confirm cannot state a
+ * different number from the one it is about to write. §17e requires the confirm
+ * to state the count; deriving it at the render site would be the second place
+ * that number lives.
+ */
+export interface BatchPlan {
+    readonly proposals: readonly Proposal[];
+    /** What the confirm states. Always `proposals.length`. */
+    readonly count: number;
+    readonly kind: EdgeKind;
+    readonly anchor: IssueRef;
+}
+export type BatchOutcome = {
+    readonly ok: true;
+    readonly plan: BatchPlan;
+} | {
+    readonly ok: false;
+    readonly refusal: BatchRefusal;
+};
+/**
+ * Turn a selection into the writes it stands for, or say why it is not a batch.
+ *
+ * Total and pure. Every refusal is checked before any proposal is built, so a
+ * refused request produces no partial plan for a caller to mistake for one.
+ */
+export declare function planBatch(request: BatchRequest): BatchOutcome;
+/**
+ * How one proposal of a batch settled.
+ *
+ * `landed` and `failed` only. A proposal still IN FLIGHT is deliberately not a
+ * third value: resuming while writes are outstanding would re-send them, which
+ * is the duplicate-write failure the store's closed operation set exists to
+ * prevent. A host resumes once the batch has settled, and a proposal it has no
+ * outcome for is treated as still owed — see {@link resumeBatch}.
+ */
+export interface BatchSettlement {
+    readonly proposal: Proposal;
+    readonly settled: 'landed' | 'failed';
+}
+/**
+ * What a partially-failed batch still owes.
+ *
+ * §17e: "the batch is resumable if some fail." Resumability is a real
+ * requirement rather than a nicety — a bulk write at §17f's sizes crosses a
+ * network N times, and a batch that has to be redone from the start after one
+ * timeout is a batch an owner will not retry.
+ *
+ * Returns a plan over the proposals that did NOT land, or `null` when nothing
+ * is owed. `null` rather than an empty plan: "the batch is finished" is a
+ * different state from "here is a batch of nothing to confirm", and an empty
+ * plan would render a confirm stating a count of zero.
+ *
+ * ## Unmentioned proposals are still owed, and that is the fail-safe direction
+ *
+ * A settlement list that is missing entries — a host that lost track, a session
+ * that died mid-batch — leaves those proposals in the resumed plan. Re-offering
+ * a write that actually landed costs the owner one refusal from the store's own
+ * duplicate rule; dropping a write that never landed loses a relationship
+ * silently, and nothing downstream would ever surface it.
+ */
+export declare function resumeBatch(plan: BatchPlan, settlements: readonly BatchSettlement[]): BatchPlan | null;
+//# sourceMappingURL=batch.d.ts.map

package/dist/firstpass/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../src/firstpass/batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,WAAW,CAAC;AAEzD,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CACjD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY;AACtB,wDAAwD;AACtD;IAAE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAAE;AACnC,0DAA0D;GACxD;IAAE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE;AACpE,iFAAiF;GAC/E;IAAE,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE7E;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IACxC,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;CAC3B;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC;AAmB3D;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAoB7D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,QAAQ,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,EACf,WAAW,EAAE,SAAS,eAAe,EAAE,GACtC,SAAS,GAAG,IAAI,CAWlB"}

package/dist/firstpass/batch.js

@@ -0,0 +1,143 @@
+/**
+ * Multi-select: the other bulk path, for structure the owner already knows.
+ *
+ * The queue is for structure the owner has to be SHOWN. This is for the case
+ * §17e names beside it — the owner already knows these six issues are one
+ * serialized group, and answering six questions about a fact they arrived
+ * holding is worse than stating it once.
+ *
+ * §17e fixes three things about it, and each is load-bearing here:
+ *
+ *   "symmetric types apply to a whole selection at once; directed types need
+ *    one pick. N issues = N writes; the confirm states the count and the batch
+ *    is resumable if some fail."
+ *
+ * ## Directedness is read from the FORMAT, never listed here
+ *
+ * `isSymmetricEdgeField` in `@issuegraph/core` owns the split, for the reason
+ * `picker/view.ts` and `create/keys.ts` both record: a local list out here is
+ * the drifting second implementation the package family removes everywhere it
+ * appears, and a sixth field added to the format would leave it silently wrong
+ * with nothing failing to say so. A new symmetric field applies to a whole
+ * selection here the day core learns about it, with no edit to this file.
+ *
+ * ## Why a STAR, and why the anchor is stated rather than inferred
+ *
+ * N selected issues do not name N-1 edges on their own; some shape has to be
+ * chosen, and the choice is an opinion whichever way it goes. A clique is
+ * N(N-1)/2 writes for a fact the owner stated once — quadratic in the thing
+ * §17e is trying to make cheap. A chain is N-1 writes but imposes an ORDER the
+ * selection never carried, and for a symmetric field an invented order is
+ * exactly the wrong kind of invention.
+ *
+ * A star is N-1 writes and imposes one fact: which issue is the anchor. So that
+ * fact is TAKEN rather than guessed — {@link BatchRequest.anchor} — and it is
+ * the owner's pick, which is what makes the shape honest instead of arbitrary.
+ * For a symmetric kind the star still describes the whole component core means
+ * by these fields: every member is connected, which is the property, and the
+ * anchor is not privileged by the format afterwards.
+ *
+ * ## The "one pick" a directed type needs is DIRECTION, not the anchor
+ *
+ * Both kinds take an anchor, so that is not the thing that distinguishes them.
+ * What a directed kind additionally needs is which way the edges point — an
+ * anchor that BLOCKS the others and one that is BLOCKED BY them are opposite
+ * facts about the same six issues, and nothing about the selection implies
+ * either. So {@link BatchRequest.direction} is required for a directed kind and
+ * REFUSED for a symmetric one, rather than accepted and ignored: a host that
+ * sends one for `together-with` has misunderstood something, and silently
+ * dropping it would let a UI grow a direction control that does nothing.
+ *
+ * ## A refusal is a value, not a throw
+ *
+ * The same call `structuralRefusal` makes in the store, and for the same
+ * reason: these are things a person can do, so they get a surface to be drawn
+ * on rather than an exception to be caught. Nothing here adjudicates whether
+ * the resulting EDGES are legal — self-edges, duplicates and unknown issues are
+ * `structuralRefusal`'s, and a second validity rule out here is a second place
+ * for the answer to drift. This module refuses only what it alone can see:
+ * whether the REQUEST names a batch at all.
+ */
+import { isSymmetricEdgeField } from '@issuegraph/core';
+/** One edge of the star, in the direction the request asked for. */
+function edgeFor(anchor, member, kind, direction) {
+    // A SYMMETRIC KIND STILL LANDS AS AN ORDERED PAIR, which is not a
+    // contradiction: `create/draft.ts` records why the store keeps the pair for
+    // symmetric kinds too — an editor has to know which issue carries the field.
+    // `from-anchor` is the arm a symmetric request takes, so the anchor holds it,
+    // which is the arrangement an owner who picked the anchor would expect.
+    return direction === 'from-anchor'
+        ? { op: 'create', kind, from: anchor, to: member }
+        : { op: 'create', kind, from: member, to: anchor };
+}
+/**
+ * Turn a selection into the writes it stands for, or say why it is not a batch.
+ *
+ * Total and pure. Every refusal is checked before any proposal is built, so a
+ * refused request produces no partial plan for a caller to mistake for one.
+ */
+export function planBatch(request) {
+    const { anchor, members, kind, direction } = request;
+    if (members.length === 0)
+        return { ok: false, refusal: { reason: 'no-members' } };
+    const symmetric = isSymmetricEdgeField(kind);
+    if (symmetric && direction !== undefined) {
+        return { ok: false, refusal: { reason: 'direction-not-applicable', kind } };
+    }
+    if (!symmetric && direction === undefined) {
+        return { ok: false, refusal: { reason: 'direction-required', kind } };
+    }
+    // `direction ?? 'from-anchor'` rather than a non-null assertion: the checks
+    // above make the fallback unreachable for a directed kind, and it is the
+    // arm a symmetric kind takes anyway — so the expression is total without a
+    // cast, which the strict-TypeScript rule forbids.
+    const pointing = direction ?? 'from-anchor';
+    const proposals = members.map((member) => edgeFor(anchor, member, kind, pointing));
+    return { ok: true, plan: { proposals, count: proposals.length, kind, anchor } };
+}
+/**
+ * What a partially-failed batch still owes.
+ *
+ * §17e: "the batch is resumable if some fail." Resumability is a real
+ * requirement rather than a nicety — a bulk write at §17f's sizes crosses a
+ * network N times, and a batch that has to be redone from the start after one
+ * timeout is a batch an owner will not retry.
+ *
+ * Returns a plan over the proposals that did NOT land, or `null` when nothing
+ * is owed. `null` rather than an empty plan: "the batch is finished" is a
+ * different state from "here is a batch of nothing to confirm", and an empty
+ * plan would render a confirm stating a count of zero.
+ *
+ * ## Unmentioned proposals are still owed, and that is the fail-safe direction
+ *
+ * A settlement list that is missing entries — a host that lost track, a session
+ * that died mid-batch — leaves those proposals in the resumed plan. Re-offering
+ * a write that actually landed costs the owner one refusal from the store's own
+ * duplicate rule; dropping a write that never landed loses a relationship
+ * silently, and nothing downstream would ever surface it.
+ */
+export function resumeBatch(plan, settlements) {
+    const landed = settlements.filter((s) => s.settled === 'landed').map((s) => s.proposal);
+    // COMPARED STRUCTURALLY, not by identity. A settlement comes back from the
+    // host — across a dispatch, possibly across a serialization boundary — so the
+    // object is not the one this module handed out, and `includes` would report
+    // every write as still owed.
+    const owed = plan.proposals.filter((proposal) => !landed.some((done) => sameProposal(proposal, done)));
+    if (owed.length === 0)
+        return null;
+    return { ...plan, proposals: owed, count: owed.length };
+}
+/**
+ * Whether two proposals stand for the same write.
+ *
+ * ONLY `create` IS COMPARED IN FULL, because only `create` can be in a batch —
+ * {@link planBatch} builds nothing else. The other three arms are answered by
+ * the `op` mismatch above them, and an exhaustive comparison of operations this
+ * module cannot produce would be untestable code asserting its own necessity.
+ */
+function sameProposal(left, right) {
+    if (left.op !== 'create' || right.op !== 'create')
+        return false;
+    return left.kind === right.kind && left.from === right.from && left.to === right.to;
+}
+//# sourceMappingURL=batch.js.map

package/dist/firstpass/batch.js.map

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

package/dist/firstpass/candidates.d.ts

@@ -0,0 +1,128 @@
+/**
+ * What a first-pass candidate IS, and the port it arrives through.
+ *
+ * §17e describes the adoption moment: a mature backlog arrives with 312 issues
+ * and zero relationships. "A blank canvas is the wrong tool: the owner doesn't
+ * want to draw 60 edges, they want to answer 60 questions." So the first pass
+ * is a review QUEUE — one proposed relationship at a time, with the evidence
+ * that suggested it, answerable in two seconds.
+ *
+ * ## The package ships no scanner, and that is a boundary rather than a gap
+ *
+ * The evidence §17e names — "both bodies reference `src/auth/session.ts`",
+ * "#455 is linked from a comment on #512" — is not derivable from a
+ * `GraphDocument`. It needs issue BODIES, COMMENTS and the host's own index,
+ * which is the tracker's world and precisely what `@issuegraph/store` refuses
+ * to fetch. A heuristic living in here would be an un-themeable product opinion
+ * shipped inside a published package: every host would get one vendor's idea of
+ * what "looks like a duplicate" means, with no way to replace it and no way to
+ * tune it against their own backlog.
+ *
+ * So candidates come IN, with their evidence already attached, exactly as
+ * `StoreConfig.derive` takes an order rather than inventing one. The port below
+ * is the declared shape of that crossing; nothing here implements it.
+ *
+ * ## Evidence carries the host's WORDS, not ours
+ *
+ * The same rule `reevaluate/words.ts` records, arriving through a different
+ * door. A sentence explaining why two issues might be duplicates is a claim
+ * about the host's tracker in the host's language, so this package cannot write
+ * one — and unlike the re-evaluate summary there is not even a fixed vocabulary
+ * to word, because the SET of reasons a host can offer is the host's to grow.
+ *
+ * What this package supplies instead is the {@link CandidateEvidence.token}: a
+ * machine-readable handle a host can style and a test can assert on, carried
+ * beside the prose rather than derived from it. That keeps the rendered surface
+ * testable without this package ever reading, parsing or authoring the text.
+ */
+import type { EdgeKind, IssueRef } from '@issuegraph/store';
+/**
+ * A candidate's identity, stable across a queue's life.
+ *
+ * OPAQUE TO THIS PACKAGE, and deliberately not derived from the relationship it
+ * proposes. Two candidates can legitimately propose the same pair with the same
+ * kind on different evidence — a host running two detectors will produce
+ * exactly that — and an identity computed from `from`/`to`/`kind` would silently
+ * collapse them, losing one detector's evidence and one of the owner's answers.
+ *
+ * The host mints it because the host knows what it means for two of its own
+ * findings to be the same finding.
+ */
+export type CandidateId = string;
+/**
+ * One reason a candidate was proposed.
+ *
+ * `text` is the host's sentence and this package renders it verbatim: it never
+ * reads it, never parses it, and never writes one of its own.
+ */
+export interface CandidateEvidence {
+    /**
+     * A machine-readable handle for this KIND of reason — `shared-path`,
+     * `linked-from-comment`, whatever the host's detectors are called.
+     *
+     * It reaches the markup as a data attribute, so a host styles one class of
+     * evidence differently and a test asserts a candidate carried the reason it
+     * should have, both without matching on prose. This package assigns it no
+     * meaning and holds no list of legal values — a closed set here would be the
+     * scanner opinion the module header refuses, one layer down.
+     */
+    readonly token: string;
+    /** The host's own words. Rendered as given. */
+    readonly text: string;
+}
+/**
+ * One proposed relationship, and why.
+ *
+ * It is shaped as the `create` proposal it would become — `kind`, `from`, `to`
+ * — rather than as a looser "these two look related". A candidate that cannot
+ * name the relationship it is proposing is not answerable in two seconds, which
+ * is the whole design target; the owner would have to open the picker for every
+ * one, and the queue would be the canvas again with extra steps.
+ */
+export interface Candidate {
+    readonly id: CandidateId;
+    /** Which relationship is being proposed. */
+    readonly kind: EdgeKind;
+    /** The issue the relationship would be created FROM. */
+    readonly from: IssueRef;
+    /** The issue it would be created TO. */
+    readonly to: IssueRef;
+    /**
+     * Why the host thinks so. At least one, by construction of a useful queue —
+     * but not enforced here, because a host with a detector that genuinely cannot
+     * explain itself should be able to say so by sending none rather than by
+     * inventing a sentence.
+     */
+    readonly evidence: readonly CandidateEvidence[];
+}
+/**
+ * The port. A host implements it; this package calls it and ships no default.
+ *
+ * ASYNC because finding candidates means reading the tracker — bodies,
+ * comments, an index — and every honest implementation of that is a network
+ * round trip. Modelling it as synchronous would force hosts to pre-compute the
+ * whole set before the surface could open, which at §17f's sizes is the wrong
+ * shape.
+ *
+ * NO DEFAULT IMPLEMENTATION, on the same reasoning `StoreConfig.derive` carries:
+ * a default would be a second implementation of the thing the host was asked to
+ * supply, and the first one anybody hit a limitation with would be impossible to
+ * replace because it was already load-bearing.
+ *
+ * The queue itself takes a resolved `readonly Candidate[]` rather than this
+ * port, so the reducer stays pure and synchronously testable. The port is what
+ * the SHELL holds; the queue is what the shell drives with the answer.
+ */
+export interface CandidateSource {
+    /**
+     * Every candidate the host can find for this document, with its evidence.
+     *
+     * "Every" is the host's to bound. §17e fixes what this package does with the
+     * count rather than what the count should be: progress is measured against
+     * candidates FOUND, so a host that returns its best 40 gets a queue with an
+     * end at 40, and one that returns 600 gets a queue with an end at 600.
+     * Neither is a truncation this package can detect or should report.
+     */
+    readonly findCandidates: () => Promise<readonly Candidate[]>;
+}
+//# sourceMappingURL=candidates.d.ts.map

package/dist/firstpass/candidates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../../src/firstpass/candidates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC;CAC9D"}

package/dist/firstpass/candidates.js

@@ -0,0 +1,39 @@
+/**
+ * What a first-pass candidate IS, and the port it arrives through.
+ *
+ * §17e describes the adoption moment: a mature backlog arrives with 312 issues
+ * and zero relationships. "A blank canvas is the wrong tool: the owner doesn't
+ * want to draw 60 edges, they want to answer 60 questions." So the first pass
+ * is a review QUEUE — one proposed relationship at a time, with the evidence
+ * that suggested it, answerable in two seconds.
+ *
+ * ## The package ships no scanner, and that is a boundary rather than a gap
+ *
+ * The evidence §17e names — "both bodies reference `src/auth/session.ts`",
+ * "#455 is linked from a comment on #512" — is not derivable from a
+ * `GraphDocument`. It needs issue BODIES, COMMENTS and the host's own index,
+ * which is the tracker's world and precisely what `@issuegraph/store` refuses
+ * to fetch. A heuristic living in here would be an un-themeable product opinion
+ * shipped inside a published package: every host would get one vendor's idea of
+ * what "looks like a duplicate" means, with no way to replace it and no way to
+ * tune it against their own backlog.
+ *
+ * So candidates come IN, with their evidence already attached, exactly as
+ * `StoreConfig.derive` takes an order rather than inventing one. The port below
+ * is the declared shape of that crossing; nothing here implements it.
+ *
+ * ## Evidence carries the host's WORDS, not ours
+ *
+ * The same rule `reevaluate/words.ts` records, arriving through a different
+ * door. A sentence explaining why two issues might be duplicates is a claim
+ * about the host's tracker in the host's language, so this package cannot write
+ * one — and unlike the re-evaluate summary there is not even a fixed vocabulary
+ * to word, because the SET of reasons a host can offer is the host's to grow.
+ *
+ * What this package supplies instead is the {@link CandidateEvidence.token}: a
+ * machine-readable handle a host can style and a test can assert on, carried
+ * beside the prose rather than derived from it. That keeps the rendered surface
+ * testable without this package ever reading, parsing or authoring the text.
+ */
+export {};
+//# sourceMappingURL=candidates.js.map

package/dist/firstpass/candidates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidates.js","sourceRoot":"","sources":["../../src/firstpass/candidates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG"}