@descryy/core 0.3.0 → 0.5.0

package/dist/multipr/overlap.d.ts

@@ -1,55 +1,14 @@
-/**
- * §14.3 — where two in-flight changes touch the same thing, and whether that
- * matters.
- *
- * ## A shared node alone is not a conflict
- *
- * §14.3 says this outright and it is the whole design. At real team scale many
- * pull requests incidentally touch the same low-importance code — a shared
- * logging helper, a barrel file, a constants module. A tool that reports every
- * shared node reports mostly noise, and a developer who has dismissed six
- * incidental overlaps will dismiss the seventh without reading it.
- *
- * So severity is a product of *what* is shared, not *that* something is:
- *
- *     score(node) = impact × NODE_TYPE_WEIGHT[type]
- *
- * A shared `API_ENDPOINT` is two changes to one contract. A shared `FUNCTION`
- * in a utility module is two people editing a file. The weights are the only
- * thing separating them and they are tuning values, labelled as such.
- *
- * ## Resolution is carried per node, and that is §14.2's one addition
- *
- * §14.2 adds `Resolution` to the persisted row with a reason: *so overlap
- * severity is not computed across incomparable evidence*. If one change's node
- * was resolved by a type checker and the other's by syntax alone, an overlap
- * asserted at the stronger level claims more than half of its own evidence
- * supports.
- *
- * The rule follows DEC-058 exactly — a claim carries the resolution of ITS OWN
- * evidence, not of the run that produced it. Here the claim rests on two
- * observations, so it carries **the weaker of the two**, and the finding's
- * reliability class follows from that rather than from either side alone.
- *
- * ## What this deliberately does not do
- *
- * §14.4's mechanical-versus-semantic classification needs the actual diff lines
- * at the shared node, which this module never sees. It reports the overlap and
- * stops; classifying it — and the auto-apply path that is the single documented
- * exception to approval-before-code-change — belongs where the diff is.
- * Guessing "mechanical" without reading the lines would be the one place in
- * this system where a wrong guess edits somebody's branch.
- */
+/** §14.3 — whether two in-flight changes touching the same node is a real
+ *  conflict: score = impact × NODE_TYPE_WEIGHT[type] (tuning values), so a
+ *  shared node alone isn't one. §14.2 carries resolution per node; a claim
+ *  uses the weaker of the two (DEC-058). Does NOT classify mechanical vs
+ *  semantic (§14.4) — needs diff lines this module never sees. */
 import type { NodeType, ResolutionLevel } from "@descryy/ir";
 import type { ReliabilityClass } from "@descryy/ir";
 /** How a change touched a node. §14.2's `DiffType`. */
 export type DiffType = "added" | "modified" | "deleted";
-/**
- * One row of a change's scoped subgraph — §14.2's shape, without persistence.
- *
- * Defined here rather than in a store module so overlap can be computed and
- * tested with no database, the same reason `AdjacencyProvider` exists.
- */
+/** One row of a change's scoped subgraph — §14.2's shape, without
+ *  persistence, so overlap can be computed/tested with no database. */
 export interface PrScopeEntry {
     readonly nodeId: string;
     readonly nodeType: NodeType;
@@ -73,15 +32,8 @@ export interface PrScope {
     readonly computedAt: number;
     /** The head commit of the change itself. Identifies it; never compares it. */
     readonly headSha: string;
-    /**
-     * The commit **the graph** was at when this scope was computed.
-     *
-     * Not the same as `headSha`, and the distinction is load-bearing: two scopes
-     * are comparable only when this agrees. A single `baseSha` field stood here
-     * first, described as "the base commit it was computed against", which is
-     * ambiguous between the two and would have let a comparison key on the wrong
-     * one. §14.2's column comment is what caught it.
-     */
+    /** Commit the graph was at when computed — not `headSha`; two scopes are
+     *  comparable only when this agrees (§14.2). */
     readonly graphCommitSha: string;
 }
 /** One node two changes both touch. */
@@ -133,40 +85,14 @@ export interface OverlapReport {
         /** Pairs refused before comparison — see `incomparable`. */
         readonly incomparable: number;
     };
-    /**
-     * Pairs that could not be compared at all.
-     *
-     * **An incomparable pair and a non-conflicting pair produce the same empty
-     * overlap**, so they are separated here rather than left to be inferred from
-     * a count that does not distinguish them.
-     */
+    /** Pairs that could not be compared at all — kept separate from
+     *  non-conflicting pairs, which produce the same empty overlap. */
     readonly incomparable: readonly IncomparablePair[];
     readonly notes: readonly string[];
 }
