@aephia/atlas-kit 0.0.0

package/dist/scanning/index.d.ts

@@ -0,0 +1,185 @@
+import { type Address, type DiscoveryRequest, type EntityRef, type ReadOptions, type SageContext } from '../client/index.js';
+import { type ScanFixedValueData, type ScanNoiseMapData } from '../internal/c4/scanning.js';
+import { type CharacterXpCategoryData } from '../internal/c4/identity.js';
+import { type CargoDefinitionSummary } from '../registry/index.js';
+/** Fixed-point scanning value with exact raw storage.
+ * @example
+ * ```ts
+ * const value: ScanFixedValue = { raw: 65_536n, value: 1 };
+ * ```
+ */
+export type ScanFixedValue = ScanFixedValueData;
+/** One translated noise-map row used by a ScanPattern.
+ * @example
+ * ```ts
+ * declare const noise: ScanNoiseMap;
+ * console.log(noise.seedOffset, noise.weight.value);
+ * ```
+ */
+export type ScanNoiseMap = ScanNoiseMapData;
+/** Options supported by targeted ScanPattern catalog discovery.
+ * @example
+ * ```ts
+ * const options: ScanPatternDiscoveryOptions = { commitment: 'confirmed' };
+ * ```
+ */
+export type ScanPatternDiscoveryOptions = Omit<DiscoveryRequest, 'filters' | 'strategy'>;
+/** One cargo-backed scan cost.
+ * @example
+ * ```ts
+ * declare const cost: ScanPatternCost;
+ * console.log(cost.cargo.name, cost.multiplier.value);
+ * ```
+ */
+export interface ScanPatternCost {
+    readonly cargo: CargoDefinitionSummary;
+    readonly multiplier: ScanFixedValue;
+}
+/** One cargo-backed scan outcome and its research-tag requirements.
+ * @example
+ * ```ts
+ * declare const outcome: ScanPatternLootOutcome;
+ * console.log(outcome.output.name, outcome.researchRequirementTagIds);
+ * ```
+ */
+export interface ScanPatternLootOutcome {
+    readonly output: CargoDefinitionSummary;
+    readonly outputAmountRaw: bigint;
+    readonly threshold: ScanFixedValue;
+    readonly rollWeight: ScanFixedValue;
+    readonly xpValue: ScanFixedValue;
+    readonly researchRequirementTagIds: readonly number[];
+}
+/** Immutable, definition-resolved ScanPattern catalog entry.
+ * @example
+ * ```ts
+ * declare const pattern: ScanPatternSnapshot;
+ * console.log(pattern.name, pattern.loot.length);
+ * ```
+ */
+export interface ScanPatternSnapshot {
+    readonly kind: 'scanPattern';
+    readonly address: Address;
+    readonly version: number;
+    readonly bump: number;
+    readonly id: number;
+    readonly name: string;
+    readonly game: EntityRef<'game'>;
+    readonly cooldownMultiplier: ScanFixedValue;
+    readonly blankWeight: ScanFixedValue;
+    readonly blankXpValue: ScanFixedValue;
+    readonly status: 'draft' | 'active';
+    readonly costs: readonly ScanPatternCost[];
+    readonly loot: readonly ScanPatternLootOutcome[];
+    readonly noiseMaps: readonly ScanNoiseMap[];
+    toJSON(): unknown;
+}
+/** Focused read-only scanning projection of one Fleet.
+ * @example
+ * ```ts
+ * declare const state: FleetScanningStateSnapshot;
+ * console.log(state.stats.power, state.cooldownEndsAtUnixSeconds);
+ * ```
+ */
+export interface FleetScanningStateSnapshot {
+    readonly kind: 'fleetScanningState';
+    readonly fleet: EntityRef<'fleet'>;
+    readonly ownerProfile: EntityRef<'profile'>;
+    readonly cooldownEndsAtUnixSeconds: bigint;
+    readonly stats: {
+        readonly power: number;
+        readonly bonus: number;
+        readonly cost: number;
+        readonly cooldownSeconds: number;
+    };
+    toJSON(): unknown;
+}
+/** Focused read-only scanning projection of one derived Character.
+ * @example
+ * ```ts
+ * declare const state: CharacterScanningStateSnapshot;
+ * console.log(state.dataRunnerXp.level, state.modifiers.power.value);
+ * ```
+ */
+export interface CharacterScanningStateSnapshot {
+    readonly kind: 'characterScanningState';
+    readonly character: EntityRef<'character'>;
+    readonly profile: EntityRef<'profile'>;
+    readonly dataRunnerXp: CharacterXpCategoryData & {
+        readonly sequenceId: number;
+    };
+    readonly modifiers: {
+        readonly sequenceId: number;
+        readonly power: ScanFixedValue;
+        readonly cooldown: ScanFixedValue;
+    };
+    readonly researchTagIds: readonly number[];
+    toJSON(): unknown;
+}
+/** Pure Fleet cooldown state at one explicit Unix timestamp.
+ * @example
+ * ```ts
+ * declare const fleet: FleetScanningStateSnapshot;
+ * const state: ScanCooldownState = deriveScanCooldownState(
+ *   fleet,
+ *   1_700_000_000n,
+ * );
+ * ```
+ */
+export type ScanCooldownState = {
+    readonly kind: 'ready';
+} | {
+    readonly kind: 'cooldown';
+    readonly remainingSeconds: bigint;
+};
+/** Derives and reads one required ScanPattern for the configured Game.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * const pattern = await getScanPattern(ctx, 2);
+ * ```
+ */
+export declare function getScanPattern(context: SageContext, patternId: number, options?: ReadOptions): Promise<ScanPatternSnapshot>;
+/** Derives and reads one optional ScanPattern for the configured Game.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * const pattern = await maybeGetScanPattern(ctx, 2);
+ * ```
+ */
+export declare function maybeGetScanPattern(context: SageContext, patternId: number, options?: ReadOptions): Promise<ScanPatternSnapshot | undefined>;
+/** Discovers the configured Game's ScanPattern catalog with targeted filters.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * const patterns = await getScanPatterns(ctx);
+ * ```
+ */
+export declare function getScanPatterns(context: SageContext, options?: ScanPatternDiscoveryOptions): Promise<readonly ScanPatternSnapshot[]>;
+/** Reads one Fleet and returns only its translated scanning state.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: Address;
+ * const state = await getFleetScanningState(ctx, fleet);
+ * ```
+ */
+export declare function getFleetScanningState(context: SageContext, address: Address, options?: ReadOptions): Promise<FleetScanningStateSnapshot>;
+/** Derives one Character from Profile and returns focused scanning progression.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const profile: Address;
+ * const state = await getCharacterScanningState(ctx, profile);
+ * ```
+ */
+export declare function getCharacterScanningState(context: SageContext, profile: Address, options?: ReadOptions): Promise<CharacterScanningStateSnapshot>;
+/** Derives whether a Fleet scan cooldown is ready at an explicit timestamp.
+ * @example
+ * ```ts
+ * declare const fleet: FleetScanningStateSnapshot;
+ * const state = deriveScanCooldownState(fleet, 1_700_000_000n);
+ * ```
+ */
+export declare function deriveScanCooldownState(fleet: FleetScanningStateSnapshot, atUnixSeconds: bigint): ScanCooldownState;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/scanning/index.js

