@aephia/atlas-kit 0.6.0-next.36 → 0.6.0-next.38

package/dist/internal/planning/fleet-arrival.js

@@ -0,0 +1,134 @@
+import { SageSdkError } from '../../client/errors.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { decodeFleetArrival, } from '../c4/fleet-arrival.js';
+import { findCharacterPda, characterAccountDefinition, profileAccountDefinition, } from '../c4/identity.js';
+import { deriveRegionTrackerAddress, regionTrackerAccountDefinition, } from '../c4/factions.js';
+import { PROFILE_SCOPE, SAGE_SCOPE } from '../c4/profile-permissions.js';
+import { requireGameAddress } from '../game-context.js';
+import { CLOCK_ADDRESS, readClock } from './faction-enrollment.js';
+import { resolveXpRuntime } from './xp-runtime.js';
+function fail(address, reason) {
+    throw new SageSdkError('ACTION_PRECONDITION_FAILED', `Arrival settlement ${reason}. Refresh the Fleet and prepare a new arrival Plan after completed travel.`, { address });
+}
+function required(raw, address) {
+    if (!raw || raw.address !== address || raw.executable)
+        fail(address, `requires the existing non-executable account ${address}`);
+    return raw;
+}
+/** Read fresh movement, chain time and direct authority without retaining signer data. */
+export async function resolveFleetArrival(ctx, fleetAddress, options) {
+    const game = requireGameAddress(ctx);
+    const [fleetRaw, clockRaw] = await readContextRawAccounts(ctx, [
+        fleetAddress,
+        CLOCK_ADDRESS,
+    ]);
+    const fleet = await decodeFleetArrival(required(fleetRaw, fleetAddress));
+    if (fleet.game !== game || fleet.canonical !== fleetAddress)
+        fail(fleetAddress, 'requires the canonical Fleet for the configured Game');
+    const journey = fleet.journey;
+    if (!journey)
+        fail(fleetAddress, 'requires a travelling Fleet; Idle and other non-travel states have no arrival to settle');
+    const now = readClock(required(clockRaw, CLOCK_ADDRESS));
+    if (journey.kind === 'subwarp'
+        ? journey.duration < 0n
+        : journey.arrival < journey.departure)
+        fail(fleetAddress, 'found invalid journey timing');
+    if (now < journey.departure ||
+        (journey.kind === 'subwarp'
+            ? (now - journey.departure) * (1n << 56n) < journey.duration
+            : now < journey.arrival))
+        fail(fleetAddress, 'cannot stop an unfinished journey that has not yet arrived; wait for chain time to reach the destination or choose the separate intentional early-stop action');
+    const character = await findCharacterPda(fleet.profile, game);
+    // Only the authorized route consumes Character XP. Legacy funders must receive
+    // an authorization remedy even when the XP budget is missing.
+    const xp = await resolveXpRuntime(ctx, {
+        game,
+        ...(options.authorization ? { character } : {}),
+    });
+    if (xp.gameVersion === 2 && journey.kind === 'warp')
+        fail(fleetAddress, 'for Game version 2 warp is unsupported; wait for a separately supported warp settlement route');
+    if (xp.gameVersion === 2 && !options.authorization)
+        fail(fleetAddress, 'for this XP-era subwarp requires explicit Profile authorization; supply { authorization } rather than a funder');
+    if (xp.gameVersion === 0 && options.authorization)
+        fail(fleetAddress, 'on legacy Game version 0 requires an explicit funder; use the legacy { funder } route');
+    const regionTracker = options.authorization
+        ? await deriveRegionTrackerAddress(game)
+        : undefined;
+    const addresses = [
+        character,
+        ...(options.authorization ? [fleet.profile, regionTracker] : []),
+    ];
+    const accounts = await readContextRawAccounts(ctx, addresses);
+    const characterData = characterAccountDefinition.decode(required(accounts[0], character));
+    if (characterData.game !== game ||
+        characterData.playerProfile !== fleet.profile)
+        fail(character, 'requires the canonical Character for this Game and owning Profile');
+    let intent;
+    if (options.authorization) {
+        const authorization = options.authorization;
+        if (authorization.certificate !== undefined ||
+            authorization.profile !== fleet.profile ||
+            fleet.subProfile !== SAGE_SCOPE)
+            fail(fleetAddress, 'supports only the owning Profile and its direct key, without a certificate or delegated sub-Profile');
+        if (!Number.isInteger(authorization.keyIndex) ||
+            authorization.keyIndex < 0 ||
+            authorization.keyIndex > 65535)
+            fail(fleet.profile, 'requires a valid direct Profile key index');
+        const profile = profileAccountDefinition.decode(required(accounts[1], fleet.profile));
+        const key = profile.keys[authorization.keyIndex];
+        if (!key || key.address !== authorization.authority)
+            fail(fleet.profile, 'requires the current direct key index for the selected authority');
+        if (key.expiresAtRaw >= 0n && key.expiresAtRaw < now)
+            fail(fleet.profile, 'cannot use an expired Profile key; renew it or select an unexpired direct key');
+        if (!((key.scope === PROFILE_SCOPE && (key.permissionsRaw & 1n) !== 0n) ||
+            (key.scope === SAGE_SCOPE && (key.permissionsRaw & (1n << 10n)) !== 0n)))
+            fail(fleet.profile, 'requires direct Profile AUTH or SAGE moveFleet permission; select an appropriately scoped key');
+        const tracker = regionTrackerAccountDefinition.decode(required(accounts[2], regionTracker));
+        if (tracker.game !== game)
+            fail(regionTracker, 'requires the canonical RegionTracker bound to this Game');
+        intent = {
+            fleet: fleetAddress,
+            game,
+            profile: fleet.profile,
+            journey,
+            route: 'authorized',
+            authorization: {
+                profile: authorization.profile,
+                authority: authorization.authority,
+                keyIndex: authorization.keyIndex,
+            },
+        };
+    }
+    else
+        intent = {
+            fleet: fleetAddress,
+            game,
+            profile: fleet.profile,
+            journey,
+            route: 'legacy',
+            funder: options.funder,
+        };
+    return { intent, character, regionTracker, xp };
+}
+/** Recheck only the selected journey/authority, permitting unrelated Fleet and XP changes. */
+export async function validateFleetArrivalIntent(ctx, intent) {
+    const current = await resolveFleetArrival(ctx, intent.fleet, intent.route === 'authorized'
+        ? { authorization: intent.authorization }
+        : { funder: intent.funder });
+    const a = intent.journey, b = current.intent.journey;
+    if (current.intent.game !== intent.game ||
+        current.intent.profile !== intent.profile ||
+        a.kind !== b.kind ||
+        a.departure !== b.departure ||
+        a.from.x !== b.from.x ||
+        a.from.y !== b.from.y ||
+        a.to.x !== b.to.x ||
+        a.to.y !== b.to.y ||
+        (a.kind === 'subwarp' &&
+            b.kind === 'subwarp' &&
+            a.duration !== b.duration) ||
+        (a.kind === 'warp' && b.kind === 'warp' && a.arrival !== b.arrival))
+        fail(intent.fleet, 'journey or ownership changed after planning');
+    return current;
+}
+//# sourceMappingURL=fleet-arrival.js.map