-/**
- * §14.3's `NodeTypeWeight`. **Tuning values, and labelled as such.**
- *
- * The architecture gives the shape and one worked contrast — a shared utility
- * function scores low, a shared API contract scores high — and fixes no
- * numbers. These are a defensible starting point and are expected to move once
- * there is data. The ordering is the part that is argued:
- *
- * - **Contract surfaces highest.** `API_ENDPOINT` and `API_ROUTE` are the join
- *   between two services; two changes to one is the case where a merge compiles
- *   and the system breaks.
- * - **Schema next.** A `DATABASE_TABLE` or `DATABASE_COLUMN` touched twice is
- *   two migrations against one object, which §14.6 checks separately and which
- *   fails at merge rather than at review.
- * - **Types above callables.** Two changes to a `DTO` or `MODEL` shape reach
- *   every consumer; two changes to one `FUNCTION` reach its callers.
- * - **`FILE` lowest of the real types.** File-level overlap is what every naive
- *   tool already reports and it is the noise this weighting exists to suppress.
- *
- * Exhaustive over the frozen vocabulary on purpose: `Record<NodeType, number>`
- * means adding a node type is a compile error here rather than a silent zero,
- * and a silent zero would make the new type invisible to conflict detection
- * without any test failing.
- */
+/** §14.3's `NodeTypeWeight` — tuning values. Ordering: contract > schema >
+ *  types (DTO/MODEL) > callables > `FILE`. `Record<NodeType,...>` is
+ *  exhaustive, so a new node type is a compile error, not a silent zero. */
 export declare const NODE_TYPE_WEIGHTS: Readonly<Record<NodeType, number>>;
 /** Default score below which a shared node is incidental rather than a conflict. */
 export declare const DEFAULT_CONFLICT_THRESHOLD = 0.3;
@@ -176,11 +102,7 @@ export interface OverlapOptions {
     /** Cap on findings, per rule 5. Truncation is reported. */
     readonly limit?: number;
 }
-/**
- * Overlaps between every pair of in-flight changes.
- *
- * Pure over scopes, so it needs no store and no graph. §14.2's persistence is a
- * layer above this, not a prerequisite for it.
- */
+/** Overlaps between every pair of in-flight changes. Pure over scopes — no
+ *  store, no graph; §14.2's persistence sits above this, not before it. */
 export declare function findOverlaps(scopes: readonly PrScope[], options?: OverlapOptions): OverlapReport;
 //# sourceMappingURL=overlap.d.ts.map

package/dist/multipr/overlap.d.ts.map

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

package/dist/multipr/overlap.js

