@aephia/atlas-kit 0.0.0

package/dist/planning/plan-sequence.d.ts

@@ -0,0 +1,244 @@
+import type { Signature } from '@solana/kit';
+import type { ClusterIdentity } from '../client/contracts.js';
+import { type SageSdkErrorCode } from '../client/errors.js';
+import type { Plan } from './index.js';
+declare const PLAN_SEQUENCE_FINGERPRINT_BRAND: unique symbol;
+/** Stable SHA-256 identity for one cluster-bound ordered Plan sequence.
+ *
+ * @example
+ * ```ts
+ * declare const fingerprint: PlanSequenceFingerprint;
+ * console.log(fingerprint.length); // 64
+ * ```
+ */
+export type PlanSequenceFingerprint = string & {
+    readonly [PLAN_SEQUENCE_FINGERPRINT_BRAND]: true;
+};
+/** Public confirmation evidence available to later lazy step preparation.
+ *
+ * @example
+ * ```ts
+ * declare const confirmed: ConfirmedStep;
+ * console.log(confirmed.stepId, confirmed.signature);
+ * ```
+ */
+export type ConfirmedStep = Readonly<{
+    stepId: string;
+    index: number;
+    signature: Signature;
+    slot: bigint;
+    commitment: 'confirmed' | 'finalized';
+}>;
+/** Stable sequence progress supplied to one capability-owned step callback.
+ *
+ * @example
+ * ```ts
+ * declare const context: PlanSequenceStepContext;
+ * console.log(context.sequenceId, context.stepId, context.confirmed.length);
+ * ```
+ */
+export type PlanSequenceStepContext = Readonly<{
+    sequenceId: string;
+    stepId: string;
+    index: number;
+    confirmed: readonly ConfirmedStep[];
+}>;
+/** Exact result of freshly preparing one sequence step.
+ *
+ * A waiting timestamp is a canonical UTC ISO-8601 string. It is advisory; the
+ * planning core neither interprets it nor polls automatically.
+ *
+ * @example
+ * ```ts
+ * declare const readiness: PlanSequenceReadiness;
+ * if (readiness.status === 'ready') console.log(readiness.plan.describe());
+ * ```
+ */
+export type PlanSequenceReadiness = Readonly<{
+    status: 'ready';
+    plan: Plan;
+}> | Readonly<{
+    status: 'waiting';
+    reason: string;
+    notBefore?: string;
+}>;
+/** One stable lazy step in a Plan sequence.
+ *
+ * The callback may close over capability context. It creates no Plan until the
+ * caller reaches this step and invokes it with current progress.
+ *
+ * @example
+ * ```ts
+ * declare const plan: Plan;
+ * const step: PlanSequenceStep = {
+ *   id: 'undock',
+ *   prepare: async () => ({ status: 'ready', plan }),
+ * };
+ * ```
+ */
+export interface PlanSequenceStep {
+    readonly id: string;
+    prepare(context: PlanSequenceStepContext): Promise<PlanSequenceReadiness>;
+}
+/** Exact caller-owned input accepted by `createPlanSequence`.
+ *
+ * @example
+ * ```ts
+ * declare const step: PlanSequenceStep;
+ * const input: CreatePlanSequenceInput = {
+ *   cluster: 'zink-ptr',
+ *   sequenceId: 'fleet-round-trip',
+ *   revision: 0,
+ *   steps: [step],
+ * };
+ * ```
+ */
+export interface CreatePlanSequenceInput {
+    readonly cluster: ClusterIdentity;
+    readonly sequenceId: string;
+    readonly revision: number;
+    readonly steps: readonly PlanSequenceStep[];
+}
+/** Inert, immutable itinerary with cluster-bound resume identity.
+ *
+ * `describe()` names stable step identities only. Each actual Plan remains
+ * lazy and must be presented separately when fresh authorization is requested.
+ *
+ * @example
+ * ```ts
+ * declare const sequence: PlanSequence;
+ * console.log(sequence.fingerprint, sequence.describe());
+ * ```
+ */
+export interface PlanSequence {
+    readonly cluster: ClusterIdentity;
+    readonly sequenceId: string;
+    readonly revision: number;
+    readonly steps: readonly PlanSequenceStep[];
+    readonly fingerprint: PlanSequenceFingerprint;
+    describe(): readonly string[];
+}
+/** @internal Distinguishes a capability callback rejection from malformed readiness data. */
+export declare class PlanSequencePreparationBoundaryError extends Error {
+    constructor();
+}
+/** Every public sequence coordination status.
+ *
+ * `completed` is the only successful terminal status.
+ *
+ * @example
+ * ```ts
+ * const status: PlanSequenceStatus = 'waiting';
+ * ```
+ */
+export type PlanSequenceStatus = 'waiting' | 'paused' | 'failed' | 'unknown' | 'completed';
+/** Finite lifecycle phase safe to expose in a sequence result.
+ *
+ * @example
+ * ```ts
+ * const phase: PlanSequencePhase = 'preparing';
+ * ```
+ */
+export type PlanSequencePhase = 'preparing' | 'prepared' | 'signing' | 'signed' | 'invoking' | 'submitted' | 'confirmed';
+/** Sequence-owned failure codes that never carry raw callback diagnostics.
+ *
+ * @example
+ * ```ts
+ * const code: PlanSequenceErrorCode = 'SEQUENCE_PREPARATION_FAILED';
+ * ```
+ */
+export type PlanSequenceErrorCode = 'SEQUENCE_IDENTITY_MISMATCH' | 'SEQUENCE_CHECKPOINT_INVALID' | 'SEQUENCE_CONFIRMATION_UNVERIFIABLE' | 'SEQUENCE_ATTEMPT_UNRESOLVED' | 'SEQUENCE_PREPARATION_FAILED' | 'SEQUENCE_PERSISTENCE_FAILED' | 'SEQUENCE_PRESENTATION_FAILED';
+/** Finite error code carried by a failed or unknown sequence result.
+ *
+ * Existing planning and execution errors retain their public SDK code; errors
+ * crossing callback or persistence boundaries use a sequence-owned code.
+ *
+ * @example
+ * ```ts
+ * const code: PlanSequenceResultCode = 'INVALID_ACTION_INPUT';
+ * ```
+ */
+export type PlanSequenceResultCode = PlanSequenceErrorCode | SageSdkErrorCode;
+/** Finite safe result envelope for future checkpoint-backed coordination.
+ *
+ * The checkpoint codec supplies the generic checkpoint value. Raw errors,
+ * signers, transactions, blockhashes, and callback values are never fields.
+ * A boundary pause is `preparing` before the first step or `confirmed` after a
+ * completed step. If saving an observable signed attempt fails before
+ * submission, the result remains a signature-bearing `failed` outcome.
+ *
+ * @example
+ * ```ts
+ * declare const result: PlanSequenceResult<{ readonly v: 1 }>;
+ * if (result.status === 'failed') console.log(result.code, result.message);
+ * ```
+ */
+export type PlanSequenceResult<Checkpoint = unknown> = Readonly<{
+    status: 'waiting';
+    stepId: string;
+    index: number;
+    phase: 'preparing';
+    reason: string;
+    notBefore?: string;
+    checkpoint: Checkpoint;
+}> | Readonly<{
+    status: 'paused';
+    stepId: string;
+    index: number;
+    phase: 'preparing' | 'confirmed';
+    checkpoint: Checkpoint;
+}> | Readonly<{
+    status: 'failed';
+    stepId: string;
+    index: number;
+    phase: 'preparing' | 'prepared' | 'signing';
+    code: PlanSequenceResultCode;
+    message: string;
+    checkpoint: Checkpoint;
+}> | Readonly<{
+    status: 'failed';
+    stepId: string;
+    index: number;
+    phase: 'signed';
+    signature: Signature;
+    code: 'SEQUENCE_PERSISTENCE_FAILED';
+    message: string;
+    checkpoint: Checkpoint;
+}> | Readonly<{
+    status: 'unknown';
+    stepId: string;
+    index: number;
+    phase: 'signed' | 'invoking' | 'submitted';
+    signature?: Signature;
+    code: PlanSequenceResultCode;
+    message: string;
+    checkpoint: Checkpoint;
+}> | Readonly<{
+    status: 'completed';
+    stepId: string;
+    index: number;
+    phase: 'confirmed';
+    signature?: Signature;
+    checkpoint: Checkpoint;
+}>;
+/** Creates an inert Plan sequence and its canonical cluster-bound fingerprint.
+ *
+ * Construction invokes no step callback and performs no context, wallet,
+ * signer, or network work. The only asynchronous operation is WebCrypto
+ * SHA-256 over the accepted canonical identity bytes.
+ *
+ * @example
+ * ```ts
+ * declare const step: PlanSequenceStep;
+ * const sequence = await createPlanSequence({
+ *   cluster: 'zink-ptr',
+ *   sequenceId: 'fleet-round-trip',
+ *   revision: 0,
+ *   steps: [step],
+ * });
+ * console.log(sequence.fingerprint);
+ * ```
+ */
+export declare function createPlanSequence(input: CreatePlanSequenceInput): Promise<PlanSequence>;
+export {};
+//# sourceMappingURL=plan-sequence.d.ts.map

