@toa.io/extensions.continuity 1.0.0-alpha.321

package/components/continuity.journal/manifest.toa.yaml

@@ -0,0 +1,47 @@
+namespace: continuity
+name: journal
+
+# One record per step of a run, under an id derived from the run and the step, so that a step is
+# written once whoever writes it first.
+entity:
+  associated: true
+  properties:
+    run:
+      description: The identity of the task or the event the step was made for
+      type: string
+    answer:
+      description: What the step answered, encoded by the extension
+      type: object
+    expires:
+      description: >
+        When the run can no longer be picked up. Every step of a run carries the moment its
+        first step fixed, so a run is reaped whole.
+      type: integer
+      format: epoch-millis
+
+operations:
+  # keeps an answer unless one is kept already, and answers what is kept
+  record:
+    type: transition
+    # two copies of a run writing one step race to create it, and the loser reads the winner's
+    concurrency: retry
+    input:
+      type: object
+      properties:
+        run:
+          type: string
+        answer:
+          type: object
+        expires:
+          type: integer
+      required:
+        - run
+        - answer
+        - expires
+    output:
+      type: object
+  # what a run has kept
+  recall:
+    type: observation
+    scope: entries
+    query: true

package/components/continuity.journal/migrations/0002-runs.yaml

@@ -0,0 +1,11 @@
+# A run is read whole, once per attempt.
+- index:
+    name: index_run
+    keys:
+      run: asc
+# A run is kept until the window its first step fixed has passed, and then reaped whole.
+- index:
+    name: index_expires
+    keys:
+      expires: asc
+    ttl: 0

package/components/continuity.journal/operations/recall.js

@@ -0,0 +1,3 @@
+export function observation(_, entries) {
+  return entries
+}

package/components/continuity.journal/operations/record.js

@@ -0,0 +1,9 @@
+export function transition(input, entry) {
+  if (entry.answer === undefined) {
+    entry.run = input.run
+    entry.answer = input.answer
+    entry.expires = input.expires
+  }
+
+  return entry.answer
+}

package/components/continuity.journal/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './toa.d.ts'
+
+// What a manifest does not state belongs here, and every run keeps it.

package/components/continuity.journal/types/toa.d.ts

@@ -0,0 +1,41 @@
+// Written by `toa types`. Every run rewrites it.
+// What a manifest does not state belongs in a file of your own.
+
+import type { Query } from '@toa.io/core/types'
+import type { Readable } from 'node:stream'
+
+export interface Entity {
+  /** The identity of the task or the event the step was made for */
+  run?: string
+  /** What the step answered, encoded by the extension */
+  answer?: Record<string, unknown>
+  /** When the run can no longer be picked up. Every step of a run carries the moment its first step fixed, so a run is reaped whole. */
+  expires?: number
+  id: string
+  VERSION: number
+  CREATED: number
+  UPDATED: number
+  DELETED: number | null
+  REGION: number
+}
+
+export type State = Entity & { DISCARD: boolean, TRAILERS: Record<string, unknown> }
+
+export type RecordInput = {
+  run: string
+  answer: Record<string, unknown>
+  expires: number
+}
+
+export type RecordOutput = Record<string, unknown>
+
+export interface Component {
+  record: (request: { input: RecordInput, query?: Query<Entity>, task?: boolean }) => Promise<RecordOutput>
+  recall: (request: { input?: null, query: Query<Entity>, task?: boolean }) => Promise<unknown>
+  assign: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity>
+  ensure: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity>
+  enumerate: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity[]>
+  observe: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity | null>
+  stream: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Readable>
+  terminate: (request: { input?: null, query?: Query<Entity>, task?: boolean }) => Promise<Entity>
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@toa.io/extensions.continuity",
+  "version": "1.0.0-alpha.321",
+  "type": "module",
+  "description": "Toa Continuity",
+  "author": "temich <tema.gurtovoy@gmail.com>",
+  "homepage": "https://github.com/toa-io/toa#readme",
+  "main": "transpiled/index.js",
+  "types": "transpiled/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toa-io/toa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/toa-io/toa/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "transpiled",
+    "components",
+    "readme.md",
+    "!**/tsconfig.tsbuildinfo",
+    "!**/*.test.*",
+    "!**/.env*"
+  ],
+  "dependencies": {
+    "@toa.io/core": "1.0.0-alpha.321",
+    "@toa.io/definitions": "1.0.0-alpha.321"
+  },
+  "scripts": {
+    "transpile": "tsc"
+  }
+}

package/readme.md

