@astrale-os/kernel-client 0.6.0-beta.59 → 0.6.0-beta.60

package/dist/session/discovery/bundle.d.ts

@@ -2,14 +2,18 @@ import type { bundle } from '@astrale-os/kernel-dsl/v1';
 import type { publication } from '@astrale-os/kernel-protocol';
 import type { Fetch } from '../../transport/http/index.js';
 import type { SessionOperation, SessionPolicy } from '../context/index.js';
+import { ClientError } from '../../errors/index.js';
 export interface BundleDiscoveryOptions {
     readonly fetch: Fetch;
     readonly policy: Readonly<SessionPolicy>;
     readonly maximumBytes: number;
 }
+/** Internal evidence that a selected immutable artifact is no longer served. */
+export declare class BundleUnavailableError extends ClientError {
+}
 export declare class BundleDiscovery {
     private readonly options;
-    private readonly bundles;
+    private retained?;
     constructor(options: BundleDiscoveryOptions);
     get(publication: publication.Publication, operation: SessionOperation): Promise<bundle.Bundle>;
     clear(): void;

package/dist/session/discovery/bundle.js

@@ -1,39 +1,48 @@
+import { bundleUrl } from '@astrale-os/kernel-protocol/publication';
 import { decodeBundleValue } from '@astrale-os/kernel-protocol/publication/bundle';
 import { ClientError } from '../../errors/index.js';
 import { allowEndpoint } from '../context/index.js';
 import { boundedResponse, requireExactResponse } from './publication.js';
 import { runAcquisition } from './transport.js';
+/** Internal evidence that a selected immutable artifact is no longer served. */
+export class BundleUnavailableError extends ClientError {
+}
 export class BundleDiscovery {
     options;
-    bundles = new Map();
+    retained;
     constructor(options) {
         this.options = options;
     }
     async get(publication, operation) {
         const key = bundleKey(publication);
-        const existing = this.bundles.get(key);
-        if (existing !== undefined)
-            return existing;
-        const discovered = await this.fetch(publication, operation);
-        const retained = this.bundles.get(key) ?? discovered;
-        this.bundles.set(key, retained);
-        return retained;
+        allowEndpoint(publication.schema.bundle.href, this.options.policy);
+        if (this.retained?.key === key)
+            return this.retained.value;
+        const value = await this.fetch(publication, operation);
+        this.retained = { key, value };
+        return value;
     }
     clear() {
-        this.bundles.clear();
+        this.retained = undefined;
     }
     async fetch(publication, operation) {
         if (publication.schema.bundle.ref.size > this.options.maximumBytes) {
             throw new ClientError('Bundle artifact exceeds its byte limit.');
         }
         const href = publication.schema.bundle.href;
-        allowEndpoint(href, this.options.policy);
+        const immutable = href === bundleUrl(publication.identity.issuer, publication.schema.bundle.ref);
         const response = await runAcquisition(operation, 'bundle', 'unknown', 'Kernel bundle could not be retrieved.', (signal) => this.options.fetch(href, {
             headers: { accept: publication.schema.bundle.ref.mediaType },
+            cache: immutable ? 'default' : 'no-cache',
             redirect: 'manual',
             signal,
         }));
         requireExactResponse(response, href, 'Bundle retrieval');
+        if (immutable && (response.status === 404 || response.status === 410)) {
+            // Cleanup must not hold discovery open on an injected body cancellation.
+            void response.body?.cancel().catch(() => undefined);
+            throw new BundleUnavailableError(`Bundle retrieval returned HTTP ${response.status}.`);
+        }
         if (!response.ok)
             throw new ClientError(`Bundle retrieval returned HTTP ${response.status}.`);
         if (response.headers.get('content-type') !== publication.schema.bundle.ref.mediaType) {
@@ -51,5 +60,14 @@ export class BundleDiscovery {
     }
 }
 function bundleKey(publication) {
-    return `${new URL(publication.schema.bundle.href).origin}\u0000${publication.etag}`;
+    const { href, ref } = publication.schema.bundle;
+    return JSON.stringify([
+        publication.identity.issuer,
+        new URL(href).origin,
+        publication.origin,
+        publication.schema.revision,
+        ref.digest,
+        ref.mediaType,
+        ref.size,
+    ]);
 }

package/dist/session/discovery/discovery.d.ts

@@ -1,8 +1,9 @@
 import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+import type { publication } from '@astrale-os/kernel-protocol';
 import type { SessionOperation, SessionPolicy } from '../context/index.js';
-import type { BundleDiscovery } from './bundle.js';
 import type { PublicationDiscovery } from './publication.js';
 import type { SessionSnapshot } from './snapshot.js';
+import { type BundleDiscovery } from './bundle.js';
 export declare class SessionDiscovery {
     readonly kernel: IssuerId;
     private readonly policy;
@@ -12,7 +13,9 @@ export declare class SessionDiscovery {
     private readonly acquisitionOperation;
     private retained?;
     private flight?;
+    private publicationFlight?;
     constructor(kernel: IssuerId, policy: Readonly<SessionPolicy>, publications: PublicationDiscovery, bundles: BundleDiscovery, requireOpen: () => void, acquisitionOperation: () => SessionOperation);
+    publication(operation: SessionOperation): Promise<publication.Publication>;
     snapshot(operation: SessionOperation): Promise<SessionSnapshot>;
     clear(): void;
     private acquireSnapshot;

package/dist/session/discovery/discovery.js

@@ -1,5 +1,6 @@
 import { runSessionOperation } from '../context/index.js';
 import { rootViewCatalog } from '../views/index.js';
+import { BundleUnavailableError } from './bundle.js';
 import { createSessionSnapshot } from './snapshot.js';
 export class SessionDiscovery {
     kernel;
@@ -10,6 +11,7 @@ export class SessionDiscovery {
     acquisitionOperation;
     retained;
     flight;
+    publicationFlight;
     constructor(kernel, policy, publications, bundles, requireOpen, acquisitionOperation) {
         this.kernel = kernel;
         this.policy = policy;
@@ -18,6 +20,24 @@ export class SessionDiscovery {
         this.requireOpen = requireOpen;
         this.acquisitionOperation = acquisitionOperation;
     }
+    publication(operation) {
+        this.requireOpen();
+        const current = this.publicationFlight;
+        if (current !== undefined)
+            return runSessionOperation(operation, () => current);
+        const flight = this.publications.revalidate(this.acquisitionOperation()).then((value) => {
+            this.requireOpen();
+            return value;
+        });
+        this.publicationFlight = flight;
+        void flight
+            .finally(() => {
+            if (this.publicationFlight === flight)
+                this.publicationFlight = undefined;
+        })
+            .catch(() => undefined);
+        return runSessionOperation(operation, () => flight);
+    }
     snapshot(operation) {
         this.requireOpen();
         const current = this.flight;
@@ -39,11 +59,20 @@ export class SessionDiscovery {
         this.retained = undefined;
     }
     async acquireSnapshot(operation) {
-        const previous = this.publications.current();
-        const publication = await this.publications.revalidate(operation);
-        if (previous !== undefined && previous.etag !== publication.etag)
-            this.bundles.clear();
-        const artifact = await this.bundles.get(publication, operation);
+        let publication = await this.publication(operation);
+        let artifact;
+        try {
+            artifact = await this.bundles.get(publication, operation);
+        }
+        catch (cause) {
+            if (!(cause instanceof BundleUnavailableError))
+                throw cause;
+            const current = await this.publication(operation);
+            if (current.etag === publication.etag)
+                throw cause;
+            publication = current;
+            artifact = await this.bundles.get(publication, operation);
+        }
         this.requireOpen();
         if (this.retained?.publication.etag === publication.etag)
             return this.retained;

package/dist/session/discovery/index.d.ts

@@ -1,10 +1,12 @@
 import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+import type { publication } from '@astrale-os/kernel-protocol';
 import type { Fetch } from '../../transport/http/index.js';
 import type { SessionOperation, SessionPolicy } from '../context/index.js';
 import type { SessionSnapshot } from './snapshot.js';
 export type { SessionSnapshot } from './snapshot.js';
 export interface SessionDiscovery {
     readonly kernel: IssuerId;
+    publication(operation: SessionOperation): Promise<publication.Publication>;
     snapshot(operation: SessionOperation): Promise<SessionSnapshot>;
     clear(): void;
 }

package/dist/session/session.d.ts

@@ -1,6 +1,7 @@
 import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
 import type { PathLike } from '@astrale-os/kernel-core/path';
 import type { Domain } from '@astrale-os/kernel-dsl/v1/domain';
+import type { publication } from '@astrale-os/kernel-protocol';
 import type { Call, Input, Result } from '../client/index.js';
 import type { DomainBinding, GraphApi } from '../graph/index.js';
 import type { ClientFactory, ClientPool as ClientPoolType } from '../pool/index.js';
@@ -52,6 +53,8 @@ export declare class ClientSession {
     constructor(options: ClientSessionOptions);
     /** Bind one admitted DSL Domain to authenticated graph projection and Method dispatch. */
     bind<const DomainValue extends Domain>(domain: DomainValue): DomainBinding<DomainValue>;
+    /** Revalidate the intrinsic Publication without acquiring its bundle or Views. */
+    publication(options?: SessionControlOptions): Promise<publication.Publication>;
     snapshot(options?: SessionControlOptions): Promise<SessionSnapshot>;
     viewsFor(target: PathLike, options?: SessionControlOptions): Promise<ViewCatalog>;
     dispatch(call: Call, options?: SessionRequestOptions): Promise<Result>;

package/dist/session/session.js

@@ -101,6 +101,10 @@ export class ClientSession {
     bind(domain) {
         return createDomainBinding(domain, this.graph, (node, method, input) => this.invokeDomainMethod(domain, node, method, input));
     }
+    /** Revalidate the intrinsic Publication without acquiring its bundle or Views. */
+    publication(options) {
+        return this.discovery.publication(this.operation(admitControlOptions(options)));
+    }
     snapshot(options) {
         return this.discovery.snapshot(this.operation(admitControlOptions(options)));
     }

package/dist/session/session.typecheck.js

@@ -10,6 +10,8 @@ void envelope;
 void policy;
 void request;
 void snapshot;
+const observedPublication = session.publication(control);
+void observedPublication;
 const dynamicReference = reference(dynamicDomain, dynamicMethod)(Path.id(NodeId('dynamic-node')));
 void session.invoke(dynamicReference, dynamicInput);
 const dynamicInputIsClientInput = true;

package/dist/store/memory.js

@@ -51,10 +51,15 @@ export class GraphMemory {
             return observeRead(shape.inflight, options, this.options.lifecycle);
         }
         const prior = shape.response;
+        const invalidation = shape.invalidation;
         this.publish(shape, prior === undefined ? 'loading' : this.overlay.hasAny() ? 'optimistic' : 'refreshing');
         const inflight = this.schedule(async () => {
             const result = await this.options.graph.query(shape.ast, queryOptions(shape.page, this.options.lifecycle, shape.expected));
             this.options.requireOpen();
+            if (shape.invalidation !== invalidation) {
+                this.publish(shape, prior === undefined ? 'cold' : this.overlay.hasAny() ? 'optimistic' : 'stale');
+                return result;
+            }
             const integration = this.entities.integrate(result.result);
             shape.references = integration.references;
             shape.confirmed = result;
@@ -82,8 +87,14 @@ export class GraphMemory {
             throw error;
         })
             .finally(() => {
-            if (shape.inflight === inflight)
-                shape.inflight = undefined;
+            if (shape.inflight !== inflight)
+                return;
+            shape.inflight = undefined;
+            if (shape.invalidation !== invalidation &&
+                shape.observed &&
+                !this.options.lifecycle.aborted) {
+                void this.read(shape, { page: shape.page }).catch((error) => this.report(error));
+            }
         });
         shape.inflight = inflight;
         return observeRead(inflight, options, this.options.lifecycle);
@@ -105,6 +116,7 @@ export class GraphMemory {
     invalidate(shape) {
         this.options.requireOpen();
         for (const candidate of shape === undefined ? this.shapes.values() : [shape]) {
+            candidate.invalidation += 1;
             if (candidate.response === undefined)
                 continue;
             this.publish(candidate, this.overlay.hasAny() ? 'optimistic' : 'stale');

package/dist/store/mutation.d.ts

@@ -2,4 +2,4 @@ import type { MutationAST as MutationASTValue, MutationInput, MutationResult } f
 import type { GraphApi, MutationAuthor } from '../graph/index.js';
 import type { GraphMemory } from './memory.js';
 import type { StoreMutationOptions } from './store.js';
-export declare function mutateStore(graph: GraphApi, memory: GraphMemory, input: MutationAuthor | MutationASTValue | MutationInput, options?: StoreMutationOptions): Promise<MutationResult>;
+export declare function mutateStore(graph: GraphApi, memory: GraphMemory, lifecycle: AbortSignal, input: MutationAuthor | MutationASTValue | MutationInput, options?: StoreMutationOptions): Promise<MutationResult>;

package/dist/store/mutation.js

@@ -1,5 +1,5 @@
 import { MutationAST } from '@astrale-os/kernel-core/graph/mutate';
-export async function mutateStore(graph, memory, input, options = {}) {
+export async function mutateStore(graph, memory, lifecycle, input, options = {}) {
     if (options === null || typeof options !== 'object') {
         throw new TypeError('Store mutation options are invalid.');
     }
@@ -11,12 +11,15 @@ export async function mutateStore(graph, memory, input, options = {}) {
         : 'format' in input
             ? MutationAST.decode(input)
             : MutationAST.create(input);
+    const { optimistic: _optimistic, signal: callerSignal, ...request } = options;
+    const signal = callerSignal === undefined ? lifecycle : AbortSignal.any([lifecycle, callerSignal]);
+    signal.throwIfAborted();
     const transaction = options.optimistic === false ? undefined : memory.overlay.add(ast);
     if (transaction !== undefined)
         memory.optimistic();
-    const { optimistic: _optimistic, ...request } = options;
     try {
-        const result = await graph.mutate(ast, request);
+        signal.throwIfAborted();
+        const result = await graph.mutate(ast, { ...request, signal });
         if (transaction !== undefined) {
             memory.overlay.delete(transaction);
             memory.settleOptimistic();

package/dist/store/shape.d.ts

@@ -16,6 +16,7 @@ export declare class QueryShape {
     response?: StoreQueryResponse;
     references?: FactReferences;
     inflight?: Promise<StoreQueryResponse>;
+    invalidation: number;
     releasedAt?: number;
     accessedAt: number;
     refreshedAt?: number;

package/dist/store/shape.js

@@ -9,6 +9,7 @@ export class QueryShape {
     response;
     references;
     inflight;
+    invalidation = 0;
     releasedAt;
     accessedAt;
     refreshedAt;

package/dist/store/store.js

@@ -76,7 +76,7 @@ export class GraphStore {
     }
     mutate(input, options) {
         this.requireOpen();
-        return mutateStore(this.graph, this.memory, input, options);
+        return mutateStore(this.graph, this.memory, this.lifecycle.signal, input, options);
     }
     invalidate(query, options) {
         this.requireOpen();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-client",
-  "version": "0.6.0-beta.59",
+  "version": "0.6.0-beta.60",
   "description": "Universal Client — protocol-first, transport-agnostic",
   "keywords": [
     "astrale",
@@ -67,12 +67,12 @@
   "dependencies": {
     "@astrale-os/kernel-core": "0.9.0-beta.46",
     "@astrale-os/kernel-dsl": "0.2.0-beta.33",
-    "@astrale-os/kernel-protocol": "0.5.0-beta.50",
+    "@astrale-os/kernel-protocol": "0.5.0-beta.51",
     "@tanstack/pacer": "0.20.1",
     "msgpackr": "^2.0.5"
   },
   "devDependencies": {
-    "@astrale-os/kernel-server": "0.5.0-beta.52",
+    "@astrale-os/kernel-server": "0.5.0-beta.53",
     "@astrale/typescript-config": "npm:@jsr/astrale__typescript-config@~1.1.0",
     "@types/node": "^22.0.0",
     "typescript": "7.0.2",