package/dist/internal/planning/fleet-arrival.js.map

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

package/dist/internal/planning/governance-fees.d.ts

@@ -0,0 +1,64 @@
+import type { Address, SageContext } from '../../client/contracts.js';
+import { type CraftingProcessAccountData } from '../c4/crafting.js';
+import type { ResolvedDemocracyHistory } from './democracy-history.js';
+export interface FeeRequest {
+    readonly game: Address;
+    readonly system: Address;
+    readonly starbaseSeqId: bigint;
+    readonly mode: 'market' | 'crafting-start' | 'crafting-complete';
+    readonly hasHab?: boolean;
+    readonly process?: Address;
+}
+export interface FeeParams {
+    readonly craftingFeeBps: number;
+    readonly localMarketFeeBps: number;
+    readonly localTreasuryShareBps: number;
+    readonly treasuryDistributionBps?: number;
+}
+export interface FeeIntent {
+    readonly request: FeeRequest;
+    readonly governance?: {
+        readonly address: Address;
+        readonly state: 'absent' | 'initialized';
+        readonly version?: number;
+        readonly enabled?: number;
+        readonly controllerFaction?: number;
+        readonly starbaseSeqId?: bigint;
+        readonly activeParams?: FeeParams;
+    };
+    readonly currencyCache?: {
+        readonly address: Address;
+        readonly version: number;
+    };
+    readonly treasury?: {
+        readonly address: Address;
+        readonly state: 'absent' | 'initialized';
+        readonly version?: number;
+        readonly governance?: Address;
+    };
+    readonly process?: {
+        readonly address: Address;
+        readonly version: number;
+        readonly feeRecipient?: 'atlas' | 'dao-atlas';
+        readonly feeGovernance?: Address;
+        readonly feeSnapshot?: CraftingProcessAccountData['feeSnapshot'];
+    };
+    readonly quote: {
+        readonly source: 'default' | 'governance' | 'history-policy' | 'history-generation' | 'history-disabled' | 'process-snapshot' | 'legacy-process';
+        readonly params?: FeeParams;
+    };
+}
+export interface ResolvedGovernanceFees {
+    readonly intent: FeeIntent;
+    readonly accounts: {
+        readonly starbaseGovernance?: Address;
+        readonly currencyCache?: Address;
+        readonly starbaseTreasury?: Address;
+    };
+    readonly description: string;
+}
+/** Resolve current fee accounts and a finite quote without creating or funding anything. */
+export declare function resolveGovernanceFees(ctx: SageContext, request: FeeRequest, history: ResolvedDemocracyHistory): Promise<ResolvedGovernanceFees>;
+/** Compare finite serialized fields; mutable shared balances are deliberately absent. */
+export declare function matchGovernanceFeesIntent(expected: FeeIntent, actual: FeeIntent): boolean;
+//# sourceMappingURL=governance-fees.d.ts.map

