@telora/daemon 0.21.26 → 0.21.81

package/dist/delivery/delivery-reconciler-shadow.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Shadow harness for the single-writer delivery reconciler.
+ *
+ * Delivery 3 (single-writer reconciler, shadow mode) of the Delivery Execution
+ * Pathway Consolidation focus (reality-tree injection #10). De-risking method:
+ * characterize -> SHADOW -> flip one transition at a time. This is the shadow
+ * step.
+ *
+ * On each poll, for every active focus's deliveries, this gathers the live
+ * signal (issue rollup, worktree-committed flag), runs the PURE
+ * reconcileDeliveryStatus(), compares its computed target to the delivery's
+ * LIVE execution_status, and LOGS every divergence. It makes ZERO writes to
+ * execution_status -- there is no status writer in its dependency surface by
+ * construction. When divergence holds steady at zero, the reconciler is safe to
+ * flip into the write path one transition at a time (Delivery 4).
+ *
+ * Default-OFF: unlike the focus/verification loops (opt-OUT via shouldRunLoop),
+ * the shadow is opt-IN. It runs only when TELORA_RECONCILER_SHADOW is a truthy
+ * value ('1'/'true'/etc); unset / '' / '0' keep it a no-op, so wiring it into
+ * the live poll changes nothing until an operator deliberately enables it.
+ *
+ * Poll-time signal note: at poll time there is no exiting review session, so the
+ * harness supplies a conservative review state (a verify delivery with no open
+ * work stays in verify -- matching what the live poll does; verify->done is
+ * driven by the review-exit path, not the poll). The transitions the shadow
+ * meaningfully exercises at poll time are the issue-rollup-driven ones
+ * (queued/coding/verify_failed) and verify->verify_failed on open work.
+ */
+import type { DaemonConfig } from '../types/index.js';
+import { getActiveFocuses } from '../queries/deliveries.js';
+import { getDeliveryIssues } from '../queries/issues.js';
+import { getFocusDeliveries } from '../queries/focuses.js';
+import { getFocusWorktree } from '../focus/focus-worktree-state.js';
+import { worktreeHasUncommittedChanges } from '../worktree/index.js';
+/** Opt-in flag name. Default-OFF (only a truthy value enables the shadow). */
+export declare const RECONCILER_SHADOW_ENV = "TELORA_RECONCILER_SHADOW";
+/** Default-off opt-in: only '1'/'true'/'yes'/'on' (case-insensitive) enable. */
+export declare function reconcilerShadowEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Injectable collaborators. The surface is READ-ONLY by design: there is NO
+ * status-writer dependency, which is the structural guarantee that the shadow
+ * cannot mutate execution_status.
+ */
+export interface ReconcilerShadowDeps {
+    isEnabled: () => boolean;
+    getActiveFocuses: typeof getActiveFocuses;
+    getFocusDeliveries: typeof getFocusDeliveries;
+    getDeliveryIssues: typeof getDeliveryIssues;
+    getFocusWorktree: typeof getFocusWorktree;
+    worktreeHasUncommittedChanges: typeof worktreeHasUncommittedChanges;
+    /** Divergence sink. Defaults to console.log; injected in tests for capture. */
+    log: (message: string) => void;
+}
+export interface ReconcilerShadowSummary {
+    /** Whether the shadow actually ran (false when the flag is off). */
+    ran: boolean;
+    /** Number of deliveries whose live status was compared. */
+    checked: number;
+    /** Number where the reconciled target differed from the live status. */
+    divergences: number;
+}
+/**
+ * Run one shadow pass for a (product-scoped) config. Reads only; never writes.
+ */
+export declare function runReconcilerShadow(config: DaemonConfig, deps?: ReconcilerShadowDeps): Promise<ReconcilerShadowSummary>;
+//# sourceMappingURL=delivery-reconciler-shadow.d.ts.map

package/dist/delivery/delivery-reconciler-shadow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-reconciler-shadow.d.ts","sourceRoot":"","sources":["../../src/delivery/delivery-reconciler-shadow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AASrE,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,6BAA6B,CAAC;AAEhE,gFAAgF;AAChF,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAErF;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,gBAAgB,CAAC;IAC1C,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,gBAAgB,EAAE,OAAO,gBAAgB,CAAC;IAC1C,6BAA6B,EAAE,OAAO,6BAA6B,CAAC;IACpE,+EAA+E;IAC/E,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAYD,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,GAAG,EAAE,OAAO,CAAC;IACb,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,YAAY,EACpB,IAAI,GAAE,oBAAkC,GACvC,OAAO,CAAC,uBAAuB,CAAC,CA4ElC"}

package/dist/delivery/delivery-reconciler-shadow.js

@@ -0,0 +1,127 @@
+/**
+ * Shadow harness for the single-writer delivery reconciler.
+ *
+ * Delivery 3 (single-writer reconciler, shadow mode) of the Delivery Execution
+ * Pathway Consolidation focus (reality-tree injection #10). De-risking method:
+ * characterize -> SHADOW -> flip one transition at a time. This is the shadow
+ * step.
+ *
+ * On each poll, for every active focus's deliveries, this gathers the live
+ * signal (issue rollup, worktree-committed flag), runs the PURE
+ * reconcileDeliveryStatus(), compares its computed target to the delivery's
+ * LIVE execution_status, and LOGS every divergence. It makes ZERO writes to
+ * execution_status -- there is no status writer in its dependency surface by
+ * construction. When divergence holds steady at zero, the reconciler is safe to
+ * flip into the write path one transition at a time (Delivery 4).
+ *
+ * Default-OFF: unlike the focus/verification loops (opt-OUT via shouldRunLoop),
+ * the shadow is opt-IN. It runs only when TELORA_RECONCILER_SHADOW is a truthy
+ * value ('1'/'true'/etc); unset / '' / '0' keep it a no-op, so wiring it into
+ * the live poll changes nothing until an operator deliberately enables it.
+ *
+ * Poll-time signal note: at poll time there is no exiting review session, so the
+ * harness supplies a conservative review state (a verify delivery with no open
+ * work stays in verify -- matching what the live poll does; verify->done is
+ * driven by the review-exit path, not the poll). The transitions the shadow
+ * meaningfully exercises at poll time are the issue-rollup-driven ones
+ * (queued/coding/verify_failed) and verify->verify_failed on open work.
+ */
+import { getActiveFocuses } from '../queries/deliveries.js';
+import { getDeliveryIssues } from '../queries/issues.js';
+import { getFocusDeliveries } from '../queries/focuses.js';
+import { getFocusWorktree } from '../focus/focus-worktree-state.js';
+import { worktreeHasUncommittedChanges } from '../worktree/index.js';
+import { reconcileDeliveryStatus } from './delivery-reconciler.js';
+import { isExecutionStatus, loadEnvConfig } from '@telora/daemon-core';
+import { createLogger } from '../shell/log.js';
+const log = createLogger({ module: 'delivery-reconciler-shadow' });
+/** Opt-in flag name. Default-OFF (only a truthy value enables the shadow). */
+export const RECONCILER_SHADOW_ENV = 'TELORA_RECONCILER_SHADOW';
+/** Default-off opt-in: only '1'/'true'/'yes'/'on' (case-insensitive) enable. */
+export function reconcilerShadowEnabled(env = process.env) {
+    return loadEnvConfig(env).TELORA_RECONCILER_SHADOW;
+}
+const defaultDeps = {
+    isEnabled: () => reconcilerShadowEnabled(),
+    getActiveFocuses,
+    getFocusDeliveries,
+    getDeliveryIssues,
+    getFocusWorktree,
+    worktreeHasUncommittedChanges,
+    log: (m) => log.info(m),
+};
+/**
+ * Run one shadow pass for a (product-scoped) config. Reads only; never writes.
+ */
+export async function runReconcilerShadow(config, deps = defaultDeps) {
+    if (!deps.isEnabled()) {
+        return { ran: false, checked: 0, divergences: 0 };
+    }
+    let checked = 0;
+    let divergences = 0;
+    let focuses;
+    try {
+        focuses = await deps.getActiveFocuses(config.organizationId, config.productId);
+    }
+    catch (err) {
+        deps.log(`[reconciler-shadow] failed to fetch active focuses: ${err.message}`);
+        return { ran: true, checked, divergences };
+    }
+    for (const focus of focuses) {
+        const reviewRequested = !!focus.review_requested_at;
+        let deliveries;
+        try {
+            deliveries = await deps.getFocusDeliveries(focus.focus_id);
+        }
+        catch (err) {
+            deps.log(`[reconciler-shadow] failed to fetch deliveries for focus ${focus.focus_id}: ${err.message}`);
+            continue;
+        }
+        // Resolve the worktree-committed signal once per focus (one worktree per focus).
+        const worktree = deps.getFocusWorktree(focus.focus_id);
+        let worktreeCommitted = true; // no worktree => nothing uncommitted can block (matches the advance precheck)
+        if (worktree) {
+            try {
+                worktreeCommitted = !deps.worktreeHasUncommittedChanges(worktree.worktreePath);
+            }
+            catch {
+                // Best-effort: a git failure should not break the shadow; assume committed.
+                worktreeCommitted = true;
+            }
+        }
+        for (const delivery of deliveries) {
+            const liveStatus = delivery.executionStatus ?? '';
+            if (!isExecutionStatus(liveStatus))
+                continue;
+            let issues;
+            try {
+                issues = await deps.getDeliveryIssues(delivery.id);
+            }
+            catch (err) {
+                deps.log(`[reconciler-shadow] failed to fetch issues for delivery ${delivery.id}: ${err.message}`);
+                continue;
+            }
+            const result = reconcileDeliveryStatus({
+                currentStatus: liveStatus,
+                issues: issues.map(i => ({ status: i.status, issueType: i.issueType })),
+                gitState: { worktreeCommitted },
+                guardVerdict: null,
+                // Poll-time review state: conservative. verify with no open work stays
+                // verify (verify->done is review-exit-driven, not poll-driven).
+                reviewState: { reviewRequested, reportExists: false, sessionType: 'coding', succeeded: false },
+            });
+            checked++;
+            if (result.changed) {
+                divergences++;
+                deps.log(`[reconciler-shadow] DIVERGENCE delivery=${delivery.id} ("${delivery.name}") ` +
+                    `live=${liveStatus} reconciled=${result.target} ` +
+                    `canonical=${result.canonical} reason="${result.reason}" (no write performed)`);
+            }
+        }
+    }
+    if (checked > 0) {
+        deps.log(`[reconciler-shadow] pass complete: ${checked} deliveries checked, ${divergences} divergence(s), 0 writes`);
+    }
+    return { ran: true, checked, divergences };
+}
+//# sourceMappingURL=delivery-reconciler-shadow.js.map

package/dist/delivery/delivery-reconciler-shadow.js.map

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

package/dist/delivery/delivery-reconciler.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Single-writer delivery reconciler (PURE).
+ *
+ * Delivery 3 of the Delivery Execution Pathway Consolidation focus
+ * (reality-tree injection #10: "Delivery execution_status has exactly one
+ * writer -- the daemon reconciler; every transition flows through it").
+ *
+ * This module is the consolidation's center of gravity: ONE pure function that
+ * computes the single next execution_status the daemon should write, plus ONE
+ * shared "issues are done" predicate that replaces the divergent copies spread
+ * across the live writers (advanceDeliveryStage / advanceDeliveryStatuses /
+ * runReviewExitHandler / checkDeliveryAutoAdvance / checkVerifyDeliveriesForOpenIssues).
+ *
+ * That claim is now TRUE of every named writer AND mechanically enforced: each
+ * of the five routes its status decision through `resolveReconciledWrite`
+ * (delivery-reconciler-apply.ts) over the delivery's REAL issue list, and uses
+ * the shared OPEN_ISSUE_STATUSES / areDeliveryIssuesDone predicate -- no writer
+ * synthesizes issues from a count, carries a `!TERMINAL_ISSUE_STATUSES.has`
+ * open-work predicate, or keeps a superseded status write. The gate that keeps
+ * this header honest is `npm run lint:reconciler-single-writer`
+ * (scripts/lint-reconciler-single-writer.mjs, wired into lint:all): it fails if
+ * any named writer reintroduces its own derivation, or if this header names a
+ * writer that no longer exists. Keep the "live writers ( ... )" list above
+ * accurate -- the gate parses it.
+ *
+ * It is deliberately PURE -- no I/O, no supabase, no git. Callers gather the
+ * signal (issues, worktree-committed flag, guard verdict, review state) and
+ * pass it in; the reconciler only computes. This is what makes it
+ * shadow-testable: run it alongside the live path, compare its target to the
+ * live status, log divergence, write nothing (see delivery-reconciler-shadow.ts).
+ *
+ * The behavior here MIRRORS the CURRENT live writers as pinned by the
+ * Delivery 2 characterization suite
+ * (__tests__/delivery-state-machine-characterization.test.ts). It characterizes
+ * what the system does today, not an idealized target -- the shadow phase exists
+ * precisely to prove parity before any cutover.
+ *
+ * The coding -> queued re-queue edge (open work at team exit -> re-queue) is
+ * present in EXECUTION_STATUS_TRANSITIONS as of the D5 cleanup. `result.canonical`
+ * flags transitions NOT in the canonical map; the coding -> queued edge now
+ * resolves to `canonical=true`.
+ */
+import type { ExecutionStatus } from '@telora/daemon-core';
+/** Minimal issue shape the reconciler needs. */
+export interface ReconcilerIssue {
+    status: string;
+    issueType: string;
+    /**
+     * Whether this open issue is a DEFERRABLE review note -- a low-severity
+     * triage note a review pass filed that is acceptable to defer past the verify
+     * gate. The deferrability POLICY (what counts as deferrable: a review-filed,
+     * open, P2/P3 issue) lives with the review classifier
+     * (review-defect-detector.isDeferrableReviewNote); the reconciler only
+     * consumes the resolved flag. Absent/false => the issue is blocking open work
+     * (the default, so callers that do not classify behave exactly as before).
+     */
+    deferrable?: boolean;
+}
+/** Git-safety signal: the irreducible worktree-commit gate. */
+export interface ReconcilerGitState {
+    /**
+     * Whether the focus worktree has NO uncommitted changes. The daemon is the
+     * only place this can be checked (Postgres has no git), which is the core
+     * reason the daemon -- not a PG trigger -- must own the coding -> verify write.
+     * When false, an otherwise-ready coding delivery is HELD in coding.
+     */
+    worktreeCommitted: boolean;
+}
+/** Verify-gate verdict (from the guard engine). null = no guard evaluated. */
+export interface ReconcilerGuardVerdict {
+    /** True when a hard guard blocked the transition -> delivery pauses. */
+    blocked: boolean;
+}
+/** Review-window signal used to route verify -> done. */
+export interface ReconcilerReviewState {
+    /** Whether the focus currently has review_requested_at set. */
+    reviewRequested: boolean;
+    /** Whether an explicit focus_reviews report exists for the review session. */
+    reportExists: boolean;
+    /** The exiting session's type. */
+    sessionType: 'coding' | 'review';
+    /** Whether that session exited successfully. */
+    succeeded: boolean;
+    /**
+     * The review's stamped VERDICT, when a focus_reviews report exists
+     * ('approved' | 'gaps_found'); null/absent when no report was stamped (a
+     * clean-session exit). A 'gaps_found' verdict can NEVER converge a verify
+     * delivery to done -- the control loop only moves reality toward intent, so an
+     * unresolved finding routes to verify_failed. When gaps_found is accompanied
+     * by blocking open work the hasBlockingOpenWork branch already routes; reaching
+     * the verdict check with gaps_found and no blocking work is a routing
+     * inconsistency (the review found gaps but filed no actionable issue) that
+     * still routes to verify_failed -- the escalation is filed by the handler, not
+     * here (this module is pure). Absent => today's behavior exactly.
+     */
+    outcome?: 'approved' | 'gaps_found' | null;
+    /**
+     * Whether the review session produced EVIDENCE OF INSPECTION -- at least one
+     * tool invocation (read the diff, filed an issue, stamped a report). This is
+     * the discriminator between "a review ran and found nothing" and "a session
+     * that inspected nothing at all". It gates ONLY the clean-session auto-approve
+     * (no report): `false` means the session did no review work, so the clean
+     * exit is a BLIND gate, not a passing review, and routes to the bounded
+     * verify_failed re-work instead of converging to done. `true` or `undefined`
+     * preserve the pre-inspection auto-approve behaviour -- production always
+     * passes an explicit boolean (from the team's tool-activity count), so the
+     * gate is fully enforced in the real path; `undefined` only occurs in callers
+     * that predate the signal (their tests assert the legacy behaviour). An
+     * explicit report (reportExists) is inspection by definition and is never
+     * gated by this field.
+     */
+    inspected?: boolean;
+}
+export interface ReconcileInput {
+    currentStatus: ExecutionStatus;
+    issues: ReadonlyArray<ReconcilerIssue>;
+    gitState: ReconcilerGitState;
+    guardVerdict?: ReconcilerGuardVerdict | null;
+    reviewState?: ReconcilerReviewState | null;
+    /**
+     * Whether the delivery is DISCOVERY-ONLY: it belongs to a read_only
+     * (audit-playbook) focus and its contract is to produce Context Group
+     * findings + a remediation delivery, never Task/Bug issues. Derived from
+     * `focus.read_only` at the call site (the sole explicit, non-heuristic marker
+     * of an audit/discovery flow).
+     *
+     * A discovery-only delivery is EXEMPT from the Task/Bug scoping gate: with no
+     * work issues it advances toward a terminal state instead of wedging in queued
+     * (the spawn-loop wedge). queued->done is not a canonical single edge, so the
+     * terminal is reached by the normal canonical walk queued->coding->verify->done,
+     * one step per reconcile. Absent/false => today's behavior exactly (the scoping
+     * gate holds a no-work delivery in queued).
+     */
+    discoveryOnly?: boolean;
+}
+export interface ReconcileResult {
+    /** The execution_status the daemon should write (equal to currentStatus when no change). */
+    target: ExecutionStatus;
+    /** Whether target differs from currentStatus. */
+    changed: boolean;
+    /** Human-readable rationale (for shadow divergence logs + debugging). */
+    reason: string;
+    /**
+     * Whether (currentStatus -> target) is present in the canonical
+     * EXECUTION_STATUS_TRANSITIONS map. Always true for a no-op (stay). False
+     * flags a live-vs-canonical gap (notably coding -> queued); see the module
+     * header.
+     */
+    canonical: boolean;
+}
+/**
+ * THE shared "issues are done" predicate. A delivery's work is done when none
+ * of its work issues (Tasks/Bugs, excluding Context Groups) are in an OPEN
+ * status. OPEN = {To Do, In Progress, Blocked}; 'In Review' and 'Verified' are
+ * terminal here -- this is the daemon predicate, deliberately chosen as the
+ * single source of truth over the Postgres auto_close predicate (which requires
+ * every issue to be literally 'Done'). A delivery with zero work issues is
+ * vacuously done.
+ *
+ * This is the ONE open-work predicate every delivery writer consumes. It is
+ * built on the shared OPEN_ISSUE_STATUSES set (constants.ts). advanceDeliveryStatuses
+ * previously computed its open count from `!TERMINAL_ISSUE_STATUSES.has` (now
+ * collapsed onto OPEN_ISSUE_STATUSES), and an `ACTIVE_WORK_STATUSES` copy that
+ * duplicated the same set has been deleted -- there is no longer a second
+ * membership definition to drift against.
+ */
+export declare function areDeliveryIssuesDone(issues: ReadonlyArray<ReconcilerIssue>): boolean;
+/** Whether the delivery has at least one work issue (Task/Bug). */
+export declare function hasWorkIssues(issues: ReadonlyArray<ReconcilerIssue>): boolean;
+/**
+ * Whether any work issue is in an OPEN (active) status. This is the routing
+ * signal for verify -> verify_failed (open work on a verify delivery) and the
+ * coding/verify_failed re-queue (open work re-queues). Mirror image of
+ * areDeliveryIssuesDone for deliveries that have work.
+ */
+export declare function hasOpenWork(issues: ReadonlyArray<ReconcilerIssue>): boolean;
+/** Whether any work issue is actively In Progress -- the queued -> coding driver. */
+export declare function hasActiveWork(issues: ReadonlyArray<ReconcilerIssue>): boolean;
+/**
+ * Whether any work issue is BLOCKING open work: open (To Do / In Progress /
+ * Blocked) AND not a deferrable review note. This is the verify -> verify_failed
+ * routing signal: a verify delivery whose only open work is deferrable
+ * low-severity review notes converges (approve) instead of re-coding. With no
+ * issue marked `deferrable` this is identical to hasOpenWork, so every
+ * non-classifying caller keeps its current behavior.
+ */
+export declare function hasBlockingOpenWork(issues: ReadonlyArray<ReconcilerIssue>): boolean;
+export { isAuditPhaseFocus, isDiscoveryOnlyDelivery, type DiscoveryOnlySignal, } from '../audit/audit-shape.js';
+/**
+ * Compute the single next execution_status for a delivery from its full signal.
+ *
+ * Faithful to the current live writers (Delivery 2 characterization):
+ *   - queued  : has work + all done -> coding (step toward verify);
+ *               has work + active   -> coding (work started);
+ *               otherwise            -> stay (scoping gate / not started).
+ *   - coding  : open work           -> queued (re-queue);
+ *               no work issues (non-discovery) -> queued (empty-delivery scoping
+ *                                    gate: never advance an issue-less delivery to
+ *                                    verify on the vacuous all-done truth);
+ *               all done + uncommitted worktree -> stay coding (git-safety gate);
+ *               all done + committed + guard blocked -> paused;
+ *               all done + committed -> verify.
+ *   - verify  : blocking open work   -> verify_failed (deferrable low-severity
+ *                                       review notes do NOT block -> converge);
+ *               guard blocked        -> paused;
+ *               verdict gaps_found   -> verify_failed (never converge on an
+ *                                       unresolved verdict);
+ *               report exists        -> done;
+ *               clean review session -> done (auto-approve);
+ *               otherwise            -> stay verify (awaiting review outcome).
+ *   - verify_failed : open work      -> queued (re-queue);
+ *                     all done       -> coding (re-iterate).
+ *   - draft/planning/paused/done/cancelled : stay (out of reconciler scope;
+ *               paused is cleared by a human re-queue, terminal states are final).
+ */
+export declare function reconcileDeliveryStatus(input: ReconcileInput): ReconcileResult;
+//# sourceMappingURL=delivery-reconciler.d.ts.map

package/dist/delivery/delivery-reconciler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-reconciler.d.ts","sourceRoot":"","sources":["../../src/delivery/delivery-reconciler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,eAAe,EAAE,OAAO,CAAC;IACzB,8EAA8E;IAC9E,YAAY,EAAE,OAAO,CAAC;IACtB,kCAAkC;IAClC,WAAW,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACjC,gDAAgD;IAChD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,IAAI,CAAC;IAC3C;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,eAAe,CAAC;IAC/B,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACvC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,YAAY,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC7C,WAAW,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC3C;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,4FAA4F;IAC5F,MAAM,EAAE,eAAe,CAAC;IACxB,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,OAAO,CAIrF;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,OAAO,CAE7E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,OAAO,CAE3E;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,OAAO,CAE7E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,OAAO,CAGnF;AAOD,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAC;AAcjC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAiH9E"}