@@ -0,0 +1,150 @@
+# Toa Continuity
+
+An operation that picks up where it failed.
+
+A [task](/documentation/tasks.md), or an event a receiver hands on, is tried again when it raises,
+and every attempt runs the operation from the top. An operation this extension continues is given
+back, on a later attempt, whatever its context answered on an earlier one: the calls, fetches and
+stashes that already answered are not made again, and what is made is the step that failed and
+what follows it.
+
+## Declaring it
+
+```yaml
+# manifest.toa.yaml
+operations:
+  onboard:
+    type: effect
+
+continuity:
+  onboard: 604800 # seconds an unfinished run can still be resumed
+```
+
+Each operation named is an `effect` of the component, with how long, in seconds, a run of it that
+has not finished can still be picked up. There is no default: how late a parked task can be put
+back is yours to know. The window is at least `600`, and a manifest that states less, names an
+operation the component does not have, or names one that is not an effect is refused.
+
+The operation is written as any other:
+
+```javascript
+async function effect(input, context) {
+  const account = await context.remote.identity.accounts.create({ input })
+  await context.fetch('crm', { method: 'POST', body: JSON.stringify(account) })
+  await context.remote.mail.messages.send({ input: { to: account.email } })
+}
+```
+
+If `send` raises, the next attempt is given the account `create` answered and the response the
+CRM gave, and only `send` is made again.
+
+## Calling it
+
+As a task, or from a receiver — where nobody waits for the answer:
+
+```javascript
+await context.call('users.onboarding.onboard', { input, task: true })
+```
+
+Any other call is refused, and so is a pulse naming it.
+
+## What you can count on
+
+**What answered is not asked again.** Within one run — a task, or one event — a step that answered
+is given back on every later attempt: after an exception, after the process died, after a redeploy,
+and after a parked task is put back within the window. A task delivered again after it finished is
+given everything back, and makes nothing.
+
+**Concurrent branches are fine.** A step is recognized by what it asks, not by when:
+
+```javascript
+await Promise.all([a().then(b), c().then(b)])
+```
+
+Each `b` is given its own answer however `a` and `c` complete on the next attempt.
+
+**Two copies of a run agree.** Where a run is delivered twice at once, both copies go on with the
+answer the first of them kept. A value taken at once — `context.id()`, `context.now()`,
+`context.random()` — is the exception: each copy has its own until it is kept, so a step one copy
+builds from it may be made by the other as well.
+
+**A call keeps its identity.** A call made from the operation carries the same identity on every
+attempt, so a callee that declares [`once`](/documentation/inbox.md) refuses a repeat of it.
+
+## What that asks of you
+
+**The next attempt may run somewhere else.** A task or an event that is tried again is taken by
+whichever replica is free, and after a restart or a redeploy by a process that has never seen the run.
+What the context answered is given back wherever that is; what the operation kept in its own process
+is not. `context.state`, a variable of the module, a cache in memory, a file on the local disk — on the
+next attempt each of them is whatever that process holds, which is not what the earlier attempt left:
+
+```javascript
+// counts in whichever process the attempt runs in, and not across attempts
+context.state.sent = (context.state.sent ?? 0) + 1
+
+// kept with the run, and given back wherever the next attempt runs
+const sent = await context.remote.mail.messages.send({ input })
+```
+
+So nothing a later attempt depends on is carried in the process: take it from a step, or from what
+the operation writes and reads back.
+
+**Take time, randomness and new ids from the context.** A step is recognized by its arguments, so an
+argument that differs between attempts makes a new step, and the step is made again:
+
+```javascript
+// a new timestamp every attempt: the call is made again every attempt
+await context.remote.billing.invoices.issue({ input: { at: Date.now() } })
+
+// the same timestamp on every attempt: the call is made once
+await context.remote.billing.invoices.issue({ input: { at: context.now() } })
+```
+
+`context.now()`, `context.random()` and `context.id()` are given back like any other step. The same
+holds for the entity an effect reads: it is read again on every attempt, and a step whose arguments
+come from it is made again if it moved.
+
+**A step that took effect may still be made again.** Where the process dies after a step took
+effect and before its answer was kept, the next attempt makes it again. A call into Toa arrives with
+the same identity, so a callee that declares `once` refuses it; a `fetch` to a third party is sent
+again, so make it safe to repeat, or pass it a key it deduplicates on.
+
+**Among identical steps, which branch gets which answer is not fixed.** Two concurrent `b(x)` are
+the same request, and each is given one of the two answers — possibly the other one than the first
+time. A later step built from the answer together with something of the branch's own has new
+arguments, and is made again. `context.id()` twice in two branches is the common case.
+
+**What cannot be kept is refused.** A step that answers with a stream raises `Unrecordable`, and
+the run is parked. A `fetch` is kept whole — its status, its headers and its body — and given back
+as a `Response`. An answer is kept as one MongoDB document, so one past its 16 MB fails to be kept,
+and the step raises.
+
+**An answer is given as it is kept, the first time too.** What a step answers is given back as the
+broker carries it, on the attempt that made it as on any later one, so the operation reads the same
+thing every time.
+
+**A run that used up its attempts is parked**, as any task is. It picks up where it stopped if it is
+put back within its window; after that, it starts from the beginning.
+
+## Not steps
+
+`logs`, `span`, `metrics`, `configuration`, `state` and `atom` are what they are on every attempt,
+and nothing of them is kept. `state` in particular belongs to one process, and the next attempt may
+run in another.
+
+## Deployment
+
+The runs are kept in the extension's own component, `continuity.journal`, in MongoDB. A context
+whose components declare `continuity` deploys it as a service of its own. Its database is given as
+for any component, so a context whose `mongodb` names one address for everything has nothing to add;
+one that names them per namespace names this one too:
+
+```yaml
+# context.toa.yaml
+mongodb:
+  todos: mongodb://todos.mongo.example.com
+  continuity: mongodb://mongo.example.com
+```
+
+See [deployment](/documentation/deployment.md).