package/dist/planning/plan-sequence.d.ts.map

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

package/dist/planning/plan-sequence.js

@@ -0,0 +1,264 @@
+import { InvalidActionInputError, } from '../client/errors.js';
+import { isPlanInstance } from './plan-instances.js';
+const FINGERPRINT_DOMAIN = 'aephia-atlas-kit/plan-sequence-fingerprint/1';
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const CUSTOM_CLUSTER_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,62})$/u;
+const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+/** @internal Distinguishes a capability callback rejection from malformed readiness data. */
+export class PlanSequencePreparationBoundaryError extends Error {
+    constructor() {
+        super('PlanSequence preparation callback rejected.');
+        this.name = 'PlanSequencePreparationBoundaryError';
+    }
+}
+function summarize(value) {
+    if (typeof value === 'number' || typeof value === 'string')
+        return value;
+    if (value === null)
+        return 'null';
+    return typeof value;
+}
+function invalid(field, value, acceptedRange) {
+    throw new InvalidActionInputError(field, summarize(value), acceptedRange, 'Correct this PlanSequence field and create the sequence again before retrying.');
+}
+function readDataRecord(value, field, acceptedRange = 'a plain object with data properties') {
+    try {
+        if (value === null ||
+            typeof value !== 'object' ||
+            Array.isArray(value) ||
+            (Object.getPrototypeOf(value) !== Object.prototype &&
+                Object.getPrototypeOf(value) !== null)) {
+            return invalid(field, value, acceptedRange);
+        }
+        const copy = {};
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== 'string') {
+                return invalid(field, 'symbol-keyed property', acceptedRange);
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (descriptor === undefined || !('value' in descriptor)) {
+                return invalid(`${field}.${key}`, 'accessor property', 'a data property');
+            }
+            copy[key] = descriptor.value;
+        }
+        return copy;
+    }
+    catch (error) {
+        if (error instanceof InvalidActionInputError)
+            throw error;
+        return invalid(field, 'unreadable object', acceptedRange);
+    }
+}
+function assertKeys(value, field, required, optional = []) {
+    const accepted = new Set([...required, ...optional]);
+    const missing = required.find((key) => !Object.hasOwn(value, key));
+    const unexpected = Object.keys(value).find((key) => !accepted.has(key));
+    if (missing !== undefined || unexpected !== undefined) {
+        invalid(field, missing === undefined ? `unexpected ${unexpected}` : `missing ${missing}`, `exactly the fields ${[...required, ...optional].join(', ')}`);
+    }
+}
+function readDenseArray(value, field) {
+    try {
+        if (!Array.isArray(value)) {
+            return invalid(field, value, 'a dense ordered array');
+        }
+        const values = [];
+        for (let index = 0; index < value.length; index += 1) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, index);
+            if (descriptor === undefined || !('value' in descriptor)) {
+                invalid(`${field}[${String(index)}]`, descriptor === undefined ? undefined : 'accessor property', 'a present data element');
+            }
+            values[index] = descriptor.value;
+        }
+        return values;
+    }
+    catch (error) {
+        if (error instanceof InvalidActionInputError)
+            throw error;
+        return invalid(field, 'unreadable array', 'a dense ordered array');
+    }
+}
+function readIdentifier(value, field) {
+    if (typeof value !== 'string') {
+        return invalid(field, value, '1 to 128 ASCII characters matching [A-Za-z0-9][A-Za-z0-9._:-]*');
+    }
+    const normalized = value.normalize('NFC');
+    if (!IDENTIFIER_PATTERN.test(normalized)) {
+        return invalid(field, value, '1 to 128 ASCII characters matching [A-Za-z0-9][A-Za-z0-9._:-]*');
+    }
+    return normalized;
+}
+function normalizeCluster(cluster) {
+    if (cluster === 'zink-ptr') {
+        return { identity: cluster, token: cluster };
+    }
+    const value = readDataRecord(cluster, 'planSequence.cluster');
+    assertKeys(value, 'planSequence.cluster', ['name']);
+    if (typeof value.name !== 'string') {
+        return invalid('planSequence.cluster.name', value.name, '1 to 63 lowercase ASCII letters, digits, or hyphens, starting with a letter or digit');
+    }
+    const name = value.name.normalize('NFC');
+    if (!CUSTOM_CLUSTER_PATTERN.test(name)) {
+        return invalid('planSequence.cluster.name', value.name, '1 to 63 lowercase ASCII letters, digits, or hyphens, starting with a letter or digit');
+    }
+    return {
+        identity: Object.freeze({ name }),
+        token: `custom:${name}`,
+    };
+}
+function readRevision(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
+        ? value
+        : invalid('planSequence.revision', value, 'a non-negative safe integer');
+}
+function readTimestamp(value, field) {
+    if (typeof value !== 'string' ||
+        !ISO_TIMESTAMP_PATTERN.test(value) ||
+        Number.isNaN(Date.parse(value)) ||
+        new Date(value).toISOString() !== value) {
+        return invalid(field, value, 'a canonical UTC ISO-8601 timestamp such as 2026-08-28T12:00:00.000Z');
+    }
+    return value;
+}
+function normalizeReadiness(value, field) {
+    const readiness = readDataRecord(value, field);
+    if (readiness.status === 'ready') {
+        assertKeys(readiness, field, ['status', 'plan']);
+        if (!isPlanInstance(readiness.plan)) {
+            return invalid(`${field}.plan`, readiness.plan, 'a Plan created by createPlan, planFromJSON, or combinePlans');
+        }
+        return Object.freeze({ status: 'ready', plan: readiness.plan });
+    }
+    if (readiness.status === 'waiting') {
+        assertKeys(readiness, field, ['status', 'reason'], ['notBefore']);
+        if (typeof readiness.reason !== 'string') {
+            return invalid(`${field}.reason`, readiness.reason, 'a string');
+        }
+        return Object.freeze({
+            status: 'waiting',
+            reason: readiness.reason,
+            ...(readiness.notBefore === undefined
+                ? {}
+                : {
+                    notBefore: readTimestamp(readiness.notBefore, `${field}.notBefore`),
+                }),
+        });
+    }
+    return invalid(`${field}.status`, readiness.status, 'exactly ready or waiting');
+}
+function normalizeStep(value, index) {
+    const field = `planSequence.steps[${String(index)}]`;
+    const step = readDataRecord(value, field);
+    assertKeys(step, field, ['id', 'prepare']);
+    const id = readIdentifier(step.id, `${field}.id`);
+    if (typeof step.prepare !== 'function') {
+        return invalid(`${field}.prepare`, step.prepare, 'an async preparation callback');
+    }
+    const prepare = step.prepare;
+    return Object.freeze({
+        id,
+        prepare: async (context) => {
+            let readiness;
+            try {
+                readiness = await prepare(context);
+            }
+            catch {
+                throw new PlanSequencePreparationBoundaryError();
+            }
+            return normalizeReadiness(readiness, `${field}.prepare result`);
+        },
+    });
+}
+function lengthPrefixedBytes(value) {
+    const encoder = new TextEncoder();
+    const valueBytes = encoder.encode(value);
+    const prefixBytes = encoder.encode(`${String(valueBytes.length)}:`);
+    const bytes = new Uint8Array(prefixBytes.length + valueBytes.length);
+    bytes.set(prefixBytes);
+    bytes.set(valueBytes, prefixBytes.length);
+    return bytes;
+}
+function canonicalFingerprintBytes(fields) {
+    const encoded = fields.map(lengthPrefixedBytes);
+    const byteLength = encoded.reduce((total, field) => total + field.length, 0);
+    const bytes = new Uint8Array(byteLength);
+    let offset = 0;
+    for (const field of encoded) {
+        bytes.set(field, offset);
+        offset += field.length;
+    }
+    return bytes;
+}
+async function fingerprint(fields) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', canonicalFingerprintBytes(fields));
+    return [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+}
+function itinerary(sequenceId, steps) {
+    return Object.freeze([
+        `Plan sequence ${sequenceId} is a non-atomic journey.`,
+        ...steps.map((step, index) => `Step ${String(index + 1)} (${step.id}) is one transaction; its Plan is freshly prepared only when this step is reached.`),
+        'Every transaction requires fresh authorization.',
+    ]);
+}
+/** Creates an inert Plan sequence and its canonical cluster-bound fingerprint.
+ *
+ * Construction invokes no step callback and performs no context, wallet,
+ * signer, or network work. The only asynchronous operation is WebCrypto
+ * SHA-256 over the accepted canonical identity bytes.
+ *
+ * @example
+ * ```ts
+ * declare const step: PlanSequenceStep;
+ * const sequence = await createPlanSequence({
+ *   cluster: 'zink-ptr',
+ *   sequenceId: 'fleet-round-trip',
+ *   revision: 0,
+ *   steps: [step],
+ * });
+ * console.log(sequence.fingerprint);
+ * ```
+ */
+export async function createPlanSequence(input) {
+    const value = readDataRecord(input, 'planSequence');
+    assertKeys(value, 'planSequence', [
+        'cluster',
+        'sequenceId',
+        'revision',
+        'steps',
+    ]);
+    const cluster = normalizeCluster(value.cluster);
+    const sequenceId = readIdentifier(value.sequenceId, 'planSequence.sequenceId');
+    const revision = readRevision(value.revision);
+    const stepValues = readDenseArray(value.steps, 'planSequence.steps');
+    if (stepValues.length === 0) {
+        invalid('planSequence.steps', stepValues.length, 'one or more ordered steps');
+    }
+    const steps = Object.freeze(stepValues.map(normalizeStep));
+    const seenStepIds = new Set();
+    for (const [index, step] of steps.entries()) {
+        if (seenStepIds.has(step.id)) {
+            invalid(`planSequence.steps[${String(index)}].id`, step.id, 'a step id unique within this sequence');
+        }
+        seenStepIds.add(step.id);
+    }
+    const descriptions = itinerary(sequenceId, steps);
+    const planSequence = {
+        cluster: cluster.identity,
+        sequenceId,
+        revision,
+        steps,
+        fingerprint: await fingerprint([
+            FINGERPRINT_DOMAIN,
+            cluster.token,
+            sequenceId,
+            String(revision),
+            String(steps.length),
+            ...steps.map((step) => step.id),
+        ]),
+        describe: () => descriptions,
+    };
+    return Object.freeze(planSequence);
+}
+//# sourceMappingURL=plan-sequence.js.map

