@aephia/atlas-kit 0.6.0-next.57 → 0.6.0-next.59

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aephia/atlas-kit",
-  "version": "0.6.0-next.57",
+  "version": "0.6.0-next.59",
   "description": "Community-maintained non-custodial TypeScript SDK for Star Atlas SAGE C4.",
   "license": "Apache-2.0",
   "author": "Aephia contributors",
@@ -147,6 +147,10 @@
     "./world": {
       "types": "./dist/world/index.d.ts",
       "import": "./dist/world/index.js"
+    },
+    "./scanning/actions": {
+      "types": "./dist/scanning/actions/index.d.ts",
+      "import": "./dist/scanning/actions/index.js"
     }
   },
   "files": [