@cello-protocol/daemon 0.0.168 → 0.0.170

package/dist/delivery-open-registry.d.ts

@@ -0,0 +1,92 @@
+/**
+ * DOD-M12B-DELIVERY-QUIET-1 — which sessions this daemon's DOCUMENT DELIVERY worker is opening.
+ *
+ * ── THE LOOP THIS EXISTS TO BREAK ────────────────────────────────────────────────────────────────
+ *
+ * Two reachability triggers fire when a session comes up, and both are correct when a PEER caused
+ * the session:
+ *
+ *   1. The initiator half — `onSessionOpened` in `initiate-session-handler.ts`, fired by the side
+ *      that dialled.
+ *   2. The inbound half — `dispatchSessionStateChangedWithTelegram` on `state === "created"`,
+ *      fired by the side that accepted, which ALSO rings the conversation doorbell and pushes a
+ *      Telegram notification.
+ *
+ * Either one calls `ReconcileScheduler.onReachable`, and that is not a nudge: it sets
+ * `failures = 0` and `nextAttemptMs = 0` and sweeps every shared document immediately. The stated
+ * rationale is sound — "the backoff modeled 'they do not answer', and here they demonstrably just
+ * did" (SYNC-P5 R39 trigger 2) — but it is only sound when the peer caused the session.
+ *
+ * When the DELIVERY WORKER opened it, the "signal" is our own outbound act reflected back at us. We
+ * learn nothing about the peer, and we wipe a backoff that a refusal — possibly that same peer's
+ * refusal, seconds earlier — had just set. Then:
+ *
+ *   the sweep needs a session → it opens one → creation fires the trigger → the trigger zeroes the
+ *   backoff and sweeps every document → the sweep needs sessions → …
+ *
+ * Measured 2026-08-17: 321 reconcile attempts in 85 minutes driving 53 sessions and 63 standing-
+ * receiver rebuilds. After `DOD-SYNC-REFUSAL-BACKOFF-1` removed the refusal storm, still 55
+ * attempts in 20 minutes with 0 refusals — the volume that fix did not reach is this trigger.
+ *
+ * ── WHY AN INTENT, KEYED ON THE PEER, AND NOT A SESSION ID ───────────────────────────────────────
+ *
+ * The obvious design is to record the session id the delivery worker opened. It does not work: the
+ * id is minted by the DIRECTORY and only reaches the opener at the end of negotiation, whereas the
+ * directory has already pushed the assignment to the counterparty — which, when both agents live on
+ * one daemon (the measured configuration), is this same process. The inbound doorbell therefore
+ * fires BEFORE the opener ever learns the id, so a session-id registry is always too late.
+ *
+ * So what is registered is the INTENT — "this local agent's delivery worker is opening a session
+ * with this peer right now" — before negotiation starts, and released when the open returns.
+ *
+ * ── THE KNOWN IMPRECISION, STATED RATHER THAN HIDDEN ─────────────────────────────────────────────
+ *
+ * If a delivery open to peer P is in flight for agent A at the same instant A's OPERATOR opens a
+ * session to the same P, the inbound half cannot tell the two assignments apart and will suppress
+ * the operator's doorbell too. It is narrow (same local agent, same peer, overlapping windows) and
+ * it costs one missed notification for a session the operator started themselves and is therefore
+ * already watching. The alternative — suppressing nothing — is the storm. This is the same class of
+ * accepted, journaled imprecision as the away-ack coalescing guard in `daemon.ts`.
+ *
+ * Counting, not a boolean: two documents can be delivering to the same peer concurrently, and a
+ * boolean cleared by whichever finishes first would re-open the loop for the other.
+ */
+/** Who caused a session to exist. Decides whether its creation is a signal about the peer. */
+export type SessionOpenedBy = "operator" | "document_delivery";
+export interface DeliveryOpenRegistry {
+    /**
+     * Register that `openerPubkey`'s delivery worker is opening a session with `targetPubkey`.
+     * Returns the release function.
+     */
+    begin(openerPubkey: string, targetPubkey: string): () => void;
+    /**
+     * True while a delivery open from `openerPubkey` toward `targetPubkey` is in flight.
+     *
+     * ORDER IS THE WHOLE THING. The two halves that ask this question stand at opposite ends of the
+     * same dial, so one of them must reverse its own arguments:
+     *
+     *   initiator half — WE opened it:  isDeliveryOpening(us, them)
+     *   inbound half   — THEY opened it: isDeliveryOpening(them, us)
+     *
+     * The first version of this registry keyed on (agent NAME, peer PUBKEY) and both halves passed
+     * their own local agent first. The initiator half matched; the inbound half asked
+     * `(receiver-name, initiator-pubkey)` against a registry holding `(initiator-name, target-pubkey)`
+     * — two tuples that can never be equal — so the doorbell guard read as protection and was
+     * unreachable in production, and the log line meant to prove it worked never fired either.
+     * Pubkeys on BOTH ends is what lets the two halves name the same pair at all.
+     */
+    isDeliveryOpening(openerPubkey: string, targetPubkey: string): boolean;
+    /** In-flight count. Exposed for assertions and for the leak check a test can make. */
+    inFlight(): number;
+}
+/**
+ * How long an entry may claim to be "in flight" before it is ignored.
+ *
+ * `openSessionAs` carries no deadline of its own, so a dial that never settles would leave the
+ * intent registered and silence that peer's doorbell for the life of the process — a worse outage
+ * than the storm this exists to stop. A dial that has been in flight for two minutes is not in
+ * flight; it is stuck, and a stuck dial must not be able to mute anything.
+ */
+export declare const DELIVERY_OPEN_STALE_MS = 120000;
+export declare function createDeliveryOpenRegistry(now?: () => number): DeliveryOpenRegistry;
+//# sourceMappingURL=delivery-open-registry.d.ts.map

