@softarc/native-federation-orchestrator 4.5.2 → 4.6.0

package/types/lib/core/1.domain/externals/basis.d.ts

@@ -0,0 +1,22 @@
+import type { SharedVersion, SharedVersionMeta } from './version.contract';
+export declare function isBetterBasis(candidate: SharedVersionMeta, basis: SharedVersionMeta): boolean;
+export declare function addRemoteToVersion(version: SharedVersion, remote: SharedVersionMeta, isHost?: boolean): void;
+export declare function versionDemands(version: SharedVersion): SharedVersionMeta[];
+export declare function findVersionForTag(versions: SharedVersion[], tag: string): SharedVersion | undefined;
+export declare function versionEntries(version: SharedVersion): Map<string, SharedVersionMeta>;
+export declare function committedEntries(version: SharedVersion): Map<string, SharedVersionMeta>;
+/**
+ * The walk both of those keep the first claim of: which copies of a version may publish a specifier, in basis
+ * precedence. Exposed so a caller that models the same fill order without needing the map — the pooling gates
+ * ask which build a consumer lands on, per specifier — reads the `servedBy` rule from here instead of
+ * restating it. It deliberately does not dedup: the callers do, and this way the walk allocates nothing.
+ *
+ * `accepts` is for a caller with a further reason to discount a copy (pooling islands one, so it self-serves).
+ * Filtering the *result* is not the same thing — that drops the specifier instead of letting the next copy
+ * claim it.
+ */
+export declare function forEachVersionEntry(version: SharedVersion, accepts: ((remote: SharedVersionMeta) => boolean) | undefined, visit: (entrypoint: string, remote: SharedVersionMeta) => void): void;
+type Covered = Pick<ReadonlySet<string>, 'has'>;
+export declare function uncoveredEntrypoints(remote: SharedVersionMeta, covered: Covered): string[];
+export declare function countUncoveredEntrypoints(remote: SharedVersionMeta, covered: Covered): number;
+export {};

package/types/lib/core/1.domain/externals/version.contract.d.ts

@@ -21,4 +21,5 @@ export type SharedVersionMeta = {
     bundle?: string;
     pool?: string;
     entries: Record<string, string>;
+    servedBy?: RemoteName;
 };

package/types/lib/core/1.domain/remote-entry/remote-entry.contract.d.ts

