@toa.io/extensions.chronicles 0.0.0-stage → 1.0.0-alpha.332

package/readme.md

@@ -0,0 +1,369 @@
+# Toa Chronicles
+
+A log of what happens in a context, kept in a store the context names. Components write to it by
+the events they name and the facts they send, browsers by a route of the gateway, and it is read
+by an [HTTP API](#reading-the-log) — which the gateway also publishes as [MCP](#over-mcp) tools.
+The service `chronicles-scribe` writes the log, and is what the store is provisioned by and read
+through.
+
+## The log
+
+Two tables.
+
+**`events`** holds a row for everything that happened, from three sources:
+
+| source                                           | `label`               | `entity`, `version`                      | `payload`              |
+| ------------------------------------------------ | --------------------- | ---------------------------------------- | ---------------------- |
+| an [event](#events-and-states) a component names | `<component>.<event>` | the entity that changed, and its version | what the event renders |
+| a [fact](#facts) an operation sends              | `<component>.<name>`  | `NULL`                                   | what was sent          |
+| an event a [browser](#from-a-browser) sends      | `agent.<name>`        | `NULL`                                   | what the browser sent  |
+
+An order placed, a search made and a page left are three rows:
+
+| `label`                 | `component`            | `entity` | `version` | `payload`                         |
+| ----------------------- | ---------------------- | -------- | --------- | --------------------------------- |
+| `store.orders.created`  | `store.orders`         | `9c1f…`  | `0`       | `{ total: 120, status: "new" }`   |
+| `store.search.searched` | `store.search`         | `NULL`   | `NULL`    | `{ query: "teapot", results: 3 }` |
+| `agent.page_left`       | `chronicles.ingestion` | `NULL`   | `NULL`    | `{ path: "/pricing" }`            |
+
+Every row also has `id`, the same however often it is delivered, so a row is kept once;
+`identity`, whose it is, where something [says so](#identity); `ip` and `country`, of the
+browser that [sent it](#from-a-browser); `time`, when it happened; `received`, when the store wrote
+it; and `trace`, the traceparent of the call that caused it.
+
+**`states`** holds each entity as it stands: for every component that names a
+[state](#events-and-states), a row per entity — `component`, `entity`, `version`, `identity`,
+`time`, `received` and `payload` — which a higher version replaces.
+
+Nothing is ordered: order by `time`, or by `version` within one entity.
+
+## Events and states
+
+```yaml
+# manifest.toa.yaml
+chronicles:
+  events: [created, paid] # what happened: rows of `events`
+  state: snapshot # the entity as it stands: its row of `states`
+```
+
+Each label is an event of the component — its own, or the prototype's `created`, `updated`,
+`deleted` and `sync`. An event is written as it renders: where its `condition` does not hold,
+nothing is written; where it has a `payload`, what the payload returns is what is written. A field
+a payload leaves out does not reach the store. A list is the `events` alone:
+
+```yaml
+# manifest.toa.yaml
+chronicles: [created, paid]
+```
+
+The state is any event whose payload is the entity, `sync` among them. An event that exists for
+the log alone is an event file like any other, and nothing else has to consume it:
+
+```typescript
+// events/snapshot.ts
+export function payload(event: Event) {
+  const { email, address, ...rest } = event.state
+
+  return rest
+}
+```
+
+A state's payload carries `id` and `VERSION`, which say which entity it is and which version: one
+that does not is refused, and kept in the parking queue of its consumer rather than written. A row
+of `events` takes its `entity`, `version` and `time` from the payload's `id`, `VERSION` and
+`UPDATED` where it carries them, and is written without them, at the time it was taken, where it
+does not. An event that is both is named in both.
+
+A committed change is written however long the scribe is away, and once however often it is
+delivered. One committed before the scribe first ran in a deployment is not.
+
+### Identity
+
+`identity` is the payload's `identity`, where it is a string:
+
+```yaml
+# manifest.toa.yaml
+chronicles:
+  events: [created, paid]
+  state: snapshot
+  identity: customer # the property of the payloads that names whose a row is
+```
+
+A component names another property, or none with `identity: ~`. One property serves every event of
+the component and its state, and a payload that leaves it out is a row of no identity. A property
+the component names is one of its entity.
+
+## Facts
+
+```typescript
+await context.chronicles.send('searched', { query: input.query, results: results.length })
+```
+
+The fact is a row of `events` under `<component>.searched`, with what was sent as its payload.
+`send` resolves once the broker has it, and it then waits for the scribe as an event does.
+
+An operation that knows whose the fact is says so; the extension does not know who called it:
+
+```typescript
+await context.chronicles.send(
+  'searched',
+  { query: input.query },
+  { identity: input.customer }
+)
+```
+
+`context.chronicles` is given to a component that declares `chronicles`. One that only sends
+declares it empty:
+
+```yaml
+# manifest.toa.yaml
+chronicles: []
+```
+
+## From a browser
+
+Served where the context says `ingest: true`, at two routes: one of an identity, and one of no one.
+
+### `POST /chronicles/ingestion/:identity/`
+
+What a signed-in client sends, as the identity it is.
+
+```http
+POST /chronicles/ingestion/9c1f0a6d5b7e4f3a8d2c1b0a9e8f7d6c/ HTTP/1.1
+authorization: Token …
+content-type: application/json
+
+{ "events": [{ "id": "0192f3a1-…", "name": "page_viewed", "time": 1761200000000, "payload": { "path": "/pricing" } }] }
+```
+
+```http
+202 Accepted
+
+accepted: 1
+```
+
+The token is the identity's, or the request is answered `403`: the rows are that identity's,
+whatever the body says. Throttled to 60 requests a minute per identity.
+
+### `POST /chronicles/ingestion/`
+
+What anyone sends, before signing in or without it. The same body, and rows of no identity; a body
+that names one is refused.
+
+```http
+POST /chronicles/ingestion/ HTTP/1.1
+content-type: application/json
+
+{ "events": [{ "id": "0192f3a2-…", "name": "page_left", "time": 1761200000000 }] }
+```
+
+It takes no credentials, and is throttled to 60 requests a minute per address. A form whose
+`events` is their JSON is read as the JSON body, so `navigator.sendBeacon`, which sends no
+`authorization`, can send a batch here as the page closes:
+
+```javascript
+navigator.sendBeacon(
+  '/chronicles/ingestion/',
+  new URLSearchParams({ events: JSON.stringify(events) })
+)
+```
+
+A signed-in client sends with `fetch(…, { keepalive: true })` instead. Anyone can send anything: a
+`user` in a payload is what the client said.
+
+### The body
+
+`{ events }`, at most 100 of them, each a row of `events` under `agent.<name>`:
+
+| property  |                                                                     |
+| --------- | ------------------------------------------------------------------- |
+| `id`      | the client's own, at most 64 characters; a retry sends the same one |
+| `name`    | lowercase letters, digits and underscores from a letter, at most 64 |
+| `time`    | when it happened, in milliseconds, by the client's clock            |
+| `payload` | an object, at most 16 KiB of JSON                                   |
+
+A request is answered once its events are written. A batch one event of which breaks any of the
+above is written not at all, and answered `422` with the code `INVALID`, or `OVERSIZED` for a
+payload too large, and the `index` of the event in `cause`.
+
+### Address and country
+
+Every row a browser sent has the `ip` and the `country` of the request, as the gateway reads them
+from the headers [`exposition.ip` and `exposition.country`](/extensions/exposition/documentation/ip.md)
+name, and `NULL` where it has none; a body that names either is overwritten. An address is
+personal data, and the log erases nothing, so of an address the log keeps its network — a `/24` of
+IPv4, a `/48` of IPv6 — unless the annotation says `ip: full`.
+
+## Reading the log
+
+Reading takes the role `system:chronicles:query`, and views take `system:chronicles:views`;
+`system:chronicles` grants both. A refusal is answered `422` with `{ code, cause }`.
+
+### `GET /chronicles/queries/`
+
+What the log holds: the dialect queries are written in, the labels of `events`, the components
+with a state, and the views.
+
+```http
+GET /chronicles/queries/ HTTP/1.1
+authorization: Token …
+accept: application/yaml
+```
+
+```http
+200 OK
+
+dialect: ClickHouse SQL; read `events` and `states` with FINAL
+labels:
+  - label: store.orders.created
+    rows: 1204
+    first: 2026-10-01 08:12:03.000
+    last: 2026-10-24 17:40:51.000
+    paths: [VERSION, id, status, total]
+states:
+  - component: store.orders
+    entities: 1180
+    paths: [VERSION, id, status, total]
+views:
+  - name: daily
+    sql: SELECT toDate(time) AS day, count() AS orders FROM events FINAL GROUP BY day
+    refresh: 3600
+```
+
+`rows` counts what the store holds, a row delivered twice possibly twice; `paths` are the fields of
+the latest payloads.
+
+### `POST /chronicles/queries/`
+
+One statement, in the dialect.
+
+```http
+POST /chronicles/queries/ HTTP/1.1
+authorization: Token …
+accept: application/yaml
+content-type: application/yaml
+
+sql: SELECT payload.status AS status, count() AS n FROM states FINAL GROUP BY status
+```
+
+```http
+201 Created
+
+columns:
+  - name: status
+    type: Dynamic
+  - name: n
+    type: UInt64
+rows:
+  - [new, 31]
+  - [paid, 1149]
+truncated: false
+```
+
+A query reads the log and nothing else, and cannot write. It runs for at most 30 seconds and
+answers at most 10,000 rows: at the rows it answers what it has, with `truncated: true`. It leaves
+`FORMAT` out.
+
+| code      | when                                                                    |
+| --------- | ----------------------------------------------------------------------- |
+| `REFUSED` | the store refused the statement; `cause.message` is what the store said |
+
+### `PUT /chronicles/queries/views/:name`
+
+A view over the log, by a statement a query could run. Defining a name again replaces the view.
+
+```http
+PUT /chronicles/queries/views/daily/ HTTP/1.1
+authorization: Token …
+content-type: application/yaml
+
+sql: SELECT toDate(time) AS day, count() AS orders FROM events FINAL GROUP BY day
+refresh: 3600
+```
+
+```http
+204 No Content
+```
+
+Without `refresh`, a view is computed when it is read. With `refresh`, in seconds and at least
+`3600`, it is computed on that cycle and read as a table. A name is lowercase letters, digits and
+underscores, and a context has at most 50 views. A query reads a view by its name.
+
+| code        | when                                                                 |
+| ----------- | -------------------------------------------------------------------- |
+| `REFUSED`   | the statement is not one a query could run; `cause.message` says why |
+| `RESERVED`  | the name is one of the log's tables                                  |
+| `EXHAUSTED` | the context has 50 views, and this is not one of them                |
+
+### `DELETE /chronicles/queries/views/:name`
+
+```http
+DELETE /chronicles/queries/views/daily/ HTTP/1.1
+authorization: Token …
+```
+
+```http
+204 No Content
+```
+
+| code        | when                  |
+| ----------- | --------------------- |
+| `NOT_FOUND` | there is no such view |
+
+### Over MCP
+
+Where the context publishes [MCP](/extensions/exposition/documentation/mcp.md), each of these
+routes is a tool, under the name the gateway gives a route, and taking what the route takes:
+
+| tool                                    | route                                    |
+| --------------------------------------- | ---------------------------------------- |
+| `chronicles.queries.GET`                | `GET /chronicles/queries/`               |
+| `chronicles.queries.POST`               | `POST /chronicles/queries/`              |
+| `chronicles.queries.views._name.PUT`    | `PUT /chronicles/queries/views/:name`    |
+| `chronicles.queries.views._name.DELETE` | `DELETE /chronicles/queries/views/:name` |
+
+A tool is listed to a caller that holds its role, and a refusal is a tool result with `isError`.
+
+## Deployment
+
+```yaml
+# context.toa.yaml
+chronicles:
+  store:
+    provider: clickhouse
+    url: https://ch.example.com:8443/shop
+  retention: 730
+  ingest: true
+```
+
+|             |                                                             |
+| ----------- | ----------------------------------------------------------- |
+| `store`     | the provider that keeps the log, and its address            |
+| `retention` | days a row of `events` is kept; absent, kept                |
+| `ingest`    | the browser route; absent, there is none                    |
+| `ip`        | `full` keeps a browser's whole address; absent, its network |
+
+```shell
+$ toa conceal chronicles-store username=… password=… reader=…
+```
+
+The user provisions the store when the service starts. It creates the reader, the user queries run
+as, with `reader` as its password.
+
+The events the components name travel where the context's `amqp` says, as every event does.
+
+## ClickHouse
+
+`url` is ClickHouse's HTTP address, and its path names the database, which is created where it does
+not exist. The user needs `CREATE`, `INSERT` and `access_management`; the reader is
+`<database>_reader`.
+
+`events` and `states` are replaced by key in the background, so a query reads them with `FINAL`,
+which collapses what was delivered twice:
+
+```sql
+SELECT payload.total::Float64, count() FROM events FINAL WHERE label = 'store.orders.paid' GROUP BY 1
+SELECT entity, payload FROM states FINAL WHERE component = 'store.orders'
+```
+
+A view with `refresh` is a refreshable materialized view.

package/transpiled/Client.d.ts

@@ -0,0 +1,19 @@
+import { Connector } from '@toa.io/core';
+import type { Address } from '@toa.io/definitions/extensions.chronicles';
+import type { Writer } from './Writer.ts';
+/**
+ * What `chronicles.ingestion` writes what browsers send through: each event under `agent.<name>`,
+ * with the client's own id and time, all of a batch in one write, and answered once it is.
+ */
+export declare class Client extends Connector {
+    readonly name = "chronicles";
+    private readonly writer;
+    private readonly address;
+    constructor(writer: () => Writer, address: () => Address);
+    invoke(method: string, ...args: any[]): Promise<unknown>;
+    /**
+     * `identity` is the one the gateway verified the caller to be, from the path; `null` for the
+     * route anyone may call, whose body is then refused where it says whose it is.
+     */
+    private ingest;
+}

package/transpiled/Client.js

@@ -0,0 +1,121 @@
+import { current, encode } from 'openspan';
+import { Connector, exceptions } from '@toa.io/core';
+import { AGENT, INGESTION, NAMESPACE } from '@toa.io/definitions/extensions.chronicles';
+import { keep } from './address.js';
+/**
+ * What `chronicles.ingestion` writes what browsers send through: each event under `agent.<name>`,
+ * with the client's own id and time, all of a batch in one write, and answered once it is.
+ */
+export class Client extends Connector {
+    name = 'chronicles';
+    writer;
+    address;
+    constructor(writer, address) {
+        super();
+        this.writer = writer;
+        this.address = address;
+    }
+    async invoke(method, ...args) {
+        if (method !== 'ingest')
+            throw new exceptions.MisuseException(`Chronicles have no '${method}'`);
+        return await this.ingest(args[0], args[1] ?? null);
+    }
+    /**
+     * `identity` is the one the gateway verified the caller to be, from the path; `null` for the
+     * route anyone may call, whose body is then refused where it says whose it is.
+     */
+    async ingest(input, identity) {
+        const events = parse(input, identity !== null);
+        if (events instanceof Error)
+            return events;
+        const context = current();
+        const trace = context === undefined ? null : encode(context);
+        // put in by the gateway, which overwrites whatever the body says of them
+        const { ip, country } = input;
+        const address = keep(ip, this.address());
+        const from = typeof country === 'string' ? country : null;
+        const rows = events.map((event) => ({
+            id: event.id,
+            label: `${AGENT}.${event.name}`,
+            component: COMPONENT,
+            time: event.time,
+            entity: null,
+            version: null,
+            identity,
+            ip: address,
+            country: from,
+            trace,
+            payload: event.payload ?? {}
+        }));
+        await this.writer().write(rows);
+        return { status: 202, accepted: rows.length };
+    }
+}
+/**
+ * A batch, `{ events }`: as JSON, or as the form `navigator.sendBeacon` sends, whose `events` is
+ * the JSON of them. Checked here rather than by the operation's schema, which cannot read the
+ * form's. `identified` is whether the gateway put the identity in, which is then a key the body
+ * may have beside `events`.
+ */
+function parse(input, identified) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input))
+        return invalid('The body is `{ events }`');
+    // `ip` and `country` are the gateway's, which sets them on every request it makes
+    const { events: given, identity, ip: _ip, country: _country, ...rest } = input;
+    const extra = Object.keys(rest);
+    if (extra.length > 0)
+        return invalid(`The body has no '${extra[0]}'`);
+    // the identity is the path's, never the body's
+    if (!identified && identity !== undefined)
+        return invalid('The body names no identity: a client that has one sends it in the path');
+    let events = given;
+    if (typeof events === 'string')
+        try {
+            events = JSON.parse(events);
+        }
+        catch {
+            return invalid('`events` is not JSON');
+        }
+    if (!Array.isArray(events))
+        return invalid('`events` is an array of events');
+    if (events.length > MAX_EVENTS)
+        return invalid(`A request carries at most ${MAX_EVENTS} events`);
+    for (const [index, event] of events.entries()) {
+        const problem = check(event);
+        if (problem !== null)
+            return invalid(problem, index);
+        if (JSON.stringify(event.payload ?? {}).length > MAX_PAYLOAD)
+            return new Error('OVERSIZED', {
+                cause: { index, message: `A payload is at most ${MAX_PAYLOAD} bytes of JSON` }
+            });
+    }
+    return events;
+}
+function check(event) {
+    if (typeof event !== 'object' || event === null || Array.isArray(event))
+        return 'An event is an object';
+    const { id, name, time, payload, ...rest } = event;
+    if (Object.keys(rest).length > 0)
+        return `An event has no '${Object.keys(rest)[0]}'`;
+    if (typeof id !== 'string' || id.length === 0 || id.length > 64)
+        return '`id` is a string of 1 to 64 characters';
+    if (typeof name !== 'string' || name.length > 64 || !NAME.test(name))
+        return '`name` is lowercase letters, digits and underscores from a letter, at most 64 characters';
+    if (!Number.isInteger(time) || time < 0)
+        return '`time` is milliseconds since the epoch';
+    if (payload !== undefined &&
+        (typeof payload !== 'object' || payload === null || Array.isArray(payload)))
+        return '`payload` is an object';
+    return null;
+}
+function invalid(message, index) {
+    return new Error('INVALID', {
+        cause: index === undefined ? { message } : { index, message }
+    });
+}
+const COMPONENT = `${NAMESPACE}.${INGESTION}`;
+const MAX_EVENTS = 100;
+const MAX_PAYLOAD = 16 * 1024;
+// no dot: a label is `agent.<name>`, and what follows the prefix is one name
+const NAME = /^[a-z][a-z0-9_]*$/;
+//# sourceMappingURL=Client.js.map

package/transpiled/Client.js.map

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

package/transpiled/Factory.d.ts

@@ -0,0 +1,16 @@
+import type { Connector, Locator } from '@toa.io/core';
+import type { extensions } from '@toa.io/core/types';
+/**
+ * A component sends facts through its context; the events it names reach the log as events of
+ * the context, which the service consumes. The components this extension ships are given what
+ * they serve instead: the queries, the provider; the facts and the client route, the writer.
+ */
+export declare class Factory implements extensions.Factory {
+    private readonly host;
+    /** one store and one writer for the process, made where the process is one that keeps the log */
+    private store;
+    constructor(host: extensions.Host);
+    aspect(locator: Locator): extensions.Aspect;
+    service(): Connector;
+    private keep;
+}

package/transpiled/Factory.js

@@ -0,0 +1,53 @@
+import { FACTS, INGESTION, NAMESPACE, QUERIES } from '@toa.io/definitions/extensions.chronicles';
+import { Client } from './Client.js';
+import { Facts } from './Facts.js';
+import { Reader } from './Reader.js';
+import { Scribe } from './Scribe.js';
+import { Sender } from './Sender.js';
+import { Writer } from './Writer.js';
+import { credentials, settings } from './settings.js';
+import { provider } from './store.js';
+/**
+ * A component sends facts through its context; the events it names reach the log as events of
+ * the context, which the service consumes. The components this extension ships are given what
+ * they serve instead: the queries, the provider; the facts and the client route, the writer.
+ */
+export class Factory {
+    host;
+    /** one store and one writer for the process, made where the process is one that keeps the log */
+    store;
+    constructor(host) {
+        this.host = host;
+    }
+    aspect(locator) {
+        if (mine(locator))
+            switch (locator.name) {
+                case QUERIES:
+                    return new Reader(() => this.keep().provider);
+                case FACTS:
+                    return new Facts(() => this.keep().writer);
+                case INGESTION:
+                    return new Client(() => this.keep().writer, () => settings().ip);
+            }
+        return new Sender(this.host, locator);
+    }
+    // nothing connects to this, so a halt takes the whole of it
+    service() {
+        return this.host.gate(async () => {
+            const { provider, writer } = this.keep();
+            return new Scribe(this.host, settings(), provider, writer);
+        });
+    }
+    keep() {
+        if (this.store === undefined) {
+            const store = provider(settings(), credentials());
+            this.store = { provider: store, writer: new Writer(store) };
+        }
+        return this.store;
+    }
+}
+/** Whether this is a component the extension ships rather than one of the application's. */
+function mine(locator) {
+    return locator.namespace === NAMESPACE;
+}
+//# sourceMappingURL=Factory.js.map

package/transpiled/Factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Factory.js","sourceRoot":"","sources":["../source/Factory.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,SAAS,EACT,SAAS,EACT,OAAO,EACR,MAAM,2CAA2C,CAAA;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAKrC;;;;GAIG;AACH,MAAM,OAAO,OAAO;IACD,IAAI,CAAiB;IAEtC,iGAAiG;IACzF,KAAK,CAAoD;IAEjE,YAAmB,IAAqB;QACtC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAEM,MAAM,CAAC,OAAgB;QAC5B,IAAI,IAAI,CAAC,OAAO,CAAC;YACf,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;gBACrB,KAAK,OAAO;oBACV,OAAO,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,CAAA;gBAC/C,KAAK,KAAK;oBACR,OAAO,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAA;gBAC5C,KAAK,SAAS;oBACZ,OAAO,IAAI,MAAM,CACf,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,EACxB,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,EAAE,CACpB,CAAA;YACL,CAAC;QAEH,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACvC,CAAC;IAED,4DAA4D;IACrD,OAAO;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;YAC/B,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;YAExC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAA;QAC5D,CAAC,CAAC,CAAA;IACJ,CAAC;IAEO,IAAI;QACV,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,EAAE,EAAE,WAAW,EAAE,CAAC,CAAA;YAEjD,IAAI,CAAC,KAAK,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;QAC7D,CAAC;QAED,OAAO,IAAI,CAAC,KAAK,CAAA;IACnB,CAAC;CACF;AAED,4FAA4F;AAC5F,SAAS,IAAI,CAAC,OAAgB;IAC5B,OAAO,OAAO,CAAC,SAAS,KAAK,SAAS,CAAA;AACxC,CAAC"}

package/transpiled/Facts.d.ts

@@ -0,0 +1,9 @@
+import { Connector } from '@toa.io/core';
+import type { Writer } from './Writer.ts';
+/** What `chronicles.facts` writes a fact a component sent through. */
+export declare class Facts extends Connector {
+    readonly name = "chronicles";
+    private readonly writer;
+    constructor(writer: () => Writer);
+    invoke(method: string, ...args: any[]): Promise<void>;
+}

package/transpiled/Facts.js

@@ -0,0 +1,16 @@
+import { Connector, exceptions } from '@toa.io/core';
+/** What `chronicles.facts` writes a fact a component sent through. */
+export class Facts extends Connector {
+    name = 'chronicles';
+    writer;
+    constructor(writer) {
+        super();
+        this.writer = writer;
+    }
+    async invoke(method, ...args) {
+        if (method !== 'record')
+            throw new exceptions.MisuseException(`Chronicles have no '${method}'`);
+        await this.writer().write([args[0]]);
+    }
+}
+//# sourceMappingURL=Facts.js.map

package/transpiled/Facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Facts.js","sourceRoot":"","sources":["../source/Facts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAIpD,sEAAsE;AACtE,MAAM,OAAO,KAAM,SAAQ,SAAS;IAClB,IAAI,GAAG,YAAY,CAAA;IAElB,MAAM,CAAc;IAErC,YAAmB,MAAoB;QACrC,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;IAEM,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,GAAG,IAAW;QAChD,IAAI,MAAM,KAAK,QAAQ;YACrB,MAAM,IAAI,UAAU,CAAC,eAAe,CAAC,uBAAuB,MAAM,GAAG,CAAC,CAAA;QAExE,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAQ,CAAC,CAAC,CAAA;IAC7C,CAAC;CACF"}