@astrale-os/adapter-cloudflare 0.5.0-beta.169 → 0.5.0-beta.170

package/README.md

@@ -61,6 +61,17 @@ label.
 - **Retention.** `retain` (called once a Publication commits) marks the summary `published`, which
   the platform's preview expiry never retires. A label the platform withdrew (`retirement:<label>`)
   answers `DEPLOYMENT_RETIRED` at the dispatcher and is refused by every later deploy.
+- **Listing.** `astrale-domain list` lists the Environment's deployments from the routing KV, and
+  writes nothing: one row per `summary:<label>` of the Environment's line, with its record as
+  `record:<label>` stores it (a record the SDK refuses is listed with `record: null` and the
+  refusal), and the call target `{ kind: 'namespace', namespace, script }` that the platform's
+  per-script tooling takes, such as its in-place secret rotation. A summary without its record is
+  `deploying` (not activated), and an active one whose label carries the tombstone is `retiring`.
+  Nothing on the namespace records last calls: they come from its calls dataset,
+  `astrale_deployment_calls_<the same hexadecimal>`, through the Analytics Engine SQL API, and an
+  active preview expires 30 days after the later of its activation and its last call. The token
+  then also needs Account Analytics Read; without it, the deployments are listed without last calls
+  or expiries.
 - **Refused.** A direct-mode parameter beside `namespace` (`route`, `workerName`, `identityIssuer`,
   `addressing`, `signingIdentity`), a `router.binding` other than `ROUTER`, and any `wrangler` key
   but `services`, `dispatch_namespaces` and `compatibility_flags`, `triggers` first: an immutable

package/dist/adapter.d.ts

