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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.5.0-beta.82](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.81...sdk-v0.5.0-beta.82) (2026-08-29)
+
+
+### Bug Fixes
+
+* **release:** align managed publication projection ([#342](https://github.com/astrale-os/sdk/issues/342)) ([269fab1](https://github.com/astrale-os/sdk/commit/269fab13d028d41a27ff50d778c73fd994cf6f22))
+
+## [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 {};