@astrale-os/sdk 0.5.0-beta.80 → 0.5.0-beta.81

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.0-beta.81](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.80...sdk-v0.5.0-beta.81) (2026-08-29)
+
+
+### Features
+
+* **app:** add development session file ([#339](https://github.com/astrale-os/sdk/issues/339)) ([f28e9c6](https://github.com/astrale-os/sdk/commit/f28e9c6fb707b8791a5bc63eba3b616aa7b02342))
+
 ## [0.5.0-beta.80](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.79...sdk-v0.5.0-beta.80) (2026-08-29)
 
 

package/dist/deployment/adapter/development/context.d.ts

@@ -10,5 +10,7 @@ export interface DevelopmentContext extends DevelopmentInput {
     readonly environment: string;
     readonly overrides: DevelopmentOverrides;
     readonly signal: AbortSignal;
+    /** Report loss of the current ready placement before provider recovery starts. */
+    onRecovering?(): Promise<void>;
     onPlacement(placement: DevelopmentPlacement): Promise<void>;
 }

package/dist/deployment/adapter/development/index.d.ts

@@ -1,4 +1,4 @@
 export type { DevelopmentContext, DevelopmentOverrides } from './context.js';
 export type { DevelopmentInput } from './input.js';
-export type { DevelopmentPlacement } from './placement.js';
+export type { DevelopmentInstalledRelease, DevelopmentPlacement } from './placement.js';
 export type { DevelopmentSession } from './session.js';

package/dist/deployment/adapter/development/placement.d.ts

@@ -2,4 +2,14 @@
 export interface DevelopmentPlacement {
     readonly releaseUrl: string;
     readonly localUrl?: string;
+    /** Exact Kernel evidence when this adapter owns installation. */
+    readonly installedRelease?: DevelopmentInstalledRelease;
+}
+/** Exact installed Release evidence supplied only by an installation-owning adapter. */
+export interface DevelopmentInstalledRelease {
+    readonly origin: string;
+    readonly revision: string;
+    readonly issuer: string;
+    readonly etag: string;
+    readonly generation: string;
 }

package/dist/tooling/cli/arguments.d.ts

@@ -8,6 +8,7 @@ export interface ParsedArgs {
     readonly format?: LintReportFormat;
     readonly port?: number;
     readonly host?: string;
+    readonly sessionFile?: string;
 }
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export declare function parseArgs(argv: readonly string[]): ParsedArgs;

package/dist/tooling/cli/arguments.js

@@ -1,4 +1,5 @@
 import { isIP } from 'node:net';
+import { isAbsolute, normalize } from 'node:path';
 export const COMMANDS = ['dev', 'build', 'deploy', 'lint', 'package'];
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export function parseArgs(argv) {
@@ -6,6 +7,7 @@ export function parseArgs(argv) {
     const fix = rest.includes('--fix');
     let port;
     let host;
+    let sessionFile;
     let format;
     let environment;
     const cleaned = [];
@@ -30,6 +32,12 @@ export function parseArgs(argv) {
         else if (argument.startsWith('--host=')) {
             host = normalizeHost(argument.slice('--host='.length));
         }
+        else if (argument === '--session-file') {
+            sessionFile = sessionFilePath(rest[++index]);
+        }
+        else if (argument.startsWith('--session-file=')) {
+            sessionFile = sessionFilePath(argument.slice('--session-file='.length));
+        }
         else if (argument === '--format') {
             format = lintFormat(rest[++index]);
         }
@@ -57,8 +65,9 @@ export function parseArgs(argv) {
     if (format !== undefined && command !== 'lint') {
         throw new Error('`--format` is only valid for `lint`.');
     }
-    if ((port !== undefined || host !== undefined) && command !== 'dev') {
-        throw new Error('`--port` and `--host` are only valid for `dev`.');
+    if ((port !== undefined || host !== undefined || sessionFile !== undefined) &&
+        command !== 'dev') {
+        throw new Error('`--port`, `--host`, and `--session-file` are only valid for `dev`.');
     }
     if (environment !== undefined && !['dev', 'deploy'].includes(command ?? '')) {
         throw new Error('`--environment` is only valid for dev or deploy.');
@@ -76,6 +85,7 @@ export function parseArgs(argv) {
                 env: environment ?? positionals[0] ?? 'dev',
                 ...(port !== undefined ? { port } : {}),
                 ...(host !== undefined ? { host } : {}),
+                ...(sessionFile !== undefined ? { sessionFile } : {}),
             };
         case 'deploy': {
             if (positionals.length > 1)
@@ -165,3 +175,10 @@ function requiredValue(flag, input) {
         throw new Error(`${flag} needs a value.`);
     return input;
 }
+function sessionFilePath(input) {
+    const value = requiredValue('--session-file', input);
+    if (!isAbsolute(value) || normalize(value) !== value) {
+        throw new Error(`--session-file needs a normalized absolute path, got "${value}"`);
+    }
+    return value;
+}

package/dist/tooling/cli/development/develop.d.ts

@@ -5,4 +5,5 @@ export declare function develop(input: {
     readonly projectDir: string;
     readonly environment: string;
     readonly overrides: DevelopmentOverrides;
+    readonly sessionFile?: string;
 }): Promise<number>;

package/dist/tooling/cli/development/develop.js

@@ -3,15 +3,18 @@ import { mkdir, rm, rmdir, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { admitRuntime, compile, isDeployment, resolveRuntime, verifyPreflight, } from '../../../deployment/index.js';
+import { addressing, assemble } from '../../../deployment/release/index.js';
 import { loadDeclaredSecrets } from '../dotenv.js';
 import { error, info } from '../log.js';
 import { DevelopmentLifecycle } from './lifecycle.js';
 import { acquireProjectLock } from './project-lock.js';
 import { LatestRebuild } from './rebuild.js';
+import { DevelopmentSessionFileError, DevelopmentSessionFileWriter } from './session-file.js';
 import { watchSources } from './source-watch.js';
 /** Run one complete provider-neutral development session until interruption. */
 export async function develop(input) {
     const lifecycle = new DevelopmentLifecycle();
+    let sessionFile;
     let lock;
     let session;
     let sourceWatch;
@@ -20,6 +23,9 @@ export async function develop(input) {
     let failed = false;
     let watcherFailure;
     try {
+        if (input.sessionFile !== undefined) {
+            sessionFile = await DevelopmentSessionFileWriter.create(input.sessionFile);
+        }
         lock = await acquireProjectLock({
             projectRoot: input.projectDir,
             environment: input.environment,
@@ -27,6 +33,16 @@ export async function develop(input) {
         const runtimePath = await discoverRuntimePath(input.configPath);
         const builder = new ProjectBuilder({ ...input, runtimePath });
         let current = await builder.prepare(lifecycle.signal);
+        let sessionEvidence;
+        let placementReady = false;
+        let rebuildActive = false;
+        let updatePrevious;
+        let placementSequence = 0;
+        const publishSessionPhase = async () => {
+            if (sessionFile === undefined || sessionEvidence === undefined)
+                return;
+            await sessionFile.transition(placementReady ? (rebuildActive ? 'updating' : 'ready') : 'recovering', sessionEvidence);
+        };
         const adapter = current.adapter;
         const parameters = current.parameters;
         let restartReported = false;
@@ -38,14 +54,28 @@ export async function develop(input) {
             secrets: current.secrets,
             overrides: input.overrides,
             signal: lifecycle.signal,
+            async onRecovering() {
+                placementReady = false;
+                await publishSessionPhase();
+            },
             async onPlacement(placement) {
+                if (sessionFile !== undefined) {
+                    sessionEvidence = coherentSessionEvidence(updatePrevious === undefined ? [current.artifact] : [current.artifact, updatePrevious], placement);
+                    placementReady = true;
+                    placementSequence += 1;
+                    await publishSessionPhase();
+                }
                 info(`Public: ${placement.releaseUrl}`);
                 if (placement.localUrl !== undefined)
                     info(`Runtime: ${placement.localUrl}`);
             },
         });
         rebuild = new LatestRebuild({
-            prepare: (_ignored, signal) => builder.prepare(signal),
+            async prepare(_ignored, signal) {
+                rebuildActive = true;
+                await publishSessionPhase();
+                return builder.prepare(signal);
+            },
             async commit(candidate) {
                 if (candidate.adapter.name !== adapter.name ||
                     candidate.adapter.version !== adapter.version ||
@@ -54,19 +84,50 @@ export async function develop(input) {
                     throw new Error('Adapter configuration changed; restart pnpm dev to apply it.');
                 }
                 const previous = current;
+                const beforePlacement = placementSequence;
+                updatePrevious = previous.artifact;
                 current = candidate;
                 try {
                     await session.update({ artifact: candidate.artifact, secrets: candidate.secrets });
+                    if (sessionFile !== undefined) {
+                        if (placementSequence === beforePlacement || sessionEvidence === undefined) {
+                            throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter completed an update without reporting installed Release evidence.');
+                        }
+                        assertEvidenceMatches(candidate.artifact, sessionEvidence);
+                    }
+                    rebuildActive = false;
+                    await publishSessionPhase();
                     sourceWatch?.update(candidate.sources);
                     info(`Updated ${candidate.artifact.build.schema.compiled.root.revision}.`);
                 }
                 catch (cause) {
                     current = previous;
+                    if (sessionFile !== undefined &&
+                        sessionEvidence !== undefined &&
+                        !evidenceMatches(previous.artifact, sessionEvidence)) {
+                        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter rejected an update without restoring prior installed Release evidence.', { cause });
+                    }
                     throw cause;
                 }
+                finally {
+                    updatePrevious = undefined;
+                }
             },
-            failed(cause) {
+            async failed(cause) {
+                rebuildActive = false;
+                if (cause instanceof DevelopmentSessionFileError) {
+                    watcherFailure = cause;
+                    lifecycle.stop(cause);
+                    return;
+                }
                 error(cause instanceof Error ? cause.message : String(cause));
+                try {
+                    await publishSessionPhase();
+                }
+                catch (sessionCause) {
+                    watcherFailure = sessionCause;
+                    lifecycle.stop(sessionCause);
+                }
             },
         });
         sourceWatch = watchSources({
@@ -103,6 +164,13 @@ export async function develop(input) {
     }
     lifecycle.stop(failure);
     const cleanup = [];
+    try {
+        await sessionFile?.transition('stopping');
+    }
+    catch (cause) {
+        failed = true;
+        failure ??= cause;
+    }
     for (const operation of [
         () => sourceWatch?.stop(),
         () => rebuild?.stop(failure),
@@ -133,6 +201,12 @@ export async function develop(input) {
                 cleanup.push(cause);
         }
     }
+    try {
+        await sessionFile?.transition(failed || cleanup.length > 0 ? 'failed' : 'stopped');
+    }
+    catch (cause) {
+        cleanup.push(cause);
+    }
     lifecycle.dispose();
     if (failed) {
         if (cleanup.length > 0)
@@ -143,6 +217,45 @@ export async function develop(input) {
         throw new AggregateError(cleanup, 'Development cleanup failed.');
     return 0;
 }
+function coherentSessionEvidence(artifacts, placement) {
+    const evidence = placement.installedRelease;
+    if (evidence === undefined) {
+        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', '--session-file requires an adapter that reports exact installed Release evidence.');
+    }
+    let issuer;
+    try {
+        issuer = new URL(placement.releaseUrl).origin;
+    }
+    catch (cause) {
+        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter reported an invalid Release URL.', { cause });
+    }
+    if (placement.releaseUrl !== issuer) {
+        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter reported a non-canonical Release URL.');
+    }
+    let matches = false;
+    try {
+        matches = artifacts.some((artifact) => evidenceMatches(artifact, evidence));
+    }
+    catch (cause) {
+        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter reported invalid installed Release evidence.', { cause });
+    }
+    if (evidence.issuer !== issuer || !matches) {
+        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter installed Release evidence does not match the current artifact and placement.');
+    }
+    return evidence;
+}
+function assertEvidenceMatches(artifact, evidence) {
+    if (!evidenceMatches(artifact, evidence)) {
+        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter installed Release evidence does not match the committed artifact.');
+    }
+}
+function evidenceMatches(artifact, evidence) {
+    const root = artifact.build.schema.compiled.root;
+    const release = assemble(artifact.build, addressing(evidence.issuer));
+    return (evidence.origin === root.origin &&
+        evidence.revision === root.revision &&
+        evidence.etag === release.publication.etag);
+}
 class ProjectBuilder {
     #configPath;
     #projectDir;

package/dist/tooling/cli/development/rebuild.d.ts

@@ -1,7 +1,7 @@
 export interface RebuildOperations<Input, Candidate> {
     prepare(input: Input, signal: AbortSignal): Promise<Candidate>;
     commit(candidate: Candidate, signal: AbortSignal): Promise<void>;
-    failed(cause: unknown): void;
+    failed(cause: unknown): void | Promise<void>;
 }
 /** Serialize rebuilds while retaining only the newest pending invalidation. */
 export declare class LatestRebuild<Input, Candidate> {

package/dist/tooling/cli/development/rebuild.js

@@ -41,7 +41,7 @@ export class LatestRebuild {
                 }
                 catch (cause) {
                     if (!controller.signal.aborted)
-                        this.#operations.failed(cause);
+                        await this.#operations.failed(cause);
                 }
                 finally {
                     if (this.#current === controller)

package/dist/tooling/cli/development/session-file.d.ts

@@ -0,0 +1,53 @@
+export declare const DEVELOPMENT_SESSION_FILE_VERSION: 1;
+export type DevelopmentSessionPhaseV1 = 'starting' | 'ready' | 'updating' | 'recovering' | 'stopping' | 'stopped' | 'failed';
+export interface DevelopmentSessionProjectV1 {
+    readonly origin: string;
+}
+export interface DevelopmentSessionReleaseV1 {
+    readonly revision: string;
+    readonly issuer: string;
+    readonly etag: string;
+    readonly generation: string;
+}
+interface DevelopmentSessionFileBaseV1 {
+    readonly version: typeof DEVELOPMENT_SESSION_FILE_VERSION;
+    readonly sessionId: string;
+    readonly sequence: number;
+    readonly phase: DevelopmentSessionPhaseV1;
+}
+interface DevelopmentSessionStartingFileV1 extends DevelopmentSessionFileBaseV1 {
+    readonly phase: 'starting';
+}
+interface DevelopmentSessionActiveFileV1 extends DevelopmentSessionFileBaseV1 {
+    readonly phase: 'ready' | 'updating' | 'recovering';
+    readonly project: DevelopmentSessionProjectV1;
+    readonly release: DevelopmentSessionReleaseV1;
+}
+interface DevelopmentSessionTerminalFileBaseV1 extends DevelopmentSessionFileBaseV1 {
+    readonly phase: 'stopping' | 'stopped' | 'failed';
+}
+type DevelopmentSessionTerminalFileV1 = DevelopmentSessionTerminalFileBaseV1 & ({
+    readonly project: DevelopmentSessionProjectV1;
+    readonly release: DevelopmentSessionReleaseV1;
+} | {
+    readonly project?: never;
+    readonly release?: never;
+});
+export type DevelopmentSessionFileV1 = DevelopmentSessionStartingFileV1 | DevelopmentSessionActiveFileV1 | DevelopmentSessionTerminalFileV1;
+export interface DevelopmentSessionReleaseEvidenceV1 extends DevelopmentSessionProjectV1, DevelopmentSessionReleaseV1 {
+}
+export declare class DevelopmentSessionFileError extends Error {
+    readonly code: 'INVALID_SESSION_FILE_PATH' | 'SESSION_FILE_PATH_UNSAFE' | 'SESSION_FILE_EXISTS' | 'SESSION_FILE_TAMPERED' | 'SESSION_FILE_TRANSITION_INVALID' | 'SESSION_FILE_EVIDENCE_INCOHERENT';
+    readonly name = "DevelopmentSessionFileError";
+    constructor(code: 'INVALID_SESSION_FILE_PATH' | 'SESSION_FILE_PATH_UNSAFE' | 'SESSION_FILE_EXISTS' | 'SESSION_FILE_TAMPERED' | 'SESSION_FILE_TRANSITION_INVALID' | 'SESSION_FILE_EVIDENCE_INCOHERENT', message: string, options?: ErrorOptions);
+}
+export declare function acceptDevelopmentSessionFileV1(input: unknown): DevelopmentSessionFileV1;
+/** SDK-private sole writer for one caller-selected machine-integration file. */
+export declare class DevelopmentSessionFileWriter {
+    #private;
+    private constructor();
+    static create(path: string): Promise<DevelopmentSessionFileWriter>;
+    transition(phase: Exclude<DevelopmentSessionPhaseV1, 'starting'>, evidence?: DevelopmentSessionReleaseEvidenceV1): Promise<DevelopmentSessionFileV1>;
+}
+export declare function developmentSessionTransitionAllowed(previous: DevelopmentSessionPhaseV1, next: Exclude<DevelopmentSessionPhaseV1, 'starting'>): boolean;
+export {};

package/dist/tooling/cli/development/session-file.js

@@ -0,0 +1,337 @@
+import { randomUUID } from 'node:crypto';
+import { link, lstat, open, readFile, realpath, rename, unlink } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, normalize, parse, sep } from 'node:path';
+import { patterns } from '../../../platform/schema/index.js';
+export const DEVELOPMENT_SESSION_FILE_VERSION = 1;
+export class DevelopmentSessionFileError extends Error {
+    code;
+    name = 'DevelopmentSessionFileError';
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+export function acceptDevelopmentSessionFileV1(input) {
+    const value = record(input, 'Development session file');
+    if (value.metadata !== undefined ||
+        value.extensions !== undefined ||
+        value.vendor !== undefined) {
+        invalid('Development session file cannot contain a metadata, extensions, or vendor bag.');
+    }
+    if (value.version !== DEVELOPMENT_SESSION_FILE_VERSION) {
+        invalid(`Unsupported development session file version: ${String(value.version)}.`);
+    }
+    const sessionId = text(value.sessionId, 'Development session id');
+    const sequence = integer(value.sequence, 'Development session sequence');
+    const phase = admitPhase(value.phase);
+    const base = Object.freeze({ version: 1, sessionId, sequence, phase });
+    const hasProject = value.project !== undefined;
+    const hasRelease = value.release !== undefined;
+    if (phase === 'starting') {
+        if (hasProject || hasRelease) {
+            invalid('Development session starting phase cannot contain Release evidence.');
+        }
+        return Object.freeze({ ...base, phase: 'starting' });
+    }
+    if (phase === 'ready' || phase === 'updating' || phase === 'recovering') {
+        if (!hasProject || !hasRelease)
+            invalid(`Development session phase ${phase} requires a Release.`);
+        return Object.freeze({
+            ...base,
+            phase,
+            project: project(value.project),
+            release: release(value.release),
+        });
+    }
+    if (hasProject !== hasRelease) {
+        invalid('Development session terminal project and Release must be present together.');
+    }
+    if (!hasProject)
+        return Object.freeze({ ...base, phase });
+    return Object.freeze({
+        ...base,
+        phase,
+        project: project(value.project),
+        release: release(value.release),
+    });
+}
+/** SDK-private sole writer for one caller-selected machine-integration file. */
+export class DevelopmentSessionFileWriter {
+    #path;
+    #parent;
+    #sessionId;
+    #sequence = 0;
+    #phase = 'starting';
+    #last;
+    #tail = Promise.resolve();
+    constructor(path, parent, sessionId) {
+        this.#path = path;
+        this.#parent = parent;
+        this.#sessionId = sessionId;
+    }
+    static async create(path) {
+        const admitted = await admitSessionFilePath(path);
+        const writer = new DevelopmentSessionFileWriter(admitted.path, admitted.parent, randomUUID());
+        await writer.#create();
+        return writer;
+    }
+    transition(phase, evidence) {
+        const operation = this.#tail.then(async () => {
+            if (!developmentSessionTransitionAllowed(this.#phase, phase)) {
+                throw new DevelopmentSessionFileError('SESSION_FILE_TRANSITION_INVALID', `Development session cannot transition from ${this.#phase} to ${phase}.`);
+            }
+            if (evidence !== undefined)
+                this.#last = admitEvidence(evidence);
+            if (['ready', 'updating', 'recovering'].includes(phase) && this.#last === undefined) {
+                throw new TypeError(`Development session phase ${phase} requires Release evidence.`);
+            }
+            const snapshot = this.#snapshot(phase, this.#sequence + 1);
+            await this.#replace(snapshot);
+            this.#sequence = snapshot.sequence;
+            this.#phase = snapshot.phase;
+            return snapshot;
+        });
+        this.#tail = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    async #create() {
+        const snapshot = this.#snapshot('starting', 1);
+        const staging = await writeStaging(this.#parent, this.#path, this.#sessionId, snapshot);
+        try {
+            await link(staging, this.#path);
+        }
+        catch (cause) {
+            if (errorCode(cause) === 'EEXIST') {
+                throw new DevelopmentSessionFileError('SESSION_FILE_EXISTS', `Development session file already exists: ${this.#path}`, { cause });
+            }
+            throw cause;
+        }
+        finally {
+            await unlink(staging).catch((cause) => {
+                if (errorCode(cause) !== 'ENOENT')
+                    throw cause;
+            });
+        }
+        await syncDirectory(this.#parent);
+        this.#sequence = snapshot.sequence;
+    }
+    #snapshot(phase, sequence) {
+        const base = {
+            version: DEVELOPMENT_SESSION_FILE_VERSION,
+            sessionId: this.#sessionId,
+            sequence,
+        };
+        if (phase === 'starting')
+            return Object.freeze({ ...base, phase: 'starting' });
+        if (this.#last === undefined) {
+            if (phase === 'ready' || phase === 'updating' || phase === 'recovering') {
+                throw new TypeError(`Development session phase ${phase} requires Release evidence.`);
+            }
+            return Object.freeze({ ...base, phase });
+        }
+        return Object.freeze({
+            ...base,
+            phase,
+            project: Object.freeze({ origin: this.#last.origin }),
+            release: Object.freeze({
+                revision: this.#last.revision,
+                issuer: this.#last.issuer,
+                etag: this.#last.etag,
+                generation: this.#last.generation,
+            }),
+        });
+    }
+    async #replace(snapshot) {
+        await assertParent(this.#parent);
+        const current = await readCurrent(this.#path);
+        if (current.sessionId !== this.#sessionId || current.sequence !== snapshot.sequence - 1) {
+            throw new DevelopmentSessionFileError('SESSION_FILE_TAMPERED', `Development session file ownership changed: ${this.#path}`);
+        }
+        const staging = await writeStaging(this.#parent, this.#path, this.#sessionId, snapshot);
+        try {
+            await rename(staging, this.#path);
+            await syncDirectory(this.#parent);
+        }
+        finally {
+            await unlink(staging).catch((cause) => {
+                if (errorCode(cause) !== 'ENOENT')
+                    throw cause;
+            });
+        }
+    }
+}
+function admitEvidence(input) {
+    const admittedProject = project({ origin: input.origin });
+    const admittedRelease = release(input);
+    return Object.freeze({ origin: admittedProject.origin, ...admittedRelease });
+}
+async function admitSessionFilePath(input) {
+    if (!isAbsolute(input) || normalize(input) !== input || basename(input).length === 0) {
+        throw new DevelopmentSessionFileError('INVALID_SESSION_FILE_PATH', '--session-file requires one normalized absolute file path.');
+    }
+    const parent = dirname(input);
+    await assertParent(parent);
+    try {
+        await lstat(input);
+        throw new DevelopmentSessionFileError('SESSION_FILE_EXISTS', `Development session file path must not exist: ${input}`);
+    }
+    catch (cause) {
+        if (errorCode(cause) !== 'ENOENT')
+            throw cause;
+    }
+    return Object.freeze({ path: input, parent });
+}
+async function assertParent(parent) {
+    const root = parse(parent).root;
+    let cursor = root;
+    for (const segment of parent.slice(root.length).split(sep).filter(Boolean)) {
+        cursor = join(cursor, segment);
+        const entry = await lstat(cursor);
+        if (entry.isSymbolicLink())
+            unsafe(`Development session file path crosses a symlink: ${cursor}`);
+    }
+    const canonical = await realpath(parent);
+    if (canonical !== parent)
+        unsafe(`Development session file parent is not canonical: ${parent}`);
+    const entry = await lstat(parent);
+    if (!entry.isDirectory())
+        unsafe(`Development session file parent is not a directory: ${parent}`);
+    const uid = process.getuid?.();
+    if (uid !== undefined && entry.uid !== uid) {
+        unsafe(`Development session file parent is not owned by the current user: ${parent}`);
+    }
+    if ((entry.mode & 0o077) !== 0) {
+        unsafe(`Development session file parent must be owner-only: ${parent}`);
+    }
+}
+async function writeStaging(parent, target, sessionId, snapshot) {
+    const path = join(parent, `.${basename(target)}.${sessionId}.${randomUUID()}.next`);
+    const file = await open(path, 'wx', 0o600);
+    try {
+        await file.writeFile(`${JSON.stringify(snapshot, null, 2)}\n`, 'utf8');
+        await file.sync();
+    }
+    catch (cause) {
+        await file.close();
+        await unlink(path).catch(() => undefined);
+        throw cause;
+    }
+    await file.close();
+    return path;
+}
+async function syncDirectory(path) {
+    const directory = await open(path, 'r');
+    try {
+        await directory.sync();
+    }
+    finally {
+        await directory.close();
+    }
+}
+async function readCurrent(path) {
+    const entry = await lstat(path);
+    if (!entry.isFile() || entry.isSymbolicLink() || (entry.mode & 0o077) !== 0) {
+        throw new DevelopmentSessionFileError('SESSION_FILE_TAMPERED', `Development session file is no longer one owner-only regular file: ${path}`);
+    }
+    try {
+        return acceptDevelopmentSessionFileV1(JSON.parse(await readFile(path, 'utf8')));
+    }
+    catch (cause) {
+        if (cause instanceof DevelopmentSessionFileError)
+            throw cause;
+        throw new DevelopmentSessionFileError('SESSION_FILE_TAMPERED', `Development session file is unreadable or invalid: ${path}`, { cause });
+    }
+}
+function project(input) {
+    const value = record(input, 'Development session project');
+    rejectBags(value, 'Development session project');
+    const origin = text(value.origin, 'Development session project origin');
+    if (!patterns.origin.test(origin))
+        invalid('Development session project origin is invalid.');
+    return Object.freeze({ origin });
+}
+function release(input) {
+    const value = record(input, 'Development session Release');
+    rejectBags(value, 'Development session Release');
+    const revision = digest(value.revision, 'Development session Release revision');
+    const etag = digest(value.etag, 'Development session Release etag');
+    const generation = digest(value.generation, 'Development session Release generation');
+    const issuer = origin(value.issuer);
+    return Object.freeze({ revision, issuer, etag, generation });
+}
+function origin(input) {
+    const value = text(input, 'Development session Release issuer');
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch (cause) {
+        throw new TypeError('Development session Release issuer must be an HTTP(S) origin.', { cause });
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.href !== `${url.origin}/`) {
+        invalid('Development session Release issuer must be an HTTP(S) origin.');
+    }
+    return url.origin;
+}
+function digest(input, label) {
+    const value = text(input, label);
+    if (!/^sha256:[0-9a-f]{64}$/u.test(value))
+        invalid(`${label} must be a sha256 digest.`);
+    return value;
+}
+function admitPhase(input) {
+    if (input !== 'starting' &&
+        input !== 'ready' &&
+        input !== 'updating' &&
+        input !== 'recovering' &&
+        input !== 'stopping' &&
+        input !== 'stopped' &&
+        input !== 'failed') {
+        invalid(`Unknown development session phase: ${String(input)}.`);
+    }
+    return input;
+}
+export function developmentSessionTransitionAllowed(previous, next) {
+    if (previous === 'stopped' || previous === 'failed')
+        return false;
+    if (previous === 'stopping')
+        return next === 'stopped' || next === 'failed';
+    if (next === 'stopping' || next === 'failed')
+        return true;
+    if (previous === 'starting')
+        return next === 'ready';
+    return next === 'ready' || next === 'updating' || next === 'recovering';
+}
+function rejectBags(value, label) {
+    if (value.metadata !== undefined ||
+        value.extensions !== undefined ||
+        value.vendor !== undefined) {
+        invalid(`${label} cannot contain a metadata, extensions, or vendor bag.`);
+    }
+}
+function record(input, label) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid(`${label} must be an object.`);
+    return input;
+}
+function text(input, label) {
+    if (typeof input !== 'string' || input.length === 0)
+        invalid(`${label} must be text.`);
+    return input;
+}
+function integer(input, label) {
+    if (!Number.isSafeInteger(input) || Number(input) <= 0)
+        invalid(`${label} must be a positive integer.`);
+    return Number(input);
+}
+function invalid(message) {
+    throw new TypeError(message);
+}
+function unsafe(message) {
+    throw new DevelopmentSessionFileError('SESSION_FILE_PATH_UNSAFE', message);
+}
+function errorCode(input) {
+    return input !== null && typeof input === 'object' && 'code' in input
+        ? String(Reflect.get(input, 'code'))
+        : undefined;
+}

package/dist/tooling/cli/help.js

@@ -43,6 +43,8 @@ Options:
   --port <port>           Use a strict local Worker port (default: OS-allocated).
   --host <url>            Use an externally managed public origin; requires a strict port
                           from --port or adapter configuration.
+  --session-file <path>   Write one retained DevelopmentSessionFileV1 snapshot at an
+                          absolute path in a caller-owned private directory.
   -h, --help              Show help for dev.
 
 Behavior:
@@ -51,6 +53,9 @@ Behavior:
   OS-allocated loopback port.
   Watches imported authored sources and declared secrets. Configuration changes
   require restarting the command.
+  The session file is machine-readable and authoritative when requested; human
+  stdout/stderr remains diagnostic. It requires an adapter that reports exact
+  installed Release evidence.
 
 Adapters:
   cloudflare              Runs the local Worker and optional Vite frontend only;

package/dist/tooling/cli/index.d.ts

@@ -1,6 +1,7 @@
 /**
  * `@astrale-os/sdk/cli` — the `astrale-domain` CLI
- * (dev | build | deploy | lint | package) and its explicit dotenv boundary.
+ * (dev | build | deploy | lint | package), explicit dotenv boundary, and admitted
+ * development-session file representation.
  *
  * Node-only: the CLI imports `node:fs`/`node:module`/`node:url` and runs under
  * Bun (it imports the project's `astrale.config.ts` directly). This subpath is
@@ -11,3 +12,5 @@
  */
 export { run } from './run.js';
 export { loadDeclaredSecrets } from './dotenv.js';
+export { DEVELOPMENT_SESSION_FILE_VERSION, acceptDevelopmentSessionFileV1, } from './development/session-file.js';
+export type { DevelopmentSessionFileV1, DevelopmentSessionPhaseV1, DevelopmentSessionProjectV1, DevelopmentSessionReleaseV1, } from './development/session-file.js';

package/dist/tooling/cli/index.js

@@ -1,6 +1,7 @@
 /**
  * `@astrale-os/sdk/cli` — the `astrale-domain` CLI
- * (dev | build | deploy | lint | package) and its explicit dotenv boundary.
+ * (dev | build | deploy | lint | package), explicit dotenv boundary, and admitted
+ * development-session file representation.
  *
  * Node-only: the CLI imports `node:fs`/`node:module`/`node:url` and runs under
  * Bun (it imports the project's `astrale.config.ts` directly). This subpath is
@@ -11,3 +12,4 @@
  */
 export { run } from './run.js';
 export { loadDeclaredSecrets } from './dotenv.js';
+export { DEVELOPMENT_SESSION_FILE_VERSION, acceptDevelopmentSessionFileV1, } from './development/session-file.js';

package/dist/tooling/cli/orchestrate.js

@@ -49,6 +49,7 @@ export async function run(argv) {
                 ...(parsed.host === undefined ? {} : { publicUrl: parsed.host }),
                 ...(parsed.port === undefined ? {} : { localPort: parsed.port }),
             }),
+            ...(parsed.sessionFile === undefined ? {} : { sessionFile: parsed.sessionFile }),
         });
     }
     const deployment = await loadDeployment(configPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.5.0-beta.80",
+  "version": "0.5.0-beta.81",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",
@@ -287,7 +287,7 @@
     "build": "node scripts/clean-dist.mjs && tsgo && node scripts/verify-no-source-maps.mjs dist && pnpm run verify:package",
     "e2e": "node __e2e__/flagship/runner.mjs",
     "typecheck": "tsgo --noEmit && pnpm run typecheck:specs && pnpm run typecheck:types && pnpm run typecheck:tests && pnpm run typecheck:e2e && pnpm run typecheck:knowledge",
-    "typecheck:specs": "tsgo --noEmit -p src/application/query/.spec/tsconfig.json && tsgo --noEmit -p src/platform/schema/.spec/tsconfig.json && tsgo --noEmit -p src/application/mutation/.spec/tsconfig.json",
+    "typecheck:specs": "tsgo --noEmit -p src/application/query/.spec/tsconfig.json && tsgo --noEmit -p src/platform/schema/.spec/tsconfig.json && tsgo --noEmit -p src/application/mutation/.spec/tsconfig.json && tsgo --noEmit -p src/deployment/adapter/development/.spec/tsconfig.json && tsgo --noEmit -p src/tooling/cli/.spec/tsconfig.json",
     "typecheck:types": "tsgo --noEmit -p __tests__/tsconfig.types.json",
     "typecheck:tests": "tsgo --noEmit -p tsconfig.test.json",
     "typecheck:e2e": "tsgo --noEmit -p __e2e__/flagship/fixtures/tsconfig.v1.json && tsgo --noEmit -p __e2e__/flagship/fixtures/tsconfig.json",