package/dist/delivery-open-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-open-registry.d.ts","sourceRoot":"","sources":["../src/delivery-open-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,8FAA8F;AAC9F,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,mBAAmB,CAAC;AAE/D,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAC9D;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;IACvE,sFAAsF;IACtF,QAAQ,IAAI,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,SAAU,CAAC;AAE9C,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,MAAiB,GAAG,oBAAoB,CAoD7F"}

package/dist/delivery-open-registry.js

@@ -0,0 +1,121 @@
+/**
+ * DOD-M12B-DELIVERY-QUIET-1 — which sessions this daemon's DOCUMENT DELIVERY worker is opening.
+ *
+ * ── THE LOOP THIS EXISTS TO BREAK ────────────────────────────────────────────────────────────────
+ *
+ * Two reachability triggers fire when a session comes up, and both are correct when a PEER caused
+ * the session:
+ *
+ *   1. The initiator half — `onSessionOpened` in `initiate-session-handler.ts`, fired by the side
+ *      that dialled.
+ *   2. The inbound half — `dispatchSessionStateChangedWithTelegram` on `state === "created"`,
+ *      fired by the side that accepted, which ALSO rings the conversation doorbell and pushes a
+ *      Telegram notification.
+ *
+ * Either one calls `ReconcileScheduler.onReachable`, and that is not a nudge: it sets
+ * `failures = 0` and `nextAttemptMs = 0` and sweeps every shared document immediately. The stated
+ * rationale is sound — "the backoff modeled 'they do not answer', and here they demonstrably just
+ * did" (SYNC-P5 R39 trigger 2) — but it is only sound when the peer caused the session.
+ *
+ * When the DELIVERY WORKER opened it, the "signal" is our own outbound act reflected back at us. We
+ * learn nothing about the peer, and we wipe a backoff that a refusal — possibly that same peer's
+ * refusal, seconds earlier — had just set. Then:
+ *
+ *   the sweep needs a session → it opens one → creation fires the trigger → the trigger zeroes the
+ *   backoff and sweeps every document → the sweep needs sessions → …
+ *
+ * Measured 2026-08-17: 321 reconcile attempts in 85 minutes driving 53 sessions and 63 standing-
+ * receiver rebuilds. After `DOD-SYNC-REFUSAL-BACKOFF-1` removed the refusal storm, still 55
+ * attempts in 20 minutes with 0 refusals — the volume that fix did not reach is this trigger.
+ *
+ * ── WHY AN INTENT, KEYED ON THE PEER, AND NOT A SESSION ID ───────────────────────────────────────
+ *
+ * The obvious design is to record the session id the delivery worker opened. It does not work: the
+ * id is minted by the DIRECTORY and only reaches the opener at the end of negotiation, whereas the
+ * directory has already pushed the assignment to the counterparty — which, when both agents live on
+ * one daemon (the measured configuration), is this same process. The inbound doorbell therefore
+ * fires BEFORE the opener ever learns the id, so a session-id registry is always too late.
+ *
+ * So what is registered is the INTENT — "this local agent's delivery worker is opening a session
+ * with this peer right now" — before negotiation starts, and released when the open returns.
+ *
+ * ── THE KNOWN IMPRECISION, STATED RATHER THAN HIDDEN ─────────────────────────────────────────────
+ *
+ * If a delivery open to peer P is in flight for agent A at the same instant A's OPERATOR opens a
+ * session to the same P, the inbound half cannot tell the two assignments apart and will suppress
+ * the operator's doorbell too. It is narrow (same local agent, same peer, overlapping windows) and
+ * it costs one missed notification for a session the operator started themselves and is therefore
+ * already watching. The alternative — suppressing nothing — is the storm. This is the same class of
+ * accepted, journaled imprecision as the away-ack coalescing guard in `daemon.ts`.
+ *
+ * Counting, not a boolean: two documents can be delivering to the same peer concurrently, and a
+ * boolean cleared by whichever finishes first would re-open the loop for the other.
+ */
+/**
+ * How long an entry may claim to be "in flight" before it is ignored.
+ *
+ * `openSessionAs` carries no deadline of its own, so a dial that never settles would leave the
+ * intent registered and silence that peer's doorbell for the life of the process — a worse outage
+ * than the storm this exists to stop. A dial that has been in flight for two minutes is not in
+ * flight; it is stuck, and a stuck dial must not be able to mute anything.
+ */
+export const DELIVERY_OPEN_STALE_MS = 120_000;
+export function createDeliveryOpenRegistry(now = Date.now) {
+    // Pubkeys reach this code from a wire assignment on one side and from a caller's parameter on the
+    // other, and those two do not agree on case. Lowercased at the boundary so a comparison here can
+    // never be the reason the suppression silently stops working.
+    //
+    // NUL separator, written as an escape rather than a raw byte: a literal U+0000 in the source made
+    // this file binary to git, so `git show` printed no diff for it at all and the one new module in
+    // the unit could not be reviewed through the normal path.
+    const key = (openerPubkey, targetPubkey) => `${openerPubkey.toLowerCase()}\u0000${targetPubkey.toLowerCase()}`;
+    // Start times, newest last. An array rather than a count so a stale entry can be dropped
+    // individually — a bare counter cannot tell which of two in-flight opens is the wedged one.
+    const opens = new Map();
+    const live = (k) => {
+        const all = opens.get(k);
+        if (all === undefined)
+            return [];
+        const cutoff = now() - DELIVERY_OPEN_STALE_MS;
+        const fresh = all.filter((startedAt) => startedAt > cutoff);
+        if (fresh.length === 0)
+            opens.delete(k);
+        else if (fresh.length !== all.length)
+            opens.set(k, fresh);
+        return fresh;
+    };
+    return {
+        begin(openerPubkey, targetPubkey) {
+            const k = key(openerPubkey, targetPubkey);
+            const startedAt = now();
+            opens.set(k, [...live(k), startedAt]);
+            let released = false;
+            return () => {
+                // Idempotent: a caller that releases twice must not drop someone else's entry and leave the
+                // doorbell suppressed for a peer whose open has not finished.
+                if (released)
+                    return;
+                released = true;
+                const remaining = opens.get(k);
+                if (remaining === undefined)
+                    return;
+                const at = remaining.indexOf(startedAt);
+                const next = at === -1 ? remaining : [...remaining.slice(0, at), ...remaining.slice(at + 1)];
+                if (next.length === 0)
+                    opens.delete(k);
+                else
+                    opens.set(k, next);
+            };
+        },
+        isDeliveryOpening(openerPubkey, targetPubkey) {
+            return live(key(openerPubkey, targetPubkey)).length > 0;
+        },
+        inFlight() {
+            let total = 0;
+            for (const k of [...opens.keys()])
+                total += live(k).length;
+            return total;
+        },
+    };
+}
+//# sourceMappingURL=delivery-open-registry.js.map

