@aephia/atlas-kit 0.6.0-next.12 → 0.6.0-next.121

package/dist/scanning/lifecycle.js

@@ -0,0 +1,93 @@
+import { SageSdkError, InvalidDerivationInputError } from '../client/errors.js';
+import { attachJsonSerialization } from '../internal/json.js';
+import { freezeResolvedSnapshot } from '../internal/resolved-snapshot.js';
+function nonnegative(field, value) {
+    if (value < 0n)
+        throw new InvalidDerivationInputError(field, value, 'Supply a nonnegative slot or radius from a fresh scan snapshot before deriving scan timing or range.');
+}
+function required(value, field) {
+    if (value === undefined)
+        throw new SageSdkError('INVALID_DERIVATION_INPUT', `The scan signal is missing ${field} required by its state. Refetch the signal snapshot before deriving scan timing or range.`);
+    return value;
+}
+function remaining(end, now) {
+    return end > now ? end - now : 0n;
+}
+function finish(value) {
+    return freezeResolvedSnapshot(attachJsonSerialization(value));
+}
+/** Projects signal cooldown, pending entropy and contact expiry using explicit clock values.
+ * Reveal starts at commitSlot + 10 and ends exclusively 256 slots later, matching
+ * the fingerprinted client. No network, polling, clock access or acknowledgement
+ * eligibility is implied; abandonment acknowledgement can shorten cooldown.
+ * @example
+ * ```ts
+ * declare const signal: ScanSignalSnapshot | undefined;
+ * const timing = deriveScanSignalTiming(signal, { slot: 54_000_000n, unixSeconds: 1_790_000_000n });
+ * console.log(timing.entropy?.phase);
+ * ```
+ */
+export function deriveScanSignalTiming(signal, clock) {
+    nonnegative('clock.slot', clock.slot);
+    let entropy;
+    let contactExpiry;
+    if (signal?.status === 'pending-entropy') {
+        const { commitSlot } = required(signal.attempt, 'attempt');
+        nonnegative('attempt.commitSlot', commitSlot);
+        const readyAtSlot = commitSlot + 10n;
+        const deadlineSlot = readyAtSlot + 256n;
+        entropy = {
+            phase: clock.slot < readyAtSlot
+                ? 'waiting'
+                : clock.slot < deadlineSlot
+                    ? 'ready'
+                    : 'expired',
+            readyAtSlot,
+            deadlineSlot,
+            slotsUntilReady: remaining(readyAtSlot, clock.slot),
+        };
+    }
+    if (signal?.status === 'contact') {
+        const { expiresAtUnixSeconds } = required(signal.contact, 'contact');
+        contactExpiry = {
+            expired: clock.unixSeconds >= expiresAtUnixSeconds,
+            remainingSeconds: remaining(expiresAtUnixSeconds, clock.unixSeconds),
+        };
+    }
+    return finish({
+        status: signal?.status ?? 'absent',
+        cooldownRemainingSeconds: signal === undefined
+            ? 0n
+            : remaining(signal.cooldownEndsAtUnixSeconds, clock.unixSeconds),
+        entropy,
+        contactExpiry,
+    });
+}
+/** Compares a contact's recovery radius with exact raw I8F56 coordinates, boundary included.
+ * Supply current raw I8F56 coordinates, not Fleet display coordinates or the
+ * original scan-attempt position. Never reconstruct exact bits from rounded values.
+ * Uses raw components only. This is geometry, not expiry, authority, capacity or
+ * instruction eligibility; an expired Contact still has measurable geometry.
+ * @example
+ * ```ts
+ * declare const signal: ScanSignalSnapshot | undefined, location: ScanCoordinates;
+ * const range = deriveScanRecoveryRange(signal, location);
+ * if (range.kind === 'contact') console.log(range.withinRange);
+ * ```
+ */
+export function deriveScanRecoveryRange(signal, location) {
+    if (signal?.status !== 'contact')
+        return finish({ kind: 'no-contact' });
+    const { target, targetRadius } = required(signal.contact, 'contact');
+    nonnegative('contact.targetRadius.raw', targetRadius.raw);
+    const dx = location.x.raw - target.x.raw, dy = location.y.raw - target.y.raw;
+    const distanceSquaredRaw = dx * dx + dy * dy;
+    const radiusSquaredRaw = targetRadius.raw * targetRadius.raw;
+    return finish({
+        kind: 'contact',
+        withinRange: distanceSquaredRaw <= radiusSquaredRaw,
+        distanceSquaredRaw,
+        radiusSquaredRaw,
+    });
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/scanning/lifecycle.js.map

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

package/dist/scanning/odds.d.ts

@@ -0,0 +1,111 @@
+import type { ScanPatternPolicySnapshot, ScanLootProfileSnapshot, ScanSignalSnapshot } from './signals.js';
+type Policy = ScanPatternPolicySnapshot;
+type Profile = ScanLootProfileSnapshot;
+type Row = Profile['loot'][number];
+type Focus = Row['category'];
+type UnavailableReason = 'missing-policy' | 'missing-loot-profile' | 'unsupported-version' | 'unsupported-pattern' | 'unsupported-loot-layout' | 'game-mismatch' | 'inactive-policy' | 'inactive-loot-profile' | 'pattern-research-locked' | 'region-research-locked' | 'focus-not-allowed' | 'empty-weighted-pool' | 'signal-not-pending' | 'committed-configuration-mismatch';
+type Exclusion = 'pattern' | 'rarity' | 'value-budget' | 'focus' | 'research' | 'not-committed';
+type Provenance = Readonly<{
+    policy: Readonly<Pick<Policy, 'address' | 'game' | 'patternId' | 'revision' | 'contentFingerprint'>> | undefined;
+    lootProfile: Readonly<Pick<Profile, 'address' | 'game' | 'regionId' | 'revision' | 'contentFingerprint'>> | undefined;
+    signal: Readonly<Pick<ScanSignalSnapshot, 'address' | 'sequence'>> | undefined;
+}>;
+type Share = Readonly<{
+    cargo: Row['cargo'];
+    weight: bigint;
+    conditionalProbability: number;
+    perScanProbability: number;
+}>;
+/** Explicit eligibility knowledge for prospective client estimates. Empty tag arrays mean known none.
+ * Regional requirements must describe the supplied loot profile's region. Focus defaults to any.
+ * @example
+ * ```ts
+ * const options: ScanLootOddsOptions = { unlockedResearchTagIds: [12], requiredRegionResearchTagIds: [], exhaustionBasisPoints: 0 };
+ * ```
+ */
+export interface ScanLootOddsOptions {
+    readonly unlockedResearchTagIds: readonly number[];
+    readonly requiredRegionResearchTagIds: readonly number[];
+    readonly exhaustionBasisPoints: number;
+    readonly focus?: Focus;
+}
+/** Client-derived selection estimates, never program-verified probabilities or recovery quantities.
+ * Unavailable results deliberately contain no probability fields. Conditional shares remain meaningful
+ * when contact probability is zero. Probabilities are numeric fractions from zero through one.
+ * @example
+ * ```ts
+ * declare const odds: ScanLootOdds;
+ * if (odds.status === 'available') console.log(odds.resources[0]?.perScanProbability);
+ * ```
+ */
+export type ScanLootOdds = Readonly<{
+    kind: 'client-derived-estimate';
+    basis: 'prospective' | 'committed';
+    provenance: Provenance;
+    toJSON(): unknown;
+}> & (Readonly<{
+    status: 'unavailable';
+    reasons: readonly UnavailableReason[];
+}> | Readonly<{
+    status: 'available';
+    contactChanceBasisPoints: number;
+    contactProbability: number;
+    noContactProbability: number;
+    totalWeight: bigint;
+    eligibleRows: readonly (Share & Readonly<{
+        rowIndex: number;
+    }>)[];
+    excludedRows: readonly Readonly<{
+        rowIndex: number;
+        reasons: readonly Exclusion[];
+    }>[];
+    resources: readonly Share[];
+}>);
+/** Client-derived exhaustion from an explicit clock and retained recovery history.
+ * @example
+ * ```ts
+ * declare const exhaustion: ScanExhaustion;
+ * console.log(exhaustion.exhaustionBasisPoints, exhaustion.effectiveRecoveries);
+ * ```
+ */
+export interface ScanExhaustion {
+    readonly kind: 'client-derived-estimate';
+    readonly exhaustionBasisPoints: number;
+    readonly effectiveRecoveries: number;
+    toJSON(): unknown;
+}
+/** Estimates prospective contact and cargo-selection odds using the fingerprinted client's eligibility rules.
+ * Requires explicit research and exhaustion knowledge. This is not full scan-launch readiness:
+ * permissions, costs, Fleet state, cooldown, target and recovery capacity are outside this calculation.
+ * @example
+ * ```ts
+ * declare const policy: ScanPatternPolicySnapshot, loot: ScanLootProfileSnapshot;
+ * const odds = deriveScanLootOdds(policy, loot, { unlockedResearchTagIds: [], requiredRegionResearchTagIds: [], exhaustionBasisPoints: 0 });
+ * ```
+ */
+export declare function deriveScanLootOdds(policy: Policy | undefined, profile: Profile | undefined, options: ScanLootOddsOptions): ScanLootOdds;
+/** Estimates a pending signal's recorded draw using its committed rows and contact chance.
+ * Revisions AND full fingerprints must match. Current activity, focus and research do not
+ * replace committed eligibility; terminal signals are not random forecasts.
+ * @example
+ * ```ts
+ * declare const signal: ScanSignalSnapshot, policy: ScanPatternPolicySnapshot, loot: ScanLootProfileSnapshot;
+ * const odds = deriveCommittedScanLootOdds(signal, policy, loot);
+ * ```
+ */
+export declare function deriveCommittedScanLootOdds(signal: ScanSignalSnapshot | undefined, policy: Policy | undefined, profile: Profile | undefined): ScanLootOdds;
+/** Applies the client exhaustion decay rule with explicit region and Unix seconds, without clock reads.
+ * An absent signal means known absence of recovery history, not an unknown/unread signal.
+ * Another region, disabled decay or a clock before the last recovery produce zero exhaustion.
+ * @example
+ * ```ts
+ * declare const policy: ScanPatternPolicySnapshot, signal: ScanSignalSnapshot | undefined;
+ * const exhaustion = deriveScanExhaustion(policy, signal, { regionId: 3, unixSeconds: 1_790_000_000n });
+ * ```
+ */
+export declare function deriveScanExhaustion(policy: Policy, signal: ScanSignalSnapshot | undefined, options: Readonly<{
+    regionId: number;
+    unixSeconds: bigint;
+}>): ScanExhaustion;
+export {};
+//# sourceMappingURL=odds.d.ts.map

package/dist/scanning/odds.d.ts.map

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

package/dist/scanning/odds.js

@@ -0,0 +1,294 @@
+import { InvalidDerivationInputError } from '../client/errors.js';
+import { attachJsonSerialization } from '../internal/json.js';
+import { freezeResolvedSnapshot } from '../internal/resolved-snapshot.js';
+const categories = [
+    'any',
+    'industrial',
+    'technology',
+    'tactical',
+    'exotic',
+];
+const rarities = [
+    'common',
+    'uncommon',
+    'rare',
+    'epic',
+    'legendary',
+    'anomalous',
+];
+function finish(value) {
+    return freezeResolvedSnapshot(attachJsonSerialization(value));
+}
+function invalid(field, value) {
+    throw new InvalidDerivationInputError(field, typeof value === 'number' || typeof value === 'bigint' ? value : NaN, 'Supply valid current scanning snapshots and explicit research, exhaustion and clock inputs before estimating scan loot.');
+}
+function integer(field, value, maximum = 65535) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > maximum)
+        invalid(field, value);
+}
+function exact(field, value, nonnegative = true) {
+    if (typeof value !== 'bigint' || (nonnegative && value < 0n))
+        invalid(field, value);
+}
+function tags(field, values) {
+    if (!Array.isArray(values))
+        invalid(field, values);
+    values.forEach((value) => integer(field, value));
+}
+function fingerprint(field, value) {
+    if (typeof value !== 'string' || !/^[0-9a-f]{64}$/.test(value))
+        invalid(field, value);
+}
+function configurations(policy, profile) {
+    const reasons = [];
+    if (!policy)
+        reasons.push('missing-policy');
+    if (!profile)
+        reasons.push('missing-loot-profile');
+    if (!policy || !profile)
+        return reasons;
+    if (policy.version !== 0 || profile.version !== 0)
+        reasons.push('unsupported-version');
+    if (!Number.isInteger(policy.patternId) ||
+        policy.patternId < 0 ||
+        policy.patternId > 4)
+        reasons.push('unsupported-pattern');
+    if (profile.loot.length > 64)
+        reasons.push('unsupported-loot-layout');
+    if (policy.game.address !== profile.game.address)
+        reasons.push('game-mismatch');
+    fingerprint('policy.contentFingerprint', policy.contentFingerprint);
+    fingerprint('lootProfile.contentFingerprint', profile.contentFingerprint);
+    integer('policy.revision', policy.revision, 0xffffffff);
+    integer('lootProfile.revision', profile.revision, 0xffffffff);
+    integer('lootProfile.regionId', profile.regionId);
+    for (const row of profile.loot) {
+        integer('loot.rollWeight', row.rollWeight, 0xffffffff);
+        integer('loot.cargo.id', row.cargo.id);
+    }
+    return reasons;
+}
+function provenance(policy, profile, signal) {
+    return {
+        policy: policy && {
+            address: policy.address,
+            game: { ...policy.game },
+            patternId: policy.patternId,
+            revision: policy.revision,
+            contentFingerprint: policy.contentFingerprint,
+        },
+        lootProfile: profile && {
+            address: profile.address,
+            game: { ...profile.game },
+            regionId: profile.regionId,
+            revision: profile.revision,
+            contentFingerprint: profile.contentFingerprint,
+        },
+        signal: signal && { address: signal.address, sequence: signal.sequence },
+    };
+}
+function result(basis, sources, reasons, profile, selected, excludedRows, chance) {
+    const base = {
+        kind: 'client-derived-estimate',
+        basis,
+        provenance: sources,
+    };
+    if (reasons.length)
+        return finish({ ...base, status: 'unavailable', reasons });
+    const totalWeight = selected.reduce((sum, index) => sum + BigInt(profile.loot[index].rollWeight), 0n);
+    if (totalWeight === 0n)
+        return finish({
+            ...base,
+            status: 'unavailable',
+            reasons: ['empty-weighted-pool'],
+        });
+    const shares = (cargo, weight) => ({
+        cargo: { ...cargo },
+        weight,
+        conditionalProbability: Number(weight) / Number(totalWeight),
+        perScanProbability: Number(weight * BigInt(chance)) / Number(totalWeight * 10000n),
+    });
+    const resourceWeights = new Map();
+    const eligibleRows = selected.map((rowIndex) => {
+        const row = profile.loot[rowIndex];
+        const weight = BigInt(row.rollWeight);
+        const previous = resourceWeights.get(row.cargo.id);
+        resourceWeights.set(row.cargo.id, {
+            cargo: row.cargo,
+            weight: (previous?.weight ?? 0n) + weight,
+        });
+        return { rowIndex, ...shares(row.cargo, weight) };
+    });
+    return finish({
+        ...base,
+        status: 'available',
+        totalWeight,
+        contactChanceBasisPoints: chance,
+        contactProbability: chance / 10000,
+        noContactProbability: (10000 - chance) / 10000,
+        eligibleRows,
+        excludedRows,
+        resources: [...resourceWeights.values()].map(({ cargo, weight }) => shares(cargo, weight)),
+    });
+}
+/** Estimates prospective contact and cargo-selection odds using the fingerprinted client's eligibility rules.
+ * Requires explicit research and exhaustion knowledge. This is not full scan-launch readiness:
+ * permissions, costs, Fleet state, cooldown, target and recovery capacity are outside this calculation.
+ * @example
+ * ```ts
+ * declare const policy: ScanPatternPolicySnapshot, loot: ScanLootProfileSnapshot;
+ * const odds = deriveScanLootOdds(policy, loot, { unlockedResearchTagIds: [], requiredRegionResearchTagIds: [], exhaustionBasisPoints: 0 });
+ * ```
+ */
+export function deriveScanLootOdds(policy, profile, options) {
+    integer('exhaustionBasisPoints', options.exhaustionBasisPoints, 10000);
+    tags('unlockedResearchTagIds', options.unlockedResearchTagIds);
+    tags('requiredRegionResearchTagIds', options.requiredRegionResearchTagIds);
+    const focus = options.focus ?? 'any';
+    if (!categories.includes(focus))
+        invalid('focus', focus);
+    const reasons = configurations(policy, profile);
+    const sources = provenance(policy, profile);
+    if (reasons.length)
+        return result('prospective', sources, reasons, profile, [], [], 0);
+    const p = policy, l = profile;
+    integer('policy.contactChanceBasisPoints', p.contactChanceBasisPoints, 10000);
+    exact('policy.valueBudgetRaw', p.valueBudgetRaw);
+    integer('lootProfile.riskValueMultiplierBasisPoints', l.riskValueMultiplierBasisPoints, 65535);
+    tags('policy.requiredResearchTagIds', p.requiredResearchTagIds);
+    if (!rarities.includes(p.maximumRarity))
+        invalid('policy.maximumRarity', p.maximumRarity);
+    if (!Array.isArray(p.allowedFocusCategories) ||
+        p.allowedFocusCategories.some((category) => !categories.includes(category)))
+        invalid('policy.allowedFocusCategories', p.allowedFocusCategories);
+    if (p.status !== 'active')
+        reasons.push('inactive-policy');
+    if (l.status !== 'active')
+        reasons.push('inactive-loot-profile');
+    const unlocked = new Set(options.unlockedResearchTagIds);
+    if (!p.requiredResearchTagIds.every((tag) => unlocked.has(tag)))
+        reasons.push('pattern-research-locked');
+    if (!options.requiredRegionResearchTagIds.every((tag) => unlocked.has(tag)))
+        reasons.push('region-research-locked');
+    if (focus !== 'any' && !p.allowedFocusCategories.includes(focus))
+        reasons.push('focus-not-allowed');
+    const budget = (p.valueBudgetRaw * BigInt(l.riskValueMultiplierBasisPoints)) / 10000n;
+    const selected = [], excluded = [];
+    l.loot.forEach((row, rowIndex) => {
+        integer('loot.valueUnits', row.valueUnits);
+        tags('loot.supportedPatternIds', row.supportedPatternIds);
+        tags('loot.requiredResearchTagIds', row.requiredResearchTagIds);
+        if (!rarities.includes(row.rarity))
+            invalid('loot.rarity', row.rarity);
+        if (!categories.includes(row.category))
+            invalid('loot.category', row.category);
+        const exclusions = [];
+        if (!row.supportedPatternIds.includes(p.patternId))
+            exclusions.push('pattern');
+        if (rarities.indexOf(row.rarity) > rarities.indexOf(p.maximumRarity))
+            exclusions.push('rarity');
+        if (BigInt(row.valueUnits) > budget)
+            exclusions.push('value-budget');
+        if (focus !== 'any' && row.category !== 'any' && row.category !== focus)
+            exclusions.push('focus');
+        if (!row.requiredResearchTagIds.every((tag) => unlocked.has(tag)))
+            exclusions.push('research');
+        if (exclusions.length)
+            excluded.push({ rowIndex, reasons: exclusions });
+        else
+            selected.push(rowIndex);
+    });
+    const chance = Math.floor((p.contactChanceBasisPoints * (10000 - options.exhaustionBasisPoints)) /
+        10000);
+    return result('prospective', sources, reasons, l, selected, excluded, chance);
+}
+/** Estimates a pending signal's recorded draw using its committed rows and contact chance.
+ * Revisions AND full fingerprints must match. Current activity, focus and research do not
+ * replace committed eligibility; terminal signals are not random forecasts.
+ * @example
+ * ```ts
+ * declare const signal: ScanSignalSnapshot, policy: ScanPatternPolicySnapshot, loot: ScanLootProfileSnapshot;
+ * const odds = deriveCommittedScanLootOdds(signal, policy, loot);
+ * ```
+ */
+export function deriveCommittedScanLootOdds(signal, policy, profile) {
+    const reasons = configurations(policy, profile), sources = provenance(policy, profile, signal);
+    if (signal?.status !== 'pending-entropy')
+        reasons.push('signal-not-pending');
+    if (signal !== undefined &&
+        signal.version !== 0 &&
+        !reasons.includes('unsupported-version'))
+        reasons.push('unsupported-version');
+    if (reasons.length)
+        return result('committed', sources, reasons, profile, [], [], 0);
+    const attempt = signal.attempt;
+    if (!attempt)
+        invalid('signal.attempt', attempt);
+    fingerprint('attempt.policyContentFingerprint', attempt.policyContentFingerprint);
+    fingerprint('attempt.lootProfileContentFingerprint', attempt.lootProfileContentFingerprint);
+    if (signal.game.address !== policy.game.address ||
+        attempt.patternId !== policy.patternId ||
+        attempt.regionId !== profile.regionId ||
+        attempt.policyRevision !== policy.revision ||
+        attempt.lootProfileRevision !== profile.revision ||
+        attempt.policyContentFingerprint !== policy.contentFingerprint ||
+        attempt.lootProfileContentFingerprint !== profile.contentFingerprint)
+        return result('committed', sources, ['committed-configuration-mismatch'], profile, [], [], 0);
+    integer('attempt.contactChanceBasisPoints', attempt.contactChanceBasisPoints, 10000);
+    if (!Array.isArray(attempt.eligibleLootRowIndexes))
+        invalid('attempt.eligibleLootRowIndexes', attempt.eligibleLootRowIndexes);
+    const selected = new Set();
+    for (const index of attempt.eligibleLootRowIndexes) {
+        integer('attempt.eligibleLootRowIndexes', index, profile.loot.length - 1);
+        if (selected.has(index))
+            invalid('attempt.eligibleLootRowIndexes', index);
+        selected.add(index);
+    }
+    const excluded = profile.loot.flatMap((_, rowIndex) => selected.has(rowIndex)
+        ? []
+        : [{ rowIndex, reasons: ['not-committed'] }]);
+    return result('committed', sources, reasons, profile, [...selected], excluded, attempt.contactChanceBasisPoints);
+}
+/** Applies the client exhaustion decay rule with explicit region and Unix seconds, without clock reads.
+ * An absent signal means known absence of recovery history, not an unknown/unread signal.
+ * Another region, disabled decay or a clock before the last recovery produce zero exhaustion.
+ * @example
+ * ```ts
+ * declare const policy: ScanPatternPolicySnapshot, signal: ScanSignalSnapshot | undefined;
+ * const exhaustion = deriveScanExhaustion(policy, signal, { regionId: 3, unixSeconds: 1_790_000_000n });
+ * ```
+ */
+export function deriveScanExhaustion(policy, signal, options) {
+    integer('regionId', options.regionId);
+    exact('unixSeconds', options.unixSeconds, false);
+    integer('policy.exhaustionPerRecoveryBasisPoints', policy.exhaustionPerRecoveryBasisPoints, 10000);
+    integer('policy.maximumExhaustionBasisPoints', policy.maximumExhaustionBasisPoints, 10000);
+    integer('policy.exhaustionDecaySeconds', policy.exhaustionDecaySeconds, 0xffffffff);
+    if (policy.version !== 0 ||
+        (signal !== undefined &&
+            (signal.version !== 0 || signal.game.address !== policy.game.address)))
+        invalid('scanning.versionOrGame', policy.version);
+    let effectiveRecoveries = 0;
+    if (signal !== undefined) {
+        const history = signal.recoveryHistory;
+        if (!history)
+            invalid('signal.recoveryHistory', history);
+        integer('recoveryHistory.lastRegionId', history.lastRegionId);
+        integer('recoveryHistory.consecutiveRecoveries', history.consecutiveRecoveries, 65535);
+        exact('recoveryHistory.lastRecoveryAtUnixSeconds', history.lastRecoveryAtUnixSeconds, false);
+        if (history.lastRegionId === options.regionId &&
+            policy.exhaustionDecaySeconds > 0 &&
+            options.unixSeconds >= history.lastRecoveryAtUnixSeconds) {
+            const decay = (options.unixSeconds - history.lastRecoveryAtUnixSeconds) /
+                BigInt(policy.exhaustionDecaySeconds);
+            const remaining = BigInt(history.consecutiveRecoveries) - decay;
+            effectiveRecoveries = remaining > 0n ? Number(remaining) : 0;
+        }
+    }
+    return finish({
+        kind: 'client-derived-estimate',
+        effectiveRecoveries,
+        exhaustionBasisPoints: Math.min(effectiveRecoveries * policy.exhaustionPerRecoveryBasisPoints, policy.maximumExhaustionBasisPoints),
+    });
+}
+//# sourceMappingURL=odds.js.map