@@ -1,70 +1,12 @@
-/**
- * §14.3 — where two in-flight changes touch the same thing, and whether that
- * matters.
- *
- * ## A shared node alone is not a conflict
- *
- * §14.3 says this outright and it is the whole design. At real team scale many
- * pull requests incidentally touch the same low-importance code — a shared
- * logging helper, a barrel file, a constants module. A tool that reports every
- * shared node reports mostly noise, and a developer who has dismissed six
- * incidental overlaps will dismiss the seventh without reading it.
- *
- * So severity is a product of *what* is shared, not *that* something is:
- *
- *     score(node) = impact × NODE_TYPE_WEIGHT[type]
- *
- * A shared `API_ENDPOINT` is two changes to one contract. A shared `FUNCTION`
- * in a utility module is two people editing a file. The weights are the only
- * thing separating them and they are tuning values, labelled as such.
- *
- * ## Resolution is carried per node, and that is §14.2's one addition
- *
- * §14.2 adds `Resolution` to the persisted row with a reason: *so overlap
- * severity is not computed across incomparable evidence*. If one change's node
- * was resolved by a type checker and the other's by syntax alone, an overlap
- * asserted at the stronger level claims more than half of its own evidence
- * supports.
- *
- * The rule follows DEC-058 exactly — a claim carries the resolution of ITS OWN
- * evidence, not of the run that produced it. Here the claim rests on two
- * observations, so it carries **the weaker of the two**, and the finding's
- * reliability class follows from that rather than from either side alone.
- *
- * ## What this deliberately does not do
- *
- * §14.4's mechanical-versus-semantic classification needs the actual diff lines
- * at the shared node, which this module never sees. It reports the overlap and
- * stops; classifying it — and the auto-apply path that is the single documented
- * exception to approval-before-code-change — belongs where the diff is.
- * Guessing "mechanical" without reading the lines would be the one place in
- * this system where a wrong guess edits somebody's branch.
- */
+/** §14.3 — whether two in-flight changes touching the same node is a real
+ *  conflict: score = impact × NODE_TYPE_WEIGHT[type] (tuning values), so a
+ *  shared node alone isn't one. §14.2 carries resolution per node; a claim
+ *  uses the weaker of the two (DEC-058). Does NOT classify mechanical vs
+ *  semantic (§14.4) — needs diff lines this module never sees. */
 import { reliabilityCap, reliabilityNote } from "@descryy/ir";