package/dist/delivery-open-registry.js.map

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

package/dist/document-amendment-store.d.ts

@@ -1,72 +1,120 @@
 /**
- * DOD-MP-AMEND-1 (daemon half) — the append-only amendment store.
+ * SYNC-P1 (daemon half) — the fork-tolerant entry store.
  *
- * One row per epoch per document, holding the amendment AS RECEIVED — the wire bytes, never a
- * re-encode. The bytes are the truth: `chain` decodes them on read, so what replay consumes is
- * exactly what was signed, and a codec asymmetry can never silently rewrite an agreed record
- * (the class of defect TRACE-1 found in the proposal codec).
+ * One row per ENTRY (keyed by entry hash — never by an epoch slot), holding the entry AS
+ * RECEIVED — the wire bytes, never a re-encode. The bytes are the truth: `chain` decodes them on
+ * read, so what the fold consumes is exactly what was signed, and a codec asymmetry can never
+ * silently rewrite an agreed record (the class of defect TRACE-1 found in the proposal codec).
  *
- * The store owns persistence and chain SHAPE:
- * - **Contiguity** — epoch N appends only onto N-1 rows. An out-of-order arrival is refused by
- *   name, not buffered; amendment-lag buffering is DOD-MP-INBOUND-N-1's design, and until it
- *   lands the honest behaviour is a loud refusal the sender retries.
- * - **Fork refusal** — a different amendment at an occupied epoch is `document_amendment_conflict`,
- *   first record kept. Two rivals for one epoch is a governance fork; absorbing either silently
- *   would have two holders replay different arrangements with no error anywhere.
- * - **Idempotent redelivery** — the same bytes again is `recorded: false`, not an error and not a
- *   second row.
+ * The store owns persistence and ANCESTRY CLOSURE:
+ * - **Held until whole (R14)** — an entry lands in `document_entries` only when every parent has
+ *   landed. Otherwise it waits in `document_entries_pending`: recorded, never applied, never in a
+ *   watermark, promoted the moment its ancestry completes — cascade included. The invariant this
+ *   buys: everything in `document_entries` has its FULL ancestry there too.
+ * - **Fork tolerance** — two entries claiming the same epoch or the same author seq are BOTH
+ *   stored. Ruling on conflicts is the causal fold's job (`deriveDocumentState`), not the
+ *   store's; the old chain-gap and epoch-conflict refusals are gone WITH the epoch spine.
+ * - **Idempotent redelivery** — the same bytes again is `recorded: false`, not an error and not
+ *   a second row.
+ * - **Watermarks** — per author, the highest CONTIGUOUS seq with its head hash(es). Two heads at
+ *   one seq is an equivocation made visible for the exchange to resolve, never silently picked.
  *
- * What the store does NOT judge: signatures, policy, subject semantics. `deriveArrangement`
- * (protocol-types) rules on those at every consumption, and the inbound path rules BEFORE
- * appending. A row in this table is a claim to be replayed, not an admitted fact.
+ * What the store does NOT judge: signatures, policy, subject semantics. The fold rules on those
+ * at every consumption, and the inbound path rules BEFORE appending. A row in these tables is a
+ * claim to be folded, not an admitted fact.
  */
 import { type DocumentAmendmentEnvelope } from "@cello-protocol/protocol-types";
 import type { DaemonDatabase } from "./sqlcipher-db.js";
 import type { Logger } from "./types.js";
 /**
- * Shared with `DocumentStore`, which also execs this (the :353 shared-definition precedent there):
- * every epoch producer already holds a DocumentStore, and `currentDocumentEpoch` reads this table
- * through it — so the table must exist whichever module constructs first. Keep the two consumers
- * on THIS one string.
+ * The PRE-PIVOT table, epoch-keyed. Still created because `DocumentStore` execs this too and the
+ * pre-pivot readers live until P4 deletes them (SYNC-D2); the entry store neither reads nor
+ * writes it. Rows predating the pivot stay untouched — old-shape bytes are not decodable by the
+ * v2 codec and are not migrated (no compatibility owed; essentially no documents exist).
+ */
+/**
+ * Shared with `DocumentStore` (the :352 shared-definition precedent): its membership walk and
+ * epoch read consume `document_entries`, so the tables must exist whichever module constructs
+ * first. Keep both consumers on THIS string.
  */