@@ -11,5 +11,7 @@ type RemoteEntry = Omit<FederationInfo, 'shared'> & {
 type SharedInfoActions = Record<string, {
     action: SharedVersionAction;
     override?: Record<string, string>;
+    covered?: string[];
+    sameVersion?: boolean;
 }>;
 export { RawRemoteEntry, RemoteEntry, FederationInfo, ExposesInfo, SharedInfo, DenseSharedInfo, SharedInfoActions, };

package/types/lib/core/2.app/config/mode.contract.d.ts

@@ -1,6 +1,7 @@
 export type ModeProfileConfig = {
     latestSharedExternal: boolean;
     skipInvalidExternalVersions: boolean;
+    scopeUncoveredEntrypoints: boolean;
     overrideCachedRemotes: 'always' | 'never' | 'init-only';
     overrideCachedRemotesIfURLMatches: boolean;
     cacheTag?: string;

package/types/lib/core/2.app/driver-ports/init/drivers.contract.d.ts

@@ -1,6 +1,7 @@
 import type { ForCommittingChanges } from './for-committing-changes.port';
 import type { ForDeterminingSharedExternals } from './for-determining-shared-externals.port';
 import type { ForPoolingSharedExternals } from './for-pooling-shared-externals.port';
+import type { ForMarkingPoolsForReelection } from './for-marking-pools-for-reelection.port';
 import type { ForPoolingDynamicExternals } from './for-pooling-dynamic-externals.port';
 import type { ForExposingModuleLoader } from './for-exposing-module-loader.port';
 import type { ForGeneratingImportMap } from './for-generating-import-map';
@@ -14,6 +15,7 @@ import type { DrivingContract } from '../../driving-ports/driving.contract';
 export type InitDriversContract = {
     getRemoteEntries: ForGettingRemoteEntries;
     processRemoteEntries: ForProcessingRemoteEntries;
+    markPoolsForReelection: ForMarkingPoolsForReelection;
     determineSharedExternals: ForDeterminingSharedExternals;
     poolSharedExternals: ForPoolingSharedExternals;
     generateImportMap: ForGeneratingImportMap;

package/types/lib/core/2.app/driver-ports/init/for-determining-shared-externals.port.d.ts

@@ -1 +1,8 @@
-export type ForDeterminingSharedExternals = () => Promise<void>;
+import type { ExternalName } from '../../../1.domain';
+/**
+ * The externals this pass re-elected, per shareScope. Determine clears `dirty` before pooling runs,
+ * so this is the only signal left of what changed; a scope with nothing re-elected is absent rather
+ * than empty.
+ */
+export type TouchedExternals = ReadonlyMap<string, ReadonlySet<ExternalName>>;
+export type ForDeterminingSharedExternals = () => Promise<TouchedExternals>;

package/types/lib/core/2.app/driver-ports/init/for-marking-pools-for-reelection.port.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Marks every member of a pool dirty when any one of them is, so `determine` re-elects the pool as a unit
+ * and pooling never reads a verdict left over from an earlier portfolio. Mutates the stored externals only;
+ * it writes nothing.
+ */
+export type ForMarkingPoolsForReelection = () => Promise<void>;

package/types/lib/core/2.app/driver-ports/init/for-pooling-shared-externals.port.d.ts

@@ -1 +1,3 @@
-export type ForPoolingSharedExternals = () => Promise<void>;
+import type { TouchedExternals } from './for-determining-shared-externals.port';
+/** Omitting `touched` means "no signal": every pool is processed, as before W2. */
+export type ForPoolingSharedExternals = (touched?: TouchedExternals) => Promise<void>;

package/types/lib/core/2.app/driving-ports/for-shared-chunks-storage.port.d.ts

@@ -1,6 +1,7 @@
 import type { Optional } from '../../../utils/optional';
 export type ForSharedChunksStorage = {
     addOrReplace: (remote: string, bundleName: string, chunks: string[]) => ForSharedChunksStorage;
+    remove: (remote: string) => ForSharedChunksStorage;
     commit: () => ForSharedChunksStorage;
     tryGet: (remote: string, bundleName: string) => Optional<string[]>;
 };

package/types/lib/core/2.app/driving-ports/for-shared-externals-storage.port.d.ts

@@ -7,9 +7,8 @@ export type ForSharedExternalsStorage = {
         includeGlobal: boolean;
     }) => string[];
     scopeType: (shareScope?: string) => 'global' | 'strict' | 'shareScope';
-    removeFromAllScopes: (remoteName: RemoteName) => void;
+    removeFromAllScopes: (remoteNames: ReadonlySet<RemoteName>) => void;
     addOrUpdate: (name: string, external: SharedExternal, shareScope?: string) => ForSharedExternalsStorage;
-    markPoolTagPresent: () => void;
-    hasPoolTag: () => boolean;
+    hasPoolTag: (shareScope?: string) => boolean;
     commit: () => ForSharedExternalsStorage;
 };

package/types/lib/core/2.app/steps/apply-winner.d.ts

@@ -0,0 +1,18 @@
+import type { SharedExternal, SharedVersion, SharedVersionMeta } from '../../1.domain';
+import type { LoggingConfig } from '../config/log.contract';
+import type { ModeConfig } from '../config/mode.contract';
+export type IsCompatible = (tag: string, requiredVersion: string) => boolean;
+export type VersionAcceptance = {
+    accepts: (version: SharedVersion, tag: string) => boolean;
+    objector: (version: SharedVersion, tag: string) => SharedVersionMeta | undefined;
+};
+export declare function versionAcceptance(external: SharedExternal, isCompatible: IsCompatible): VersionAcceptance;
+/**
+ * The tail of winner election: derive every other version's verdict from the chosen one, apply the
+ * entrypoint coverage policy, clear `dirty`. `determine` is the only caller, and passes its memoized
+ * `isCompatible` plus the `acceptance` it already built for the election.
+ *
+ * A hazard for anyone who ever adds a second caller that re-points a winner: `findTears` keys off the
+ * winner's merged entries, so moving the winner moves the surface coverage is measured against.
+ */
+export declare function createApplyWinner(config: LoggingConfig & ModeConfig): (externalName: string, external: SharedExternal, winner: SharedVersion, isCompatible: IsCompatible, acceptance?: VersionAcceptance) => SharedExternal;

package/types/lib/core/2.app/steps/pooling/anchoring.d.ts

@@ -0,0 +1,69 @@
+import type { ExternalName, RemoteName, VersionName } from '../../../1.domain';
+import type { BuildView, Coverage, FamilyInstance, PoolMember, Specifier } from './pool.types';
+/**
+ * The gates that choose which build serves a consumer. Everything here reads **coverage** and
+ * `isCompatible`; no function in this file compares two tags for distance, only for identity. The
+ * projections they read are in `pool-views.ts`, the rationale in docs/version-resolver.md §"The
+ * provenance promise".
+ */
+/** `remote -> member -> every tag that remote's own `requiredVersion` accepts.` */
+export type Acceptance = Map<RemoteName, Map<ExternalName, Set<VersionName>>>;
+/** The build serving each remote, or `undefined` where it serves its own family. */
+export type Assignment = Map<RemoteName, RemoteName | undefined>;
+/**
+ * Every tag each remote's own range accepts, per member. Precomputed rather than asked per
+ * consumer/candidate pair, and `isCompatible` is expected to be `determine`'s memoized one — this must
+ * never replicate its O(versions²) search.
+ */
+export declare function acceptanceTable(members: PoolMember[], isCompatible: (tag: VersionName, range: string) => boolean): Acceptance;
+/** Does a build serve a superset of what a consumer imports? */
+export declare function covers(coverage: Coverage, consumed: Iterable<Specifier>): boolean;
+/** Does a build offer every member a consumer needs, at a tag the consumer's own range accepts? */
+export declare function acceptsAll(acceptance: Acceptance, build: FamilyInstance, consumer: RemoteName, consumed: readonly ExternalName[]): boolean;
+/**
+ * Is the combination the global mapping would hand this remote one that some live build shipped?
+ *
+ * All-or-nothing across the family: **every** specifier it imports has to be published at the tag that one
+ * single build ships it at. Taken per specifier instead it reintroduces the defect, a combination nothing
+ * compiled. Why the general form is sound and not just the remote's-own-build case: §"Why the witness is
+ * sound".
+ *
+ * Asked before coverage on both paths, because a witnessed remote needs no anchor at all: asking coverage
+ * first pins remotes already sitting at the shared tags onto one build for no gain.
+ */
+export declare function isWitnessed(specifiers: Iterable<Specifier>, shared: Map<Specifier, VersionName>, builds: Map<RemoteName, BuildView>): boolean;
+export type SelfServeReason = {
+    gap: string;
+    closest?: RemoteName;
+};
+/**
+ * Why no build could serve this remote, in the terms a portfolio owner can act on. Runs only for a remote
+ * that is actually self-serving, so it costs nothing on a healthy portfolio.
+ *
+ * "Closest" is fewest missing entrypoints; a build that misses none failed on versions instead, and the gap
+ * is then the member whose offered tag this remote's own range rejects.
+ */
+export declare function explainSelfServe(remote: RemoteName, wants: readonly ExternalName[], specifiers: Set<Specifier>, pool: {
+    builds: Map<RemoteName, BuildView>;
+    acceptance: Acceptance;
+}): SelfServeReason;
+export type AnchorInput = {
+    builds: Map<RemoteName, BuildView>;
+    acceptance: Acceptance;
+    consumedSpecifiers: Map<RemoteName, Set<Specifier>>;
+    consumedMembers: Map<RemoteName, ExternalName[]>;
+    hosts: Set<RemoteName>;
+    arrival: Map<RemoteName, number>;
+};
+/**
+ * Assign each consumer the build that serves it, or `undefined` where it serves its own family.
+ *
+ * Multi-anchor is mandatory rather than an optimisation (constraint 3): a single anchor per pool scopes
+ * members nothing required to be scoped, and two remotes sharing no member already satisfy the promise.
+ *
+ * Greedy and deterministic, never a search. Tiebreaks in order: host, then most consumers fully covered,
+ * then arrival, then name. A build chosen as an anchor **runs its own build**, so it is never itself
+ * assigned elsewhere — a consumer deduping onto a remote that is itself deduping would inherit that
+ * remote's foreign copies.
+ */
+export declare function assignAnchors(input: AnchorInput): Assignment;

package/types/lib/core/2.app/steps/pooling/mark-pools-for-reelection.d.ts

@@ -0,0 +1,5 @@
+import type { ForMarkingPoolsForReelection } from '../../driver-ports/init/for-marking-pools-for-reelection.port';
+import type { DrivingContract } from '../../driving-ports/driving.contract';
+import type { LoggingConfig } from '../../config/log.contract';
+import type { ModeConfig } from '../../config/mode.contract';
+export declare function createMarkPoolsForReelection(config: LoggingConfig & ModeConfig, ports: Pick<DrivingContract, 'sharedExternalsRepo'>): ForMarkingPoolsForReelection;

package/types/lib/core/2.app/steps/pooling/pool-dynamic-externals.d.ts

@@ -1,3 +1,5 @@
 import type { ForPoolingDynamicExternals } from '../../driver-ports/init/for-pooling-dynamic-externals.port';
 import type { ModeConfig } from '../../config/mode.contract';
-export declare function createPoolDynamicExternals(config: ModeConfig): ForPoolingDynamicExternals;
+import type { LoggingConfig } from '../../config/log.contract';
+import type { DrivingContract } from '../../driving-ports/driving.contract';
+export declare function createPoolDynamicExternals(config: LoggingConfig & ModeConfig, ports: Pick<DrivingContract, 'sharedExternalsRepo' | 'remoteInfoRepo' | 'versionCheck'>): ForPoolingDynamicExternals;

package/types/lib/core/2.app/steps/pooling/pool-graph.d.ts

@@ -9,16 +9,21 @@ export type PoolCandidate<T> = {
     name: ExternalName;
     scope?: string;
     tags: readonly PoolEdge[];
+    remotes: readonly string[];
     value: T;
 };
 export declare function autoScope(name: string, useAutoExternalPooling: boolean): string | undefined;
+export declare function owningPackage(name: ExternalName): ExternalName | undefined;
 /**
  * Group one shareScope's candidates into pools by shared membership: pool = connected component of a
- * graph with edges from auto-pooling (`external -> scope`, global) and declared tags
- * (`external -> tag@remote`, remote-local). See docs/version-resolver.md + plan.md. Returns only real
- * pools (>=2 members), keyed by and iterated in order of their canonical name (smallest member —
- * reload-stable). An explicit-tag member that pooled with nothing is warned (likely typo or missing
- * sibling); auto-scope singletons stay silent.
+ * graph whose edges are all remote-local — `external -> scope@remote` for each remote that declares
+ * it (auto-pooling) and `external -> tag@remote` for each declared tag — plus an unconditional
+ * `entrypoint -> package` edge. A pool therefore forms exactly when some remote declares members
+ * from both sides. See docs/version-resolver.md.
+ *
+ * Returns only real pools (>=2 members), keyed by and iterated in order of their canonical name
+ * (smallest member — reload-stable). An explicit-tag member that pooled with nothing is warned
+ * (likely typo or missing sibling); auto-scope singletons stay silent.
  */
 export declare function groupByMembership<T>(candidates: readonly PoolCandidate<T>[], log?: LogHandler): Map<PoolName, T[]>;
 /** Init-path grouping: build candidates from the stored shared externals of one shareScope. */

package/types/lib/core/2.app/steps/pooling/pool-shared-externals.d.ts

@@ -1,5 +1,34 @@
 import type { ForPoolingSharedExternals } from '../../driver-ports/init/for-pooling-shared-externals.port';
+import type { ExternalName, RemoteName } from '../../../1.domain';
 import type { DrivingContract } from '../../driving-ports/driving.contract';
 import type { LoggingConfig } from '../../config/log.contract';
 import type { ModeConfig } from '../../config/mode.contract';
-export declare function createPoolSharedExternals(config: LoggingConfig & ModeConfig, ports: Pick<DrivingContract, 'sharedExternalsRepo'>): ForPoolingSharedExternals;
+import type { Islanded, PoolMember } from './pool.types';
+/**
+ * Per remote, the members it must be served from a build other than that member's own basis — an anchor's,
+ * or its own where it is an anchor for somebody else. Absent means the default: the copy resolves through
+ * the global mapping, which is right whenever the shared tag is already the remote's own.
+ */
+type Served = Map<RemoteName, Map<ExternalName, RemoteName>>;
+/**
+ * The no-tear guarantee, checked on what is about to be written rather than argued from the gates: every
+ * non-host remote must resolve a `(specifier → tag)` combination that some single build shipped. Which remote
+ * serves a tag is free — two builds at one tag are interchangeable providers — so this compares tags only,
+ * never origins. A host is never judged: it cannot be repointed onto another build.
+ *
+ * Keyed by specifier like everything else in the design, not by member: a specifier no copy of the winning
+ * version bundles is published from a `skip` copy at that version's tag (`selfFillUncovered`), so a
+ * member-level check reads one tag for a package the remote really resolves at two. Copies of the winning
+ * tag merging their entrypoints (`mergeVersionEntries`) never do this — one tag, nothing to tear.
+ *
+ * No portfolio is known to reach a tear through `poolFamily` — the gates leave it true — and it is checked
+ * regardless, because it is the one thing pooling exists to prevent and because `rebuildMember`'s last rule
+ * (a copy whose member lost its basis self-serves) is decided after gate 2 has stopped looking. Exported so
+ * `find-torn-remotes.spec.ts` can pin the contract on hand-built input, the only way to reach it.
+ */
+export declare function findTornRemotes(members: PoolMember[], islanded: Islanded, basis: Map<ExternalName, RemoteName>, served: Served, hosts: ReadonlySet<RemoteName>): {
+    remote: RemoteName;
+    combination: string;
+}[];
+export declare function createPoolSharedExternals(config: LoggingConfig & ModeConfig, ports: Pick<DrivingContract, 'sharedExternalsRepo' | 'versionCheck'>): ForPoolingSharedExternals;
+export {};

package/types/lib/core/2.app/steps/pooling/pool-views.d.ts

@@ -0,0 +1,63 @@
+import type { ExternalName, RemoteName, VersionName } from '../../../1.domain';
+import type { BuildView, CommittedView, Islanded, OwnCopy, PoolMember, Specifier } from './pool.types';
+/**
+ * Per build: the specifiers it serves and from which file, the tag each is served at, and the
+ * `(member → tag)` instance it runs. Built once per pool and reused across consumers, so a coverage question
+ * is a subset test rather than a walk of `entries`.
+ *
+ * A `scope` copy is excluded — it is about to self-serve, so it serves nobody else.
+ */
+export declare function liveBuilds(members: PoolMember[], islanded?: Islanded): Map<RemoteName, BuildView>;
+/**
+ * The same walk over the *committed* record, where a `scope` copy is a **stable island** rather than a
+ * remote about to self-serve: its files are already in the map under its own scope and it demonstrably runs
+ * its own build, so it can serve a remote loaded later.
+ */
+export declare function committedView(members: PoolMember[]): CommittedView;
+/**
+ * Per remote, every copy it holds — **including** ones marked `scope`, which is what separates this from
+ * `liveBuilds`. That one answers "what can this build serve others"; this one answers "what does this remote
+ * run itself", where a `scope` copy is precisely what it runs. Only the second question can see a torn
+ * family.
+ */
+export declare function ownCopies(members: PoolMember[], only?: ReadonlySet<RemoteName>): Map<RemoteName, OwnCopy[]>;
+export declare function consumedMembers(members: PoolMember[]): Map<RemoteName, ExternalName[]>;
+/** `consumedMembers` in specifier space. */
+export declare function consumedSpecifiers(members: PoolMember[]): Map<RemoteName, Set<Specifier>>;
+/**
+ * Does one build serve every specifier the pool's live copies consume? The cheap form of
+ * `consumedSpecifiers` against one `liveBuilds` entry, for the only question the healthy path asks.
+ *
+ * Keyed by specifier, because being the basis of every *member* is not the same thing: an entrypoint the
+ * basis does not carry is served from the declaring remote's own build, at that remote's own tag (see
+ * §"Entrypoint coverage and tearing"), which is a torn package and not something a member-level test can
+ * see.
+ */
+export declare function coversWholePool(members: PoolMember[], build: RemoteName, islanded: Islanded): boolean;
+/**
+ * The build serving each member, i.e. `remotes[0]` of its shared version — skipping copies islanding has
+ * taken, since those are about to self-serve. A member with no entry is served by nobody and every
+ * consumer falls back to its own build.
+ */
+export declare function servingBuilds(members: PoolMember[], islanded: Islanded): Map<ExternalName, RemoteName>;
+/**
+ * The copy whose file the global mapping publishes, per member: the first copy of the member's `share`
+ * version that still runs its own build. A remote deduping onto a foreign build is skipped, because
+ * publishing its file while it runs somebody else's makes the global mapping and `servedBy` name two
+ * different builds for one remote (constraint 17). Order is otherwise the basis precedence `commit()`
+ * established, so skipping never promotes a worse-covered copy over a better one. A member with no entry has
+ * no basis left and leaves the shared set.
+ */
+export declare function basisPerMember(members: PoolMember[], islanded?: Islanded, dedupsElsewhere?: (remote: RemoteName) => boolean): Map<ExternalName, RemoteName>;
+/**
+ * The host, when it ships anything in this pool. A host-contributed version carries `host: true` and
+ * basis precedence puts the host's own copy first on it, so `remotes[0]` of such a version is the host.
+ */
+export declare function hostRemotes(members: PoolMember[]): Set<RemoteName>;
+/** First appearance of each remote across the pool — the arrival order anchor tiebreaks read. */
+export declare function arrivalOrder(members: PoolMember[]): Map<RemoteName, number>;
+/**
+ * The tag the global `imports` publishes per specifier. Reading the winning version's basis alone
+ * understates it, which islands remotes that were never at risk.
+ */
+export declare function sharedTagPerSpecifier(members: PoolMember[], islanded: Islanded): Map<Specifier, VersionName>;

package/types/lib/core/2.app/steps/pooling/pool.types.d.ts

@@ -1,6 +1,35 @@
-import type { ExternalName, SharedExternal } from '../../../1.domain';
+import type { ExternalName, RemoteName, SharedExternal, VersionName } from '../../../1.domain';
 export type PoolName = string;
+/** An entrypoint as a consumer imports it. Nothing is keyed by external name — see `pool-views.ts`. */
+export type Specifier = string;
 export type PoolMember = {
     name: ExternalName;
     external: SharedExternal;
 };
+export type FamilyInstance = Map<ExternalName, VersionName>;
+/** Every specifier a build serves, mapped to the file it serves it from. */
+export type Coverage = Map<Specifier, string>;
+/** One copy a remote holds, as it runs it itself: `scope` rows included. */
+export type OwnCopy = {
+    member: ExternalName;
+    tag: VersionName;
+    entries: Record<Specifier, string>;
+};
+/** One build, as every gate reads it. */
+export type BuildView = {
+    coverage: Coverage;
+    tags: Map<Specifier, VersionName>;
+    instance: FamilyInstance;
+};
+export type CommittedView = {
+    builds: Map<RemoteName, BuildView>;
+    /** Per specifier, what the committed `imports` serves and from where. */
+    global: Map<Specifier, {
+        tag: VersionName;
+        remote: RemoteName;
+        file: string;
+    }>;
+};
+export type Islanded = {
+    has: (remote: RemoteName) => boolean;
+};

package/types/lib/core/2.app/steps/pooling/pool.util.d.ts

@@ -1,3 +1,18 @@
 import type { RemoteName } from '../../../1.domain';
+import type { ForSharedExternalsStorage } from '../../driving-ports/for-shared-externals-storage.port';
+import type { ModeConfig } from '../../config/mode.contract';
 import type { PoolMember } from './pool.types';
+export declare function lazy<T>(make: () => T): () => T;
 export declare function remotesInPool(members: PoolMember[]): RemoteName[];
+/**
+ * The scopes either pooling step has anything to do in. With auto-pooling off only a scope that carries a
+ * `pool` tag of its own can pool anything, and a pool never spans share scopes — so one tag must not put
+ * every other scope through a graph build. Auto-pooling on must never early-out, since any scoped package is
+ * potentially poolable. The `strict` scope is never pooled.
+ *
+ * Names only, so a caller that decides to skip a scope never reads it out of storage.
+ */
+export declare function poolableScopes(config: ModeConfig, repo: Pick<ForSharedExternalsStorage, 'getScopes' | 'scopeType' | 'hasPoolTag'>): {
+    useAutoExternalPooling: boolean;
+    scopes: string[];
+};

package/types/lib/core/2.app/steps/store-remote-entry.d.ts

@@ -1,8 +1,15 @@
-import { type RemoteEntry, type SharedExternal, type DenseSharedInfo, type SharedVersion, type SharedVersionMeta } from '../../1.domain';
+import { type RemoteEntry, type RemoteName, type SharedExternal, type DenseSharedInfo, type SharedVersion, type SharedVersionMeta } from '../../1.domain';
 import type { DrivingContract } from '../driving-ports/driving.contract';
 import type { LoggingConfig } from '../config/log.contract';
 import type { ModeConfig } from '../config/mode.contract';
 export type StoreRemoteEntry = (remoteEntry: RemoteEntry, onSharedExternal: SharedExternalHandler) => void;
+export type RemoveCachedRemoteEntries = (remoteNames: ReadonlySet<RemoteName>) => void;
+/**
+ * Evict overridden remotes before their replacements are merged in. Kept out of `storeRemoteEntry`
+ * because `removeFromAllScopes` costs a full traversal of the shared-externals graph: the init
+ * pipeline evicts its whole override set at once, the dynamic pipeline passes a single name.
+ */
+export declare function createRemoveCachedRemoteEntries(ports: Pick<DrivingContract, 'remoteInfoRepo' | 'scopedExternalsRepo' | 'sharedExternalsRepo' | 'sharedChunksRepo'>): RemoveCachedRemoteEntries;
 export type SharedExternalHandler = (remoteEntry: RemoteEntry, external: DenseSharedInfo, ctx: SharedExternalContext) => void;
 export type SharedExternalContext = {
     tag: string;
@@ -13,11 +20,12 @@ export type SharedExternalContext = {
     commit: () => void;
 };
 /**
- * Not a pipeline step but the template both storage steps specialize: it owns the full
- * storage sequence for a remoteEntry, and only the resolution of a singleton external
- * differs between the init pipeline (process-remote-entries, step 2) and the dynamic
- * pipeline (update-cache, step 8), injected per call. The pipelines must not be merged,
- * see docs/version-resolver.md "Dynamic Init". If a change ever needs a flag or
- * parameter here to serve only one caller, inline this back into the steps instead.
+ * Not a pipeline step but the template both storage steps specialize: it owns the merge sequence
+ * for a remoteEntry, and only the resolution of a singleton external differs between the init
+ * pipeline (process-remote-entries, step 2) and the dynamic pipeline (update-cache, step 8),
+ * injected per call. Evicting an overridden remote is the caller's job, see
+ * `createRemoveCachedRemoteEntries` — every entry reaching here is merged additively. The
+ * pipelines must not be merged, see docs/version-resolver.md "Dynamic Init". If a change ever
+ * needs a flag or parameter here to serve only one caller, inline this back into the steps instead.
  */
 export declare function createStoreRemoteEntry(config: LoggingConfig & ModeConfig, ports: Pick<DrivingContract, 'remoteInfoRepo' | 'scopedExternalsRepo' | 'sharedExternalsRepo' | 'sharedChunksRepo' | 'versionCheck'>, logStep: number): StoreRemoteEntry;

package/types/lib/testing/pooling/no-tear.d.ts

@@ -0,0 +1,37 @@
+import type { ExternalName, ImportMap, RemoteName, SharedExternal, VersionName } from '../../core/1.domain';
+type Specifier = string;
+/** Per remote, the `(specifier → tag)` set its own build ships — the witness candidates. */
+export type Builds = Map<RemoteName, Map<Specifier, VersionName>>;
+export type Incoherence = {
+    remote: RemoteName;
+    /** What the map resolves for it, per specifier of the pool. */
+    resolved: Record<Specifier, VersionName>;
+    /** The build that came closest to witnessing it, for a legible failure message. */
+    closest?: {
+        build: RemoteName;
+        matched: number;
+        of: number;
+    };
+};
+export type CoherenceInput = {
+    importMap: ImportMap;
+    /** The pool's members as stored — what `sharedExternalsRepo.getFromScope` returns, filtered to the pool. */
+    members: Record<ExternalName, SharedExternal>;
+    scopeUrls: Record<RemoteName, string>;
+    /** I3's only exemption: a host cannot be repointed onto another build, so it is never judged. */
+    hosts?: RemoteName[];
+};
+/**
+ * I3, the no-tear invariant, checked off the emitted import map rather than off the stored verdicts:
+ * for every non-host remote, the `(specifier → tag)` combination it really resolves must be a subset of
+ * some live build's own combination. Which remote *serves* a given tag is free — two builds at one tag
+ * are interchangeable providers — so this compares tags only, never origins.
+ *
+ * Reads the map the way a browser would (a remote's own scope entry wins over `imports`), so it fails on
+ * exactly the combinations a page would really run. Deliberately not called `findTears`:
+ * `apply-winner.ts:110` owns that name for entrypoint coverage, which is a different failure.
+ */
+export declare function findIncoherentRemotes({ importMap, members, scopeUrls, hosts, }: CoherenceInput): Incoherence[];
+/** Every file the map can make a browser fetch — the static stand-in for the e2e download count. */
+export declare function emittedUrls(importMap: ImportMap): Set<string>;
+export {};