actor-ts 0.9.0

package/dist/coordination/leases/k8sApi.d.ts

@@ -0,0 +1,82 @@
+export interface K8sCredentials {
+    /** API server URL (defaults to https://kubernetes.default.svc when running in-cluster). */
+    readonly apiServerUrl: string;
+    /** Bearer token for the ServiceAccount. */
+    readonly authToken: string;
+    /** PEM-encoded CA cert pinned for the API server's TLS. */
+    readonly caCert: string;
+    /** Default namespace as read from the SA mount; user-supplied namespace wins where supplied. */
+    readonly defaultNamespace?: string;
+}
+/**
+ * Load credentials from the standard ServiceAccount mount points.  Returns
+ * `null` (rather than throwing) when none of the files are present so the
+ * caller can fall back to explicit settings.
+ */
+export declare function loadInClusterCredentials(): Promise<K8sCredentials | null>;
+export interface K8sRequestOptions {
+    readonly method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    readonly path: string;
+    readonly body?: unknown;
+    /** Provide a request-injected client (test override). */
+    readonly client?: K8sFetchClient;
+}
+export interface K8sResponse {
+    readonly status: number;
+    readonly body: unknown;
+}
+/** Test seam — the real impl uses `node:https`; tests pass a mock. */
+export interface K8sFetchClient {
+    request(creds: K8sCredentials, opts: K8sRequestOptions): Promise<K8sResponse>;
+}
+/**
+ * Perform a request against the K8s API server.  Uses `node:https` with
+ * the SA-supplied CA pinned, plus a `Bearer` token in the `Authorization`
+ * header.  Returns `{ status, body }` — the caller is responsible for
+ * mapping HTTP status to lease semantics (200 ok, 404 missing,
+ * 409 conflict).
+ */
+export declare function k8sRequest(creds: K8sCredentials, opts: K8sRequestOptions): Promise<K8sResponse>;
+/**
+ * Wire shape for `coordination.k8s.io/v1/Lease`.  We only model the fields
+ * we touch — Kubernetes returns more (managedFields, generateName, etc.)
+ * but they round-trip through `unknown` if we send them back unchanged.
+ */
+export interface K8sLeaseObject {
+    readonly apiVersion: 'coordination.k8s.io/v1';
+    readonly kind: 'Lease';
+    readonly metadata: {
+        readonly name: string;
+        readonly namespace: string;
+        readonly resourceVersion?: string;
+        readonly [key: string]: unknown;
+    };
+    readonly spec: {
+        readonly holderIdentity?: string;
+        readonly leaseDurationSeconds?: number;
+        readonly acquireTime?: string;
+        readonly renewTime?: string;
+        readonly leaseTransitions?: number;
+    };
+}
+/** GET — returns null on 404 (lease doesn't exist yet). */
+export declare function getLease(creds: K8sCredentials, namespace: string, name: string, client?: K8sFetchClient): Promise<K8sLeaseObject | null>;
+/**
+ * CREATE — returns the created lease, or null on 409 (race: someone else
+ * created it first; the caller should re-GET and try acquire).
+ */
+export declare function createLease(creds: K8sCredentials, namespace: string, spec: Pick<K8sLeaseObject['spec'], 'holderIdentity' | 'leaseDurationSeconds' | 'acquireTime' | 'renewTime'>, name: string, client?: K8sFetchClient): Promise<K8sLeaseObject | null>;
+/**
+ * PUT — optimistic-write update.  Pass the lease object you got from
+ * `getLease`, with `metadata.resourceVersion` intact, and the spec
+ * fields modified.  Returns null on 409 (someone else mutated the lease
+ * since we read it; caller should re-GET + retry or treat as lost).
+ */
+export declare function updateLease(creds: K8sCredentials, lease: K8sLeaseObject, client?: K8sFetchClient): Promise<K8sLeaseObject | null>;
+/** DELETE — best-effort, returns void.  404 is treated as success (already gone). */
+export declare function deleteLease(creds: K8sCredentials, namespace: string, name: string, client?: K8sFetchClient): Promise<void>;
+export declare class K8sLeaseError extends Error {
+    readonly response: K8sResponse;
+    constructor(message: string, response: K8sResponse);
+}
+//# sourceMappingURL=k8sApi.d.ts.map

package/dist/coordination/leases/k8sApi.d.ts.map

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

package/dist/coordination/leases/k8sApi.js