-export declare const DOCUMENT_AMENDMENTS_CREATE_SQL = "\n  CREATE TABLE IF NOT EXISTS document_amendments (\n    owner_agent_id  TEXT    NOT NULL,\n    document_id     TEXT    NOT NULL,\n    epoch_id        INTEGER NOT NULL,\n    amendment_hash  TEXT    NOT NULL,\n    received_bytes  BLOB    NOT NULL,\n    recorded_at     INTEGER NOT NULL,\n    PRIMARY KEY (owner_agent_id, document_id, epoch_id)\n  );\n";
-export interface MembershipVerdict {
-    state: "holder" | "removed" | "untouched";
-    epochId: number | null;
-}
 /**
- * The last membership event naming this agent in an ordered chain — ONE implementation, because
- * two walks (the inbound refusal's and the publish gate's) disagreeing about whether someone was
- * removed is two daemons disagreeing about the arrangement.
+ * D7 — the epoch spine is deleted. A database born before that carries a NOT NULL `epoch_id`
+ * with no default, which would refuse every insert from this build. Dropped in place (SQLite
+ * ≥3.35 / SQLCipher 4.5); a fresh database never has it.
  */
-export declare function walkMembership(chain: readonly DocumentAmendmentEnvelope[], agentId: string): MembershipVerdict;
+type ColumnDropper = {
+    exec(sql: string): void;
+    prepare(sql: string): {
+        all(...a: unknown[]): unknown[];
+    };
+};
+/**
+ * Drop columns a previous milestone left behind, birth-gated: only what the table actually still
+ * has is touched, so this is safe on a database created yesterday and on one created before the
+ * column existed. Dead schema is not free — it is the design a future author reads and rebuilds.
+ */
+export declare function dropLegacyColumns(db: ColumnDropper, table: string, columns: readonly string[]): void;
+export declare function dropLegacyEpochColumn(db: ColumnDropper, table: string): void;
+export declare const DOCUMENT_ENTRIES_CREATE_SQL = "\n  CREATE TABLE IF NOT EXISTS document_entries (\n    owner_agent_id  TEXT    NOT NULL,\n    document_id     TEXT    NOT NULL,\n    entry_hash      TEXT    NOT NULL,\n    author_agent_id TEXT    NOT NULL,\n    author_seq      INTEGER NOT NULL,\n    received_bytes  BLOB    NOT NULL,\n    recorded_at     INTEGER NOT NULL,\n    PRIMARY KEY (owner_agent_id, document_id, entry_hash)\n  );\n  CREATE INDEX IF NOT EXISTS idx_document_entries_author\n    ON document_entries (owner_agent_id, document_id, author_agent_id, author_seq);\n  CREATE TABLE IF NOT EXISTS document_entries_pending (\n    owner_agent_id  TEXT    NOT NULL,\n    document_id     TEXT    NOT NULL,\n    entry_hash      TEXT    NOT NULL,\n    author_agent_id TEXT    NOT NULL,\n    received_bytes  BLOB    NOT NULL,\n    recorded_at     INTEGER NOT NULL,\n    PRIMARY KEY (owner_agent_id, document_id, entry_hash)\n  );\n";
 export interface AmendmentAppendResult {
-    /** False on an idempotent redelivery — the row already existed with the same hash. */
+    /** False on an idempotent redelivery — the entry (or its pending row) already existed. */
     recorded: boolean;
-    epochId: number;
-    /** Hex of the amendment's TBS hash. */
-    amendmentHash: string;
+    /** True when the entry is waiting on missing parents (R14) — recorded but not yet applied. */
+    held: boolean;
+    /** Hex of the entry's TBS hash. */
+    entryHash: string;
+    /** Previously-held entries this arrival completed, now applied — envelopes included, so the
+     *  caller can run the same post-apply surfacing it runs for a direct arrival (review F2: the
+     *  held path silently dropped removal notices and lifecycle completion). */
+    promoted: PromotedEntry[];
+}
+export interface PromotedEntry {
+    entryHash: string;
+    envelope: DocumentAmendmentEnvelope;
+}
+export interface PendingEntry {
+    entryHash: string;
+    /** The parents not yet held — the exchange asks for exactly these. */
+    missingParents: string[];
+    recordedAtMs: number;
+}
+/**
+ * Ceiling on HELD entries per (document, author). An honest author's pending set is a short gap
+ * awaiting one delivery; a hostile known author fabricating parents could otherwise grow the
+ * pending table without bound (review F4).
+ */
+export declare const MAX_PENDING_PER_AUTHOR = 64;
+export interface AuthorWatermark {
+    /** Highest CONTIGUOUS seq held from this author. */
+    seq: number;
+    /** Entry hash(es) at that seq — more than one is an equivocation, visible by design. */
+    headHashes: string[];
 }
 export declare class DocumentAmendmentStore {
     #private;
     constructor(db: DaemonDatabase, logger: Logger);
     /**
-     * Append one amendment from its wire bytes. Decodes first — malformed bytes refuse with the
-     * decoder's named reason and nothing is stored.
+     * Append one entry from its wire bytes. Decodes first — malformed bytes refuse with the
+     * decoder's named reason and nothing is stored. An entry with missing parents is HELD; an
+     * arrival that completes held ancestry promotes the whole cascade.
      */
     append(ownerAgentId: string, documentId: string, receivedBytes: Uint8Array, nowMs: number): AmendmentAppendResult;
-    /** The ordered chain, decoded from the stored received bytes. */
+    /** Every applied entry, decoded from the stored received bytes. The set is ancestry-closed. */
     chain(ownerAgentId: string, documentId: string): DocumentAmendmentEnvelope[];
+    /** Held entries and exactly which parents they still wait on (R37's receiver-side record). */
+    pending(ownerAgentId: string, documentId: string): PendingEntry[];
+    /**
+     * This author's applied entries with seq strictly beyond `afterSeq`, as WIRE BYTES in seq
+     * order — what a reconcile reply carries to a peer whose watermark for this author is behind
+     * ours (R10 step 2/3). Forked seqs both ship: the peer's fold rules on them like ours did.
+     */
+    entriesByAuthorAfter(ownerAgentId: string, documentId: string, authorAgentId: string, afterSeq: number): Uint8Array[];
     /**
-     * DOD-MP-REMOVE-1 — this agent's LAST membership event in the recorded chain.
-     * "holder" = admitted (or never touched by any membership amendment — genesis membership is
-     * the CALLER's fact, not this table's); "removed" = the last event naming them was
-     * remove_holder, with the epoch it happened at, so a refusal can name the removal rather than
-     * a generic condition. Reads the recorded chain only — validity was ruled before append
-     * (the standing invariant).
+     * Per-author position: the highest CONTIGUOUS seq held and the head hash(es) at it. A held
+     * (pending) entry is not counted — a gap ends the walk (R13: report contiguous, never highest
+     * received).
      */
-    membershipOf(ownerAgentId: string, documentId: string, agentId: string): MembershipVerdict;
-    /** The highest recorded epoch, or 0 — genesis — when no amendment exists. */
-    currentEpoch(ownerAgentId: string, documentId: string): number;
+    watermarks(ownerAgentId: string, documentId: string): Map<string, AuthorWatermark>;
 }