package/dist/planning/plan-sequence.js.map

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

package/dist/planning/simulation.d.ts

@@ -0,0 +1,50 @@
+import { type Address } from '@solana/kit';
+import type { SageContext } from '../client/contracts.js';
+import type { Plan } from './index.js';
+import { type AssemblyPolicy } from './assembly.js';
+/** Return data emitted by the last program to set it during simulation.
+ *
+ * @example
+ * ```ts
+ * declare const returnData: SimulationReturnData;
+ * console.log(returnData.programAddress, returnData.data);
+ * ```
+ */
+export interface SimulationReturnData {
+    readonly programAddress: Address;
+    readonly data: string;
+}
+/** Node-provenance result from simulating one unsigned Plan.
+ *
+ * @example
+ * ```ts
+ * declare const result: SimulationResult;
+ * console.log(result.slot, result.replacementBlockhash.blockhash);
+ * ```
+ */
+export interface SimulationResult {
+    readonly slot: bigint;
+    readonly unitsConsumed: bigint | undefined;
+    readonly logs: readonly string[];
+    readonly returnData?: SimulationReturnData;
+    readonly replacementBlockhash: Readonly<{
+        blockhash: string;
+        lastValidBlockHeight: bigint;
+    }>;
+}
+/** Simulates one Plan without receiving or invoking a signer.
+ *
+ * The same assembly policy used for execution produces the unsigned transaction.
+ * The node replaces its recent blockhash and verifies no signatures.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const plan: Plan;
+ * declare const feePayer: Address;
+ * const result = await simulatePlan(ctx, plan, { feePayer });
+ * console.log(result.logs, result.unitsConsumed);
+ * ```
+ */
+export declare function simulatePlan(context: SageContext, plan: Plan, policy: AssemblyPolicy): Promise<SimulationResult>;
+//# sourceMappingURL=simulation.d.ts.map