@@ -16,8 +16,9 @@ export interface CloudflareDependencies extends CloudflareDeployDependencies {
  * Deploy one Project Environment through Cloudflare Workers.
  *
  * With `namespace`, each release becomes one immutable deployment in that platform dispatch
- * namespace (adapter interface v2). Without it, the Environment stays on the legacy direct mode:
- * one stable Worker replaced in place by each deploy (CT33).
+ * namespace (adapter interface v2), and `astrale-domain list` lists them. Without it, the
+ * Environment stays on the legacy direct mode: one stable Worker replaced in place by each deploy
+ * (CT33).
  */
 export declare function cloudflare(parameters?: CloudflareParams): Deployment<CloudflareParams, Adapter<CloudflareParams>>;
 export declare function cloudflareWithDependencies(parameters: CloudflareParams, dependencies: CloudflareDependencies): Deployment<CloudflareParams, Adapter<CloudflareParams>>;

package/dist/adapter.js

@@ -3,7 +3,7 @@ import { createRequire } from 'node:module';
 import { cloudflareWorkerBundler } from './build/bundler.js';
 import { createSigningIdentity } from './identity/material.js';
 import { artifact, deployCloudflare, directReadiness, materialize, runWranglerDeploymentStatus, runWranglerRollout, signingIdentity, } from './legacy/direct/index.js';
-import { admitNamespace, configureNamespace, deployNamespaceRelease, placeNamespace, retainNamespaceDeployment, } from './namespace/index.js';
+import { admitNamespace, configureNamespace, deployNamespaceRelease, listNamespaceDeployments, placeNamespace, retainNamespaceDeployment, } from './namespace/index.js';
 export { waitForReadiness } from './legacy/direct/index.js';
 const packageVersion = createRequire(import.meta.url)('../package.json')
     .version;
@@ -11,8 +11,9 @@ const packageVersion = createRequire(import.meta.url)('../package.json')
  * Deploy one Project Environment through Cloudflare Workers.
  *
  * With `namespace`, each release becomes one immutable deployment in that platform dispatch
- * namespace (adapter interface v2). Without it, the Environment stays on the legacy direct mode:
- * one stable Worker replaced in place by each deploy (CT33).
+ * namespace (adapter interface v2), and `astrale-domain list` lists them. Without it, the
+ * Environment stays on the legacy direct mode: one stable Worker replaced in place by each deploy
+ * (CT33).
  */
 export function cloudflare(parameters = {}) {
     return cloudflareWithDependencies(parameters, {
@@ -34,6 +35,7 @@ export function cloudflareWithDependencies(parameters, dependencies) {
         configure: configureNamespace,
         placement: async (parameters) => placeNamespace(parameters),
         deployRelease: (parameters, context) => deployNamespaceRelease(parameters, context, namespace),
+        list: (parameters, context) => listNamespaceDeployments(parameters, context, namespace),
         retain: (parameters, context) => retainNamespaceDeployment(parameters, context, namespace),
         // Legacy direct mode (CT33 `legacy-direct`), deleted with it (D10).
         prepare: dependencies.artifact,

package/dist/namespace/api.d.ts

@@ -27,7 +27,8 @@ export interface CloudflarePage {
 }
 /**
  * The few Cloudflare account endpoints namespace mode uses: dispatch-namespace scripts, their
- * secrets, their static assets, and the routing KV. The token is sent only to the API base; it is
+ * secrets, their static assets, the routing KV, and the calls dataset it lists last calls from. The
+ * token is sent only to the API base; it is
  * never logged, and neither is any request body (they carry secret values).
  */
 export declare class CloudflareApi {
@@ -52,6 +53,17 @@ export declare class CloudflareApi {
     form(method: string, path: string, body: FormData, headers?: Readonly<Record<string, string>>, bearer?: string): Promise<unknown>;
     /** Read one KV value as text, or undefined when the key is absent. */
     kvGet(kv: string, key: string): Promise<string | undefined>;
+    /**
+     * The names of every key of one KV namespace that starts with `prefix`, in Cloudflare's order
+     * (lexicographic), following the listing's cursor to its end.
+     */
+    kvKeys(kv: string, prefix: string): Promise<readonly string[]>;
+    /**
+     * Run one read-only Analytics Engine SQL query (`SELECT … FORMAT JSON`) and return the text it
+     * answers, which is the query's JSON document and not Cloudflare's envelope. A token without
+     * Account Analytics Read is refused with 401 or 403.
+     */
+    sql(query: string): Promise<string>;
     /** Write one KV value as text. */
     kvPut(kv: string, key: string, value: string, contentType: string): Promise<void>;
     private envelope;

package/dist/namespace/api.js

@@ -4,6 +4,8 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 const UPLOAD_TIMEOUT_MS = 120_000;
 const MAXIMUM_RATE_LIMIT_RETRIES = 3;
 const MAXIMUM_RATE_LIMIT_WAIT_MS = 10_000;
+/** The most keys one page of a KV key listing returns, as Cloudflare caps it. */
+const KV_KEYS_PAGE = 1_000;
 /**
  * A Cloudflare API refusal or failure. `status` is the HTTP status (412 for a create-only upload
  * over an existing script); `codes` are the error codes of Cloudflare's envelope, when it sent one
@@ -21,7 +23,8 @@ export class CloudflareApiError extends Error {
 }
 /**
  * The few Cloudflare account endpoints namespace mode uses: dispatch-namespace scripts, their
- * secrets, their static assets, and the routing KV. The token is sent only to the API base; it is
+ * secrets, their static assets, the routing KV, and the calls dataset it lists last calls from. The
+ * token is sent only to the API base; it is
  * never logged, and neither is any request body (they carry secret values).
  */
 export class CloudflareApi {
@@ -92,6 +95,52 @@ export class CloudflareApi {
             throw failure('GET', 'KV value', response.status, text);
         return text;
     }
+    /**
+     * The names of every key of one KV namespace that starts with `prefix`, in Cloudflare's order
+     * (lexicographic), following the listing's cursor to its end.
+     */
+    async kvKeys(kv, prefix) {
+        const names = [];
+        let cursor = '';
+        for (;;) {
+            const query = new URLSearchParams({ prefix, limit: String(KV_KEYS_PAGE) });
+            if (cursor !== '')
+                query.set('cursor', cursor);
+            const envelope = await this.envelope('GET', this.account(`/storage/kv/namespaces/${encodeURIComponent(kv)}/keys?${query}`), {});
+            if (!Array.isArray(envelope.result)) {
+                throw new CloudflareApiError('Cloudflare returned an invalid KV key listing.', 200);
+            }
+            for (const entry of envelope.result) {
+                const name = entry?.name;
+                if (typeof name !== 'string' || !name.startsWith(prefix)) {
+                    throw new CloudflareApiError('Cloudflare returned an invalid KV key listing.', 200);
+                }
+                names.push(name);
+            }
+            const next = envelope.result_info?.cursor;
+            if (typeof next !== 'string' || next === '')
+                return names;
+            if (next === cursor) {
+                throw new CloudflareApiError('Cloudflare repeated a KV key listing cursor.', 200);
+            }
+            cursor = next;
+        }
+    }
+    /**
+     * Run one read-only Analytics Engine SQL query (`SELECT … FORMAT JSON`) and return the text it
+     * answers, which is the query's JSON document and not Cloudflare's envelope. A token without
+     * Account Analytics Read is refused with 401 or 403.
+     */
+    async sql(query) {
+        const response = await this.send('POST', this.account('/analytics_engine/sql'), {
+            body: query,
+            headers: { 'content-type': 'text/plain' },
+        });
+        const text = await response.text();
+        if (!response.ok)
+            throw failure('POST', 'Analytics Engine query', response.status, text);
+        return text;
+    }
     /** Write one KV value as text. */
     async kvPut(kv, key, value, contentType) {
         const response = await this.send('PUT', this.kvValue(kv, key), {
@@ -185,6 +234,10 @@ function describe(path) {
         return 'script settings';
     if (path.includes('/dispatch/namespaces/'))
         return 'namespace script';
+    if (path.includes('/analytics_engine/sql'))
+        return 'Analytics Engine query';
+    if (/\/storage\/kv\/namespaces\/[^/]+\/keys/u.test(path))
+        return 'KV keys';
     if (path.includes('/storage/kv/namespaces'))
         return 'KV namespace';
     return 'request';

package/dist/namespace/calls.d.ts

@@ -0,0 +1,29 @@
+import { type CloudflareApi } from './api.js';
+/** The most labels one Analytics Engine query names; a longer list is read in several queries. */
+export declare const LAST_CALL_QUERY_LABELS = 100;
+/**
+ * How long a preview is kept after its activation or its last call, whichever is later (AM-123):
+ * Services' rule, which the platform's preview expiry plan (SV6) applies to the platform namespace.
+ */
+export declare const PREVIEW_RETENTION_MILLISECONDS: number;
+/**
+ * The instant of each label's last call, from the data point the platform dispatcher writes for
+ * each call that runs a deployment (`CALLS.writeDataPoint({ indexes: [label] })`), read with the
+ * Analytics Engine SQL API: one read-only query for every `LAST_CALL_QUERY_LABELS` labels, the same
+ * query Services' `lastCalls` runs. A label without a data point reads `null`. Analytics Engine
+ * keeps three months of data points and samples busy labels, so the instant is the last call it
+ * kept: a busy label's is recent anyway.
+ *
+ * `undefined` when the API token lacks Account Analytics Read (the query is refused with 401 or
+ * 403): a listing then omits last calls and expiries rather than computing them from anything else
+ * (AM-133). Any other failure, or an answer that is not exactly the query's rows, throws: a listing
+ * never prints a last call it could not read.
+ */
+export declare function readLastCalls(api: CloudflareApi, dataset: string, labels: readonly string[]): Promise<ReadonlyMap<string, string | null> | undefined>;
+/** One Analytics Engine SQL query for the last call of each label in a batch. */
+export declare function lastCallsQuery(dataset: string, labels: readonly string[]): string;
+/**
+ * A preview's expiry: `PREVIEW_RETENTION_MILLISECONDS` after the later of its activation and its
+ * last call, as an ISO instant.
+ */
+export declare function previewExpiresAt(activatedAt: string, lastCallAt: string | null): string;

package/dist/namespace/calls.js

@@ -0,0 +1,104 @@
+import { parseDeploymentLabel } from '@astrale-os/sdk/deployment/address';
+import { CloudflareApiError } from './api.js';
+/** The most labels one Analytics Engine query names; a longer list is read in several queries. */
+export const LAST_CALL_QUERY_LABELS = 100;
+/**
+ * How long a preview is kept after its activation or its last call, whichever is later (AM-123):
+ * Services' rule, which the platform's preview expiry plan (SV6) applies to the platform namespace.
+ */
+export const PREVIEW_RETENTION_MILLISECONDS = 30 * 24 * 60 * 60 * 1_000;
+/** Analytics Engine dataset names, as `platformCallsDataset` derives them. */
+const DATASET = /^astrale_deployment_calls_[0-9a-f]{32}$/u;
+/** The only characters a deployment label has, so a label is quoted into SQL as it is. */
+const SQL_SAFE_LABEL = /^[a-z0-9-]+$/u;
+/**
+ * The instant of each label's last call, from the data point the platform dispatcher writes for
+ * each call that runs a deployment (`CALLS.writeDataPoint({ indexes: [label] })`), read with the
+ * Analytics Engine SQL API: one read-only query for every `LAST_CALL_QUERY_LABELS` labels, the same
+ * query Services' `lastCalls` runs. A label without a data point reads `null`. Analytics Engine
+ * keeps three months of data points and samples busy labels, so the instant is the last call it
+ * kept: a busy label's is recent anyway.
+ *
+ * `undefined` when the API token lacks Account Analytics Read (the query is refused with 401 or
+ * 403): a listing then omits last calls and expiries rather than computing them from anything else
+ * (AM-133). Any other failure, or an answer that is not exactly the query's rows, throws: a listing
+ * never prints a last call it could not read.
+ */
+export async function readLastCalls(api, dataset, labels) {
+    if (!DATASET.test(dataset))
+        throw new TypeError('The calls dataset name is invalid.');
+    const unique = [...new Set(labels)].sort();
+    for (const label of unique) {
+        parseDeploymentLabel(label);
+        if (!SQL_SAFE_LABEL.test(label))
+            throw new TypeError('Deployment label is invalid.');
+    }
+    const calls = new Map(unique.map((label) => [label, null]));
+    for (let start = 0; start < unique.length; start += LAST_CALL_QUERY_LABELS) {
+        const batch = unique.slice(start, start + LAST_CALL_QUERY_LABELS);
+        let text;
+        try {
+            text = await api.sql(lastCallsQuery(dataset, batch));
+        }
+        catch (cause) {
+            if (cause instanceof CloudflareApiError && (cause.status === 401 || cause.status === 403)) {
+                return undefined;
+            }
+            throw cause;
+        }
+        for (const [label, instant] of lastCallRows(text, new Set(batch)))
+            calls.set(label, instant);
+    }
+    return calls;
+}
+/** One Analytics Engine SQL query for the last call of each label in a batch. */
+export function lastCallsQuery(dataset, labels) {
+    const list = labels.map((label) => `'${label}'`).join(', ');
+    return [
+        'SELECT index1 AS label, toUnixTimestamp(max(timestamp)) AS last',
+        `FROM ${dataset}`,
+        `WHERE index1 IN (${list})`,
+        'GROUP BY index1',
+        'FORMAT JSON',
+    ].join(' ');
+}
+/**
+ * A preview's expiry: `PREVIEW_RETENTION_MILLISECONDS` after the later of its activation and its
+ * last call, as an ISO instant.
+ */
+export function previewExpiresAt(activatedAt, lastCallAt) {
+    const activated = Date.parse(activatedAt);
+    const called = lastCallAt === null ? activated : Date.parse(lastCallAt);
+    return new Date(Math.max(activated, called) + PREVIEW_RETENTION_MILLISECONDS).toISOString();
+}
+/** The rows of one query's JSON document: each a label it asked for and a positive instant. */
+function lastCallRows(text, asked) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new TypeError('Cloudflare returned invalid deployment call evidence.', { cause });
+    }
+    const data = parsed?.data;
+    if (!Array.isArray(data))
+        invalid();
+    const rows = [];
+    const seen = new Set();
+    for (const row of data) {
+        if (row === null || typeof row !== 'object' || Array.isArray(row))
+            invalid();
+        const { label, last } = row;
+        if (typeof label !== 'string' || !asked.has(label) || seen.has(label))
+            invalid();
+        const seconds = typeof last === 'string' ? Number(last) : last;
+        if (typeof seconds !== 'number' || !Number.isSafeInteger(seconds) || seconds <= 0)
+            invalid();
+        seen.add(label);
+        rows.push([label, new Date(seconds * 1_000).toISOString()]);
+    }
+    return rows;
+}
+function invalid() {
+    throw new TypeError('Cloudflare returned invalid deployment call evidence.');
+}

package/dist/namespace/coordinates.d.ts

@@ -12,6 +12,8 @@ export interface NamespaceCoordinates {
     readonly account?: string;
     /** The title of the routing KV the platform dispatcher reads (`SCHEDULES`). */
     readonly routingKvTitle: string;
+    /** The Analytics Engine dataset the platform dispatcher writes one data point to per call (`CALLS`). */
+    readonly callsDataset: string;
 }
 /**
  * Admit the `namespace` of one Environment, and that the Environment names no direct-mode
@@ -25,6 +27,13 @@ export declare function namespaceCoordinates(parameters: CloudflareParams): Name
  * namespace name alone and its configuration holds no KV id.
  */
 export declare function platformRoutingKvTitle(name: string): string;
+/**
+ * The Analytics Engine dataset of a platform namespace's calls: `astrale_deployment_calls_<hex32>`,
+ * with the `<hex32>` of its routing KV title (AM-131). The platform dispatcher (SV6) writes one data
+ * point `{ indexes: [label] }` to it for each call that runs a deployment; a listing reads the last
+ * call of each label from it, with the Analytics Engine SQL API, and never writes to it.
+ */
+export declare function platformCallsDataset(name: string): string;
 /** The KV key whose presence activates a label at the dispatcher (AM-89): its record. */
 export declare function recordKey(label: string): string;
 /** The KV key of a platform deployment's summary (AM-131), written before its record. */

package/dist/namespace/coordinates.js

@@ -37,6 +37,7 @@ export function namespaceCoordinates(parameters) {
         routingDomain: namespace.routingDomain,
         ...(namespace.account === undefined ? {} : { account: namespace.account }),
         routingKvTitle: platformRoutingKvTitle(namespace.name),
+        callsDataset: platformCallsDataset(namespace.name),
     });
 }
 /**
@@ -48,6 +49,15 @@ export function namespaceCoordinates(parameters) {
 export function platformRoutingKvTitle(name) {
     return `astrale-deployment-routing-${digestPrefix(name)}`;
 }
+/**
+ * The Analytics Engine dataset of a platform namespace's calls: `astrale_deployment_calls_<hex32>`,
+ * with the `<hex32>` of its routing KV title (AM-131). The platform dispatcher (SV6) writes one data
+ * point `{ indexes: [label] }` to it for each call that runs a deployment; a listing reads the last
+ * call of each label from it, with the Analytics Engine SQL API, and never writes to it.
+ */
+export function platformCallsDataset(name) {
+    return `astrale_deployment_calls_${digestPrefix(name)}`;
+}
 /** The KV key whose presence activates a label at the dispatcher (AM-89): its record. */
 export function recordKey(label) {
     return `record:${label}`;

package/dist/namespace/deploy-release.d.ts

@@ -1,6 +1,8 @@
 import type { Placement, ReleaseDeployContext, ReleaseDeployResult, RetainContext } from '@astrale-os/sdk/deployment/adapter';
 import type { SigningIdentityMaterial } from '../identity/material.js';
 import type { CloudflareParams } from '../params.js';
+import type { NamespaceCoordinates } from './coordinates.js';
+import { CloudflareApi } from './api.js';
 /** The effects of namespace mode, replaceable in tests. */
 export interface NamespaceDependencies {
     /** Reaches the Cloudflare API, and the deployment URL for readiness. */
@@ -47,3 +49,8 @@ export declare function deployNamespaceRelease(parameters: CloudflareParams, con
  * `published`, which the platform's preview expiry never retires. Nothing else changes.
  */
 export declare function retainNamespaceDeployment(parameters: CloudflareParams, context: RetainContext, dependencies: NamespaceDependencies): Promise<void>;
+/**
+ * The Cloudflare API of the namespace's account, with the token of `CLOUDFLARE_API_TOKEN`; `token`
+ * says what the operation needs of it.
+ */
+export declare function cloudflareApi(coordinates: NamespaceCoordinates, signal: AbortSignal, dependencies: Pick<NamespaceDependencies, 'fetch' | 'environment' | 'pause' | 'apiBase'>, token?: string): CloudflareApi;

package/dist/namespace/deploy-release.js

@@ -364,19 +364,24 @@ function expectedBinding(binding) {
 function byName(left, right) {
     return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
 }
-function cloudflareApi(coordinates, signal, dependencies) {
+/** What a deploy asks of `CLOUDFLARE_API_TOKEN`, as a missing token is told. */
+const DEPLOY_TOKEN = 'a token that edits the scripts of the platform namespace and the values of its routing KV';
+/**
+ * The Cloudflare API of the namespace's account, with the token of `CLOUDFLARE_API_TOKEN`; `token`
+ * says what the operation needs of it.
+ */
+export function cloudflareApi(coordinates, signal, dependencies, token = DEPLOY_TOKEN) {
     const accountId = coordinates.account ?? dependencies.environment.CLOUDFLARE_ACCOUNT_ID;
     if (accountId === undefined || !/^[0-9a-f]{32}$/u.test(accountId)) {
         throw new TypeError('Namespace mode needs the Cloudflare account: set `namespace.account` or CLOUDFLARE_ACCOUNT_ID.');
     }
-    const token = dependencies.environment.CLOUDFLARE_API_TOKEN;
-    if (token === undefined || token.length === 0 || token.trim() !== token) {
-        throw new TypeError('Namespace mode needs CLOUDFLARE_API_TOKEN: a token that edits the scripts of the platform ' +
-            'namespace and the values of its routing KV.');
+    const secret = dependencies.environment.CLOUDFLARE_API_TOKEN;
+    if (secret === undefined || secret.length === 0 || secret.trim() !== secret) {
+        throw new TypeError(`Namespace mode needs CLOUDFLARE_API_TOKEN: ${token}.`);
     }
     return new CloudflareApi({
         accountId,
-        token,
+        token: secret,
         fetch: dependencies.fetch,
         signal,
         ...(dependencies.apiBase === undefined ? {} : { base: dependencies.apiBase }),

package/dist/namespace/index.d.ts

@@ -1,12 +1,15 @@
 /**
  * Namespace mode of adapter-cloudflare (D4, CT33 `canonical`): each release of an Environment
  * becomes one immutable script in a platform dispatch namespace, named by its deployment label
- * and activated by its record in the namespace's routing KV (AM-131).
+ * and activated by its record in the namespace's routing KV (AM-131). Its deployments are listed
+ * from that KV, with their last calls from the namespace's calls dataset (AM-133).
  */
 export { CloudflareApi, CloudflareApiError, CLOUDFLARE_API_BASE } from './api.js';
+export { LAST_CALL_QUERY_LABELS, lastCallsQuery, PREVIEW_RETENTION_MILLISECONDS, previewExpiresAt, readLastCalls, } from './calls.js';
 export { ASSETS_BINDING, configureNamespace, ROUTER_BINDING, VERSION_METADATA_BINDING, } from './configure.js';
-export { admitNamespace, DIRECT_PARAMETERS, namespaceCoordinates, platformRoutingKvTitle, recordKey, retirementKey, summaryKey, type NamespaceCoordinates, } from './coordinates.js';
+export { admitNamespace, DIRECT_PARAMETERS, namespaceCoordinates, platformCallsDataset, platformRoutingKvTitle, recordKey, retirementKey, summaryKey, type NamespaceCoordinates, } from './coordinates.js';
 export { deployNamespaceRelease, placeNamespace, retainNamespaceDeployment, type NamespaceDependencies, } from './deploy-release.js';
+export { listNamespaceDeployments } from './list.js';
 export { ACTIVATION_READINESS_MS, ROTATION_READINESS_MS, waitForNamespaceReadiness, } from './readiness.js';
 export { NamespaceRefusal, PlatformRouting, sameRelease } from './routing.js';
 export { ARTIFACT_TAG_PREFIX, deploymentBindings, deploymentSettings, deploymentTags, KEY_TAG_PREFIX, LINE_TAG_PREFIX, SERVICES_TAG, versionUuid, type NamespaceScript, type ScriptBinding, } from './script.js';

package/dist/namespace/index.js

@@ -1,12 +1,15 @@
 /**
  * Namespace mode of adapter-cloudflare (D4, CT33 `canonical`): each release of an Environment
  * becomes one immutable script in a platform dispatch namespace, named by its deployment label
- * and activated by its record in the namespace's routing KV (AM-131).
+ * and activated by its record in the namespace's routing KV (AM-131). Its deployments are listed
+ * from that KV, with their last calls from the namespace's calls dataset (AM-133).
  */
 export { CloudflareApi, CloudflareApiError, CLOUDFLARE_API_BASE } from './api.js';
+export { LAST_CALL_QUERY_LABELS, lastCallsQuery, PREVIEW_RETENTION_MILLISECONDS, previewExpiresAt, readLastCalls, } from './calls.js';
 export { ASSETS_BINDING, configureNamespace, ROUTER_BINDING, VERSION_METADATA_BINDING, } from './configure.js';
-export { admitNamespace, DIRECT_PARAMETERS, namespaceCoordinates, platformRoutingKvTitle, recordKey, retirementKey, summaryKey, } from './coordinates.js';
+export { admitNamespace, DIRECT_PARAMETERS, namespaceCoordinates, platformCallsDataset, platformRoutingKvTitle, recordKey, retirementKey, summaryKey, } from './coordinates.js';
 export { deployNamespaceRelease, placeNamespace, retainNamespaceDeployment, } from './deploy-release.js';
+export { listNamespaceDeployments } from './list.js';
 export { ACTIVATION_READINESS_MS, ROTATION_READINESS_MS, waitForNamespaceReadiness, } from './readiness.js';
 export { NamespaceRefusal, PlatformRouting, sameRelease } from './routing.js';
 export { ARTIFACT_TAG_PREFIX, deploymentBindings, deploymentSettings, deploymentTags, KEY_TAG_PREFIX, LINE_TAG_PREFIX, SERVICES_TAG, versionUuid, } from './script.js';

package/dist/namespace/list.d.ts

@@ -0,0 +1,33 @@
+import type { ListContext, ListedDeployment } from '@astrale-os/sdk/deployment/adapter';
+import type { CloudflareParams } from '../params.js';
+import type { NamespaceDependencies } from './deploy-release.js';
+/**
+ * The deployments of one Environment that the platform namespace keeps: one per `summary:<label>`
+ * of the Environment's line in the routing KV found by its derived title (AM-131), in label order.
+ * Nothing is written, to the KV, to a script or to the calls dataset.
+ *
+ * Each deployment carries what its summary says of it, its record as `record:<label>` stores it,
+ * unadmitted (the listing admits it, and lists one it refuses from the summary's facts), and its
+ * call target, the namespace and the script SV6's per-script tooling takes: there is no Services
+ * node to call. The routing KV decides what the dispatcher serves, so it also decides the state: a
+ * summary without `record:<label>` is a deployment uploaded but not activated (`deploying`, without
+ * a record, since the platform keeps none: the dispatcher answers 503 for it), and an `active`
+ * summary whose label carries the tombstone `retirement:<label>` is `retiring`, with the tombstone's
+ * value as its retirement (the dispatcher answers 410), until the retirement tooling records it in
+ * the summary.
+ *
+ * The records and tombstones are listed before the summaries: a deployer writes a label's summary
+ * before the record that activates it (AM-131), so a deploy that lands during the listing is seen
+ * whole or not at all. A record whose summary the key listing does not show yet (Workers KV lists
+ * are eventually consistent) has its summary read directly.
+ *
+ * Nothing on the platform namespace records a last call (AM-133): each one is read from the calls
+ * dataset, for every activated label (the dispatcher counts no other), and an active preview expires
+ * 30 days after the later of its activation (`createdAt`) and that call. Without Account Analytics
+ * Read, both are omitted, never taken from anything else. A summary that does not decode, a record
+ * whose summary cannot be read, a tombstone that is neither `expired` nor `withdrawn`, a key of the
+ * line that names no deployment, or a last-calls query that fails or answers other rows, fails the
+ * listing of the Environment: a row is never printed without its facts, and no activated deployment
+ * is left out.
+ */
+export declare function listNamespaceDeployments(parameters: CloudflareParams, context: ListContext, dependencies: NamespaceDependencies): Promise<readonly ListedDeployment[]>;

package/dist/namespace/list.js

@@ -0,0 +1,139 @@
+import { deploymentLine } from '@astrale-os/sdk/deployment/address';
+import { previewExpiresAt, readLastCalls } from './calls.js';
+import { namespaceCoordinates } from './coordinates.js';
+import { cloudflareApi } from './deploy-release.js';
+import { NamespaceRefusal, PlatformRouting } from './routing.js';
+/** What a listing asks of `CLOUDFLARE_API_TOKEN`, as a missing token is told. */
+const LIST_TOKEN = 'a token that reads the values of its routing KV, and with Account Analytics Read the calls ' +
+    'dataset its last calls come from';
+/**
+ * The deployments of one Environment that the platform namespace keeps: one per `summary:<label>`
+ * of the Environment's line in the routing KV found by its derived title (AM-131), in label order.
+ * Nothing is written, to the KV, to a script or to the calls dataset.
+ *
+ * Each deployment carries what its summary says of it, its record as `record:<label>` stores it,
+ * unadmitted (the listing admits it, and lists one it refuses from the summary's facts), and its
+ * call target, the namespace and the script SV6's per-script tooling takes: there is no Services
+ * node to call. The routing KV decides what the dispatcher serves, so it also decides the state: a
+ * summary without `record:<label>` is a deployment uploaded but not activated (`deploying`, without
+ * a record, since the platform keeps none: the dispatcher answers 503 for it), and an `active`
+ * summary whose label carries the tombstone `retirement:<label>` is `retiring`, with the tombstone's
+ * value as its retirement (the dispatcher answers 410), until the retirement tooling records it in
+ * the summary.
+ *
+ * The records and tombstones are listed before the summaries: a deployer writes a label's summary
+ * before the record that activates it (AM-131), so a deploy that lands during the listing is seen
+ * whole or not at all. A record whose summary the key listing does not show yet (Workers KV lists
+ * are eventually consistent) has its summary read directly.
+ *
+ * Nothing on the platform namespace records a last call (AM-133): each one is read from the calls
+ * dataset, for every activated label (the dispatcher counts no other), and an active preview expires
+ * 30 days after the later of its activation (`createdAt`) and that call. Without Account Analytics
+ * Read, both are omitted, never taken from anything else. A summary that does not decode, a record
+ * whose summary cannot be read, a tombstone that is neither `expired` nor `withdrawn`, a key of the
+ * line that names no deployment, or a last-calls query that fails or answers other rows, fails the
+ * listing of the Environment: a row is never printed without its facts, and no activated deployment
+ * is left out.
+ */
+export async function listNamespaceDeployments(parameters, context, dependencies) {
+    const coordinates = namespaceCoordinates(parameters);
+    const api = cloudflareApi(coordinates, context.signal, dependencies, LIST_TOKEN);
+    const routing = await PlatformRouting.open(api, coordinates.routingKvTitle);
+    const line = deploymentLine({
+        origin: context.origin,
+        environment: context.environment,
+        addressing: 'readable',
+    });
+    const activated = new Set(await routing.labels('record', line));
+    const withdrawn = new Set(await routing.labels('retirement', line));
+    const summarized = new Set(await routing.labels('summary', line));
+    const labels = [...new Set([...summarized, ...activated])].sort();
+    const listed = [];
+    for (const label of labels) {
+        const summary = await routing.summary(label);
+        if (summary === undefined) {
+            throw new NamespaceRefusal('summary-invalid', summarized.has(label)
+                ? `The summary of ${label} disappeared while the namespace was listed; list again.`
+                : // The deployer writes a summary before the record that activates its label (AM-131).
+                    `The routing KV activates ${label} without a summary; list again, and if it ` +
+                        'persists, the summary its deployer writes first is lost.');
+        }
+        let record = {};
+        if (activated.has(label)) {
+            const stored = await routing.storedRecord(label);
+            if (stored === undefined) {
+                throw new NamespaceRefusal('record-invalid', `The record of ${label} disappeared while the namespace was listed; list again.`);
+            }
+            record = { record: stored };
+        }
+        else if (summary.state === 'active') {
+            // A deploy may write its summary and then its record between the record and the summary
+            // key listings: read the record of an active summary-only label directly, so a deployment
+            // activated during the listing is listed as the dispatcher serves it.
+            const stored = await routing.storedRecord(label);
+            if (stored !== undefined) {
+                activated.add(label);
+                record = { record: stored };
+            }
+        }
+        let retirement = {};
+        if (withdrawn.has(label) && summary.state === 'active') {
+            const tombstone = await routing.retirement(label);
+            if (tombstone !== undefined) {
+                if (tombstone !== 'expired' && tombstone !== 'withdrawn') {
+                    throw new NamespaceRefusal('retirement-invalid', `The tombstone of ${label} is neither expired nor withdrawn.`);
+                }
+                retirement = { retirement: tombstone };
+            }
+        }
+        listed.push({ summary, ...record, ...retirement });
+    }
+    const called = await readLastCalls(api, coordinates.callsDataset, labels.filter((label) => activated.has(label)));
+    return Object.freeze(listed.map((deployment) => {
+        const { summary } = deployment;
+        const state = observedState(summary, 'record' in deployment, deployment.retirement);
+        const lastCall = called?.get(summary.label);
+        return Object.freeze({
+            id: summary.id,
+            url: summary.url,
+            label: summary.label,
+            line: summary.line,
+            owner: summary.owner,
+            state: state.state,
+            retention: summary.retention,
+            createdAt: summary.createdAt,
+            ...(lastCall === undefined || lastCall === null ? {} : { lastCallAt: lastCall }),
+            ...(called !== undefined && state.state === 'active' && summary.retention === 'preview'
+                ? { expiresAt: previewExpiresAt(summary.createdAt, lastCall ?? null) }
+                : {}),
+            ...(summary.retiredAt === undefined ? {} : { retiredAt: summary.retiredAt }),
+            ...(state.retirement === undefined ? {} : { retirement: state.retirement }),
+            signingKeyId: summary.signingKeyId,
+            ...('record' in deployment ? { record: deployment.record } : {}),
+            callTarget: Object.freeze({
+                kind: 'namespace',
+                namespace: coordinates.name,
+                script: summary.label,
+            }),
+        });
+    }));
+}
+/**
+ * The state of a platform deployment as the dispatcher serves it: its summary's, except that an
+ * `active` summary is `retiring` once the tombstone `retirement:<label>` retires the label (with the
+ * tombstone's value), and else `deploying` until `record:<label>` activates it. The dispatcher reads
+ * the tombstone first: a tombstoned label answers 410 with or without a record.
+ */
+function observedState(summary, activated, tombstone) {
+    if (summary.state !== 'active') {
+        return {
+            state: summary.state,
+            ...(summary.retirement === undefined ? {} : { retirement: summary.retirement }),
+        };
+    }
+    if (tombstone !== undefined)
+        return { state: 'retiring', retirement: tombstone };
+    if (!activated)
+        return { state: 'deploying' };
+    return { state: 'active' };
+}

package/dist/namespace/routing.d.ts

@@ -2,7 +2,7 @@ import type { DeploymentRecordV1, PlatformDeploymentSummaryV1 } from '@astrale-o
 import type { CloudflareApi } from './api.js';
 /** Why namespace mode refused before or instead of a write at the host. */
 export declare class NamespaceRefusal extends Error {
-    readonly reason: 'not-provisioned' | 'deployment-conflict' | 'deployment-retired' | 'summary-invalid' | 'record-invalid';
+    readonly reason: 'not-provisioned' | 'deployment-conflict' | 'deployment-retired' | 'summary-invalid' | 'record-invalid' | 'retirement-invalid';
     constructor(reason: NamespaceRefusal['reason'], message: string);
 }
 /**
@@ -21,6 +21,19 @@ export declare class PlatformRouting {
     retirement(label: string): Promise<string | undefined>;
     /** The record a label was activated with, admitted exactly, or undefined when not activated. */
     record(label: string): Promise<DeploymentRecordV1 | undefined>;
+    /**
+     * The labels of one line that hold a key of `kind` (`summary:<label>`, `record:<label>` or
+     * `retirement:<label>`), from one listing of the keys under `<kind>:<line>-`. A key there that
+     * names no deployment label is refused; one whose label is on another line, whose readable part
+     * happens to extend this one, is not this line's.
+     */
+    labels(kind: 'summary' | 'record' | 'retirement', line: string): Promise<readonly string[]>;
+    /**
+     * The record a label was activated with, as stored and never admitted: its JSON value (JSON
+     * `null` included), or its text when that is not JSON; undefined when the label has no record. A
+     * listing admits it.
+     */
+    storedRecord(label: string): Promise<unknown>;
     /** The summary of a label, admitted exactly, or undefined when it has none. */
     summary(label: string): Promise<PlatformDeploymentSummaryV1 | undefined>;
     /** Write one summary as its canonical text and read it back. */

package/dist/namespace/routing.js

@@ -1,4 +1,4 @@
-import { acceptDeploymentRecord, acceptPlatformDeploymentSummary, encodePlatformDeploymentSummary, } from '@astrale-os/sdk/deployment/address';
+import { acceptDeploymentRecord, acceptPlatformDeploymentSummary, encodePlatformDeploymentSummary, parseDeploymentLabel, } from '@astrale-os/sdk/deployment/address';
 import { json } from '@astrale-os/sdk/value';
 import { recordKey, retirementKey, summaryKey } from './coordinates.js';
 /** Why namespace mode refused before or instead of a write at the host. */
@@ -64,6 +64,45 @@ export class PlatformRouting {
         }
         return record;
     }
+    /**
+     * The labels of one line that hold a key of `kind` (`summary:<label>`, `record:<label>` or
+     * `retirement:<label>`), from one listing of the keys under `<kind>:<line>-`. A key there that
+     * names no deployment label is refused; one whose label is on another line, whose readable part
+     * happens to extend this one, is not this line's.
+     */
+    async labels(kind, line) {
+        const prefix = `${kind}:`;
+        const labels = [];
+        for (const name of await this.api.kvKeys(this.kv, `${prefix}${line}-`)) {
+            const label = name.slice(prefix.length);
+            let parts;
+            try {
+                parts = parseDeploymentLabel(label);
+            }
+            catch {
+                throw new NamespaceRefusal(`${kind}-invalid`, `The routing KV holds ${name}, which names no deployment label.`);
+            }
+            if (parts.line === line)
+                labels.push(label);
+        }
+        return labels;
+    }
+    /**
+     * The record a label was activated with, as stored and never admitted: its JSON value (JSON
+     * `null` included), or its text when that is not JSON; undefined when the label has no record. A
+     * listing admits it.
+     */
+    async storedRecord(label) {
+        const text = await this.api.kvGet(this.kv, recordKey(label));
+        if (text === undefined)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
     /** The summary of a label, admitted exactly, or undefined when it has none. */
     async summary(label) {
         const text = await this.api.kvGet(this.kv, summaryKey(label));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/adapter-cloudflare",
-  "version": "0.5.0-beta.169",
+  "version": "0.5.0-beta.170",
   "description": "Deploy an Astrale Domain through Cloudflare Workers",
   "keywords": [
     "adapter",
@@ -61,7 +61,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@astrale-os/sdk": "0.6.0-beta.14",
+    "@astrale-os/sdk": "0.6.0-beta.15",
     "@noble/hashes": "2.3.0",
     "@restatedev/restate-sdk-cloudflare-workers": "1.17.0",
     "hono": "^4.6.20",