@@ -0,0 +1,191 @@
+import { Lazy } from '../../util/Lazy.js';
+/**
+ * Low-level Kubernetes API helpers used by `KubernetesLease`.  Three
+ * concerns live here: where we get our credentials (Pod-mounted
+ * ServiceAccount or explicit overrides), how we talk to the API server
+ * (TLS-pinned `node:https.request`), and the four CRUD operations on
+ * `coordination.k8s.io/v1/Lease` objects.
+ *
+ * We intentionally do NOT depend on `@kubernetes/client-node` — the
+ * surface we need is small (3 endpoints), and the official client adds
+ * ~3 MB of dependencies that small / edge deployments can do without.
+ */
+/* --------------------------- credentials ------------------------------ */
+const SERVICE_ACCOUNT_DIR = '/var/run/secrets/kubernetes.io/serviceaccount';
+/**
+ * Load credentials from the standard ServiceAccount mount points.  Returns
+ * `null` (rather than throwing) when none of the files are present so the
+ * caller can fall back to explicit settings.
+ */
+export async function loadInClusterCredentials() {
+    const fs = await fsLazy.get();
+    try {
+        const [token, caCert, ns] = await Promise.all([
+            fs.readFile(`${SERVICE_ACCOUNT_DIR}/token`, 'utf8').catch(() => null),
+            fs.readFile(`${SERVICE_ACCOUNT_DIR}/ca.crt`, 'utf8').catch(() => null),
+            fs.readFile(`${SERVICE_ACCOUNT_DIR}/namespace`, 'utf8').catch(() => null),
+        ]);
+        if (!token || !caCert)
+            return null;
+        // KUBERNETES_SERVICE_HOST is set by the kubelet in every Pod.
+        const host = globalThis
+            .process?.env?.KUBERNETES_SERVICE_HOST;
+        const port = globalThis
+            .process?.env?.KUBERNETES_SERVICE_PORT_HTTPS
+            ?? globalThis
+                .process?.env?.KUBERNETES_SERVICE_PORT
+            ?? '443';
+        const apiServerUrl = host
+            ? `https://${host}:${port}`
+            : 'https://kubernetes.default.svc';
+        return {
+            apiServerUrl,
+            authToken: token.trim(),
+            caCert,
+            defaultNamespace: ns ? ns.trim() : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Perform a request against the K8s API server.  Uses `node:https` with
+ * the SA-supplied CA pinned, plus a `Bearer` token in the `Authorization`
+ * header.  Returns `{ status, body }` — the caller is responsible for
+ * mapping HTTP status to lease semantics (200 ok, 404 missing,
+ * 409 conflict).
+ */
+export async function k8sRequest(creds, opts) {
+    const client = opts.client ?? (await defaultClient.get());
+    return client.request(creds, opts);
+}
+/** Real `node:https` client — lazy-imported so test mocks can short-circuit. */
+const defaultClient = Lazy.of(async () => {
+    const httpsModule = 'node:https';
+    const urlModule = 'node:url';
+    const https = await import(httpsModule);
+    const { URL } = await import(urlModule);
+    return {
+        async request(creds, opts) {
+            return new Promise((resolve, reject) => {
+                const url = new URL(opts.path, creds.apiServerUrl);
+                const bodyString = opts.body === undefined ? null : JSON.stringify(opts.body);
+                const headers = {
+                    Authorization: `Bearer ${creds.authToken}`,
+                    Accept: 'application/json',
+                };
+                if (bodyString !== null) {
+                    headers['Content-Type'] = 'application/json';
+                    headers['Content-Length'] = String(Buffer.byteLength(bodyString));
+                }
+                const req = https.request({
+                    method: opts.method,
+                    hostname: url.hostname,
+                    port: url.port || 443,
+                    path: url.pathname + url.search,
+                    headers,
+                    ca: creds.caCert,
+                    // Conservative timeout — beyond this the K8s API server is
+                    // probably unreachable; the lease ought to be considered lost.
+                    timeout: 10_000,
+                }, (res) => {
+                    const chunks = [];
+                    res.on('data', (c) => chunks.push(c));
+                    res.on('end', () => {
+                        const raw = Buffer.concat(chunks).toString('utf8');
+                        let parsed = raw;
+                        if (raw.length > 0) {
+                            try {
+                                parsed = JSON.parse(raw);
+                            }
+                            catch { /* leave as string */ }
+                        }
+                        resolve({ status: res.statusCode ?? 0, body: parsed });
+                    });
+                });
+                req.on('error', reject);
+                req.on('timeout', () => { req.destroy(new Error('k8s request timeout')); });
+                if (bodyString !== null)
+                    req.write(bodyString);
+                req.end();
+            });
+        },
+    };
+});
+const fsLazy = Lazy.of(async () => {
+    const name = 'node:fs/promises';
+    return await import(name);
+});
+const leasePath = (ns, name) => `/apis/coordination.k8s.io/v1/namespaces/${encodeURIComponent(ns)}/leases${name ? `/${encodeURIComponent(name)}` : ''}`;
+/** GET — returns null on 404 (lease doesn't exist yet). */
+export async function getLease(creds, namespace, name, client) {
+    const res = await k8sRequest(creds, {
+        method: 'GET', path: leasePath(namespace, name), client,
+    });
+    if (res.status === 404)
+        return null;
+    if (res.status !== 200)
+        throw new K8sLeaseError(`GET lease ${namespace}/${name} → HTTP ${res.status}`, res);
+    return res.body;
+}
+/**
+ * CREATE — returns the created lease, or null on 409 (race: someone else
+ * created it first; the caller should re-GET and try acquire).
+ */
+export async function createLease(creds, namespace, spec, name, client) {
+    const body = {
+        apiVersion: 'coordination.k8s.io/v1',
+        kind: 'Lease',
+        metadata: { name, namespace },
+        spec: { ...spec, leaseTransitions: 1 },
+    };
+    const res = await k8sRequest(creds, {
+        method: 'POST', path: leasePath(namespace), body, client,
+    });
+    if (res.status === 201)
+        return res.body;
+    if (res.status === 409)
+        return null;
+    throw new K8sLeaseError(`CREATE lease ${namespace}/${name} → HTTP ${res.status}`, res);
+}
+/**
+ * PUT — optimistic-write update.  Pass the lease object you got from
+ * `getLease`, with `metadata.resourceVersion` intact, and the spec
+ * fields modified.  Returns null on 409 (someone else mutated the lease
+ * since we read it; caller should re-GET + retry or treat as lost).
+ */
+export async function updateLease(creds, lease, client) {
+    const res = await k8sRequest(creds, {
+        method: 'PUT',
+        path: leasePath(lease.metadata.namespace, lease.metadata.name),
+        body: lease,
+        client,
+    });
+    if (res.status === 200)
+        return res.body;
+    if (res.status === 409)
+        return null;
+    if (res.status === 404)
+        return null; // someone deleted it between get + put
+    throw new K8sLeaseError(`PUT lease ${lease.metadata.namespace}/${lease.metadata.name} → HTTP ${res.status}`, res);
+}
+/** DELETE — best-effort, returns void.  404 is treated as success (already gone). */
+export async function deleteLease(creds, namespace, name, client) {
+    const res = await k8sRequest(creds, {
+        method: 'DELETE', path: leasePath(namespace, name), client,
+    });
+    if (res.status === 200 || res.status === 202 || res.status === 404)
+        return;
+    throw new K8sLeaseError(`DELETE lease ${namespace}/${name} → HTTP ${res.status}`, res);
+}
+/* ---------------------------- errors --------------------------------- */
+export class K8sLeaseError extends Error {
+    response;
+    constructor(message, response) {
+        super(message);
+        this.response = response;
+        this.name = 'K8sLeaseError';
+    }
+}
+//# sourceMappingURL=k8sApi.js.map

package/dist/coordination/leases/k8sApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"k8sApi.js","sourceRoot":"","sources":["../../../src/coordination/leases/k8sApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE1C;;;;;;;;;;GAUG;AAEH,4EAA4E;AAE5E,MAAM,mBAAmB,GAAG,+CAA+C,CAAC;AAa5E;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB;IAC5C,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC5C,EAAE,CAAC,QAAQ,CAAC,GAAG,mBAAmB,QAAQ,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;YACrE,EAAE,CAAC,QAAQ,CAAC,GAAG,mBAAmB,SAAS,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;YACtE,EAAE,CAAC,QAAQ,CAAC,GAAG,mBAAmB,YAAY,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;SAC1E,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QACnC,8DAA8D;QAC9D,MAAM,IAAI,GAAI,UAAyE;aACpF,OAAO,EAAE,GAAG,EAAE,uBAAuB,CAAC;QACzC,MAAM,IAAI,GAAI,UAAyE;aACpF,OAAO,EAAE,GAAG,EAAE,6BAA6B;eACxC,UAAyE;iBAC1E,OAAO,EAAE,GAAG,EAAE,uBAAuB;eACrC,KAAK,CAAC;QACX,MAAM,YAAY,GAAG,IAAI;YACvB,CAAC,CAAC,WAAW,IAAI,IAAI,IAAI,EAAE;YAC3B,CAAC,CAAC,gCAAgC,CAAC;QACrC,OAAO;YACL,YAAY;YACZ,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE;YACvB,MAAM;YACN,gBAAgB,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS;SAC7C,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAsBD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAqB,EACrB,IAAuB;IAEvB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,aAAa,CAAC,GAAG,EAAE,CAAC,CAAC;IAC1D,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,gFAAgF;AAChF,MAAM,aAAa,GAAkC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE;IACtE,MAAM,WAAW,GAAG,YAAY,CAAC;IACjC,MAAM,SAAS,GAAG,UAAU,CAAC;IAC7B,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,WAAW,CAAgC,CAAC;IACvE,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAA8B,CAAC;IACrE,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,KAAqB,EAAE,IAAuB;YAC1D,OAAO,IAAI,OAAO,CAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAClD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;gBACnD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC9E,MAAM,OAAO,GAA2B;oBACtC,aAAa,EAAE,UAAU,KAAK,CAAC,SAAS,EAAE;oBAC1C,MAAM,EAAE,kBAAkB;iBAC3B,CAAC;gBACF,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;oBACxB,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;oBAC7C,OAAO,CAAC,gBAAgB,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;gBACpE,CAAC;gBACD,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC;oBACxB,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,QAAQ,EAAE,GAAG,CAAC,QAAQ;oBACtB,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,GAAG;oBACrB,IAAI,EAAE,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM;oBAC/B,OAAO;oBACP,EAAE,EAAE,KAAK,CAAC,MAAM;oBAChB,2DAA2D;oBAC3D,+DAA+D;oBAC/D,OAAO,EAAE,MAAM;iBAChB,EAAE,CAAC,GAAG,EAAE,EAAE;oBACT,MAAM,MAAM,GAAa,EAAE,CAAC;oBAC5B,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC9C,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;wBACjB,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;wBACnD,IAAI,MAAM,GAAY,GAAG,CAAC;wBAC1B,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;4BACnB,IAAI,CAAC;gCAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;4BAAC,CAAC;4BACjC,MAAM,CAAC,CAAC,qBAAqB,CAAC,CAAC;wBACjC,CAAC;wBACD,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,UAAU,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;oBACzD,CAAC,CAAC,CAAC;gBACL,CAAC,CAAC,CAAC;gBACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;gBACxB,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC5E,IAAI,UAAU,KAAK,IAAI;oBAAE,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;gBAC/C,GAAG,CAAC,GAAG,EAAE,CAAC;YACZ,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,MAAM,MAAM,GAAqD,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE;IAClF,MAAM,IAAI,GAAG,kBAAkB,CAAC;IAChC,OAAO,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC,CAAC,CAAC;AA2BH,MAAM,SAAS,GAAG,CAAC,EAAU,EAAE,IAAa,EAAU,EAAE,CACtD,2CAA2C,kBAAkB,CAAC,EAAE,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AAE1H,2DAA2D;AAC3D,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,KAAqB,EACrB,SAAiB,EACjB,IAAY,EACZ,MAAuB;IAEvB,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE;QAClC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM;KACxD,CAAC,CAAC;IACH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,MAAM,IAAI,aAAa,CAAC,aAAa,SAAS,IAAI,IAAI,WAAW,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC;IAC5G,OAAO,GAAG,CAAC,IAAsB,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAqB,EACrB,SAAiB,EACjB,IAA2G,EAC3G,IAAY,EACZ,MAAuB;IAEvB,MAAM,IAAI,GAAmB;QAC3B,UAAU,EAAE,wBAAwB;QACpC,IAAI,EAAE,OAAO;QACb,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;QAC7B,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,gBAAgB,EAAE,CAAC,EAAE;KACvC,CAAC;IACF,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE;QAClC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM;KACzD,CAAC,CAAC;IACH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,GAAG,CAAC,IAAsB,CAAC;IAC1D,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,IAAI,aAAa,CAAC,gBAAgB,SAAS,IAAI,IAAI,WAAW,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC;AACzF,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAqB,EACrB,KAAqB,EACrB,MAAuB;IAEvB,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE;QAClC,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC9D,IAAI,EAAE,KAAK;QACX,MAAM;KACP,CAAC,CAAC;IACH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,GAAG,CAAC,IAAsB,CAAC;IAC1D,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC,CAAE,uCAAuC;IAC7E,MAAM,IAAI,aAAa,CACrB,aAAa,KAAK,CAAC,QAAQ,CAAC,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,WAAW,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,CACzF,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAqB,EACrB,SAAiB,EACjB,IAAY,EACZ,MAAuB;IAEvB,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE;QAClC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM;KAC3D,CAAC,CAAC;IACH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO;IAC3E,MAAM,IAAI,aAAa,CAAC,gBAAgB,SAAS,IAAI,IAAI,WAAW,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC;AACzF,CAAC;AAED,2EAA2E;AAE3E,MAAM,OAAO,aAAc,SAAQ,KAAK;IACO;IAA7C,YAAY,OAAe,EAAkB,QAAqB;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,aAAQ,GAAR,QAAQ,CAAa;QAEhE,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF"}

package/dist/crdt/Crdt.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Conflict-free Replicated Data Type — a value that converges under
+ * replication without coordination.  Every implementation is a
+ * **state-based CvRDT**: replicas exchange full state, and `merge`
+ * forms a join-semilattice.
+ *
+ * Three properties every implementation must satisfy — `tests/unit/crdt`
+ * verifies them by hand-rolled property tests against generated samples:
+ *
+ *   - **Idempotent**:    `merge(a, a) === a`
+ *   - **Commutative**:   `merge(a, b) === merge(b, a)`
+ *   - **Associative**:   `merge(merge(a, b), c) === merge(a, merge(b, c))`
+ *
+ * Together these mean: gossip can deliver state updates in any order,
+ * deduplicate, retransmit, and the world converges as long as every
+ * replica eventually sees every state.
+ *
+ * **Why state-based and not delta-state.**  Delta-CRDTs ship only the
+ * incremental change rather than the full state — much cheaper on the
+ * wire, but the implementation has more moving parts and you need
+ * delta acknowledgement protocols.  State-based is the simplest thing
+ * that converges; we ship it first and revisit if payload size hurts.
+ *
+ * @typeParam Self - The concrete CRDT type.  F-bounded so subclass
+ *   `merge` keeps the right return type without casting at every call
+ *   site.
+ */
+export interface Crdt<Self extends Crdt<Self>> {
+    /**
+     * Join two replicas.  Must be a join-semilattice operation: total,
+     * idempotent, commutative, associative.
+     */
+    merge(other: Self): Self;
+    /**
+     * Wire-friendly representation — every CRDT must be JSON-encodable
+     * so it can travel through the cluster transport without bespoke
+     * codecs.  `toJSON()` is the inverse of the static `fromJSON`
+     * factory each impl exposes.
+     */
+    toJSON(): unknown;
+}
+/**
+ * Identifier of the replica producing an update.  In a cluster, this is
+ * typically `cluster.selfAddress.toString()` — every NodeAddress is
+ * already unique within the cluster, so we can reuse it as the replica
+ * id rather than minting a separate one.
+ *
+ * The CRDT operations themselves treat the id as opaque — any string
+ * that's stable across a process's lifetime is fine.
+ */
+export type ReplicaId = string;
+//# sourceMappingURL=Crdt.d.ts.map

package/dist/crdt/Crdt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Crdt.d.ts","sourceRoot":"","sources":["../../src/crdt/Crdt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,IAAI,CAAC,IAAI,SAAS,IAAI,CAAC,IAAI,CAAC;IAC3C;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CAAC;IAEzB;;;;;OAKG;IACH,MAAM,IAAI,OAAO,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC"}

package/dist/crdt/Crdt.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Crdt.js.map

package/dist/crdt/Crdt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Crdt.js","sourceRoot":"","sources":["../../src/crdt/Crdt.ts"],"names":[],"mappings":""}

package/dist/crdt/DistributedData.d.ts

@@ -0,0 +1,314 @@
+import type { ActorRef } from '../ActorRef.js';
+import type { ActorSystem } from '../ActorSystem.js';
+import type { DurableStateStore } from '../persistence/DurableStateStore.js';
+import { type Extension, type ExtensionId } from '../Extension.js';
+import type { Cluster } from '../cluster/Cluster.js';
+import { NodeAddress } from '../cluster/NodeAddress.js';
+import type { Crdt } from './Crdt.js';
+import { type GCounterJson } from './GCounter.js';
+import { type GCounterMapJson } from './GCounterMap.js';
+import { type PNCounterJson } from './PNCounter.js';
+import { type GSetJson } from './GSet.js';
+import { type ORSetJson } from './ORSet.js';
+import { type ORMapJson } from './ORMap.js';
+import { type LWWRegisterJson } from './LWWRegister.js';
+import { type LWWMapJson } from './LWWMap.js';
+import { type MVRegisterJson } from './MVRegister.js';
+/** Discriminated union of every CRDT's wire representation. */
+export type CrdtJson = GCounterJson | PNCounterJson | GSetJson | ORSetJson | LWWRegisterJson<unknown> | GCounterMapJson | LWWMapJson<unknown> | MVRegisterJson<unknown> | ORMapJson;
+/**
+ * Reconstruct a CRDT from its `toJSON()` payload.  Dispatches on the
+ * `kind` discriminator each impl writes — adding a new CRDT type is
+ * one more case here.  Returned as `Crdt<unknown>` because the
+ * concrete type is only known at the call site that asked for the
+ * key in the first place.
+ *
+ * Exported so containers like `ORMap` (whose values are themselves
+ * CRDTs of arbitrary kind) can wire it as their inner-value decoder.
+ *
+ * ## Reference example: discriminated-union dispatch
+ *
+ * This function is the **codebase's reference shape** for
+ * dispatching on a closed string-literal-discriminator union.  Two
+ * properties matter:
+ *
+ *   1. **No `default` arm** — the switch lists every kind explicitly.
+ *      The `default` branch's `const _exhaustive: never = json`
+ *      assertion gives compile-time exhaustiveness: TypeScript
+ *      narrows `json` to `never` after all real arms; adding a new
+ *      variant to `CrdtJson` without a matching `case` makes
+ *      `json` *not* assignable to `never` and the file fails to
+ *      compile.
+ *
+ *   2. **`throw` inside the default** — defensive belt-and-braces
+ *      for the type-erasure boundary (legacy wire data, force-casts).
+ *      Unreachable from well-typed callers.
+ *
+ * Equivalent shape: `match(json).with({ kind: 'X' }, ...).exhaustive()`
+ * from `ts-pattern`.  Used elsewhere in the codebase when the
+ * discriminator is more complex than a string literal (e.g. nominal
+ * type via `instanceof`).  Both forms achieve compile-time
+ * exhaustiveness; pick the more readable one per site.
+ *
+ * **Do not** add a permissive `default` case that returns a stub —
+ * it defeats the exhaustiveness check and turns missing variants
+ * into silent runtime bugs.
+ */
+export declare function decodeCrdt(json: CrdtJson): Crdt<any>;
+/**
+ * Empty-CRDT factory.  Callers pass this to `update(key, factory, fn)`
+ * so the extension can materialize a brand-new CRDT for a key that
+ * doesn't exist yet — without DistributedData itself needing to know
+ * about every CRDT type.
+ *
+ *   GCounter.empty       satisfies CrdtFactory<GCounter>
+ *   () => ORSet.empty()  satisfies CrdtFactory<ORSet<X>>
+ */
+export type CrdtFactory<C extends Crdt<C>> = () => C;
+/**
+ * One gossip round = a snapshot of every key this replica currently
+ * knows.  Receivers merge each entry into their own state.
+ *
+ * Deliberately simple: no digest, no delta — just push the full set
+ * to one random peer per tick.  Cheap to implement and good enough
+ * for the small-to-medium stores DistributedData is meant for.
+ */
+interface DDataGossipMsg {
+    readonly t: 'ddata-gossip';
+    readonly from: ReturnType<NodeAddress['toJSON']>;
+    /** Keyed by user-key; payload is the CRDT's own JSON discriminator. */
+    readonly entries: Record<string, CrdtJson>;
+}
+/**
+ * Quorum-write request — sent by the originator of a
+ * `updateAsync(..., { consistency: 'majority' | 'all' | { from } })`
+ * call to every other up-member.  Each receiver merges `value` into
+ * its local replica (same merge as gossip) and replies with a
+ * `DDataWriteAckMsg` carrying the same `pendingId` so the originator
+ * can match it to the pending write.
+ */
+interface DDataWriteRequestMsg {
+    readonly t: 'ddata-write-request';
+    readonly from: ReturnType<NodeAddress['toJSON']>;
+    readonly pendingId: string;
+    readonly key: string;
+    readonly value: CrdtJson;
+}
+interface DDataWriteAckMsg {
+    readonly t: 'ddata-write-ack';
+    readonly from: ReturnType<NodeAddress['toJSON']>;
+    readonly pendingId: string;
+    readonly key: string;
+}
+/**
+ * Quorum-read request — sent by the originator of a
+ * `getAsync(..., { consistency: ... })` call to every other
+ * up-member.  Each receiver replies with its current local value
+ * (or `null` if it has no entry) so the originator can merge the
+ * responses and return the result.
+ */
+interface DDataReadRequestMsg {
+    readonly t: 'ddata-read-request';
+    readonly from: ReturnType<NodeAddress['toJSON']>;
+    readonly pendingId: string;
+    readonly key: string;
+}
+interface DDataReadResponseMsg {
+    readonly t: 'ddata-read-response';
+    readonly from: ReturnType<NodeAddress['toJSON']>;
+    readonly pendingId: string;
+    readonly key: string;
+    readonly value: CrdtJson | null;
+}
+/**
+ * Quorum target for `updateAsync` / `getAsync`.
+ *
+ *   - `'local'` — return immediately after applying locally.  Equivalent
+ *     to the sync `update` / `get` API, kept for API symmetry.
+ *   - `'majority'` — wait for `floor(N/2)+1` replicas (incl. self).
+ *   - `'all'` — wait for every up-member.
+ *   - `{ from: K }` — wait for `K` replicas (clamped to `[1, N]`).
+ *
+ * `N` is `cluster.upMembers().length` at the moment the call starts.
+ * Self always counts as the first ack (the local apply is synchronous),
+ * so a single-node cluster resolves immediately regardless of the
+ * chosen consistency level.
+ */
+export type WriteConsistency = 'local' | 'majority' | 'all' | {
+    readonly from: number;
+};
+export type ReadConsistency = WriteConsistency;
+export interface DistributedDataSettings {
+    /** Period between gossip pushes.  Default: 1 s. */
+    readonly gossipIntervalMs?: number;
+    /**
+     * Optional durable backend.  When provided, the local CRDT view
+     * is loaded from the store on `preStart` and re-saved after every
+     * mutation (local update, gossip merge, delete).  Without this,
+     * `DistributedData` is purely in-memory — a full cluster restart
+     * (deploy / outage) starts every replica empty.
+     *
+     * The store is keyed by replica id, so each cluster member owns
+     * its own durable record.  CRDT semantics handle convergence
+     * across replicas via gossip — durability is per-replica.
+     *
+     * Plug in any of the existing `DurableStateStore` implementations:
+     * `InMemoryDurableStateStore` for tests, the SQLite / Cassandra /
+     * S3 / filesystem backends for production.
+     */
+    readonly durableStore?: DurableStateStore;
+}
+/**
+ * Cluster-wide replicated key-value store of CRDTs.  Each node hosts
+ * one local replica.  `update(key, ...)` mutates the local replica
+ * (idempotent, conflict-free), and gossip fans the state out so
+ * every replica eventually agrees on `merge(...)` of all updates.
+ *
+ * **Lifecycle:** call `extension(DistributedDataId).start(cluster)`
+ * once per process to spawn the internal gossip actor.  Subsequent
+ * calls return the same handle.
+ *
+ *   const dd = system.extension(DistributedDataId).start(cluster);
+ *   dd.update('cart-42', () => ORSet.empty<string>(),
+ *     (cart) => cart.add(cluster.selfAddress.toString(), 'apple'));
+ *   const cart = dd.get<ORSet<string>>('cart-42');
+ *
+ * **Limits / non-goals (v1):**
+ *   - Full-state push on every gossip tick — fine for small stores.
+ *   - No durable persistence: the store lives in memory.
+ *   - No tombstone delete; `delete(key)` is best-effort and can be
+ *     undone by an in-flight gossip from a peer who still has the
+ *     key.  Plan a workload-specific tombstone pattern (typically
+ *     embed deletion in the CRDT — e.g. `ORSet.remove`).
+ */
+export declare class DistributedData implements Extension {
+    private readonly system;
+    private _handle;
+    private _cluster;
+    constructor(system: ActorSystem);
+    start(cluster: Cluster, settings?: DistributedDataSettings): DistributedDataHandle;
+    /** Tear down the wire-handler subscriptions (test/shutdown only). */
+    stop(): void;
+    get(): DistributedDataHandle;
+    isStarted(): boolean;
+}
+export declare const DistributedDataId: ExtensionId<DistributedData>;
+/** Shared between actor + handle so reads stay synchronous. */
+interface SharedView {
+    state: Map<string, Crdt<any>>;
+    listeners: Map<string, Set<(value: Crdt<any>) => void>>;
+}
+interface UpdateMsg {
+    readonly t: 'ddata-update';
+    readonly key: string;
+    readonly factory: CrdtFactory<Crdt<any>>;
+    readonly fn: (c: Crdt<any>) => Crdt<any>;
+    /**
+     * Optional quorum settings.  When present, the update runs as a
+     * quorum write — the actor broadcasts the merged value to peers,
+     * collects acks, and only then resolves the user's promise.  When
+     * absent, behaves like the legacy sync path (apply locally + let
+     * gossip carry the value eventually).
+     */
+    readonly quorum?: {
+        readonly pendingId: string;
+        readonly consistency: WriteConsistency;
+        readonly timeoutMs: number;
+        readonly resolve: () => void;
+        readonly reject: (err: Error) => void;
+    };
+}
+interface DeleteMsg {
+    readonly t: 'ddata-delete';
+    readonly key: string;
+}
+/** Out-of-mailbox: a quorum-read user call.  See {@link DistributedDataHandle.getAsync}. */
+interface ReadMsg {
+    readonly t: 'ddata-read';
+    readonly key: string;
+    readonly pendingId: string;
+    readonly consistency: ReadConsistency;
+    readonly timeoutMs: number;
+    readonly resolve: (value: Crdt<any> | undefined) => void;
+    readonly reject: (err: Error) => void;
+}
+type ActorMsg = UpdateMsg | DeleteMsg | ReadMsg | DDataGossipMsg | DDataWriteRequestMsg | DDataWriteAckMsg | DDataReadRequestMsg | DDataReadResponseMsg;
+/**
+ * Public handle returned from `extension.start(cluster)`.  Holds a
+ * ref to the internal actor + a synchronously-readable view of the
+ * replicated state.
+ */
+export declare class DistributedDataHandle {
+    private readonly ref;
+    private readonly view;
+    private readonly cluster;
+    private wireUnsubs;
+    constructor(ref: ActorRef<ActorMsg>, view: SharedView, cluster: Cluster, wireUnsubs?: ReadonlyArray<() => void>);
+    /** @internal — called by the extension's `stop()`. */
+    _stopWireHandlers(): void;
+    /** Synchronously read the local replica's view of `key`. */
+    get<C extends Crdt<C>>(key: string): C | undefined;
+    /**
+     * Mutate `key` via `fn`.  If the key doesn't exist yet, `factory()`
+     * is called to seed a fresh CRDT.  The mutation runs on the actor
+     * thread so concurrent local callers serialize cleanly.
+     */
+    update<C extends Crdt<C>>(key: string, factory: CrdtFactory<C>, fn: (current: C) => C): void;
+    /**
+     * Quorum-write variant of {@link update}.  Returns a promise that
+     * resolves only after the requested number of replicas have
+     * acknowledged the merge.  Self always counts as the first ack, so
+     * single-node clusters and `consistency: 'local'` resolve as soon as
+     * the local apply is done.
+     *
+     * Rejects with a timeout error if not enough acks arrive within
+     * `timeoutMs` (default `gossipIntervalMs × 5`).  A timeout does NOT
+     * roll the local write back — the value is already applied locally
+     * and will continue to gossip; the rejection only signals "I'm not
+     * sure enough replicas saw it".
+     *
+     *   await dd.updateAsync<GCounter>('hits', GCounter.empty,
+     *     (c) => c.increment(dd.selfReplicaId(), 1),
+     *     { consistency: 'majority' });
+     */
+    updateAsync<C extends Crdt<C>>(key: string, factory: CrdtFactory<C>, fn: (current: C) => C, opts?: {
+        readonly consistency: WriteConsistency;
+        readonly timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Quorum-read variant of {@link get}.  Sends a read request to peers
+     * matching the consistency target, merges all incoming responses
+     * (plus the local replica), and resolves with the merged value.
+     * `undefined` if no replica knows the key.
+     *
+     * Self always counts as the first response — `'local'` returns
+     * immediately with whatever's in the local view.  Timeout default is
+     * the same as {@link updateAsync}.
+     *
+     *   const cart = await dd.getAsync<ORSet<string>>('cart-42',
+     *     { consistency: 'majority' });
+     */
+    getAsync<C extends Crdt<C>>(key: string, opts?: {
+        readonly consistency: ReadConsistency;
+        readonly timeoutMs?: number;
+    }): Promise<C | undefined>;
+    /**
+     * Best-effort delete.  Forgets `key` on this replica only — peers
+     * may re-introduce it via gossip.  See class header for the
+     * tombstone story.
+     */
+    delete(key: string): void;
+    /**
+     * Subscribe to changes for `key`.  Listener fires synchronously
+     * after every successful update / merge that changes the local
+     * value (deep-equal check via the CRDT's own `toJSON`).  Returns
+     * an unsubscribe function.
+     */
+    subscribe<C extends Crdt<C>>(key: string, listener: (value: C) => void): () => void;
+    /** Snapshot of every key currently known on the local replica. */
+    keys(): string[];
+    /** ReplicaId used when seeding ops (delegated from `cluster.selfAddress`). */
+    selfReplicaId(): string;
+}
+export {};
+//# sourceMappingURL=DistributedData.d.ts.map