package/dist/planning/simulation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../../src/planning/simulation.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,OAAO,EAEb,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAEL,KAAK,cAAc,EAIpB,MAAM,eAAe,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAC3C,QAAQ,CAAC,oBAAoB,EAAE,QAAQ,CAAC;QACtC,SAAS,EAAE,MAAM,CAAC;QAClB,oBAAoB,EAAE,MAAM,CAAC;KAC9B,CAAC,CAAC;CACJ;AAsBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,gBAAgB,CAAC,CA+C3B"}

package/dist/planning/simulation.js

@@ -0,0 +1,69 @@
+import { getBase64EncodedWireTransaction, } from '@solana/kit';
+import { SageSdkError } from '../client/errors.js';
+import { assembleValidatedPlan, requireWriteRpc, validateAssemblyPolicy, validatePlan, } from './assembly.js';
+class SimulationFailedError extends SageSdkError {
+    transactionError;
+    logs;
+    unitsConsumed;
+    constructor(transactionError, logs, unitsConsumed) {
+        super('SIMULATION_FAILED', 'The unsigned Plan simulation failed on chain. Inspect the transaction error and program logs, correct the Plan inputs, and create a new Plan before retrying.');
+        this.transactionError = transactionError;
+        this.logs = logs;
+        if (unitsConsumed !== undefined)
+            this.unitsConsumed = unitsConsumed;
+    }
+}
+/** Simulates one Plan without receiving or invoking a signer.
+ *
+ * The same assembly policy used for execution produces the unsigned transaction.
+ * The node replaces its recent blockhash and verifies no signatures.
+ *
+ * @example
+ * ```ts
+ * declare const ctx: SageContext;
+ * declare const plan: Plan;
+ * declare const feePayer: Address;
+ * const result = await simulatePlan(ctx, plan, { feePayer });
+ * console.log(result.logs, result.unitsConsumed);
+ * ```
+ */
+export async function simulatePlan(context, plan, policy) {
+    validatePlan(plan);
+    const validatedPolicy = validateAssemblyPolicy(policy);
+    const writeRpc = requireWriteRpc(context);
+    const transaction = await assembleValidatedPlan(writeRpc, plan, validatedPolicy);
+    const response = await writeRpc
+        .simulateTransaction(getBase64EncodedWireTransaction(transaction), {
+        commitment: validatedPolicy.commitment,
+        encoding: 'base64',
+        replaceRecentBlockhash: true,
+        sigVerify: false,
+    })
+        .send();
+    const logs = Object.freeze([...(response.value.logs ?? [])]);
+    const unitsConsumed = response.value.unitsConsumed === undefined
+        ? undefined
+        : BigInt(response.value.unitsConsumed);
+    if (response.value.err !== null) {
+        throw new SimulationFailedError(response.value.err, logs, unitsConsumed);
+    }
+    const returnData = response.value.returnData;
+    return Object.freeze({
+        logs,
+        replacementBlockhash: Object.freeze({
+            blockhash: response.value.replacementBlockhash.blockhash,
+            lastValidBlockHeight: BigInt(response.value.replacementBlockhash.lastValidBlockHeight),
+        }),
+        ...(returnData === null
+            ? {}
+            : {
+                returnData: Object.freeze({
+                    data: returnData.data[0],
+                    programAddress: returnData.programId,
+                }),
+            }),
+        slot: BigInt(response.context.slot),
+        unitsConsumed,
+    });
+}
+//# sourceMappingURL=simulation.js.map