package/dist/internal/planning/governance-fees.d.ts.map

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

package/dist/internal/planning/governance-fees.js

@@ -0,0 +1,239 @@
+import { getAddressEncoder, getProgramDerivedAddress, getU64Encoder, } from '@solana/kit';
+import { SageSdkError } from '../../client/errors.js';
+import { readContextRawAccounts } from '../../client/reconciliation.js';
+import { CURRENCY_CONFIG_CACHE_DISCRIMINATOR, SAGE_PROGRAM_ADDRESS, STARBASE_GOVERNANCE_DISCRIMINATOR, STARBASE_TREASURY_DISCRIMINATOR, getCurrencyConfigCacheDecoder, getStarbaseGovernanceDecoder, getStarbaseTreasuryDecoder, } from '../c4/runtime-bindings.js';
+import { deriveStarSystemAddress, starSystemAccountDefinition, } from '../c4/world.js';
+import { craftingProcessAccountDefinition, } from '../c4/crafting.js';
+function requireFee(condition, reason) {
+    if (!condition)
+        throw new SageSdkError('ACTION_PRECONDITION_FAILED', `${reason} Refresh the Starbase fee configuration and recreate this action; ask its operator to initialize missing fee-routing accounts.`);
+}
+async function derive(literal, scope, sequence) {
+    return getProgramDerivedAddress({
+        programAddress: SAGE_PROGRAM_ADDRESS,
+        seeds: [
+            new TextEncoder().encode(literal),
+            getAddressEncoder().encode(scope),
+            ...(sequence === undefined ? [] : [getU64Encoder().encode(sequence)]),
+        ],
+    });
+}
+function decode(raw, address, discriminator, decoder) {
+    requireFee(raw &&
+        raw.address === address &&
+        raw.owner === SAGE_PROGRAM_ADDRESS &&
+        !raw.executable, `Fee-routing account ${address} is missing or has an unexpected owner or address.`);
+    requireFee(discriminator.every((byte, index) => raw.data[index] === byte), `Fee-routing account ${address} has the wrong discriminator.`);
+    try {
+        const [value, consumed] = decoder.read(raw.data, 0);
+        requireFee(consumed === raw.data.length, `Fee-routing account ${address} has trailing bytes.`);
+        return value;
+    }
+    catch (cause) {
+        if (cause instanceof SageSdkError)
+            throw cause;
+        throw new SageSdkError('ACTION_PRECONDITION_FAILED', `Fee-routing account ${address} cannot be decoded. Refresh the deployment and recreate this action with supported account data.`);
+    }
+}
+function params(value) {
+    return {
+        craftingFeeBps: value.craftingFeeBps,
+        localMarketFeeBps: value.localMarketFeeBps,
+        localTreasuryShareBps: value.localTreasuryShareBps,
+        treasuryDistributionBps: value.treasuryDistributionBps,
+    };
+}
+function description(intent) {
+    const quote = intent.quote;
+    if (!quote.params)
+        return 'Legacy Crafting Process has no captured governance fee snapshot. No governed fee amount or recipient is inferred from synthetic defaults.';
+    const value = quote.params;
+    return `Fee policy source: ${quote.source}. Recipe fee multiplier: ${value.craftingFeeBps} basis points (10,000 = 1×); Local Market fee: ${value.localMarketFeeBps} basis points of executed ATLAS value; local Treasury share: ${value.localTreasuryShareBps} basis points of governed fees.${intent.process?.feeRecipient ? ` Captured original recipe recipient: ${intent.process.feeRecipient}.` : ''}${intent.treasury?.state === 'initialized' ? ` Treasury: ${intent.treasury.address}.` : ''} These rates do not predict an executed debit and can race a policy change after validation.`;
+}
+/** Resolve current fee accounts and a finite quote without creating or funding anything. */
+export async function resolveGovernanceFees(ctx, request, history) {
+    requireFee(history.intent.game === request.game &&
+        history.intent.system === request.system, 'Fee and history scopes do not match.');
+    requireFee(request.mode === 'crafting-complete'
+        ? request.process !== undefined
+        : request.process === undefined, 'The fee route has an invalid Crafting Process selection.');
+    const [governanceAddress, governanceBump] = await derive('StarbaseGovernance', request.system, request.starbaseSeqId);
+    const [cacheAddress, cacheBump] = await derive('CurrencyConfig', request.game);
+    const needsCache = request.mode !== 'crafting-start' || request.hasHab === true;
+    const firstAddresses = request.mode === 'crafting-complete'
+        ? [request.process, cacheAddress]
+        : [
+            governanceAddress,
+            ...(needsCache ? [cacheAddress] : []),
+            request.system,
+        ];
+    const read = async (addresses) => {
+        const rows = await readContextRawAccounts(ctx, addresses, {
+            commitment: 'confirmed',
+        });
+        requireFee(rows.length === addresses.length &&
+            rows.every((raw, index) => !raw ||
+                (raw.address === addresses[index] && raw.slot >= history.slot)), 'Fee-routing reads are incomplete or older than their history context.');
+        return rows;
+    };
+    const rows = await read(firstAddresses);
+    if (request.mode !== 'crafting-complete') {
+        const raw = rows[rows.length - 1];
+        requireFee(raw && !raw.executable, 'The fee route System account is missing or invalid.');
+        const system = starSystemAccountDefinition.decode(raw);
+        const canonical = await deriveStarSystemAddress(request.game, system.systemId);
+        requireFee(raw.address === request.system &&
+            canonical === request.system &&
+            system.game === request.game &&
+            system.sequenceId === request.starbaseSeqId &&
+            system.starbase !== undefined, 'The fee route System does not match its canonical address, Game or active Starbase sequence.');
+    }
+    let currencyCache;
+    if (needsCache) {
+        const value = decode(rows[1], cacheAddress, CURRENCY_CONFIG_CACHE_DISCRIMINATOR, getCurrencyConfigCacheDecoder());
+        requireFee(value.gameId === request.game && value.bump === cacheBump, 'CurrencyCache does not match the configured Game or canonical PDA bump.');
+        currencyCache = { address: cacheAddress, version: value.version };
+    }
+    let governance;
+    let process;
+    let quote;
+    let treasuryGovernance;
+    let treasuryRequired = false;
+    if (request.mode === 'crafting-complete') {
+        const raw = rows[0];
+        requireFee(raw && raw.address === request.process && !raw.executable, 'The selected Crafting Process is missing or invalid.');
+        const value = craftingProcessAccountDefinition.decode(raw);
+        requireFee(value.system === request.system &&
+            value.starbaseSequenceId === request.starbaseSeqId, 'The Crafting Process belongs to a different System or Starbase generation.');
+        process = {
+            address: request.process,
+            version: value.version,
+            ...(value.feeRecipient === undefined
+                ? {}
+                : { feeRecipient: value.feeRecipient }),
+            ...(value.feeGovernance === undefined
+                ? {}
+                : { feeGovernance: value.feeGovernance }),
+            ...(value.feeSnapshot === undefined
+                ? {}
+                : { feeSnapshot: value.feeSnapshot }),
+        };
+        quote = value.feeSnapshot
+            ? {
+                source: 'process-snapshot',
+                params: {
+                    craftingFeeBps: value.feeSnapshot.craftingFeeBasisPoints,
+                    localMarketFeeBps: value.feeSnapshot.localMarketFeeBasisPoints,
+                    localTreasuryShareBps: value.feeSnapshot.localTreasuryShareBasisPoints,
+                },
+            }
+            : { source: 'legacy-process' };
+        treasuryGovernance = value.feeGovernance;
+        treasuryRequired = treasuryGovernance !== undefined;
+    }
+    else {
+        const raw = rows[0];
+        const value = raw
+            ? decode(raw, governanceAddress, STARBASE_GOVERNANCE_DISCRIMINATOR, getStarbaseGovernanceDecoder())
+            : undefined;
+        if (value) {
+            requireFee(value.version === 2 || value.version === 3, 'Starbase governance has an unsupported schema version.');
+            requireFee(value.gameId === request.game &&
+                value.system === request.system &&
+                value.starbaseSeqId === request.starbaseSeqId &&
+                value.bump === governanceBump &&
+                value.enabled <= 1, 'Starbase governance has invalid scope, sequence, bump or enabled state.');
+            requireFee(!(value.version === 3 && history.intent.state === 'absent'), 'This Starbase governance requires initialized daily Democracy history.');
+            governance = {
+                address: governanceAddress,
+                state: 'initialized',
+                version: value.version,
+                enabled: value.enabled,
+                controllerFaction: value.controllerFaction,
+                starbaseSeqId: value.starbaseSeqId,
+                ...(history.intent.state === 'absent' && value.enabled === 1
+                    ? { activeParams: params(value.activeParams) }
+                    : {}),
+            };
+        }
+        else
+            governance = { address: governanceAddress, state: 'absent' };
+        if (history.intent.state === 'initialized')
+            quote = {
+                source: history.intent.enabled === 0
+                    ? 'history-disabled'
+                    : history.intent.generation
+                        ? 'history-generation'
+                        : 'history-policy',
+                params: params(history.intent.effectiveParams),
+            };
+        else if (value?.enabled)
+            quote = { source: 'governance', params: params(value.activeParams) };
+        else
+            quote = {
+                source: 'default',
+                params: {
+                    craftingFeeBps: 10000,
+                    localMarketFeeBps: 0,
+                    localTreasuryShareBps: 0,
+                    treasuryDistributionBps: 0,
+                },
+            };
+        if (request.mode === 'market') {
+            treasuryGovernance = governanceAddress;
+            treasuryRequired = quote.params.localTreasuryShareBps > 0;
+        }
+    }
+    let treasury;
+    if (treasuryGovernance) {
+        const [treasuryAddress, treasuryBump] = await derive('StarbaseTreasury', treasuryGovernance);
+        const [raw] = await read([treasuryAddress]);
+        if (raw) {
+            const value = decode(raw, treasuryAddress, STARBASE_TREASURY_DISCRIMINATOR, getStarbaseTreasuryDecoder());
+            requireFee(value.governance === treasuryGovernance &&
+                value.bump === treasuryBump &&
+                (request.mode !== 'market' || governance?.state === 'initialized'), 'Starbase Treasury does not match its governance or canonical PDA.');
+            treasury = {
+                address: treasuryAddress,
+                state: 'initialized',
+                version: value.version,
+                governance: value.governance,
+            };
+        }
+        else {
+            requireFee(!treasuryRequired, 'This fee route requires a Starbase Treasury that has not been initialized.');
+            treasury = { address: treasuryAddress, state: 'absent' };
+        }
+    }
+    const intent = {
+        request: { ...request },
+        ...(governance ? { governance } : {}),
+        ...(currencyCache ? { currencyCache } : {}),
+        ...(treasury ? { treasury } : {}),
+        ...(process ? { process } : {}),
+        quote,
+    };
+    return {
+        intent,
+        accounts: {
+            ...(request.mode === 'crafting-complete'
+                ? {}
+                : { starbaseGovernance: governanceAddress }),
+            ...(currencyCache ? { currencyCache: cacheAddress } : {}),
+            ...(treasury?.state === 'initialized'
+                ? { starbaseTreasury: treasury.address }
+                : {}),
+        },
+        description: description(intent),
+    };
+}
+/** Compare finite serialized fields; mutable shared balances are deliberately absent. */
+export function matchGovernanceFeesIntent(expected, actual) {
+    const canonical = (value) => JSON.stringify(value, (_key, field) => typeof field === 'bigint'
+        ? field.toString()
+        : field && typeof field === 'object' && !Array.isArray(field)
+            ? Object.fromEntries(Object.entries(field).sort(([left], [right]) => left.localeCompare(right)))
+            : field);
+    return canonical(expected) === canonical(actual);
+}
+//# sourceMappingURL=governance-fees.js.map