+export {};
 //# sourceMappingURL=document-amendment-store.d.ts.map

package/dist/document-amendment-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-amendment-store.d.ts","sourceRoot":"","sources":["../src/document-amendment-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,oWAU1C,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;IAC1C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,yBAAyB,EAAE,EAC3C,OAAO,EAAE,MAAM,GACd,iBAAiB,CAcnB;AAED,MAAM,WAAW,qBAAqB;IACpC,sFAAsF;IACtF,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,sBAAsB;;gBAIrB,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM;IAM9C;;;OAGG;IACH,MAAM,CACJ,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,UAAU,EACzB,KAAK,EAAE,MAAM,GACZ,qBAAqB;IAmExB,iEAAiE;IACjE,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,yBAAyB,EAAE;IAW5E;;;;;;;OAOG;IACH,YAAY,CACV,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,iBAAiB;IAIpB,6EAA6E;IAC7E,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;CAS/D"}
+{"version":3,"file":"document-amendment-store.d.ts","sourceRoot":"","sources":["../src/document-amendment-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;GAKG;AACH;;;;GAIG;AACH;;;;GAIG;AACH,KAAK,aAAa,GAAG;IAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAA;KAAE,CAAA;CAAE,CAAC;AAE5G;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAOpG;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAE5E;AAED,eAAO,MAAM,2BAA2B,63BAsBvC,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,0FAA0F;IAC1F,QAAQ,EAAE,OAAO,CAAC;IAClB,8FAA8F;IAC9F,IAAI,EAAE,OAAO,CAAC;IACd,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB;;gFAE4E;IAC5E,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,yBAAyB,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,wFAAwF;IACxF,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,qBAAa,sBAAsB;;gBAIrB,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM;IAW9C;;;;OAIG;IACH,MAAM,CACJ,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,UAAU,EACzB,KAAK,EAAE,MAAM,GACZ,qBAAqB;IA0DxB,+FAA+F;IAC/F,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,yBAAyB,EAAE;IAW5E,8FAA8F;IAC9F,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,EAAE;IAwBjE;;;;OAIG;IACH,oBAAoB,CAClB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,UAAU,EAAE;IAaf;;;;OAIG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC;CAqInF"}