package/dist/planning/simulation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulation.js","sourceRoot":"","sources":["../../src/planning/simulation.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,+BAA+B,GAGhC,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EACL,qBAAqB,EAErB,eAAe,EACf,sBAAsB,EACtB,YAAY,GACb,MAAM,eAAe,CAAC;AAkCvB,MAAM,qBAAsB,SAAQ,YAAY;IACrC,gBAAgB,CAAmB;IACnC,IAAI,CAAoB;IACxB,aAAa,CAAU;IAEhC,YACE,gBAAkC,EAClC,IAAuB,EACvB,aAAiC;QAEjC,KAAK,CACH,mBAAmB,EACnB,+JAA+J,CAChK,CAAC;QACF,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,aAAa,KAAK,SAAS;YAAE,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACtE,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAoB,EACpB,IAAU,EACV,MAAsB;IAEtB,YAAY,CAAC,IAAI,CAAC,CAAC;IACnB,MAAM,eAAe,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,WAAW,GAAG,MAAM,qBAAqB,CAC7C,QAAQ,EACR,IAAI,EACJ,eAAe,CAChB,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,QAAQ;SAC5B,mBAAmB,CAAC,+BAA+B,CAAC,WAAW,CAAC,EAAE;QACjE,UAAU,EAAE,eAAe,CAAC,UAAU;QACtC,QAAQ,EAAE,QAAQ;QAClB,sBAAsB,EAAE,IAAI;QAC5B,SAAS,EAAE,KAAK;KACjB,CAAC;SACD,IAAI,EAAE,CAAC;IACV,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7D,MAAM,aAAa,GACjB,QAAQ,CAAC,KAAK,CAAC,aAAa,KAAK,SAAS;QACxC,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAE3C,IAAI,QAAQ,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;QAChC,MAAM,IAAI,qBAAqB,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC;IAC7C,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI;QACJ,oBAAoB,EAAE,MAAM,CAAC,MAAM,CAAC;YAClC,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,oBAAoB,CAAC,SAAS;YACxD,oBAAoB,EAAE,MAAM,CAC1B,QAAQ,CAAC,KAAK,CAAC,oBAAoB,CAAC,oBAAoB,CACzD;SACF,CAAC;QACF,GAAG,CAAC,UAAU,KAAK,IAAI;YACrB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC;oBACxB,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;oBACxB,cAAc,EAAE,UAAU,CAAC,SAAS;iBACrC,CAAC;aACH,CAAC;QACN,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC;QACnC,aAAa;KACd,CAAC,CAAC;AACL,CAAC"}

package/dist/registry/combat.d.ts

@@ -0,0 +1,5 @@
+import type { ReadOptions, SageContext, SnapshotEnvelope } from '../client/contracts.js';
+import { type GameCombatConfigurationData } from '../internal/c4/game.js';
+/** Reads the registry-owned Game combat section through the shared data plane. */
+export declare function readGameCombatConfiguration(context: SageContext, options?: ReadOptions): Promise<SnapshotEnvelope<GameCombatConfigurationData>>;
+//# sourceMappingURL=combat.d.ts.map