package/transpiled/Composition.d.ts

@@ -0,0 +1,14 @@
+import { Connector } from '@toa.io/core';
+import type { Host } from './Factory.ts';
+/** The components this extension ships, which run inside its own service. */
+export declare function components(): Components;
+export declare class Composition extends Connector {
+    private readonly host;
+    constructor(host: Host);
+    protected open(): Promise<void>;
+}
+interface Components {
+    labels: string[];
+    paths: string[];
+}
+export {};

package/transpiled/Composition.js

@@ -0,0 +1,30 @@
+import { readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Connector } from '@toa.io/core';
+/** The components this extension ships, which run inside its own service. */
+export function components() {
+    const labels = [];
+    const paths = [];
+    for (const entry of entries()) {
+        labels.push(entry.name.replace('.', '-'));
+        paths.push(resolve(ROOT, entry.name));
+    }
+    return { labels, paths };
+}
+export class Composition extends Connector {
+    host;
+    constructor(host) {
+        super();
+        this.host = host;
+    }
+    async open() {
+        const composition = await this.host.composition(components().paths);
+        await composition.connect();
+        this.depends(composition);
+    }
+}
+function entries() {
+    return readdirSync(ROOT, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+}
+const ROOT = resolve(import.meta.dirname, '../components/');
+//# sourceMappingURL=Composition.js.map

package/transpiled/Composition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Composition.js","sourceRoot":"","sources":["../source/Composition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAIxC,6EAA6E;AAC7E,MAAM,UAAU,UAAU;IACxB,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;QACzC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;IACvC,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AAC1B,CAAC;AAED,MAAM,OAAO,WAAY,SAAQ,SAAS;IACvB,IAAI,CAAM;IAE3B,YAAmB,IAAU;QAC3B,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAEkB,KAAK,CAAC,IAAI;QAC3B,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAA;QAEnE,MAAM,WAAW,CAAC,OAAO,EAAE,CAAA;QAE3B,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;IAC3B,CAAC;CACF;AAED,SAAS,OAAO;IACd,OAAO,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;AAC1F,CAAC;AAOD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAA"}

package/transpiled/Factory.d.ts

@@ -0,0 +1,21 @@
+import type { Component, Connector, Context, Locator } from '@toa.io/core';
+import type { Declaration } from '@toa.io/definitions/extensions.continuity';
+import type { extensions } from '@toa.io/core/types';
+export declare class Factory implements extensions.Factory {
+    private readonly host;
+    /** what each component declared, by its locator: the hooks that wrap it are handed no more */
+    private readonly declared;
+    private journal?;
+    constructor(host: extensions.Host);
+    /**
+     * Nothing is put on the context: this is where a component's declaration is handed over, ahead
+     * of the context and the component being built.
+     */
+    aspect(locator: Locator, declaration: Declaration): extensions.Aspect[];
+    component(component: Component): Component;
+    context(context: Context): Context;
+    service(): Connector;
+    /** one journal for the process, which the component it serves goes down with */
+    private connected;
+}
+export type Host = extensions.Host;

package/transpiled/Factory.js

@@ -0,0 +1,156 @@
+import { exceptions } from '@toa.io/core';
+import { NAMESPACE } from '@toa.io/definitions/extensions.continuity';
+import { Composition } from './Composition.js';
+import { Journal } from './Journal.js';
+import { Run } from './Run.js';
+export class Factory {
+    host;
+    /** what each component declared, by its locator: the hooks that wrap it are handed no more */
+    declared = {};
+    journal;
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * Nothing is put on the context: this is where a component's declaration is handed over, ahead
+     * of the context and the component being built.
+     */
+    aspect(locator, declaration) {
+        if (!mine(locator))
+            this.declared[locator.id] = declaration;
+        return [];
+    }
+    component(component) {
+        const declaration = this.declared[component.locator.id];
+        if (declaration === undefined)
+            return component;
+        const journal = this.connected(component);
+        const invoke = component.invoke.bind(component);
+        component.invoke = async (endpoint, request, options) => {
+            const window = declaration[endpoint];
+            if (window === undefined)
+                return await invoke(endpoint, request, options);
+            const refusal = refuse(component, endpoint, request);
+            if (refusal !== undefined)
+                return { exception: refusal };
+            let run;
+            try {
+                run = await Run.begin(request.id, journal, window);
+            }
+            catch (exception) {
+                return { exception: coded(exception) };
+            }
+            const reply = await run.within(async () => await invoke(endpoint, request, options));
+            // what was taken without waiting is kept before the attempt is done with
+            try {
+                await run.settle();
+            }
+            catch (exception) {
+                return { exception: coded(exception) };
+            }
+            return reply;
+        };
+        return component;
+    }
+    context(context) {
+        if (context.locator === undefined || this.declared[context.locator.id] === undefined)
+            return context;
+        continued(context);
+        return context;
+    }
+    // nothing connects to this, so a halt takes the whole of it
+    service() {
+        return this.host.gate(async () => new Composition(this.host));
+    }
+    /** one journal for the process, which the component it serves goes down with */
+    connected(component) {
+        if (this.journal === undefined || this.journal.disposed)
+            this.journal = new Journal(this.host);
+        component.depends(this.journal);
+        return this.journal;
+    }
+}
+/**
+ * The members of the context that answer an operation, each made a step of the run where there is
+ * one, and left alone where there is none. What is no step — a log, a span, a metric, the
+ * configuration, a process's own state and what its replicas decide — is not touched.
+ */
+function continued(context) {
+    const call = context.call.bind(context);
+    const apply = context.apply.bind(context);
+    const newid = context.newid.bind(context);
+    const now = context.now.bind(context);
+    const random = context.random.bind(context);
+    // eslint-disable-next-line max-params
+    context.call = async (namespace, name, endpoint, request, options) => {
+        const run = Run.current();
+        if (run === undefined)
+            return await call(namespace, name, endpoint, request, options);
+        return await run.step(`call:${namespace}.${name}.${endpoint}`, [request], (id) => call(namespace, name, endpoint, identified(request, id), options));
+    };
+    context.apply = async (endpoint, request, options) => {
+        const run = Run.current();
+        if (run === undefined)
+            return await apply(endpoint, request, options);
+        return await run.step(`apply:${endpoint}`, [request], (id) => apply(endpoint, identified(request, id), options));
+    };
+    context.newid = () => Run.current()?.value('newid', newid) ?? newid();
+    context.now = () => Run.current()?.value('now', now) ?? now();
+    context.random = () => Run.current()?.value('random', random) ?? random();
+    const aspects = context.aspects;
+    for (let i = 0; i < aspects.length; i++) {
+        const aspect = aspects[i];
+        if (PASSED.has(aspect.name))
+            continue;
+        const invoke = aspect.invoke.bind(aspect);
+        // what the bridge reads of an aspect is its name and `invoke`, and the aspect itself stays a
+        // dependency of the context as it was
+        aspects[i] = {
+            name: aspect.name,
+            invoke: (...args) => {
+                const run = Run.current();
+                if (run === undefined)
+                    return invoke(...args);
+                return run.step(`aspect:${aspect.name}`, args, async () => await invoke(...args));
+            }
+        };
+    }
+}
+/**
+ * A call made as a step carries the identity its key derives, so that it arrives under the same one
+ * on every attempt. The request is copied rather than written to: one request object may be handed
+ * to more than one call.
+ */
+function identified(request, id) {
+    return { ...request, id: request?.id ?? id };
+}
+/**
+ * A run is known by the identity a task or an event carries on every attempt. A caller that waits
+ * retries by itself, under an identity of its own, and a run of it would not be one run.
+ */
+function refuse(component, endpoint, request) {
+    const target = `'${component.locator.id}.${endpoint}'`;
+    if (request?.task !== true && !delivered(request))
+        return new exceptions.RequestContractException(`${target} is continued, and runs as a task or for an event, which nobody waits for`);
+    if (typeof request.id !== 'string' || !IDENTITY.test(request.id))
+        return new exceptions.RequestContractException(`${target} is continued, and a request that carries no identity has no run to continue`);
+    return undefined;
+}
+/** whether a receiver handed this request on, which is the last hop its chain names */
+function delivered(request) {
+    const hops = request?.trail;
+    return Array.isArray(hops) && hops.at(-1)?.startsWith('~') === true;
+}
+function coded(exception) {
+    if (typeof exception?.code === 'number')
+        return exception;
+    return new exceptions.SystemException(exception);
+}
+/** Whether this is a component the extension ships rather than one of the application's. */
+function mine(locator) {
+    return locator.namespace === NAMESPACE;
+}
+const PASSED = new Set(['logs', 'span', 'metrics', 'configuration', 'state', 'atom']);
+// what a run is looked up by in the journal's criteria, so nothing it could hold is quoted
+const IDENTITY = /^[0-9A-Za-z_-]{1,128}$/;
+//# sourceMappingURL=Factory.js.map

package/transpiled/Factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Factory.js","sourceRoot":"","sources":["../source/Factory.ts"],"names":[],"mappings":"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"}

package/transpiled/Journal.d.ts

@@ -0,0 +1,24 @@
+import { Connector } from '@toa.io/core';
+import type { extensions } from '@toa.io/core/types';
+import type { Kept } from './answers.ts';
+/**
+ * The component that keeps the runs, as something to call.
+ *
+ * Resolved on the first call and not before: an extension is built ahead of the components of its
+ * composition, so at that point there is nothing to look up yet.
+ */
+export declare class Journal extends Connector {
+    private readonly host;
+    private remote?;
+    constructor(host: extensions.Host);
+    /** what a run has kept so far, by the key of each step, and when the run is reaped */
+    recall(run: string): Promise<Recalled>;
+    /** keeps what a step answered, unless another attempt kept it first, and answers what is kept */
+    record(run: string, key: string, answer: Kept, expires: number): Promise<Kept>;
+    private invoke;
+    private locate;
+}
+export interface Recalled {
+    steps: Map<string, Kept>;
+    expires: number | undefined;
+}

package/transpiled/Journal.js

@@ -0,0 +1,57 @@
+import { Connector, Locator } from '@toa.io/core';
+import { COMPONENT, NAMESPACE } from '@toa.io/definitions/extensions.continuity';
+/**
+ * The component that keeps the runs, as something to call.
+ *
+ * Resolved on the first call and not before: an extension is built ahead of the components of its
+ * composition, so at that point there is nothing to look up yet.
+ */
+export class Journal extends Connector {
+    host;
+    remote;
+    constructor(host) {
+        super();
+        this.host = host;
+    }
+    /** what a run has kept so far, by the key of each step, and when the run is reaped */
+    async recall(run) {
+        const steps = new Map();
+        let expires;
+        for (let omit = 0;; omit += PAGE) {
+            const page = (await this.invoke('recall', {
+                query: { criteria: `run=="${run}"`, limit: PAGE, omit }
+            }));
+            for (const record of page) {
+                steps.set(record.id, record.answer);
+                expires = record.expires;
+            }
+            if (page.length < PAGE)
+                break;
+        }
+        return { steps, expires };
+    }
+    /** keeps what a step answered, unless another attempt kept it first, and answers what is kept */
+    // eslint-disable-next-line max-params
+    async record(run, key, answer, expires) {
+        return (await this.invoke('record', {
+            query: { id: key },
+            input: { run, answer, expires }
+        }));
+    }
+    async invoke(endpoint, request) {
+        this.remote ??= this.locate();
+        // what the journal refuses or fails with is thrown, as for any call
+        return await (await this.remote).invoke(endpoint, request);
+    }
+    async locate() {
+        const remote = await this.host.remote(new Locator(COMPONENT, NAMESPACE), SOURCE);
+        this.depends(remote);
+        await remote.connect();
+        return remote;
+    }
+}
+/** records one read brings back */
+const PAGE = 1000;
+// what the journal is called by; without it the calls arrive unattributed
+const SOURCE = { service: 'continuity' };
+//# sourceMappingURL=Journal.js.map

package/transpiled/Journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Journal.js","sourceRoot":"","sources":["../source/Journal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,2CAA2C,CAAA;AAKhF;;;;;GAKG;AACH,MAAM,OAAO,OAAQ,SAAQ,SAAS;IACnB,IAAI,CAAiB;IAC9B,MAAM,CAAkB;IAEhC,YAAmB,IAAqB;QACtC,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAED,sFAAsF;IAC/E,KAAK,CAAC,MAAM,CAAC,GAAW;QAC7B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAA;QACrC,IAAI,OAA2B,CAAA;QAE/B,KAAK,IAAI,IAAI,GAAG,CAAC,GAAI,IAAI,IAAI,IAAI,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE;gBACxC,KAAK,EAAE,EAAE,QAAQ,EAAE,SAAS,GAAG,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE;aACxD,CAAC,CAAa,CAAA;YAEf,KAAK,MAAM,MAAM,IAAI,IAAI,EAAE,CAAC;gBAC1B,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;gBACnC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;YAC1B,CAAC;YAED,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI;gBAAE,MAAK;QAC/B,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;IAC3B,CAAC;IAED,iGAAiG;IACjG,sCAAsC;IAC/B,KAAK,CAAC,MAAM,CACjB,GAAW,EACX,GAAW,EACX,MAAY,EACZ,OAAe;QAEf,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE;YAClC,KAAK,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE;YAClB,KAAK,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;SAChC,CAAC,CAAS,CAAA;IACb,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,QAAgB,EAAE,OAAe;QACpD,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAA;QAE7B,oEAAoE;QACpE,OAAO,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IAC5D,CAAC;IAEO,KAAK,CAAC,MAAM;QAClB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,CAAA;QAEhF,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QAEpB,MAAM,MAAM,CAAC,OAAO,EAAE,CAAA;QAEtB,OAAO,MAAM,CAAA;IACf,CAAC;CACF;AAaD,mCAAmC;AACnC,MAAM,IAAI,GAAG,IAAI,CAAA;AAEjB,0EAA0E;AAC1E,MAAM,MAAM,GAAW,EAAE,OAAO,EAAE,YAAY,EAAE,CAAA"}

package/transpiled/Run.d.ts

@@ -0,0 +1,52 @@
+import type { Journal } from './Journal.ts';
+/**
+ * One attempt of a run: a task or an event, known by the identity it carries on every attempt.
+ *
+ * Put in scope where the component is invoked, and read where the context is asked. The context
+ * of an operation is one object shared by every invocation of it, so nothing per invocation can
+ * be handed to it — as the trail is not, for the same reason.
+ */
+export declare class Run {
+    readonly id: string;
+    private readonly journal;
+    private readonly window;
+    private readonly steps;
+    private expires;
+    /** how many times this attempt has asked each thing, by what it asked */
+    private readonly asked;
+    /** what was taken without waiting and is still being written */
+    private readonly writing;
+    private constructor();
+    /** an attempt, with what the run kept before it */
+    static begin(id: string, journal: Journal, window: number): Promise<Run>;
+    /**
+     * The run the invocation running now is, where it is one. Only the invocation the run was
+     * handed to: a call it makes to its own component runs in the same scope, and under an identity
+     * of its own.
+     */
+    static current(): Run | undefined;
+    /** runs `attempt` as this run */
+    within<T>(attempt: () => Promise<T>): Promise<T>;
+    /**
+     * A step that answers later: what was kept is given back, and what was not is made — under the
+     * identity the step's key is — kept, and what is kept is given back. So the operation is given
+     * what a later attempt will be given, including where a copy of the run kept it first.
+     */
+    step(member: string, args: unknown[], make: (id: string) => Promise<unknown>): Promise<unknown>;
+    /**
+     * A step that answers at once — a new id, the time, a random number. What was kept is given
+     * back; what was not is taken, given, and written without waiting, and anything the attempt makes
+     * after it waits for the write.
+     */
+    value<T>(member: string, take: () => T): T;
+    /** waits for what is being written, and raises where a write failed */
+    settle(): Promise<void>;
+    /**
+     * The member, a digest of what it was asked, and how many times this attempt has asked exactly
+     * that before: the order steps are made in is not the same on every attempt, and what they ask
+     * is.
+     */
+    private key;
+    /** fixed by the run's first step, so that a run is kept whole and reaped whole */
+    private expiry;
+}

package/transpiled/Run.js

@@ -0,0 +1,109 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { entities, trail } from '@toa.io/core';
+import { decode, encode } from './answers.js';
+import { fingerprint } from './fingerprint.js';
+/**
+ * One attempt of a run: a task or an event, known by the identity it carries on every attempt.
+ *
+ * Put in scope where the component is invoked, and read where the context is asked. The context
+ * of an operation is one object shared by every invocation of it, so nothing per invocation can
+ * be handed to it — as the trail is not, for the same reason.
+ */
+export class Run {
+    id;
+    journal;
+    window;
+    steps;
+    expires;
+    /** how many times this attempt has asked each thing, by what it asked */
+    asked = new Map();
+    /** what was taken without waiting and is still being written */
+    writing = new Set();
+    // eslint-disable-next-line max-params
+    constructor(id, journal, window, recalled) {
+        this.id = id;
+        this.journal = journal;
+        this.window = window;
+        this.steps = recalled.steps;
+        this.expires = recalled.expires;
+    }
+    /** an attempt, with what the run kept before it */
+    static async begin(id, journal, window) {
+        return new Run(id, journal, window, await journal.recall(id));
+    }
+    /**
+     * The run the invocation running now is, where it is one. Only the invocation the run was
+     * handed to: a call it makes to its own component runs in the same scope, and under an identity
+     * of its own.
+     */
+    static current() {
+        const run = storage.getStore();
+        if (run === undefined || trail.current()?.id !== run.id)
+            return undefined;
+        return run;
+    }
+    /** runs `attempt` as this run */
+    async within(attempt) {
+        return await storage.run(this, attempt);
+    }
+    /**
+     * A step that answers later: what was kept is given back, and what was not is made — under the
+     * identity the step's key is — kept, and what is kept is given back. So the operation is given
+     * what a later attempt will be given, including where a copy of the run kept it first.
+     */
+    async step(member, args, make) {
+        const key = this.key(member, args);
+        const kept = this.steps.get(key);
+        if (kept !== undefined)
+            return decode(kept);
+        // a value taken without waiting may be what this step is asked with, so it is kept first
+        await this.settle();
+        const answer = await make(key);
+        const stored = await this.journal.record(this.id, key, await encode(answer), this.expiry());
+        this.steps.set(key, stored);
+        return decode(stored);
+    }
+    /**
+     * A step that answers at once — a new id, the time, a random number. What was kept is given
+     * back; what was not is taken, given, and written without waiting, and anything the attempt makes
+     * after it waits for the write.
+     */
+    value(member, take) {
+        const key = this.key(member, []);
+        const kept = this.steps.get(key);
+        if (kept !== undefined)
+            return decode(kept);
+        const value = take();
+        const encoded = { value };
+        this.steps.set(key, encoded);
+        const write = this.journal.record(this.id, key, encoded, this.expiry());
+        this.writing.add(write);
+        void write.then(() => this.writing.delete(write), () => undefined);
+        return value;
+    }
+    /** waits for what is being written, and raises where a write failed */
+    async settle() {
+        if (this.writing.size > 0)
+            await Promise.all(this.writing);
+    }
+    /**
+     * The member, a digest of what it was asked, and how many times this attempt has asked exactly
+     * that before: the order steps are made in is not the same on every attempt, and what they ask
+     * is.
+     */
+    key(member, args) {
+        const asked = member + ':' + fingerprint(args);
+        const count = this.asked.get(asked) ?? 0;
+        this.asked.set(asked, count + 1);
+        return entities.derive(this.id, asked, count);
+    }
+    /** fixed by the run's first step, so that a run is kept whole and reaped whole */
+    expiry() {
+        this.expires ??= Date.now() + this.window * 1000;
+        return this.expires;
+    }
+}
+// as the trail holds its own: a process may carry two copies of this module
+const KEY = Symbol.for('toa.continuity.run');
+const storage = (globalThis[KEY] ??= new AsyncLocalStorage());
+//# sourceMappingURL=Run.js.map

package/transpiled/Run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Run.js","sourceRoot":"","sources":["../source/Run.ts"],"names":[],"mappings":"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"}

package/transpiled/answers.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What a step answered, in the form it is kept in: something the journal's storage holds and the
+ * broker carries as it is, and that gives back what the operation was given.
+ */
+export type Kept = {
+    value: unknown;
+} | {
+    none: true;
+} | {
+    bytes: string;
+} | {
+    error: Record<string, unknown>;
+} | {
+    response: KeptResponse;
+};
+interface KeptResponse {
+    status: number;
+    statusText: string;
+    headers: Array<[string, string]>;
+    body: string | null;
+}
+/**
+ * A stream cannot be kept: it is read once, and what it would give back is whatever is left of it.
+ * A `Response` is the exception, because what a `fetch` answers with is one, and it is read whole
+ * to be kept.
+ */
+export declare function encode(answer: unknown): Promise<Kept>;
+export declare function decode(kept: Kept): unknown;
+export {};

package/transpiled/answers.js

@@ -0,0 +1,61 @@
+import { exceptions } from '@toa.io/core';
+/**
+ * A stream cannot be kept: it is read once, and what it would give back is whatever is left of it.
+ * A `Response` is the exception, because what a `fetch` answers with is one, and it is read whole
+ * to be kept.
+ */
+export async function encode(answer) {
+    if (answer === undefined)
+        return { none: true };
+    if (answer instanceof Response)
+        return { response: await response(answer) };
+    if (streamed(answer))
+        throw new exceptions.UnrecordableException(`a step answered with a stream, which is read once and cannot be given back`);
+    if (ArrayBuffer.isView(answer))
+        return {
+            bytes: Buffer.from(answer.buffer, answer.byteOffset, answer.byteLength).toString('base64')
+        };
+    // a declared error a call answered with: its own properties are what the caller reads
+    if (answer instanceof Error)
+        return { error: { ...answer } };
+    return { value: answer };
+}
+export function decode(kept) {
+    if ('none' in kept)
+        return undefined;
+    if ('bytes' in kept)
+        return Buffer.from(kept.bytes, 'base64');
+    if ('error' in kept)
+        return Object.assign(new Error(), kept.error);
+    if ('response' in kept)
+        return revive(kept.response);
+    return kept.value;
+}
+async function response(answer) {
+    const body = answer.body === null
+        ? null
+        : Buffer.from(await answer.arrayBuffer()).toString('base64');
+    return {
+        status: answer.status,
+        statusText: answer.statusText,
+        headers: [...answer.headers.entries()],
+        body
+    };
+}
+function revive(kept) {
+    const body = kept.body === null ? null : Buffer.from(kept.body, 'base64');
+    return new Response(body, {
+        status: kept.status,
+        statusText: kept.statusText,
+        headers: kept.headers
+    });
+}
+function streamed(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const object = value;
+    return (typeof object.pipe === 'function' ||
+        typeof object.getReader === 'function' ||
+        typeof object[Symbol.asyncIterator] === 'function');
+}
+//# sourceMappingURL=answers.js.map

package/transpiled/answers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"answers.js","sourceRoot":"","sources":["../source/answers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAoBzC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,MAAe;IAC1C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAE/C,IAAI,MAAM,YAAY,QAAQ;QAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAA;IAE3E,IAAI,QAAQ,CAAC,MAAM,CAAC;QAClB,MAAM,IAAI,UAAU,CAAC,qBAAqB,CACxC,4EAA4E,CAC7E,CAAA;IAEH,IAAI,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC;QAC5B,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,QAAQ,CAC9E,QAAQ,CACT;SACF,CAAA;IAEH,sFAAsF;IACtF,IAAI,MAAM,YAAY,KAAK;QAAE,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,CAAA;IAE5D,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AAC1B,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,IAAU;IAC/B,IAAI,MAAM,IAAI,IAAI;QAAE,OAAO,SAAS,CAAA;IACpC,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IAC7D,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;IAClE,IAAI,UAAU,IAAI,IAAI;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAEpD,OAAO,IAAI,CAAC,KAAK,CAAA;AACnB,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,MAAgB;IACtC,MAAM,IAAI,GACR,MAAM,CAAC,IAAI,KAAK,IAAI;QAClB,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAEhE,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACtC,IAAI;KACL,CAAA;AACH,CAAC;AAED,SAAS,MAAM,CAAC,IAAkB;IAChC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;IAEzE,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;QACxB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAA;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAE7D,MAAM,MAAM,GAAG,KAAyC,CAAA;IAExD,OAAO,CACL,OAAO,MAAM,CAAC,IAAI,KAAK,UAAU;QACjC,OAAO,MAAM,CAAC,SAAS,KAAK,UAAU;QACtC,OAAO,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,UAAU,CACnD,CAAA;AACH,CAAC"}

package/transpiled/fingerprint.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What a step asks, as a digest: the same arguments give the same one on every attempt, whatever
+ * order an object's keys were written in.
+ *
+ * Only what a step is asked is read. A value no attempt can give twice — a function, a signal, a
+ * stream — is told by its kind alone, so it neither tells two attempts apart nor fails to digest.
+ */
+export declare function fingerprint(args: unknown[]): string;

package/transpiled/fingerprint.js

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto';
+/**
+ * What a step asks, as a digest: the same arguments give the same one on every attempt, whatever
+ * order an object's keys were written in.
+ *
+ * Only what a step is asked is read. A value no attempt can give twice — a function, a signal, a
+ * stream — is told by its kind alone, so it neither tells two attempts apart nor fails to digest.
+ */
+export function fingerprint(args) {
+    const hash = createHash('sha1');
+    write(hash, args, new Set());
+    return hash.digest('hex');
+}
+function write(hash, value, seen) {
+    if (value === null || typeof value !== 'object') {
+        // the type as well, so that `1` and `'1'` are two different asks
+        hash.update(typeof value + ':' + String(value) + ';');
+        return;
+    }
+    if (seen.has(value)) {
+        hash.update('cycle;');
+        return;
+    }
+    seen.add(value);
+    if (ArrayBuffer.isView(value)) {
+        hash.update('bytes:');
+        hash.update(value);
+        hash.update(';');
+    }
+    else if (value instanceof Date)
+        hash.update('date:' + value.toISOString() + ';');
+    else if (value instanceof URL)
+        hash.update('url:' + value.href + ';');
+    else if (Array.isArray(value)) {
+        hash.update('[');
+        for (const item of value)
+            write(hash, item, seen);
+        hash.update(']');
+    }
+    else if (plain(value)) {
+        hash.update('{');
+        for (const key of Object.keys(value).sort()) {
+            const item = value[key];
+            // absent and undefined are one ask, as they are once the request is on the wire
+            if (item === undefined)
+                continue;
+            hash.update(JSON.stringify(key) + '=');
+            write(hash, item, seen);
+        }
+        hash.update('}');
+    }
+    else
+        hash.update('<' + (value.constructor?.name ?? 'object') + '>;');
+    seen.delete(value);
+}
+function plain(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+//# sourceMappingURL=fingerprint.js.map

package/transpiled/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../source/fingerprint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAe;IACzC,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;IAE/B,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,CAAC,CAAA;IAE5B,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC3B,CAAC;AAID,SAAS,KAAK,CAAC,IAAU,EAAE,KAAc,EAAE,IAAiB;IAC1D,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,iEAAiE;QACjE,IAAI,CAAC,MAAM,CAAC,OAAO,KAAK,GAAG,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAA;QAErD,OAAM;IACR,CAAC;IAED,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QAErB,OAAM;IACR,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IAEf,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QACrB,IAAI,CAAC,MAAM,CAAC,KAAmB,CAAC,CAAA;QAChC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAClB,CAAC;SAAM,IAAI,KAAK,YAAY,IAAI;QAAE,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,CAAA;SAC7E,IAAI,KAAK,YAAY,GAAG;QAAE,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,CAAA;SAChE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAEhB,KAAK,MAAM,IAAI,IAAI,KAAK;YAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;QAEjD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAClB,CAAC;SAAM,IAAI,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAEhB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAC5C,MAAM,IAAI,GAAI,KAAiC,CAAC,GAAG,CAAC,CAAA;YAEpD,gFAAgF;YAChF,IAAI,IAAI,KAAK,SAAS;gBAAE,SAAQ;YAEhC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAA;YACtC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;QACzB,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAClB,CAAC;;QAAM,IAAI,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,IAAI,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAA;IAEtE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACpB,CAAC;AAED,SAAS,KAAK,CAAC,KAAa;IAC1B,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAA;IAE9C,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAA;AAC7D,CAAC"}

package/transpiled/index.d.ts

@@ -0,0 +1,3 @@
+export { Factory } from './Factory.ts';
+export { components } from './Composition.ts';
+export type { Declaration } from '@toa.io/definitions/extensions.continuity';

package/transpiled/index.js

@@ -0,0 +1,3 @@
+export { Factory } from './Factory.js';
+export { components } from './Composition.js';
+//# sourceMappingURL=index.js.map

package/transpiled/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA"}