@toa.io/extensions.introspection 1.0.0-alpha.262

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [1.0.0-alpha.262](https://github.com/toa-io/toa/compare/v1.0.0-alpha.261...v1.0.0-alpha.262) (2026-08-28)
+
+
+### Bug Fixes
+
+* **introspection:** keep the collector off the critical path ([965ec77](https://github.com/toa-io/toa/commit/965ec77482d361a5a9a88579152158c7e1c79e66))
+* **introspection:** meet a card across the edge the line touches ([2002de9](https://github.com/toa-io/toa/commit/2002de9bdc12400abc64d5234fa319339db4588f))
+* **introspection:** return the whole map over HTTP ([053c0cd](https://github.com/toa-io/toa/commit/053c0cd5c22b1a80bceb23d2cda68ede33a0d1c0))
+* **introspection:** serve a route that looks like a file ([b43bbb4](https://github.com/toa-io/toa/commit/b43bbb4a290819463c61bcba64357385c2423d25))
+* **introspection:** show the lines an opened neighbour sends ([5fe8aed](https://github.com/toa-io/toa/commit/5fe8aed64c1f1e54f1c10e29b91b50c5cdc296ab))
+* **introspection:** wait for the page before capturing it ([9e63af3](https://github.com/toa-io/toa/commit/9e63af34ee090a4f90dce9658b0d022f4acae50f))
+
+
+* feat(introspection)!: publish the UI ([81fe2cb](https://github.com/toa-io/toa/commit/81fe2cb4bafe91e74d3af8359327e3102e5b0e8a))
+
+
+### Features
+
+* **introspection:** act on the only thing the filter left ([1a83709](https://github.com/toa-io/toa/commit/1a8370987b7d60c009f4d58f07005618899cdfd6))
+* **introspection:** add the introspection extension ([a07ed86](https://github.com/toa-io/toa/commit/a07ed8651404258d544f3b6d8236e58cf4da09ac))
+* **introspection:** animate a card opening on the map ([1d2180f](https://github.com/toa-io/toa/commit/1d2180f48fb9dc18d9fa0c2cc4eefa6f46626898))
+* **introspection:** animate every collapsible from one place ([0b6a32b](https://github.com/toa-io/toa/commit/0b6a32b69128f2db2d3e449896614ff478f2775b))
+* **introspection:** ask for the role rather than be refused it ([1ad01a7](https://github.com/toa-io/toa/commit/1ad01a7dd817ae37ed84e3a3b6b20b72049a4216))
+* **introspection:** cache the map API ([f550c27](https://github.com/toa-io/toa/commit/f550c2780a80bbe2fdd131984c33d9848daa8c82))
+* **introspection:** fold away a component's extensions ([de1bea6](https://github.com/toa-io/toa/commit/de1bea6329a1fd920cff6b5ad9a13eedfc527884))
+* **introspection:** give a card's rows their own space ([3253639](https://github.com/toa-io/toa/commit/32536395b9d25e743c25b61deb9dbd5b79d966b6))
+* **introspection:** give the map's two screens their own addresses ([90fd5af](https://github.com/toa-io/toa/commit/90fd5af39b8b6c38e22e05df46c70de533eb15c6))
+* **introspection:** open a component on the map ([6382740](https://github.com/toa-io/toa/commit/63827403407fc5a305d95e9fde72ed5a99a1499a))
+* **introspection:** open an operation onto what it takes ([f16a683](https://github.com/toa-io/toa/commit/f16a683175a89d3660c538768b24cd872b6d0b3d))
+* **introspection:** publish the map as a page ([21b16b2](https://github.com/toa-io/toa/commit/21b16b2220a1b26796bdbedc85a0df2a88df31dd))
+* **introspection:** say a component's shape in counts ([54aa771](https://github.com/toa-io/toa/commit/54aa771a51c257db759107d584d063916f0cd351))
+* **introspection:** say how a silenced card comes back ([6e7674f](https://github.com/toa-io/toa/commit/6e7674f88137cfb780f3a7cac1fc67f191f96984))
+* **introspection:** separate what the runtime provides ([289c7a3](https://github.com/toa-io/toa/commit/289c7a301dd0ab9c063a5b77b24745983ec79e29))
+* **introspection:** show a schema as a shape ([7d9a595](https://github.com/toa-io/toa/commit/7d9a595d86f88846b21bb79aba82bb332b77fbf6))
+* **introspection:** the map is the front page ([dbf1b5f](https://github.com/toa-io/toa/commit/dbf1b5fd6d262aa2aa952bbfe2a6be1e44af6302))
+
+
+### Performance Improvements
+
+* **introspection:** build a card's details when it shows them ([c10f7c4](https://github.com/toa-io/toa/commit/c10f7c42e51cbef2d3767c36559d846f0e34653a))
+
+
+### BREAKING CHANGES
+
+* the extension is predefined, so every Context now declares an
+ingress and must say where it lands:
+
+    ingress:
+      hosts: [api.example.com]
+
+An application that does not want the page says `introspection: { ui: false }`,
+and one that wants no map at all says `introspection: false`. Failing the export
+is deliberate: the alternative is quietly not publishing a page that was asked
+for.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

package/components/introspection.edges/manifest.toa.yaml

@@ -0,0 +1,48 @@
+namespace: introspection
+name: edges
+
+# One document per edge of the map: a call one component made to another, with `src`
+# saying what caused it — another operation, an event, or a service. What the
+# application declares is described by `introspection.nodes`; an edge is what
+# actually happened.
+#
+# Every replica of a component derives the same id for the same edge, so `merge` is
+# an upsert and `_updated` shows when the edge was last observed.
+
+entity:
+  associated: true
+  schema:
+    src: ~
+    dst: ~
+    sample: ~
+
+operations:
+  # a mass transition: the scope is inferred from the algorithm's `objects` parameter
+  merge:
+    concurrency: retry
+    input:
+      type: object
+      properties:
+        edges:
+          type: object
+      required: [edges]
+
+# the map must not describe itself
+introspection: false
+
+exposition:
+  /:
+    auth:role: system:introspection
+
+    # the map is the whole document, and its shape is what the application happens to declare
+    io:output: true
+    cache:control: max-age=60, public
+    # the map is read whole: a page of ten is of no use to anything that draws it
+    GET:
+      endpoint: enumerate
+      query:
+        limit:
+          value: 10000
+          range: [1, 10000]
+    /:id:
+      GET: observe

package/components/introspection.edges/operations/lib/types.d.ts

@@ -0,0 +1,28 @@
+export interface Source {
+    namespace?: string;
+    component?: string;
+    operation?: string;
+    event?: string;
+    service?: string;
+}
+export interface Target {
+    namespace: string;
+    component: string;
+    operation: string;
+}
+export interface Sample {
+    at: number;
+    input?: unknown;
+    outcome: string;
+}
+export interface Observed {
+    src: Source;
+    dst: Target;
+    sample?: Sample;
+}
+export interface Edge extends Observed {
+    id: string;
+}
+export interface Input {
+    edges: Record<string, Observed>;
+}

package/components/introspection.edges/operations/lib/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/components/introspection.edges/operations/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../source/lib/types.ts"],"names":[],"mappings":""}

package/components/introspection.edges/operations/merge.d.ts

@@ -0,0 +1,9 @@
+import type { Edge, Input } from './lib/types';
+/**
+ * Records the calls observed by a collector since its last flush.
+ *
+ * The scope is `objects`, so the caller passes every affected id in `query.ids`
+ * and the matching edge under `edges[id]`. Unknown edges are initialized by the
+ * runtime, since the entity is `associated`.
+ */
+export declare function transition(input: Input, objects: Edge[]): Edge[];

package/components/introspection.edges/operations/merge.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transition = void 0;
+/**
+ * Records the calls observed by a collector since its last flush.
+ *
+ * The scope is `objects`, so the caller passes every affected id in `query.ids`
+ * and the matching edge under `edges[id]`. Unknown edges are initialized by the
+ * runtime, since the entity is `associated`.
+ */
+function transition(input, objects) {
+    for (const edge of objects) {
+        const observed = input.edges[edge.id];
+        if (observed === undefined)
+            continue;
+        edge.src = observed.src;
+        edge.dst = observed.dst;
+        // absent when sampling is off, and the last one wins otherwise
+        if (observed.sample !== undefined)
+            edge.sample = observed.sample;
+    }
+    return objects;
+}
+exports.transition = transition;
+//# sourceMappingURL=merge.js.map

package/components/introspection.edges/operations/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../source/merge.ts"],"names":[],"mappings":";;;AAEA;;;;;;GAMG;AACH,SAAgB,UAAU,CAAE,KAAY,EAAE,OAAe;IACvD,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAErC,IAAI,QAAQ,KAAK,SAAS;YACxB,SAAQ;QAEV,IAAI,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAA;QACvB,IAAI,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAA;QAEvB,+DAA+D;QAC/D,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS;YAC/B,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAA;IACjC,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC;AAhBD,gCAgBC"}

package/components/introspection.edges/source/lib/types.ts

@@ -0,0 +1,33 @@
+export interface Source {
+  namespace?: string
+  component?: string
+  operation?: string
+  event?: string
+  service?: string
+}
+
+export interface Target {
+  namespace: string
+  component: string
+  operation: string
+}
+
+export interface Sample {
+  at: number
+  input?: unknown
+  outcome: string
+}
+
+export interface Observed {
+  src: Source
+  dst: Target
+  sample?: Sample
+}
+
+export interface Edge extends Observed {
+  id: string
+}
+
+export interface Input {
+  edges: Record<string, Observed>
+}

package/components/introspection.edges/source/merge.ts

@@ -0,0 +1,26 @@
+import type { Edge, Input } from './lib/types'
+
+/**
+ * Records the calls observed by a collector since its last flush.
+ *
+ * The scope is `objects`, so the caller passes every affected id in `query.ids`
+ * and the matching edge under `edges[id]`. Unknown edges are initialized by the
+ * runtime, since the entity is `associated`.
+ */
+export function transition (input: Input, objects: Edge[]): Edge[] {
+  for (const edge of objects) {
+    const observed = input.edges[edge.id]
+
+    if (observed === undefined)
+      continue
+
+    edge.src = observed.src
+    edge.dst = observed.dst
+
+    // absent when sampling is off, and the last one wins otherwise
+    if (observed.sample !== undefined)
+      edge.sample = observed.sample
+  }
+
+  return objects
+}

package/components/introspection.edges/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./operations"
+  },
+  "include": [
+    "source"
+  ]
+}

package/components/introspection.nodes/manifest.toa.yaml

@@ -0,0 +1,49 @@
+namespace: introspection
+name: nodes
+
+# The static description of an application component: entity, operations, events, receivers.
+# Every replica of a component announces the same id, thus `merge` is an upsert
+# (`associated` initializes a missing object) and re-announcing refreshes `_updated`.
+
+entity:
+  associated: true
+  schema:
+    namespace*: string
+    component*: string
+    version: string
+    entity: ~
+    operations: ~
+    events: ~
+    receivers: ~
+    extensions: ~
+
+operations:
+  # a mass transition: the scope is inferred from the algorithm's `objects` parameter
+  merge:
+    concurrency: retry
+    input:
+      type: object
+      properties:
+        nodes:
+          type: object
+      required: [nodes]
+
+# the map must not describe itself
+introspection: false
+
+exposition:
+  /:
+    auth:role: system:introspection
+
+    # the map is the whole document, and its shape is what the application happens to declare
+    io:output: true
+    cache:control: max-age=60, public
+    # the map is read whole: a page of ten is of no use to anything that draws it
+    GET:
+      endpoint: enumerate
+      query:
+        limit:
+          value: 1000
+          range: [1, 1000]
+    /:id:
+      GET: observe

package/components/introspection.nodes/operations/lib/types.d.ts

@@ -0,0 +1,16 @@
+export interface Described {
+    namespace: string;
+    component: string;
+    version?: string;
+    entity?: unknown;
+    operations?: unknown;
+    events?: unknown;
+    receivers?: unknown;
+    extensions?: unknown;
+}
+export interface Node extends Described {
+    id: string;
+}
+export interface Input {
+    nodes: Record<string, Described>;
+}

package/components/introspection.nodes/operations/lib/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/components/introspection.nodes/operations/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../source/lib/types.ts"],"names":[],"mappings":""}

package/components/introspection.nodes/operations/merge.d.ts

@@ -0,0 +1,9 @@
+import type { Input, Node } from './lib/types';
+/**
+ * Records the components described by a collector since its last flush.
+ *
+ * The scope is `objects`, so the caller passes every affected id in `query.ids`
+ * and the matching description under `nodes[id]`. Unknown nodes are initialized
+ * by the runtime, since the entity is `associated`.
+ */
+export declare function transition(input: Input, objects: Node[]): Node[];

package/components/introspection.nodes/operations/merge.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transition = void 0;
+/**
+ * Records the components described by a collector since its last flush.
+ *
+ * The scope is `objects`, so the caller passes every affected id in `query.ids`
+ * and the matching description under `nodes[id]`. Unknown nodes are initialized
+ * by the runtime, since the entity is `associated`.
+ */
+function transition(input, objects) {
+    for (const node of objects) {
+        const described = input.nodes[node.id];
+        if (described === undefined)
+            continue;
+        Object.assign(node, described);
+    }
+    return objects;
+}
+exports.transition = transition;
+//# sourceMappingURL=merge.js.map

package/components/introspection.nodes/operations/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../source/merge.ts"],"names":[],"mappings":";;;AAEA;;;;;;GAMG;AACH,SAAgB,UAAU,CAAE,KAAY,EAAE,OAAe;IACvD,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAEtC,IAAI,SAAS,KAAK,SAAS;YACzB,SAAQ;QAEV,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;IAChC,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC;AAXD,gCAWC"}

package/components/introspection.nodes/source/lib/types.ts

@@ -0,0 +1,18 @@
+export interface Described {
+  namespace: string
+  component: string
+  version?: string
+  entity?: unknown
+  operations?: unknown
+  events?: unknown
+  receivers?: unknown
+  extensions?: unknown
+}
+
+export interface Node extends Described {
+  id: string
+}
+
+export interface Input {
+  nodes: Record<string, Described>
+}

package/components/introspection.nodes/source/merge.ts

@@ -0,0 +1,21 @@
+import type { Input, Node } from './lib/types'
+
+/**
+ * Records the components described by a collector since its last flush.
+ *
+ * The scope is `objects`, so the caller passes every affected id in `query.ids`
+ * and the matching description under `nodes[id]`. Unknown nodes are initialized
+ * by the runtime, since the entity is `associated`.
+ */
+export function transition (input: Input, objects: Node[]): Node[] {
+  for (const node of objects) {
+    const described = input.nodes[node.id]
+
+    if (described === undefined)
+      continue
+
+    Object.assign(node, described)
+  }
+
+  return objects
+}

package/components/introspection.nodes/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./operations"
+  },
+  "include": [
+    "source"
+  ]
+}

package/cucumber.js

@@ -0,0 +1,8 @@
+module.exports = {
+  default: {
+    paths: ['features/**/*.feature'],
+    requireModule: ['ts-node/register'],
+    require: ['./features/**/*.ts'],
+    failFast: true
+  }
+}

package/features/calls.feature

@@ -0,0 +1,123 @@
+Feature: Call edges
+
+  An edge is recorded by the component being called. The caller only declares who
+  it is, on the request, so a caller that runs no collector of its own — a service,
+  the CLI — still appears on the map. A local call and a remote one are the same.
+
+  The origin is what tells a direct call apart from the delivery of an event. Which
+  events exist and who receives them is declared, so it is a node's business; an
+  edge is what actually happened.
+
+  Scenario: A remote call
+    When the `probe.source.relay` is called with:
+      """yaml
+      input:
+        a: 2
+        b: 3
+      """
+    Then the map contains an edge:
+      """yaml
+      src:
+        namespace: probe
+        component: source
+        operation: relay
+      dst:
+        namespace: probe
+        component: target
+        operation: compute
+      """
+
+  Scenario: A call caused by an event
+    When the `probe.source.transit` is called with:
+      """yaml
+      query:
+        id: c0ffee00c0ffee00c0ffee00c0ffee00
+      input:
+        value: 1
+      """
+    Then the map contains an edge:
+      """yaml
+      src:
+        namespace: probe
+        component: source
+        event: created
+      dst:
+        namespace: probe
+        component: target
+        operation: count
+      """
+
+  Scenario: A call from a service
+    When the `probe.target.compute` is called with:
+      """yaml
+      input:
+        a: 1
+        b: 1
+      source:
+        service: cli
+      """
+    Then the map contains an edge:
+      """yaml
+      src:
+        service: cli
+      dst:
+        namespace: probe
+        component: target
+        operation: compute
+      """
+
+  Scenario: A call from an unidentified caller
+    When the `probe.target.compute` is called with:
+      """yaml
+      input:
+        a: 1
+        b: 1
+      """
+    Then the map contains an edge:
+      """yaml
+      src:
+        service: unknown
+      dst:
+        namespace: probe
+        component: target
+        operation: compute
+      """
+
+  Scenario: An operation returning an error is still an edge
+    When the `probe.source.fail` is called with:
+      """yaml
+      input: null
+      """
+    Then the map contains an edge:
+      """yaml
+      dst:
+        namespace: probe
+        component: source
+        operation: fail
+      """
+
+  Scenario: An operation throwing is still an edge
+    When the `probe.source.crash` is called with:
+      """yaml
+      input: null
+      """
+    Then the map contains an edge:
+      """yaml
+      dst:
+        namespace: probe
+        component: source
+        operation: crash
+      """
+
+  Scenario: An opted out component produces no edges
+    When the `probe.quiet.ping` is called with:
+      """yaml
+      input:
+        a: 1
+      """
+    Then the map contains no edge:
+      """yaml
+      dst:
+        namespace: probe
+        component: quiet
+      """

package/features/nodes.feature

@@ -0,0 +1,70 @@
+Feature: Component descriptions
+
+  The static half of the map: what each component is, taken from its manifest
+  when the composition starts. This is where the event graph lives — which events
+  a component publishes, and which event each of its receivers takes — since all
+  of it is declared, and none of it needs traffic to be true.
+
+  Scenario: Describing operations
+    Then the map contains a node:
+      """yaml
+      namespace: probe
+      component: target
+      operations:
+        - endpoint: compute
+          type: computation
+          scope: none
+          input:
+            type: object
+            properties:
+              a: { type: number }
+              b: { type: number }
+          output:
+            type: number
+      """
+
+  Scenario: Describing the entity
+    Then the map contains a node:
+      """yaml
+      namespace: probe
+      component: target
+      entity:
+        storage: "@toa.io/storages.null"
+        schema:
+          properties:
+            counted:
+              type: integer
+      """
+
+  Scenario: Describing events
+    Then the map contains a node:
+      """yaml
+      namespace: probe
+      component: source
+      events:
+        - label: created
+        - label: updated
+        - label: deleted
+        - label: sync
+      """
+
+  Scenario: Describing receivers
+    Then the map contains a node:
+      """yaml
+      namespace: probe
+      component: target
+      receivers:
+        - label: probe.source.created
+          source: probe.source
+          event: created
+          operation: count
+          conditioned: false
+          adaptive: false
+      """
+
+  Scenario: An opted out component is not described
+    Then the map contains no node:
+      """yaml
+      namespace: probe
+      component: quiet
+      """