@microwiseai/snapshot 0.8.0 → 0.9.0

package/dist/lib/grant.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Snapshot grant (istsg_) installer support — Plan A (grant-unify P1).
+ *
+ * Every install can obtain ONE short-lived `istsg_` grant from license-api
+ * (`POST /api/snapshot-grant`) that authorizes the snapshot's frozen closure at
+ * the registry-proxy. The grant token becomes the single proxy transport token
+ * (IST_SESSION_TOKEN) for the snapshot fetch, the npm batch, skit kit npm deps
+ * and converge. The closure `members[]` is used as the ALLOWED set only — the
+ * installer still installs the manifest top-level packages (no global install of
+ * transitive members).
+ *
+ * Gate: env SNAPSHOT_GRANT_MODE
+ *   off (default / unset) — no grant code runs; install is byte-identical to the
+ *                           legacy path (authorizeSession / anonymous npmrc).
+ *   prefer                — request a grant; on any grant failure warn and run the
+ *                           WHOLE install on the legacy path (no path mixing).
+ *   require               — request a grant; any grant failure is fail-loud.
+ *
+ * Secrets: the grant token is never logged or put in an error message. Logs use
+ * maskToken() (first 4 chars + …, same rule as maskSessionId).
+ */
+export type GrantMode = 'off' | 'prefer' | 'require';
+export declare const GRANT_MODE_ENV = "SNAPSHOT_GRANT_MODE";
+export declare const GRANT_TIMEOUT_ENV = "SNAPSHOT_GRANT_TIMEOUT_MS";
+export declare const DEFAULT_GRANT_TIMEOUT_MS = 15000;
+/**
+ * Resolve the grant mode from the environment. Unset / empty / 'off' → 'off'.
+ * An unknown value is reported via `warn` and treated as 'off' (never silently
+ * enables a new path).
+ */
+export declare function readGrantMode(env?: NodeJS.ProcessEnv, warn?: (msg: string) => void): GrantMode;
+export declare function readGrantTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/** Mask a secret for logs: first 4 chars + '…' (same rule as maskSessionId). */
+export declare function maskToken(token: string | undefined | null): string;
+export interface GrantMember {
+    /** npm-canonical name ('@scope/name'); generic members use '@scope/name' too. */
+    name: string;
+    version: string;
+    /** Present when license-api builds the closure from access-index.json. */
+    kind?: 'npm' | 'generic';
+}
+export interface SnapshotGrant {
+    token: string;
+    members: GrantMember[];
+    closureHash: string;
+    /** Grant TTL in seconds. */
+    expiresIn: number;
+}
+export type GrantErrorCode = 'unauthorized' | 'not-found' | 'closure-resolve' | 'timeout' | 'network' | 'invalid-response' | 'http' | 'closure-changed' | 'version-mismatch' | 'version-resolve';
+export declare class GrantError extends Error {
+    readonly code: GrantErrorCode;
+    readonly status?: number | undefined;
+    constructor(code: GrantErrorCode, message: string, status?: number | undefined);
+}
+export interface GrantRequest {
+    /** Snapshot name, e.g. '@ist/beta' (no version). */
+    snapshot: string;
+    /** Exact version or 'latest'. */
+    version: string;
+    /** Optional IST JWT — sent as Bearer to license-api only. */
+    authToken?: string | null;
+}
+export interface GrantRequestDeps {
+    /** license-api base incl. '/api', e.g. https://license-api…/api */
+    licenseApiUrl: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * POST {licenseApiUrl}/snapshot-grant {snapshot, version} (+ Bearer when logged
+ * in). Anonymous requests are valid (public roots). Throws GrantError; messages
+ * never contain the token or the Authorization header.
+ */
+export declare function requestSnapshotGrant(req: GrantRequest, deps: GrantRequestDeps): Promise<SnapshotGrant>;
+/**
+ * The proxy's `latest` rule (registry-proxy version.ts resolveLatest): the
+ * highest STABLE version; the highest prerelease only when no stable exists.
+ * Non-semver entries are ignored.
+ */
+export declare function resolveLatestStable(versions: string[]): string | undefined;
+/** '@ist/beta' → 'ist__beta' (proxy generic path form). */
+export declare function snapshotGenericName(snapshotName: string): string;
+export interface VersionResolveDeps {
+    registryUrl: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * Resolve the snapshot version to grant/install. An explicit exact version is
+ * used as-is; none / 'latest' → GET {proxy}/generic/<name>/versions (no auth)
+ * and pick resolveLatestStable over the returned list. Throws GrantError
+ * ('version-resolve') on any failure.
+ */
+export declare function resolveInstallVersion(snapshotName: string, requested: string | undefined, deps: VersionResolveDeps): Promise<string>;
+/** '@ist/beta@0.2.0' → {name:'@ist/beta', version:'0.2.0'}; no version → undefined. */
+export declare function splitSnapshotSpec(spec: string): {
+    name: string;
+    version?: string;
+};
+/** Canonical member name: lowercase, generic path form `ist__x` → `@ist/x`. */
+export declare function canonicalMemberName(name: string): string;
+/** The root snapshot's own version as frozen in the closure, if present. */
+export declare function findRootMemberVersion(members: GrantMember[], snapshotName: string): string | null;
+export interface CoverageResult {
+    ok: boolean;
+    /** 'name@version' specs not in the closure. */
+    missing: string[];
+}
+/**
+ * Check that every expected exact pin is a closure member (name@version, name
+ * case-insensitive). Kind is not compared in v1 (canonical key = @scope/name@ver).
+ */
+export declare function checkGrantCoverage(expected: Record<string, string> | Array<{
+    name: string;
+    version: string;
+}>, members: GrantMember[]): CoverageResult;
+/** Re-issue when remaining lifetime falls below max(120s, 25% of TTL). */
+export declare function reissueThresholdSec(expiresIn: number): number;
+export interface GrantStateDeps {
+    request: (req: GrantRequest) => Promise<SnapshotGrant>;
+    /** ms clock (injectable for tests). */
+    now?: () => number;
+    /** Called with every new token (initial issue and each re-issue). */
+    onToken?: (token: string) => void;
+}
+/**
+ * Holds the active grant for ONE snapshot@exact-version and re-issues it before
+ * a long phase when the remaining lifetime is low. A re-issue whose closureHash
+ * differs from the original is a GrantError('closure-changed') — the caller
+ * decides (require: fail-loud; prefer: fall back).
+ */
+export declare class GrantState {
+    private req;
+    private readonly deps;
+    private grant;
+    private issuedAtMs;
+    private reissueCount;
+    private readonly now;
+    constructor(req: GrantRequest, deps: GrantStateDeps);
+    issue(): Promise<SnapshotGrant>;
+    /** Pin subsequent re-issues to the exact version (after 'latest' resolution). */
+    pinVersion(version: string): void;
+    get current(): SnapshotGrant;
+    get reissues(): number;
+    get version(): string;
+    /** Seconds of lifetime left (0 when TTL unknown/expired). */
+    remainingSec(): number;
+    /**
+     * Re-issue if the remaining lifetime is below the threshold. A grant with an
+     * unknown TTL (expiresIn 0) is never re-issued. Returns true when re-issued.
+     */
+    ensureFresh(): Promise<boolean>;
+    private set;
+}
+/** The single grant log line: mode, member count, TTL, closure prefix, masked token. */
+export declare function formatGrantLog(mode: GrantMode, grant: SnapshotGrant): string;
+//# sourceMappingURL=grant.d.ts.map

package/dist/lib/grant.d.ts.map

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

package/dist/lib/grant.js

@@ -0,0 +1,352 @@
+/**
+ * Snapshot grant (istsg_) installer support — Plan A (grant-unify P1).
+ *
+ * Every install can obtain ONE short-lived `istsg_` grant from license-api
+ * (`POST /api/snapshot-grant`) that authorizes the snapshot's frozen closure at
+ * the registry-proxy. The grant token becomes the single proxy transport token
+ * (IST_SESSION_TOKEN) for the snapshot fetch, the npm batch, skit kit npm deps
+ * and converge. The closure `members[]` is used as the ALLOWED set only — the
+ * installer still installs the manifest top-level packages (no global install of
+ * transitive members).
+ *
+ * Gate: env SNAPSHOT_GRANT_MODE
+ *   off (default / unset) — no grant code runs; install is byte-identical to the
+ *                           legacy path (authorizeSession / anonymous npmrc).
+ *   prefer                — request a grant; on any grant failure warn and run the
+ *                           WHOLE install on the legacy path (no path mixing).
+ *   require               — request a grant; any grant failure is fail-loud.
+ *
+ * Secrets: the grant token is never logged or put in an error message. Logs use
+ * maskToken() (first 4 chars + …, same rule as maskSessionId).
+ */
+export const GRANT_MODE_ENV = 'SNAPSHOT_GRANT_MODE';
+export const GRANT_TIMEOUT_ENV = 'SNAPSHOT_GRANT_TIMEOUT_MS';
+export const DEFAULT_GRANT_TIMEOUT_MS = 15_000;
+/**
+ * Resolve the grant mode from the environment. Unset / empty / 'off' → 'off'.
+ * An unknown value is reported via `warn` and treated as 'off' (never silently
+ * enables a new path).
+ */
+export function readGrantMode(env = process.env, warn = () => { }) {
+    const raw = (env[GRANT_MODE_ENV] ?? '').trim().toLowerCase();
+    if (raw === '' || raw === 'off')
+        return 'off';
+    if (raw === 'prefer' || raw === 'require')
+        return raw;
+    warn(`${GRANT_MODE_ENV}=${raw} is not one of off|prefer|require — treating as off`);
+    return 'off';
+}
+export function readGrantTimeoutMs(env = process.env) {
+    const n = Number(env[GRANT_TIMEOUT_ENV]);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_GRANT_TIMEOUT_MS;
+}
+/** Mask a secret for logs: first 4 chars + '…' (same rule as maskSessionId). */
+export function maskToken(token) {
+    if (!token)
+        return '(none)';
+    return token.length <= 4 ? '…' : `${token.slice(0, 4)}…`;
+}
+export class GrantError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'GrantError';
+    }
+}
+/**
+ * POST {licenseApiUrl}/snapshot-grant {snapshot, version} (+ Bearer when logged
+ * in). Anonymous requests are valid (public roots). Throws GrantError; messages
+ * never contain the token or the Authorization header.
+ */
+export async function requestSnapshotGrant(req, deps) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_GRANT_TIMEOUT_MS;
+    const spec = `${req.snapshot}@${req.version}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+        res = await fetchImpl(`${deps.licenseApiUrl}/snapshot-grant`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(req.authToken ? { Authorization: `Bearer ${req.authToken}` } : {}),
+            },
+            body: JSON.stringify({ snapshot: req.snapshot, version: req.version }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (controller.signal.aborted) {
+            throw new GrantError('timeout', `snapshot grant for ${spec} timed out after ${timeoutMs}ms`);
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new GrantError('network', `snapshot grant for ${spec} failed: ${msg}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        const code = typeof body.code === 'string' ? body.code : '';
+        const detail = [code, typeof body.error === 'string' ? body.error : ''].filter(Boolean).join(': ') || res.statusText;
+        if (res.status === 401 || res.status === 403) {
+            throw new GrantError('unauthorized', `not authorized for ${spec} (${res.status} ${detail}). A non-public snapshot requires sign-in / entitlement.`, res.status);
+        }
+        if (res.status === 404) {
+            throw new GrantError('not-found', `snapshot ${spec} not found (${detail})`, 404);
+        }
+        if (res.status === 502 || code === 'CLOSURE_RESOLVE_FAILED') {
+            throw new GrantError('closure-resolve', `server could not resolve the full closure for ${spec} (${res.status} ${detail})`, res.status);
+        }
+        throw new GrantError('http', `snapshot grant for ${spec} failed: ${res.status} ${detail}`, res.status);
+    }
+    const body = (await res.json().catch(() => null));
+    if (!body || typeof body.token !== 'string' || !body.token) {
+        throw new GrantError('invalid-response', `invalid grant response for ${spec}: missing token`);
+    }
+    if (!Array.isArray(body.members)) {
+        throw new GrantError('invalid-response', `grant response for ${spec} has no members[] (license-api without the closure contract)`);
+    }
+    const members = [];
+    for (const m of body.members) {
+        const mm = m;
+        if (!mm || typeof mm.name !== 'string' || typeof mm.version !== 'string') {
+            throw new GrantError('invalid-response', `invalid grant response for ${spec}: malformed member`);
+        }
+        members.push({ name: mm.name, version: mm.version, ...(mm.kind ? { kind: mm.kind } : {}) });
+    }
+    return {
+        token: body.token,
+        members,
+        closureHash: typeof body.closureHash === 'string' ? body.closureHash : '',
+        expiresIn: typeof body.expiresIn === 'number' && body.expiresIn > 0 ? body.expiresIn : 0,
+    };
+}
+// ============================================================
+// Exact version resolution (before the grant request)
+// ============================================================
+// license-api resolves a grant for version 'latest' to the most recent UPLOAD
+// (prereleases included), while the legacy install path's 'latest' (proxy
+// generic latest) is the highest STABLE version. Grant mode therefore never asks
+// for 'latest': core resolves the exact version first with the proxy rule.
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+function semverKey(v) {
+    const m = SEMVER_RE.exec(v.trim());
+    if (!m)
+        return null;
+    return { rel: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ? m[4].split('.') : [] };
+}
+function compareSemver(a, b) {
+    const x = semverKey(a);
+    const y = semverKey(b);
+    for (let i = 0; i < 3; i++)
+        if (x.rel[i] !== y.rel[i])
+            return x.rel[i] < y.rel[i] ? -1 : 1;
+    if (x.pre.length === 0 || y.pre.length === 0)
+        return x.pre.length === y.pre.length ? 0 : x.pre.length === 0 ? 1 : -1;
+    for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+        if (i >= x.pre.length)
+            return -1;
+        if (i >= y.pre.length)
+            return 1;
+        const p = x.pre[i];
+        const q = y.pre[i];
+        if (p === q)
+            continue;
+        const pn = /^\d+$/.test(p);
+        const qn = /^\d+$/.test(q);
+        if (pn && qn)
+            return BigInt(p) < BigInt(q) ? -1 : 1;
+        if (pn)
+            return -1;
+        if (qn)
+            return 1;
+        return p < q ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * The proxy's `latest` rule (registry-proxy version.ts resolveLatest): the
+ * highest STABLE version; the highest prerelease only when no stable exists.
+ * Non-semver entries are ignored.
+ */
+export function resolveLatestStable(versions) {
+    const valid = versions.filter((v) => semverKey(v) !== null);
+    if (valid.length === 0)
+        return undefined;
+    const stable = valid.filter((v) => semverKey(v).pre.length === 0);
+    const pool = stable.length > 0 ? stable : valid;
+    return pool.reduce((best, v) => (compareSemver(v, best) > 0 ? v : best));
+}
+/** '@ist/beta' → 'ist__beta' (proxy generic path form). */
+export function snapshotGenericName(snapshotName) {
+    const m = /^@([^/]+)\/(.+)$/.exec(snapshotName.trim());
+    return m ? `${m[1]}__${m[2]}` : snapshotName.trim();
+}
+/**
+ * Resolve the snapshot version to grant/install. An explicit exact version is
+ * used as-is; none / 'latest' → GET {proxy}/generic/<name>/versions (no auth)
+ * and pick resolveLatestStable over the returned list. Throws GrantError
+ * ('version-resolve') on any failure.
+ */
+export async function resolveInstallVersion(snapshotName, requested, deps) {
+    if (requested && requested !== 'latest')
+        return requested;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const generic = snapshotGenericName(snapshotName);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.timeoutMs ?? DEFAULT_GRANT_TIMEOUT_MS);
+    let body = null;
+    try {
+        const res = await fetchImpl(`${deps.registryUrl}/generic/${generic}/versions`, { signal: controller.signal });
+        if (!res.ok) {
+            throw new GrantError('version-resolve', `cannot list versions of ${snapshotName} (HTTP ${res.status})`, res.status);
+        }
+        body = (await res.json().catch(() => null));
+    }
+    catch (err) {
+        if (err instanceof GrantError)
+            throw err;
+        const msg = controller.signal.aborted ? 'timed out' : err instanceof Error ? err.message : String(err);
+        throw new GrantError('version-resolve', `cannot list versions of ${snapshotName}: ${msg}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const list = Array.isArray(body?.versions) ? body.versions.filter((v) => typeof v === 'string') : [];
+    const latest = resolveLatestStable(list);
+    if (!latest)
+        throw new GrantError('version-resolve', `no published versions of ${snapshotName}`);
+    return latest;
+}
+// ============================================================
+// Member helpers
+// ============================================================
+/** '@ist/beta@0.2.0' → {name:'@ist/beta', version:'0.2.0'}; no version → undefined. */
+export function splitSnapshotSpec(spec) {
+    const at = spec.lastIndexOf('@');
+    if (at > 0)
+        return { name: spec.slice(0, at), version: spec.slice(at + 1) || undefined };
+    return { name: spec };
+}
+/** Canonical member name: lowercase, generic path form `ist__x` → `@ist/x`. */
+export function canonicalMemberName(name) {
+    const n = name.trim().toLowerCase();
+    if (!n.startsWith('@')) {
+        const i = n.indexOf('__');
+        if (i > 0)
+            return `@${n.slice(0, i)}/${n.slice(i + 2)}`;
+    }
+    return n;
+}
+function memberKey(name, version) {
+    return `${canonicalMemberName(name)}@${version.trim()}`;
+}
+/** The root snapshot's own version as frozen in the closure, if present. */
+export function findRootMemberVersion(members, snapshotName) {
+    const root = canonicalMemberName(snapshotName);
+    const hit = members.filter((m) => canonicalMemberName(m.name) === root && m.kind !== 'npm');
+    return hit.length === 1 ? hit[0].version : null;
+}
+/**
+ * Check that every expected exact pin is a closure member (name@version, name
+ * case-insensitive). Kind is not compared in v1 (canonical key = @scope/name@ver).
+ */
+export function checkGrantCoverage(expected, members) {
+    const allowed = new Set(members.map((m) => memberKey(m.name, m.version)));
+    const entries = Array.isArray(expected) ? expected.map((e) => [e.name, e.version]) : Object.entries(expected);
+    const missing = [];
+    for (const [name, version] of entries) {
+        if (!allowed.has(memberKey(name, version)))
+            missing.push(`${name}@${version}`);
+    }
+    return { ok: missing.length === 0, missing };
+}
+// ============================================================
+// Grant state + TTL re-issue
+// ============================================================
+/** Re-issue when remaining lifetime falls below max(120s, 25% of TTL). */
+export function reissueThresholdSec(expiresIn) {
+    return Math.max(120, Math.floor(expiresIn * 0.25));
+}
+/**
+ * Holds the active grant for ONE snapshot@exact-version and re-issues it before
+ * a long phase when the remaining lifetime is low. A re-issue whose closureHash
+ * differs from the original is a GrantError('closure-changed') — the caller
+ * decides (require: fail-loud; prefer: fall back).
+ */
+export class GrantState {
+    req;
+    deps;
+    grant = null;
+    issuedAtMs = 0;
+    reissueCount = 0;
+    now;
+    constructor(req, deps) {
+        this.req = req;
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+    }
+    async issue() {
+        const g = await this.deps.request(this.req);
+        this.set(g);
+        return g;
+    }
+    /** Pin subsequent re-issues to the exact version (after 'latest' resolution). */
+    pinVersion(version) {
+        this.req = { ...this.req, version };
+    }
+    get current() {
+        if (!this.grant)
+            throw new Error('GrantState: no grant issued');
+        return this.grant;
+    }
+    get reissues() {
+        return this.reissueCount;
+    }
+    get version() {
+        return this.req.version;
+    }
+    /** Seconds of lifetime left (0 when TTL unknown/expired). */
+    remainingSec() {
+        if (!this.grant || this.grant.expiresIn <= 0)
+            return 0;
+        const elapsed = (this.now() - this.issuedAtMs) / 1000;
+        return Math.max(0, this.grant.expiresIn - elapsed);
+    }
+    /**
+     * Re-issue if the remaining lifetime is below the threshold. A grant with an
+     * unknown TTL (expiresIn 0) is never re-issued. Returns true when re-issued.
+     */
+    async ensureFresh() {
+        const g = this.current;
+        if (g.expiresIn <= 0)
+            return false;
+        if (this.remainingSec() >= reissueThresholdSec(g.expiresIn))
+            return false;
+        const next = await this.deps.request(this.req);
+        if (g.closureHash && next.closureHash && next.closureHash !== g.closureHash) {
+            throw new GrantError('closure-changed', `re-issued grant for ${this.req.snapshot}@${this.req.version} has a different closure ` +
+                `(${g.closureHash.slice(0, 8)} → ${next.closureHash.slice(0, 8)})`);
+        }
+        this.set(next);
+        this.reissueCount++;
+        return true;
+    }
+    set(g) {
+        this.grant = g;
+        this.issuedAtMs = this.now();
+        this.deps.onToken?.(g.token);
+    }
+}
+/** The single grant log line: mode, member count, TTL, closure prefix, masked token. */
+export function formatGrantLog(mode, grant) {
+    const hash = grant.closureHash ? grant.closureHash.slice(0, 8) : '-';
+    return (`Grant: mode=${mode} members=${grant.members.length} expiresIn=${grant.expiresIn}s ` +
+        `closure=${hash} token=${maskToken(grant.token)}`);
+}
+//# sourceMappingURL=grant.js.map

package/dist/lib/grant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grant.js","sourceRoot":"","sources":["../../src/lib/grant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,MAAM,CAAC,MAAM,cAAc,GAAG,qBAAqB,CAAC;AACpD,MAAM,CAAC,MAAM,iBAAiB,GAAG,2BAA2B,CAAC;AAC7D,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAE/C;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAyB,OAAO,CAAC,GAAG,EACpC,OAA8B,GAAG,EAAE,GAAE,CAAC;IAEtC,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC7D,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IACtD,IAAI,CAAC,GAAG,cAAc,IAAI,GAAG,qDAAqD,CAAC,CAAC;IACpF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACrE,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACzC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,wBAAwB,CAAC;AACpE,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,SAAS,CAAC,KAAgC;IACxD,IAAI,CAAC,KAAK;QAAE,OAAO,QAAQ,CAAC;IAC5B,OAAO,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC;AAC3D,CAAC;AAkCD,MAAM,OAAO,UAAW,SAAQ,KAAK;IAExB;IAEA;IAHX,YACW,IAAoB,EAC7B,OAAe,EACN,MAAe;QAExB,KAAK,CAAC,OAAO,CAAC,CAAC;QAJN,SAAI,GAAJ,IAAI,CAAgB;QAEpB,WAAM,GAAN,MAAM,CAAS;QAGxB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAkBD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,GAAiB,EAAE,IAAsB;IAClF,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC;IAC1C,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,wBAAwB,CAAC;IAC7D,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;IAC9C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAE9D,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,IAAI,CAAC,aAAa,iBAAiB,EAAE;YAC5D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACvE;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;YACtE,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,IAAI,UAAU,CAAC,SAAS,EAAE,sBAAsB,IAAI,oBAAoB,SAAS,IAAI,CAAC,CAAC;QAC/F,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,UAAU,CAAC,SAAS,EAAE,sBAAsB,IAAI,YAAY,GAAG,EAAE,CAAC,CAAC;IAC/E,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAwC,CAAC;QACzF,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC;QACrH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC7C,MAAM,IAAI,UAAU,CAClB,cAAc,EACd,sBAAsB,IAAI,KAAK,GAAG,CAAC,MAAM,IAAI,MAAM,0DAA0D,EAC7G,GAAG,CAAC,MAAM,CACX,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,IAAI,UAAU,CAAC,WAAW,EAAE,YAAY,IAAI,eAAe,MAAM,GAAG,EAAE,GAAG,CAAC,CAAC;QACnF,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,KAAK,wBAAwB,EAAE,CAAC;YAC5D,MAAM,IAAI,UAAU,CAClB,iBAAiB,EACjB,iDAAiD,IAAI,KAAK,GAAG,CAAC,MAAM,IAAI,MAAM,GAAG,EACjF,GAAG,CAAC,MAAM,CACX,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,UAAU,CAAC,MAAM,EAAE,sBAAsB,IAAI,YAAY,GAAG,CAAC,MAAM,IAAI,MAAM,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzG,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAkC,CAAC;IACnF,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAC3D,MAAM,IAAI,UAAU,CAAC,kBAAkB,EAAE,8BAA8B,IAAI,iBAAiB,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,UAAU,CAClB,kBAAkB,EAClB,sBAAsB,IAAI,8DAA8D,CACzF,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAoB,EAAE,CAAC;QAC1C,MAAM,EAAE,GAAG,CAAyB,CAAC;QACrC,IAAI,CAAC,EAAE,IAAI,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,EAAE,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACzE,MAAM,IAAI,UAAU,CAAC,kBAAkB,EAAE,8BAA8B,IAAI,oBAAoB,CAAC,CAAC;QACnG,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,OAAO;QACP,WAAW,EAAE,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE;QACzE,SAAS,EAAE,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;KACzF,CAAC;AACJ,CAAC;AAED,+DAA+D;AAC/D,sDAAsD;AACtD,+DAA+D;AAC/D,8EAA8E;AAC9E,0EAA0E;AAC1E,iFAAiF;AACjF,2EAA2E;AAE3E,MAAM,SAAS,GAAG,oEAAoE,CAAC;AAEvF,SAAS,SAAS,CAAC,CAAS;IAC1B,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AAC/F,CAAC;AAED,SAAS,aAAa,CAAC,CAAS,EAAE,CAAS;IACzC,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAE,CAAC;IACxB,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAE,CAAC;IACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3F,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrH,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9D,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM;YAAE,OAAO,CAAC,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM;YAAE,OAAO,CAAC,CAAC;QAChC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACnB,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,CAAC,KAAK,CAAC;YAAE,SAAS;QACtB,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC3B,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,EAAE,IAAI,EAAE;YAAE,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpD,IAAI,EAAE;YAAE,OAAO,CAAC,CAAC,CAAC;QAClB,IAAI,EAAE;YAAE,OAAO,CAAC,CAAC;QACjB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAkB;IACpD,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IAC5D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAE,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;IAChD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,mBAAmB,CAAC,YAAoB;IACtD,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC;IACvD,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;AACtD,CAAC;AAQD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,YAAoB,EACpB,SAA6B,EAC7B,IAAwB;IAExB,IAAI,SAAS,IAAI,SAAS,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC;IAC1C,MAAM,OAAO,GAAG,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAClD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,IAAI,wBAAwB,CAAC,CAAC;IAC/F,IAAI,IAAI,GAAkC,IAAI,CAAC;IAC/C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,IAAI,CAAC,WAAW,YAAY,OAAO,WAAW,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9G,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,UAAU,CAAC,iBAAiB,EAAE,2BAA2B,YAAY,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACtH,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAkC,CAAC;IAC/E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,UAAU;YAAE,MAAM,GAAG,CAAC;QACzC,MAAM,GAAG,GAAG,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvG,MAAM,IAAI,UAAU,CAAC,iBAAiB,EAAE,2BAA2B,YAAY,KAAK,GAAG,EAAE,CAAC,CAAC;IAC7F,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAE,IAAK,CAAC,QAAsB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClI,MAAM,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,UAAU,CAAC,iBAAiB,EAAE,4BAA4B,YAAY,EAAE,CAAC,CAAC;IACjG,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+DAA+D;AAC/D,iBAAiB;AACjB,+DAA+D;AAE/D,uFAAuF;AACvF,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,EAAE,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,SAAS,EAAE,CAAC;IACzF,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IAC1D,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,SAAS,CAAC,IAAY,EAAE,OAAe;IAC9C,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;AAC1D,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,qBAAqB,CAAC,OAAsB,EAAE,YAAoB;IAChF,MAAM,IAAI,GAAG,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC;IAC5F,OAAO,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC;AAQD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAA2E,EAC3E,OAAsB;IAEtB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1E,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvH,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,OAAO,EAAE,CAAC;QACtC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,OAAO,EAAE,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;AAC/C,CAAC;AAED,+DAA+D;AAC/D,6BAA6B;AAC7B,+DAA+D;AAE/D,0EAA0E;AAC1E,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC;AACrD,CAAC;AAUD;;;;;GAKG;AACH,MAAM,OAAO,UAAU;IAOX;IACS;IAPX,KAAK,GAAyB,IAAI,CAAC;IACnC,UAAU,GAAG,CAAC,CAAC;IACf,YAAY,GAAG,CAAC,CAAC;IACR,GAAG,CAAe;IAEnC,YACU,GAAiB,EACR,IAAoB;QAD7B,QAAG,GAAH,GAAG,CAAc;QACR,SAAI,GAAJ,IAAI,CAAgB;QAErC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACZ,OAAO,CAAC,CAAC;IACX,CAAC;IAED,iFAAiF;IACjF,UAAU,CAAC,OAAe;QACxB,IAAI,CAAC,GAAG,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC;IACtC,CAAC;IAED,IAAI,OAAO;QACT,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QAChE,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;IAC1B,CAAC;IAED,6DAA6D;IAC7D,YAAY;QACV,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;QACvD,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;QACtD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,OAAO,CAAC,CAAC;IACrD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,WAAW;QACf,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC;QACvB,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACnC,IAAI,IAAI,CAAC,YAAY,EAAE,IAAI,mBAAmB,CAAC,CAAC,CAAC,SAAS,CAAC;YAAE,OAAO,KAAK,CAAC;QAC1E,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/C,IAAI,CAAC,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YAC5E,MAAM,IAAI,UAAU,CAClB,iBAAiB,EACjB,uBAAuB,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,2BAA2B;gBACrF,IAAI,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CACrE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,GAAG,CAAC,CAAgB;QAC1B,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QACf,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;CACF;AAED,wFAAwF;AACxF,MAAM,UAAU,cAAc,CAAC,IAAe,EAAE,KAAoB;IAClE,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACrE,OAAO,CACL,eAAe,IAAI,YAAY,KAAK,CAAC,OAAO,CAAC,MAAM,cAAc,KAAK,CAAC,SAAS,IAAI;QACpF,WAAW,IAAI,UAAU,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAClD,CAAC;AACJ,CAAC"}

package/dist/lib/install-verify.d.ts

@@ -65,14 +65,28 @@ export declare function verifyInstallMap(installMap: Record<string, string>, opt
  * Returns the FINAL VerificationResult (ok=true iff the disk converged). The
  * integrator decides how to react (exit non-zero, log, fold into the ledger).
  *
+ * Re-pinning is BATCHED: every mismatch in a round is repaired in a single
+ * `installMany([...])` call (which maps to one `npm install -g A@vA B@vB ...`),
+ * instead of one npm spawn per package. This collapses N sequential global
+ * installs per round into one, the dominant cost of a slow converge phase.
+ *
+ * `installMany` is preferred; the legacy per-package `install(name, version)`
+ * hook is still accepted for backward compatibility (used when `installMany`
+ * is not supplied — each mismatch is then installed individually).
+ *
  * @param installMap manifest npm pins (name → exact version)
  * @param overrides  FB pin overrides (name → version); {} for none
- * @param deps.install     re-pin one package to an exact version (side-effecting)
+ * @param deps.installMany batch re-pin ALL mismatches at once (preferred)
+ * @param deps.install     legacy single re-pin (fallback when no installMany)
  * @param deps.readVersion disk reader (defaults to readInstalledNpmVersion)
  * @param deps.maxRounds   max convergence rounds (default 3)
  */
 export declare function runConverge(installMap: Record<string, string>, overrides: Record<string, string>, deps: {
-    install: (name: string, version: string) => void;
+    install?: (name: string, version: string) => void;
+    installMany?: (pkgs: Array<{
+        name: string;
+        version: string;
+    }>) => void;
     readVersion?: VersionReader;
     maxRounds?: number;
 }): VerificationResult;

package/dist/lib/install-verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install-verify.d.ts","sourceRoot":"","sources":["../../src/lib/install-verify.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,EAAE,EAAE,OAAO,CAAC;IACZ,+DAA+D;IAC/D,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oFAAoF;AACpF,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAmB5D,wEAAwE;AACxE,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYnE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,aAAa,CAAA;CAAO,GACzC,kBAAkB,CAsBpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,IAAI,EAAE;IACJ,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,kBAAkB,CAapB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUnG;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,MAAM,CAU/E"}
+{"version":3,"file":"install-verify.d.ts","sourceRoot":"","sources":["../../src/lib/install-verify.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,EAAE,EAAE,OAAO,CAAC;IACZ,+DAA+D;IAC/D,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oFAAoF;AACpF,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAmB5D,wEAAwE;AACxE,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYnE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,aAAa,CAAA;CAAO,GACzC,kBAAkB,CAsBpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,IAAI,EAAE;IACJ,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IACvE,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,kBAAkB,CAuBpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUnG;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,MAAM,CAU/E"}

package/dist/lib/install-verify.js

@@ -90,20 +90,41 @@ export function verifyInstallMap(installMap, opts = {}) {
  * Returns the FINAL VerificationResult (ok=true iff the disk converged). The
  * integrator decides how to react (exit non-zero, log, fold into the ledger).
  *
+ * Re-pinning is BATCHED: every mismatch in a round is repaired in a single
+ * `installMany([...])` call (which maps to one `npm install -g A@vA B@vB ...`),
+ * instead of one npm spawn per package. This collapses N sequential global
+ * installs per round into one, the dominant cost of a slow converge phase.
+ *
+ * `installMany` is preferred; the legacy per-package `install(name, version)`
+ * hook is still accepted for backward compatibility (used when `installMany`
+ * is not supplied — each mismatch is then installed individually).
+ *
  * @param installMap manifest npm pins (name → exact version)
  * @param overrides  FB pin overrides (name → version); {} for none
- * @param deps.install     re-pin one package to an exact version (side-effecting)
+ * @param deps.installMany batch re-pin ALL mismatches at once (preferred)
+ * @param deps.install     legacy single re-pin (fallback when no installMany)
  * @param deps.readVersion disk reader (defaults to readInstalledNpmVersion)
  * @param deps.maxRounds   max convergence rounds (default 3)
  */
 export function runConverge(installMap, overrides, deps) {
+    if (!deps.installMany && !deps.install) {
+        throw new Error('runConverge requires either deps.installMany or deps.install');
+    }
     const effectiveMap = applyPinOverrides(installMap, overrides);
     const readVersion = deps.readVersion ?? readInstalledNpmVersion;
     const maxRounds = deps.maxRounds ?? 3;
     let verification = verifyInstallMap(effectiveMap, { readVersion });
     for (let round = 1; round <= maxRounds && !verification.ok; round++) {
-        for (const m of verification.mismatches) {
-            deps.install(m.name, m.expected);
+        const pkgs = verification.mismatches.map((m) => ({ name: m.name, version: m.expected }));
+        if (deps.installMany) {
+            // Batch: one npm invocation repairs the whole round.
+            deps.installMany(pkgs);
+        }
+        else {
+            // Legacy fallback: one install per mismatched package.
+            for (const p of pkgs) {
+                deps.install(p.name, p.version);
+            }
         }
         verification = verifyInstallMap(effectiveMap, { readVersion });
     }

package/dist/lib/install-verify.js.map

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