@@ -0,0 +1,207 @@
+import { AccountDecodeError, entityRef, } from '../client/index.js';
+import { discoverScanPatternAccounts, deriveScanPatternAddress, scanPatternAccountDefinition, } from '../internal/c4/scanning.js';
+import { assertCanonicalFleetAddress, fleetAccountDefinition, } from '../internal/c4/fleet.js';
+import { characterAccountDefinition, findCharacterPda, } from '../internal/c4/identity.js';
+import { requireGameAddress } from '../internal/game-context.js';
+import { attachJsonSerialization } from '../internal/json.js';
+import { attachReadMeta, readMeta } from '../internal/read-meta.js';
+import { freezeResolvedSnapshot } from '../internal/resolved-snapshot.js';
+import { resolveCargo, } from '../registry/index.js';
+const PATTERN_SNAPSHOTS = new WeakMap();
+const FLEET_SNAPSHOTS = new WeakMap();
+const CHARACTER_SNAPSHOTS = new WeakMap();
+function metadata(envelope, strategy = 'direct') {
+    return {
+        commitment: envelope.commitment,
+        slot: envelope.slot,
+        source: envelope.source,
+        strategy,
+    };
+}
+async function createPatternSnapshot(context, envelope, strategy) {
+    const game = requireGameAddress(context);
+    if (envelope.data.game !== game) {
+        throw new AccountDecodeError('scanPattern', envelope.address, new RangeError('The ScanPattern belongs to a different Game.'), `ScanPattern ${envelope.address} belongs to Game ${envelope.data.game}, not configured Game ${game}. Verify the pattern id, address, and cluster before retrying.`);
+    }
+    return freezeResolvedSnapshot(attachReadMeta(attachJsonSerialization({
+        address: envelope.address,
+        blankWeight: envelope.data.blankWeight,
+        blankXpValue: envelope.data.blankXpValue,
+        bump: envelope.data.bump,
+        cooldownMultiplier: envelope.data.cooldownMultiplier,
+        costs: await Promise.all(envelope.data.costs.map(async (cost) => ({
+            cargo: await resolveCargo(context, cost.cargoId),
+            multiplier: cost.multiplier,
+        }))),
+        game: entityRef('game', envelope.data.game),
+        id: envelope.data.id,
+        kind: 'scanPattern',
+        loot: await Promise.all(envelope.data.loot.map(async (outcome) => ({
+            output: await resolveCargo(context, outcome.outputCargoId),
+            outputAmountRaw: outcome.outputAmountRaw,
+            researchRequirementTagIds: outcome.researchRequirementTagIds,
+            rollWeight: outcome.rollWeight,
+            threshold: outcome.threshold,
+            xpValue: outcome.xpValue,
+        }))),
+        name: envelope.data.name,
+        noiseMaps: envelope.data.noiseMaps,
+        status: envelope.data.status,
+        version: envelope.data.version,
+    }), metadata(envelope, strategy)));
+}
+function patternSnapshot(context, envelope, strategy) {
+    let cache = PATTERN_SNAPSHOTS.get(envelope);
+    if (cache === undefined) {
+        cache = new Map();
+        PATTERN_SNAPSHOTS.set(envelope, cache);
+    }
+    const existing = cache.get(strategy);
+    if (existing !== undefined)
+        return existing;
+    const pending = createPatternSnapshot(context, envelope, strategy);
+    cache.set(strategy, pending);
+    void pending.catch(() => cache.delete(strategy));
+    return pending;
+}
+/** Derives and reads one required ScanPattern for the configured Game.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * const pattern = await getScanPattern(ctx, 2);
+ * ```
+ */
+export async function getScanPattern(context, patternId, options) {
+    const game = requireGameAddress(context);
+    const address = await deriveScanPatternAddress(game, patternId);
+    const envelope = await context.data.read(scanPatternAccountDefinition, address, options);
+    if (envelope.data.id !== patternId) {
+        throw new AccountDecodeError('scanPattern', address, new RangeError('The ScanPattern id contradicted its derived seeds.'), `ScanPattern ${address} stores id ${String(envelope.data.id)}, not derived id ${String(patternId)}. Verify the configured cluster and pinned PDA recipe before retrying.`);
+    }
+    return patternSnapshot(context, envelope, 'derived');
+}
+/** Derives and reads one optional ScanPattern for the configured Game.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * const pattern = await maybeGetScanPattern(ctx, 2);
+ * ```
+ */
+export async function maybeGetScanPattern(context, patternId, options) {
+    const game = requireGameAddress(context);
+    const address = await deriveScanPatternAddress(game, patternId);
+    const [envelope] = await context.data.readMany(scanPatternAccountDefinition, [address], options);
+    if (envelope === undefined)
+        return undefined;
+    if (envelope.data.id !== patternId) {
+        throw new AccountDecodeError('scanPattern', address, new RangeError('The ScanPattern id contradicted its derived seeds.'));
+    }
+    return patternSnapshot(context, envelope, 'derived');
+}
+/** Discovers the configured Game's ScanPattern catalog with targeted filters.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * const patterns = await getScanPatterns(ctx);
+ * ```
+ */
+export async function getScanPatterns(context, options) {
+    requireGameAddress(context);
+    const envelopes = await discoverScanPatternAccounts(context, options);
+    const snapshots = await Promise.all(envelopes.map((envelope) => patternSnapshot(context, envelope, 'targeted-program-accounts')));
+    return Object.freeze(attachReadMeta(snapshots, readMeta(envelopes)));
+}
+/** Reads one Fleet and returns only its translated scanning state.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const fleet: Address;
+ * const state = await getFleetScanningState(ctx, fleet);
+ * ```
+ */
+export async function getFleetScanningState(context, address, options) {
+    const game = requireGameAddress(context);
+    const envelope = await context.data.read(fleetAccountDefinition, address, options);
+    if (envelope.data.game !== game) {
+        throw new AccountDecodeError('fleet', address, new RangeError('The Fleet belongs to a different Game.'), `Fleet ${address} belongs to Game ${envelope.data.game}, not configured Game ${game}. Verify the Fleet address and cluster before retrying.`);
+    }
+    await assertCanonicalFleetAddress(envelope);
+    const existing = FLEET_SNAPSHOTS.get(envelope);
+    if (existing !== undefined)
+        return existing;
+    const misc = envelope.data.stats.misc;
+    const snapshot = freezeResolvedSnapshot(attachReadMeta(attachJsonSerialization({
+        cooldownEndsAtUnixSeconds: envelope.data.scanCooldownExpiresAt,
+        fleet: entityRef('fleet', envelope.address),
+        kind: 'fleetScanningState',
+        ownerProfile: entityRef('profile', envelope.data.ownerProfile),
+        stats: {
+            bonus: misc.scanBonus,
+            cooldownSeconds: misc.scanCoolDownSeconds,
+            cost: misc.scanCost,
+            power: misc.scanPower,
+        },
+    }), metadata(envelope)));
+    FLEET_SNAPSHOTS.set(envelope, snapshot);
+    return snapshot;
+}
+/** Derives one Character from Profile and returns focused scanning progression.
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const profile: Address;
+ * const state = await getCharacterScanningState(ctx, profile);
+ * ```
+ */
+export async function getCharacterScanningState(context, profile, options) {
+    const game = requireGameAddress(context);
+    const address = await findCharacterPda(profile, game);
+    const envelope = await context.data.read(characterAccountDefinition, address, options);
+    if (envelope.data.game !== game || envelope.data.playerProfile !== profile) {
+        throw new AccountDecodeError('character', address, new RangeError('The Character contradicted its derived Game/Profile.'), `Character ${address} does not match Profile ${profile} and configured Game ${game}. Verify the Profile address and cluster before retrying.`);
+    }
+    const existing = CHARACTER_SNAPSHOTS.get(envelope);
+    if (existing !== undefined)
+        return existing;
+    const modifiers = envelope.data.modifiers;
+    const snapshot = freezeResolvedSnapshot(attachReadMeta(attachJsonSerialization({
+        character: entityRef('character', envelope.address),
+        dataRunnerXp: {
+            ...envelope.data.xp.dataRunner,
+            sequenceId: envelope.data.xp.seqId,
+        },
+        kind: 'characterScanningState',
+        modifiers: {
+            cooldown: {
+                raw: modifiers.values.scanCoolDownModifierRaw,
+                value: modifiers.values.scanCoolDownModifier,
+            },
+            power: {
+                raw: modifiers.values.scanPowerModifierRaw,
+                value: modifiers.values.scanPowerModifier,
+            },
+            sequenceId: modifiers.seqId,
+        },
+        profile: entityRef('profile', profile),
+        researchTagIds: modifiers.values.researchTags,
+    }), metadata(envelope, 'derived')));
+    CHARACTER_SNAPSHOTS.set(envelope, snapshot);
+    return snapshot;
+}
+/** Derives whether a Fleet scan cooldown is ready at an explicit timestamp.
+ * @example
+ * ```ts
+ * declare const fleet: FleetScanningStateSnapshot;
+ * const state = deriveScanCooldownState(fleet, 1_700_000_000n);
+ * ```
+ */
+export function deriveScanCooldownState(fleet, atUnixSeconds) {
+    if (atUnixSeconds >= fleet.cooldownEndsAtUnixSeconds) {
+        return { kind: 'ready' };
+    }
+    return {
+        kind: 'cooldown',
+        remainingSeconds: fleet.cooldownEndsAtUnixSeconds - atUnixSeconds,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/scanning/index.js.map

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

package/dist/starbases/actions/index.d.ts

@@ -0,0 +1,60 @@
+import { type Address } from '@solana/kit';
+import type { SageContext } from '../../client/contracts.js';
+import type { EntityRef } from '../../client/refs.js';
+import { type WorldStarbaseData } from '../../internal/c4/world.js';
+import { type Plan } from '../../planning/index.js';
+interface CharacterSnapshot {
+    readonly kind: 'character';
+    readonly address: Address;
+    readonly game: Address;
+    readonly profile: EntityRef<'profile'>;
+}
+interface StarSystemSnapshot {
+    readonly kind: 'starSystem';
+    readonly address: Address;
+    readonly game: Address;
+    readonly systemId: number;
+    readonly name: string;
+    readonly starbase?: WorldStarbaseData;
+}
+/** Address-only StarbasePlayer registration input.
+ *
+ * The funder is the sole required signer and pays account rent. Reusing the
+ * later assembly fee payer is convenient, but the planner does not require the
+ * two addresses to match.
+ *
+ * @example
+ * ```ts
+ * declare const funder: Address;
+ * const options: PlanRegisterStarbasePlayerOptions = { funder };
+ * ```
+ */
+export interface PlanRegisterStarbasePlayerOptions {
+    readonly funder: Address;
+}
+/** Plans one StarbasePlayer registration without signing, assembly, or writes.
+ *
+ * The Character and Star System must already be loaded public snapshots. The
+ * planner derives and directly validates every plumbing account, requires the
+ * current fail-closed Starbase FactionOwnership sidecar, and returns a Plan only
+ * when the canonical StarbasePlayer address is absent. Optional faction
+ * expansion accounts use the generated omitted-account convention.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const character: CharacterSnapshot;
+ * declare const system: StarSystemSnapshot;
+ * declare const funder: Address;
+ * const plan = await planRegisterStarbasePlayer(
+ *   ctx,
+ *   character,
+ *   system,
+ *   { funder },
+ * );
+ * console.log(plan.describe());
+ * ```
+ */
+export declare function planRegisterStarbasePlayer(ctx: SageContext, character: CharacterSnapshot, system: StarSystemSnapshot, input: PlanRegisterStarbasePlayerOptions): Promise<Plan>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/starbases/actions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/starbases/actions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAEzE,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAIzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAoBtD,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAEL,KAAK,IAAI,EAEV,MAAM,yBAAyB,CAAC;AAEjC,UAAU,iBAAiB;IACzB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CACxC;AAED,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAuGD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,WAAW,EAChB,SAAS,EAAE,iBAAiB,EAC5B,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,iCAAiC,GACvC,OAAO,CAAC,IAAI,CAAC,CAiQf"}