-/**
- * §14.3's `NodeTypeWeight`. **Tuning values, and labelled as such.**
- *
- * The architecture gives the shape and one worked contrast — a shared utility
- * function scores low, a shared API contract scores high — and fixes no
- * numbers. These are a defensible starting point and are expected to move once
- * there is data. The ordering is the part that is argued:
- *
- * - **Contract surfaces highest.** `API_ENDPOINT` and `API_ROUTE` are the join
- *   between two services; two changes to one is the case where a merge compiles
- *   and the system breaks.
- * - **Schema next.** A `DATABASE_TABLE` or `DATABASE_COLUMN` touched twice is
- *   two migrations against one object, which §14.6 checks separately and which
- *   fails at merge rather than at review.
- * - **Types above callables.** Two changes to a `DTO` or `MODEL` shape reach
- *   every consumer; two changes to one `FUNCTION` reach its callers.
- * - **`FILE` lowest of the real types.** File-level overlap is what every naive
- *   tool already reports and it is the noise this weighting exists to suppress.
- *
- * Exhaustive over the frozen vocabulary on purpose: `Record<NodeType, number>`
- * means adding a node type is a compile error here rather than a silent zero,
- * and a silent zero would make the new type invisible to conflict detection
- * without any test failing.
- */
+/** §14.3's `NodeTypeWeight` — tuning values. Ordering: contract > schema >
+ *  types (DTO/MODEL) > callables > `FILE`. `Record<NodeType,...>` is
+ *  exhaustive, so a new node type is a compile error, not a silent zero. */
 export const NODE_TYPE_WEIGHTS = {
     API_ENDPOINT: 1.0,
     API_ROUTE: 1.0,
@@ -79,32 +21,21 @@ export const NODE_TYPE_WEIGHTS = {
     FUNCTION: 0.4,
     TEST_CASE: 0.3,
     FILE: 0.2,
-    // History artefacts. Two changes cannot both "touch" an incident; if these
-    // ever appear in a diff scope something upstream is wrong, and a weight of
-    // zero would hide that rather than surface it.
+    // History artefacts; if these appear in a diff scope something upstream is
+    // wrong — zero weight would hide that rather than surface it.
     INCIDENT: 0.1,
     FIX_PATTERN: 0.1,
 };
 /** Default score below which a shared node is incidental rather than a conflict. */
 export const DEFAULT_CONFLICT_THRESHOLD = 0.3;
-/**
- * The impact a shared node carries is the **higher** of the two.
- *
- * A node peripheral to one change and central to the other is a real conflict:
- * somebody is about to have their central concern edited from underneath them.
- * Taking the minimum would let a large blast radius be discounted by a
- * one-line drive-by touching the same node, which is the case most worth
- * catching.
- */
+/** Impact of a shared node is the **higher** of the two — a node peripheral
+ *  to one change and central to the other is still a real conflict; the
+ *  min would let a drive-by touch discount a large blast radius. */
 function impactOfPair(a, b) {
     return Math.max(a.impactScore, b.impactScore);
 }
-/**
- * Overlaps between every pair of in-flight changes.
- *
- * Pure over scopes, so it needs no store and no graph. §14.2's persistence is a
- * layer above this, not a prerequisite for it.
- */
+/** Overlaps between every pair of in-flight changes. Pure over scopes — no
+ *  store, no graph; §14.2's persistence sits above this, not before it. */
 export function findOverlaps(scopes, options = {}) {
     const threshold = options.threshold ?? DEFAULT_CONFLICT_THRESHOLD;
     const weights = options.weights ?? NODE_TYPE_WEIGHTS;
@@ -121,14 +52,9 @@ export function findOverlaps(scopes, options = {}) {
             pairs += 1;
             const left = byId[i];
             const right = byId[j];
-            // Refused BEFORE any node is compared. §14.2's schema puts the graph
-            // commit in the primary key so two graph states of one PR cannot
-            // overwrite each other, and warns that a reader ignoring it "will happily
-            // overlap a scope from last week with one from today and report a
-            // number". That warning is honoured here rather than in the store,
-            // because a caller constructing scopes by hand never touches a store —
-            // and because an incomparable pair returns the same empty overlap a
-            // genuinely non-conflicting one does.
+            // Refused BEFORE any node is compared: comparing across two graph
+            // states of one PR would silently overlap "last week" with "today".
+            // Checked here, not the store, since hand-built scopes never touch one.
             const reason = left.scope.repo !== right.scope.repo
                 ? "different-repo"
                 : left.scope.graphCommitSha !== right.scope.graphCommitSha
@@ -146,9 +72,8 @@ export function findOverlaps(scopes, options = {}) {
                 if (b === undefined)
                     continue;
                 overlapSize += 1;
-                // DEC-058 at the pair level: the claim rests on two observations, so it
-                // carries the weaker. Asserting at the stronger would claim more than
-                // half its own evidence supports.
+                // DEC-058 at the pair level: claim carries the weaker of the two
+                // observations — the stronger would claim more than its evidence supports.
                 const resolution = Math.min(a.resolution, b.resolution);
                 const resolutionMismatch = a.resolution !== b.resolution;
                 if (resolutionMismatch)
@@ -169,9 +94,8 @@ export function findOverlaps(scopes, options = {}) {
                     score,
                     diffTypes: [a.diffType, b.diffType],
                     resolution,
-                    // An overlap is a claim about which symbols two changes both name —
-                    // a name-level fact, not a claim about shapes. R2 therefore permits
-                    // class A here where a shape claim on the same evidence would not.
+                    // Name-level fact (which symbols both changes touch), not a shape
+                    // claim — R2 permits class A here where a shape claim would not.
                     reliability: reliabilityCap(resolution, true),
                     resolutionMismatch,
                 });
@@ -195,13 +119,9 @@ export function findOverlaps(scopes, options = {}) {
                 b: right.scope.prId,
                 overlapSize,
                 surfaced: shared,
-                // §14.3 writes `OverlapSize × ImpactScore × NodeTypeWeight`. Read
-                // literally that multiplies a pair-level count by two node-level
-                // quantities, which lets one shared trivial node scale with the size of
-                // an unrelated overlap. Summing the per-node scores keeps the same
-                // intent — more shared, and more important, scores higher — and stays
-                // monotonic in both. The divergence is deliberate and recorded rather
-                // than silently "interpreted".
+                // §14.3 literally says OverlapSize × ImpactScore × NodeTypeWeight,
+                // which would let one trivial node scale with an unrelated overlap's
+                // size. Summing per-node scores keeps the same intent; deliberate divergence.
                 conflictScore: shared.reduce((sum, s) => sum + s.score, 0),
                 disclosure,
             });

package/dist/multipr/overlap.js.map

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

package/dist/multipr/scope-store.d.ts

@@ -1,105 +1,40 @@
 /**
- * §14.2 — persisting a change's scoped subgraph, and the one field that makes
- * two of them comparable.
- *
- * ## Why this is stored at all, when everything else derived is thrown away
- *
- * A scope looks derived. It is not, and the reason is easy to get backwards:
- * everything on the derived side regenerates because *the source still produces
- * it*. A PR scope was computed against a graph **at one commit**, and that graph
- * moves. Recomputing it later does not restore it — it answers a different
- * question and returns a plausible answer to it. Dropping it does not lose time,
- * it loses the comparison basis.
- *
- * That is why `pr_scopes` sits in `EARNED_TABLES` beside observed edges and
- * human corrections, and it is the weaker-looking member of that set in one
- * respect and the more dangerous in another: an R4 observation cannot be
- * recomputed at any price, whereas a PR scope can be recomputed **wrongly**.
- *
- * ## `graphCommitSha` is the whole design
- *
- * Two scopes are comparable only when they were computed against the same
- * graph. The schema puts that commit in the primary key so the same PR at two
- * graph states is two rows rather than one silently overwriting the other, and
- * indexes `(repo, graph_commit_sha)` because overlap scoring's only real query
- * is *every scope computed against one graph*.
- *
- * **It is a different commit from the PR's own head**, and this module renamed a
- * field to say so. `overlap.ts` originally carried one `baseSha` described as
- * "the base commit it was computed against", which is ambiguous between the two
- * and would have let a comparison key on the wrong one. The store's column
- * comment is what caught it.
- *
- * ## An incomparable pair and a non-conflicting pair look identical
- *
- * Both produce an empty overlap. The schema comment warns that a reader
- * ignoring `graph_commit_sha` "will happily overlap a scope from last week with
- * one from today and report a number" — so the refusal lives in `findOverlaps`
- * rather than here, where it also protects the caller who never touches a store.
+ * §14.2 — persisting a change's scoped subgraph. Looks derived but isn't: computed against a graph at one commit, and that graph moves — recomputing later answers a different question, so pr_scopes sits in EARNED_TABLES (worse than an R4 observation: it can be recomputed wrongly, not just never).
+ * graphCommitSha (distinct from the PR's head — a prior `baseSha` name was ambiguous) is in the primary key so two graph states are two rows, not an overwrite. An incomparable pair and a non-conflicting pair both produce empty overlap, so that refusal lives in findOverlaps, not here.
  */
 import type { SqlDriver } from "../store/driver/driver.ts";
 import type { PrScope } from "./overlap.ts";
-/**
- * Thrown when a stored scope cannot be turned back into one.
- *
- * A corrupt row is not an empty scope. Returning `[]` here would make a damaged
- * store indistinguishable from a PR that touched nothing, which is the
- * conflation §14.8 exists to refuse one layer up.
- */
+/** Thrown when a stored scope can't be decoded. A corrupt row is not an
+ *  empty scope — returning [] would conflate the two (§14.8 refuses this). */
 export declare class ScopeDecodeError extends Error {
     readonly name = "ScopeDecodeError";
     constructor(message: string, options?: {
         cause?: unknown;
     });
 }
-/**
- * Row access for `pr_scopes`. Thin on purpose, in the style of `reader.ts`:
- * nothing here scores, compares or decides staleness.
- */
+/** Row access for pr_scopes. Thin on purpose (style of reader.ts): nothing
+ *  here scores, compares or decides staleness. */
 export declare class ScopeStore {
     #private;
     constructor(driver: SqlDriver);
-    /**
-     * Write a scope, replacing any row for the same `(repo, prId, graphCommitSha)`.
-     *
-     * Replacement is safe **only** because the graph commit is in the key:
-     * recomputing the same PR against the same graph must produce the same scope,
-     * so the row being replaced is equal to the one replacing it. Recomputing
-     * against a *different* graph writes a new row and leaves the old comparison
-     * basis intact, which is the entire reason the column is in the key.
-     */
+    /** Write a scope, replacing any row for (repo, prId, graphCommitSha).
+     *  Safe only because the graph commit is in the key — a different graph
+     *  writes a new row and leaves the old comparison basis intact. */
     save(scope: PrScope): void;
     saveAll(scopes: readonly PrScope[]): void;
     /** One scope, or `undefined` when no row exists for that exact graph state. */
     load(repo: string, prId: string, graphCommitSha: string): PrScope | undefined;
-    /**
-     * **The query overlap scoring is for**: every scope computed against one
-     * graph, and therefore every scope that can legitimately be compared.
-     *
-     * Ordered by `pr_id` so a report is stable across runs — an unordered read
-     * makes two identical graphs produce two differently-ordered reports and
-     * turns a diff into noise.
-     */
+    /** The query overlap scoring is for: every scope computed against one
+     *  graph. Ordered by pr_id so a report is stable across runs. */
     loadForGraph(repo: string, graphCommitSha: string): PrScope[];
-    /**
-     * Every graph state a PR has a scope for, newest computation first.
-     *
-     * Exposed because "this PR was scoped against three different graphs" is a
-     * fact a caller may need and cannot reconstruct from `load`, which requires
-     * knowing the commit in advance.
-     */
+    /** Every graph state a PR has a scope for, newest first — not reconstructable
+     *  from `load`, which requires knowing the commit in advance. */
     graphStatesFor(repo: string, prId: string): {
         graphCommitSha: string;
         computedAt: number;
     }[];
-    /**
-     * Forget a PR entirely — every graph state it was scoped against.
-     *
-     * The only legitimate deletion: a closed or merged PR is not in flight and
-     * cannot conflict with anything. Deleting a *single* graph state is not
-     * offered, because the row is the comparison basis and there is no caller who
-     * wants exactly one of them gone.
-     */
+    /** Forget a PR entirely — every graph state it was scoped against. The only
+     *  legitimate deletion: a closed/merged PR can't conflict with anything. */
     forget(repo: string, prId: string): number;
 }
 //# sourceMappingURL=scope-store.d.ts.map

package/dist/multipr/scope-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-store.d.ts","sourceRoot":"","sources":["../../src/multipr/scope-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,cAAc,CAAC;AAc1D;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAkB,IAAI,sBAAsB;gBAEhC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAG3D;AAiDD;;;GAGG;AACH,qBAAa,UAAU;;gBAGT,MAAM,EAAE,SAAS;IAI7B;;;;;;;;OAQG;IACH,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAsB1B,OAAO,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAMzC,+EAA+E;IAC/E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAS7E;;;;;;;OAOG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,EAAE;IAS7D;;;;;;OAMG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE;IAU5F;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;CAK3C"}
+{"version":3,"file":"scope-store.d.ts","sourceRoot":"","sources":["../../src/multipr/scope-store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,cAAc,CAAC;AAc1D;8EAC8E;AAC9E,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAkB,IAAI,sBAAsB;gBAEhC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAG3D;AA4CD;kDACkD;AAClD,qBAAa,UAAU;;gBAGT,MAAM,EAAE,SAAS;IAI7B;;uEAEmE;IACnE,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAsB1B,OAAO,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAMzC,+EAA+E;IAC/E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAS7E;qEACiE;IACjE,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,EAAE;IAS7D;qEACiE;IACjE,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE;IAU5F;gFAC4E;IAC5E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;CAK3C"}