package/dist/internal/planning/governance-fees.js.map

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

package/dist/internal/planning/runtime-guards.d.ts

@@ -0,0 +1,43 @@
+import { type Address } from '@solana/kit';
+import type { SageContext } from '../../client/contracts.js';
+import type { PlanPrecondition, PlanStep } from '../../planning/index.js';
+import { type HistoryIntent, type ResolvedDemocracyHistory } from './democracy-history.js';
+import { type XpRuntimeIntent, type XpRuntimeAccounts } from './xp-runtime.js';
+import { resolveGovernanceFees, type FeeIntent } from './governance-fees.js';
+type FeeAccounts = Awaited<ReturnType<typeof resolveGovernanceFees>>['accounts'];
+type BaseGuard = {
+    readonly address: Address;
+    readonly describes: string;
+    readonly dataHash?: never;
+};
+/** Finite runtime eligibility and consumed fee routes, excluding changing balances. */
+export type RuntimeGuard = BaseGuard & ({
+    readonly kind: 'democracy-history';
+    readonly intent: HistoryIntent;
+    readonly accounts: ResolvedDemocracyHistory['accounts'];
+} | {
+    readonly kind: 'xp-runtime';
+    readonly intent: XpRuntimeIntent;
+    readonly accounts: XpRuntimeAccounts;
+} | {
+    readonly kind: 'governance-fees';
+    readonly intent: FeeIntent;
+    readonly accounts: FeeAccounts;
+});
+export type RuntimeWire<T> = T extends bigint ? string : T extends Address ? string : T extends object ? {
+    readonly [K in keyof T]: RuntimeWire<T[K]>;
+} : T;
+export type RuntimeGuardJson = RuntimeWire<RuntimeGuard>;
+export declare function isRuntimeGuard(value: {
+    readonly kind?: unknown;
+}): value is RuntimeGuard;
+/** Strict nested runtime parsing applies both to factory values and persisted JSON. */
+export declare function normalizeRuntimeGuard(value: unknown, field: string, wire?: boolean): RuntimeGuard;
+/** Bigints use canonical decimal strings; schema validation excludes arbitrary object graphs. */
+export declare function runtimeGuardToJSON(guard: RuntimeGuard): RuntimeGuardJson;
+/** Resolve canonical accounts again; shared balances and XP counters are not compared. */
+export declare function revalidateRuntimeGuards(ctx: SageContext, guards: readonly RuntimeGuard[]): Promise<void>;
+/** Old layouts and unguarded persisted instructions fail before assembly or signing. */
+export declare function validateRuntimeInstructions(steps: readonly PlanStep[], preconditions: readonly PlanPrecondition[]): void;
+export {};
+//# sourceMappingURL=runtime-guards.d.ts.map