package/dist/scanning/odds.js.map

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

package/dist/scanning/signals.d.ts

@@ -0,0 +1,121 @@
+import { type Address, type EntityRef, type ReadOptions, type SageContext } from '../client/index.js';
+import { type ScanSignalData, type ScanPatternPolicyData, type ScanLootProfileData, type ScanPointData } from '../internal/c4/scan-lifecycle.js';
+import { type CargoDefinitionSummary } from '../registry/index.js';
+type Immutable<T> = T extends (...args: never[]) => unknown ? T : T extends object ? {
+    readonly [K in keyof T]: Immutable<T[K]>;
+} : T;
+type Base<T> = Omit<T, 'game' | 'bump'> & {
+    readonly address: Address;
+    readonly game: EntityRef<'game'>;
+    toJSON(): unknown;
+};
+type CargoRow<T> = Omit<T, 'cargoId'> & {
+    readonly cargo: CargoDefinitionSummary;
+};
+/** Coordinates in map units, with exact signed I8F56 storage retained per axis.
+ * @example
+ * ```ts
+ * declare const point: ScanCoordinates;
+ * console.log(point.x.value, point.x.raw);
+ * ```
+ */
+export type ScanCoordinates = Immutable<ScanPointData>;
+/** Observed signal lifecycle state; it does not predict transition eligibility.
+ * @example
+ * ```ts
+ * const status: ScanSignalStatus = 'pending-entropy';
+ * ```
+ */
+export type ScanSignalStatus = ScanSignalData['status'];
+/** Fleet signal snapshot. Empty signals have no attempt, contact or receipt.
+ * Contact/recovered cargo is resolved only for that state; no-contact has its own XP receipt.
+ * @example
+ * ```ts
+ * declare const signal: ScanSignalSnapshot;
+ * console.log(signal.status, signal.contact?.cargo.name);
+ * ```
+ */
+export type ScanSignalSnapshot = Immutable<Base<Omit<ScanSignalData, 'fleet' | 'ownerProfile' | 'ownerCharacter' | 'contact' | 'receipt' | 'attempt' | 'noContact' | 'ended'>> & {
+    attempt: NonNullable<ScanSignalData['attempt']> | undefined;
+    ended: NonNullable<ScanSignalData['ended']> | undefined;
+    noContact: NonNullable<ScanSignalData['noContact']> | undefined;
+    kind: 'scanSignal';
+    fleet: EntityRef<'fleet'>;
+    ownerProfile: EntityRef<'profile'>;
+    ownerCharacter: EntityRef<'character'>;
+    contact: CargoRow<NonNullable<ScanSignalData['contact']>> | undefined;
+    receipt: CargoRow<NonNullable<ScanSignalData['receipt']>> | undefined;
+}>;
+/** Current scan policy parameters. Basis points use 10,000 = 100%; XP stays exact raw units.
+ * Value budgets and permitted focus categories support client-derived estimates.
+ * @example
+ * ```ts
+ * declare const policy: ScanPatternPolicySnapshot;
+ * console.log(policy.strategy, policy.signalLifetimeSeconds);
+ * ```
+ */
+export type ScanPatternPolicySnapshot = Immutable<Base<ScanPatternPolicyData> & {
+    kind: 'scanPatternPolicy';
+}>;
+/** Regional loot configuration, not a reward forecast. Weights are relative integers.
+ * Pattern eligibility is translated to IDs; opaque quantity modes remain unprojected.
+ * @example
+ * ```ts
+ * declare const profile: ScanLootProfileSnapshot;
+ * console.log(profile.regionId, profile.loot[0]?.cargo.name);
+ * ```
+ */
+export type ScanLootProfileSnapshot = Immutable<Base<Omit<ScanLootProfileData, 'loot'>> & {
+    kind: 'scanLootProfile';
+    loot: readonly CargoRow<ScanLootProfileData['loot'][number]>[];
+}>;
+/** Derives and reads a required ScanSignal for the configured Game. Absence throws AccountNotFoundError.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext, fleet: Address;
+ * const snapshot = await getScanSignalForFleet(ctx, fleet, { refresh: true });
+ * ```
+ */
+export declare function getScanSignalForFleet(context: SageContext, fleet: Address, options?: ReadOptions): Promise<ScanSignalSnapshot>;
+/** Derives and reads an optional ScanSignal for the configured Game. Absence returns undefined; malformed accounts still throw.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext, fleet: Address;
+ * const snapshot = await maybeGetScanSignalForFleet(ctx, fleet, { refresh: true });
+ * ```
+ */
+export declare function maybeGetScanSignalForFleet(context: SageContext, fleet: Address, options?: ReadOptions): Promise<ScanSignalSnapshot | undefined>;
+/** Derives and reads a required ScanPatternPolicy for the configured Game. Absence throws AccountNotFoundError.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext, patternId: number;
+ * const snapshot = await getScanPatternPolicy(ctx, patternId, { refresh: true });
+ * ```
+ */
+export declare function getScanPatternPolicy(context: SageContext, patternId: number, options?: ReadOptions): Promise<ScanPatternPolicySnapshot>;
+/** Derives and reads an optional ScanPatternPolicy for the configured Game. Absence returns undefined; malformed accounts still throw.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext, patternId: number;
+ * const snapshot = await maybeGetScanPatternPolicy(ctx, patternId, { refresh: true });
+ * ```
+ */
+export declare function maybeGetScanPatternPolicy(context: SageContext, patternId: number, options?: ReadOptions): Promise<ScanPatternPolicySnapshot | undefined>;
+/** Derives and reads a required ScanLootProfile for the configured Game. Absence throws AccountNotFoundError.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext, regionId: number;
+ * const snapshot = await getScanLootProfile(ctx, regionId, { refresh: true });
+ * ```
+ */
+export declare function getScanLootProfile(context: SageContext, regionId: number, options?: ReadOptions): Promise<ScanLootProfileSnapshot>;
+/** Derives and reads an optional ScanLootProfile for the configured Game. Absence returns undefined; malformed accounts still throw.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext, regionId: number;
+ * const snapshot = await maybeGetScanLootProfile(ctx, regionId, { refresh: true });
+ * ```
+ */
+export declare function maybeGetScanLootProfile(context: SageContext, regionId: number, options?: ReadOptions): Promise<ScanLootProfileSnapshot | undefined>;
+export {};
+//# sourceMappingURL=signals.d.ts.map