package/dist/internal/planning/runtime-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-guards.d.ts","sourceRoot":"","sources":["../../../src/internal/planning/runtime-guards.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,OAAO,EAGb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAgB7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAGL,KAAK,aAAa,EAElB,KAAK,wBAAwB,EAC9B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,qBAAqB,EAErB,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAE9B,KAAK,WAAW,GAAG,OAAO,CACxB,UAAU,CAAC,OAAO,qBAAqB,CAAC,CACzC,CAAC,UAAU,CAAC,CAAC;AACd,KAAK,SAAS,GAAG;IACf,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;CAC3B,CAAC;AACF,uFAAuF;AACvF,MAAM,MAAM,YAAY,GAAG,SAAS,GAClC,CACI;IACE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC,UAAU,CAAC,CAAC;CACzD,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;CAChC,CACJ,CAAC;AACJ,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,GACzC,MAAM,GACN,CAAC,SAAS,OAAO,GACf,MAAM,GACN,CAAC,SAAS,MAAM,GACd;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAC9C,CAAC,CAAC;AACV,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;AACzD,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,KAAK,IAAI,YAAY,CAMxB;AAkLD,uFAAuF;AACvF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,IAAI,UAAQ,GACX,YAAY,CAuDd;AACD,iGAAiG;AACjG,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,gBAAgB,CAMxE;AAiBD,0FAA0F;AAC1F,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,SAAS,YAAY,EAAE,GAC9B,OAAO,CAAC,IAAI,CAAC,CAuCf;AAgTD,wFAAwF;AACxF,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,aAAa,EAAE,SAAS,gBAAgB,EAAE,GACzC,IAAI,CAkIN"}