@jam-overture/loom 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +743 -0
- package/dist/catalogue.d.ts +70 -0
- package/dist/catalogue.js +88 -0
- package/dist/cli/args.d.ts +17 -0
- package/dist/cli/args.js +83 -0
- package/dist/cli/filesystem.d.ts +15 -0
- package/dist/cli/filesystem.js +31 -0
- package/dist/cli/index.d.ts +12 -0
- package/dist/cli/index.js +12 -0
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.js +30 -0
- package/dist/cli/namespace.d.ts +40 -0
- package/dist/cli/namespace.js +40 -0
- package/dist/cli/plan.d.ts +84 -0
- package/dist/cli/plan.js +113 -0
- package/dist/cli/run.d.ts +17 -0
- package/dist/cli/run.js +75 -0
- package/dist/cli/templates.d.ts +43 -0
- package/dist/cli/templates.js +134 -0
- package/dist/closed-set.d.ts +34 -0
- package/dist/closed-set.js +34 -0
- package/dist/data/adapter.d.ts +123 -0
- package/dist/data/adapter.js +91 -0
- package/dist/data/binding.d.ts +48 -0
- package/dist/data/binding.js +39 -0
- package/dist/data/catalogue.d.ts +26 -0
- package/dist/data/catalogue.js +6 -0
- package/dist/data/index.d.ts +14 -0
- package/dist/data/index.js +14 -0
- package/dist/data/plan.d.ts +58 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +91 -0
- package/dist/data/resolution.js +96 -0
- package/dist/data/resolve.d.ts +46 -0
- package/dist/data/resolve.js +37 -0
- package/dist/data/source.d.ts +40 -0
- package/dist/data/source.js +45 -0
- package/dist/deadline.d.ts +57 -0
- package/dist/deadline.js +78 -0
- package/dist/frame/catalogue.d.ts +24 -0
- package/dist/frame/catalogue.js +5 -0
- package/dist/frame/index.d.ts +12 -0
- package/dist/frame/index.js +12 -0
- package/dist/frame/origin.d.ts +87 -0
- package/dist/frame/origin.js +114 -0
- package/dist/frame/resolution.d.ts +85 -0
- package/dist/frame/resolution.js +79 -0
- package/dist/grammar.d.ts +26 -0
- package/dist/grammar.js +28 -0
- package/dist/ids.d.ts +57 -0
- package/dist/ids.js +104 -0
- package/dist/index.d.ts +26 -0
- package/dist/index.js +26 -0
- package/dist/interactivity.d.ts +50 -0
- package/dist/interactivity.js +22 -0
- package/dist/interpretation/anthropic.d.ts +22 -0
- package/dist/interpretation/anthropic.js +76 -0
- package/dist/interpretation/client.d.ts +83 -0
- package/dist/interpretation/client.js +2 -0
- package/dist/interpretation/draft.d.ts +234 -0
- package/dist/interpretation/draft.js +84 -0
- package/dist/interpretation/index.d.ts +15 -0
- package/dist/interpretation/index.js +15 -0
- package/dist/interpretation/interpreter.d.ts +62 -0
- package/dist/interpretation/interpreter.js +151 -0
- package/dist/interpretation/materialize.d.ts +42 -0
- package/dist/interpretation/materialize.js +107 -0
- package/dist/interpretation/prompt.d.ts +229 -0
- package/dist/interpretation/prompt.js +285 -0
- package/dist/interpretation/render.d.ts +76 -0
- package/dist/interpretation/render.js +272 -0
- package/dist/interpretation/schema.d.ts +49 -0
- package/dist/interpretation/schema.js +131 -0
- package/dist/json.d.ts +35 -0
- package/dist/json.js +11 -0
- package/dist/paging.d.ts +60 -0
- package/dist/paging.js +49 -0
- package/dist/primitive-type.d.ts +32 -0
- package/dist/primitive-type.js +39 -0
- package/dist/render/addressing.d.ts +59 -0
- package/dist/render/addressing.js +60 -0
- package/dist/render/anchor.d.ts +105 -0
- package/dist/render/anchor.js +84 -0
- package/dist/render/behaviour-adjust.d.ts +62 -0
- package/dist/render/behaviour-adjust.js +78 -0
- package/dist/render/behaviour-copy.d.ts +53 -0
- package/dist/render/behaviour-copy.js +75 -0
- package/dist/render/behaviour-disclose.d.ts +74 -0
- package/dist/render/behaviour-disclose.js +77 -0
- package/dist/render/behaviour-present.d.ts +123 -0
- package/dist/render/behaviour-present.js +173 -0
- package/dist/render/behaviour.d.ts +243 -0
- package/dist/render/behaviour.js +284 -0
- package/dist/render/control.d.ts +81 -0
- package/dist/render/control.js +80 -0
- package/dist/render/decorative.d.ts +62 -0
- package/dist/render/decorative.js +2 -0
- package/dist/render/diagnostics.d.ts +260 -0
- package/dist/render/diagnostics.js +61 -0
- package/dist/render/disclosed.d.ts +37 -0
- package/dist/render/disclosed.js +37 -0
- package/dist/render/editable.d.ts +34 -0
- package/dist/render/editable.js +35 -0
- package/dist/render/frame.d.ts +42 -0
- package/dist/render/frame.js +31 -0
- package/dist/render/index.d.ts +35 -0
- package/dist/render/index.js +35 -0
- package/dist/render/inline-variables.d.ts +77 -0
- package/dist/render/inline-variables.js +220 -0
- package/dist/render/presented.d.ts +82 -0
- package/dist/render/presented.js +82 -0
- package/dist/render/primitive.d.ts +228 -0
- package/dist/render/primitive.js +36 -0
- package/dist/render/props.d.ts +48 -0
- package/dist/render/props.js +2 -0
- package/dist/render/reads.d.ts +73 -0
- package/dist/render/reads.js +45 -0
- package/dist/render/render.d.ts +164 -0
- package/dist/render/render.js +571 -0
- package/dist/render/request.d.ts +111 -0
- package/dist/render/request.js +60 -0
- package/dist/render/text.d.ts +91 -0
- package/dist/render/text.js +44 -0
- package/dist/render/theme.d.ts +61 -0
- package/dist/render/theme.js +52 -0
- package/dist/reserved-props.d.ts +35 -0
- package/dist/reserved-props.js +45 -0
- package/dist/result.d.ts +27 -0
- package/dist/result.js +30 -0
- package/dist/role.d.ts +71 -0
- package/dist/role.js +22 -0
- package/dist/runtime/analysis.d.ts +149 -0
- package/dist/runtime/analysis.js +187 -0
- package/dist/runtime/assessment.d.ts +35 -0
- package/dist/runtime/assessment.js +13 -0
- package/dist/runtime/disposition.d.ts +102 -0
- package/dist/runtime/disposition.js +59 -0
- package/dist/runtime/events.d.ts +187 -0
- package/dist/runtime/events.js +7 -0
- package/dist/runtime/gate.d.ts +43 -0
- package/dist/runtime/gate.js +169 -0
- package/dist/runtime/index.d.ts +27 -0
- package/dist/runtime/index.js +27 -0
- package/dist/runtime/intent.d.ts +60 -0
- package/dist/runtime/intent.js +36 -0
- package/dist/runtime/interpreter.d.ts +117 -0
- package/dist/runtime/interpreter.js +46 -0
- package/dist/runtime/inverse-interpreter.d.ts +90 -0
- package/dist/runtime/inverse-interpreter.js +56 -0
- package/dist/runtime/inverse.d.ts +87 -0
- package/dist/runtime/inverse.js +48 -0
- package/dist/runtime/narration.d.ts +24 -0
- package/dist/runtime/narration.js +36 -0
- package/dist/runtime/nesting.d.ts +31 -0
- package/dist/runtime/nesting.js +46 -0
- package/dist/runtime/pipeline.d.ts +124 -0
- package/dist/runtime/pipeline.js +178 -0
- package/dist/runtime/policy-fingerprint.d.ts +29 -0
- package/dist/runtime/policy-fingerprint.js +119 -0
- package/dist/runtime/policy-source.d.ts +42 -0
- package/dist/runtime/policy-source.js +8 -0
- package/dist/runtime/policy.d.ts +156 -0
- package/dist/runtime/policy.js +107 -0
- package/dist/runtime/proposal.d.ts +423 -0
- package/dist/runtime/proposal.js +109 -0
- package/dist/runtime/redirection.d.ts +53 -0
- package/dist/runtime/redirection.js +38 -0
- package/dist/runtime/repointing.d.ts +71 -0
- package/dist/runtime/repointing.js +0 -0
- package/dist/runtime/reversibility.d.ts +36 -0
- package/dist/runtime/reversibility.js +39 -0
- package/dist/runtime/stake-level.d.ts +33 -0
- package/dist/runtime/stake-level.js +58 -0
- package/dist/runtime/stakes.d.ts +47 -0
- package/dist/runtime/stakes.js +305 -0
- package/dist/runtime/vocabulary.d.ts +122 -0
- package/dist/runtime/vocabulary.js +87 -0
- package/dist/sdk/audit.d.ts +195 -0
- package/dist/sdk/audit.js +128 -0
- package/dist/sdk/catalogue.d.ts +37 -0
- package/dist/sdk/catalogue.js +16 -0
- package/dist/sdk/conformance.d.ts +342 -0
- package/dist/sdk/conformance.js +494 -0
- package/dist/sdk/copy.d.ts +105 -0
- package/dist/sdk/copy.js +90 -0
- package/dist/sdk/definition.d.ts +242 -0
- package/dist/sdk/definition.js +64 -0
- package/dist/sdk/index.d.ts +19 -0
- package/dist/sdk/index.js +19 -0
- package/dist/sdk/interactivity.d.ts +29 -0
- package/dist/sdk/interactivity.js +34 -0
- package/dist/sdk/pairings.d.ts +124 -0
- package/dist/sdk/pairings.js +81 -0
- package/dist/sdk/registry.d.ts +162 -0
- package/dist/sdk/registry.js +329 -0
- package/dist/sdk/selection.d.ts +46 -0
- package/dist/sdk/selection.js +24 -0
- package/dist/sdk/text.d.ts +100 -0
- package/dist/sdk/text.js +105 -0
- package/dist/sdk/vocabulary.d.ts +39 -0
- package/dist/sdk/vocabulary.js +36 -0
- package/dist/signals/broadcast.d.ts +134 -0
- package/dist/signals/broadcast.js +451 -0
- package/dist/signals/collect.d.ts +184 -0
- package/dist/signals/collect.js +196 -0
- package/dist/signals/deliver.d.ts +64 -0
- package/dist/signals/deliver.js +85 -0
- package/dist/signals/fold.d.ts +112 -0
- package/dist/signals/fold.js +76 -0
- package/dist/signals/index.d.ts +31 -0
- package/dist/signals/index.js +31 -0
- package/dist/signals/ingest.d.ts +51 -0
- package/dist/signals/ingest.js +70 -0
- package/dist/signals/intake.d.ts +149 -0
- package/dist/signals/intake.js +154 -0
- package/dist/signals/journal.d.ts +94 -0
- package/dist/signals/journal.js +11 -0
- package/dist/signals/kinds.d.ts +22 -0
- package/dist/signals/kinds.js +22 -0
- package/dist/signals/ledger.d.ts +46 -0
- package/dist/signals/ledger.js +81 -0
- package/dist/signals/memory.d.ts +17 -0
- package/dist/signals/memory.js +99 -0
- package/dist/signals/migrate.d.ts +27 -0
- package/dist/signals/migrate.js +78 -0
- package/dist/signals/postgres.d.ts +7 -0
- package/dist/signals/postgres.js +295 -0
- package/dist/signals/rollup.d.ts +142 -0
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +534 -0
- package/dist/signals/schema.js +92 -0
- package/dist/signals/signal.d.ts +381 -0
- package/dist/signals/signal.js +150 -0
- package/dist/signals/tally.d.ts +70 -0
- package/dist/signals/tally.js +2 -0
- package/dist/signals/view.d.ts +51 -0
- package/dist/signals/view.js +54 -0
- package/dist/store/attribution.d.ts +125 -0
- package/dist/store/attribution.js +116 -0
- package/dist/store/database.d.ts +14 -0
- package/dist/store/database.js +2 -0
- package/dist/store/driver.d.ts +29 -0
- package/dist/store/driver.js +39 -0
- package/dist/store/errors.d.ts +56 -0
- package/dist/store/errors.js +37 -0
- package/dist/store/index.d.ts +16 -0
- package/dist/store/index.js +16 -0
- package/dist/store/memory.d.ts +3 -0
- package/dist/store/memory.js +115 -0
- package/dist/store/migrate.d.ts +54 -0
- package/dist/store/migrate.js +122 -0
- package/dist/store/postgres-holds.d.ts +4 -0
- package/dist/store/postgres-holds.js +192 -0
- package/dist/store/postgres.d.ts +8 -0
- package/dist/store/postgres.js +262 -0
- package/dist/store/replay.d.ts +94 -0
- package/dist/store/replay.js +82 -0
- package/dist/store/revert.d.ts +116 -0
- package/dist/store/revert.js +243 -0
- package/dist/store/schema.d.ts +371 -0
- package/dist/store/schema.js +78 -0
- package/dist/store/source.d.ts +23 -0
- package/dist/store/source.js +37 -0
- package/dist/store/store.d.ts +231 -0
- package/dist/store/store.js +52 -0
- package/dist/store/undone.d.ts +18 -0
- package/dist/store/undone.js +89 -0
- package/dist/submit/catalogue.d.ts +20 -0
- package/dist/submit/catalogue.js +5 -0
- package/dist/submit/declaration.d.ts +39 -0
- package/dist/submit/declaration.js +30 -0
- package/dist/submit/endpoint.d.ts +131 -0
- package/dist/submit/endpoint.js +160 -0
- package/dist/submit/index.d.ts +13 -0
- package/dist/submit/index.js +13 -0
- package/dist/submit/plan.d.ts +49 -0
- package/dist/submit/plan.js +47 -0
- package/dist/submit/resolution.d.ts +61 -0
- package/dist/submit/resolution.js +64 -0
- package/dist/submit/resolve.d.ts +45 -0
- package/dist/submit/resolve.js +36 -0
- package/dist/telemetry/calibration.d.ts +132 -0
- package/dist/telemetry/calibration.js +151 -0
- package/dist/telemetry/episode.d.ts +140 -0
- package/dist/telemetry/episode.js +272 -0
- package/dist/telemetry/event.d.ts +2310 -0
- package/dist/telemetry/event.js +405 -0
- package/dist/telemetry/index.d.ts +15 -0
- package/dist/telemetry/index.js +15 -0
- package/dist/telemetry/journal.d.ts +116 -0
- package/dist/telemetry/journal.js +11 -0
- package/dist/telemetry/memory.d.ts +24 -0
- package/dist/telemetry/memory.js +75 -0
- package/dist/telemetry/migrate.d.ts +26 -0
- package/dist/telemetry/migrate.js +40 -0
- package/dist/telemetry/postgres.d.ts +6 -0
- package/dist/telemetry/postgres.js +139 -0
- package/dist/telemetry/retention.d.ts +131 -0
- package/dist/telemetry/retention.js +217 -0
- package/dist/telemetry/schema.d.ts +113 -0
- package/dist/telemetry/schema.js +33 -0
- package/dist/telemetry/sink.d.ts +42 -0
- package/dist/telemetry/sink.js +61 -0
- package/dist/testing/contracts.d.ts +34 -0
- package/dist/testing/contracts.js +34 -0
- package/dist/testing/definitions.d.ts +15 -0
- package/dist/testing/definitions.js +48 -0
- package/dist/testing/doubles.d.ts +94 -0
- package/dist/testing/doubles.js +141 -0
- package/dist/testing/episode-harness.d.ts +49 -0
- package/dist/testing/episode-harness.js +65 -0
- package/dist/testing/filesystem.d.ts +17 -0
- package/dist/testing/filesystem.js +17 -0
- package/dist/testing/fixtures.d.ts +57 -0
- package/dist/testing/fixtures.js +84 -0
- package/dist/testing/hold-contract.d.ts +19 -0
- package/dist/testing/hold-contract.js +374 -0
- package/dist/testing/index.d.ts +41 -0
- package/dist/testing/index.js +41 -0
- package/dist/testing/journal-contract.d.ts +17 -0
- package/dist/testing/journal-contract.js +353 -0
- package/dist/testing/model-replies.d.ts +34 -0
- package/dist/testing/model-replies.js +101 -0
- package/dist/testing/primitives.d.ts +7 -0
- package/dist/testing/primitives.js +29 -0
- package/dist/testing/reader-signal-contract.d.ts +38 -0
- package/dist/testing/reader-signal-contract.js +318 -0
- package/dist/testing/row-security.d.ts +17 -0
- package/dist/testing/row-security.js +21 -0
- package/dist/testing/store-contract.d.ts +25 -0
- package/dist/testing/store-contract.js +500 -0
- package/dist/theme/apply.d.ts +17 -0
- package/dist/theme/apply.js +60 -0
- package/dist/theme/contrast.d.ts +197 -0
- package/dist/theme/contrast.js +259 -0
- package/dist/theme/derive.d.ts +77 -0
- package/dist/theme/derive.js +167 -0
- package/dist/theme/faces.d.ts +73 -0
- package/dist/theme/faces.js +119 -0
- package/dist/theme/font-packs.d.ts +25 -0
- package/dist/theme/font-packs.js +257 -0
- package/dist/theme/index.d.ts +20 -0
- package/dist/theme/index.js +20 -0
- package/dist/theme/lab.d.ts +30 -0
- package/dist/theme/lab.js +46 -0
- package/dist/theme/library.d.ts +114 -0
- package/dist/theme/library.js +300 -0
- package/dist/theme/measure.d.ts +144 -0
- package/dist/theme/measure.js +145 -0
- package/dist/theme/palettes.d.ts +64 -0
- package/dist/theme/palettes.js +497 -0
- package/dist/theme/registry.d.ts +59 -0
- package/dist/theme/registry.js +60 -0
- package/dist/theme/separation.d.ts +177 -0
- package/dist/theme/separation.js +203 -0
- package/dist/theme/style-presets.d.ts +60 -0
- package/dist/theme/style-presets.js +124 -0
- package/dist/theme/theme.d.ts +253 -0
- package/dist/theme/theme.js +171 -0
- package/dist/tree/apply.d.ts +16 -0
- package/dist/tree/apply.js +104 -0
- package/dist/tree/builders.d.ts +19 -0
- package/dist/tree/builders.js +20 -0
- package/dist/tree/compare.d.ts +68 -0
- package/dist/tree/compare.js +75 -0
- package/dist/tree/configuration.d.ts +25 -0
- package/dist/tree/configuration.js +108 -0
- package/dist/tree/delta.d.ts +288 -0
- package/dist/tree/delta.js +88 -0
- package/dist/tree/errors.d.ts +69 -0
- package/dist/tree/errors.js +34 -0
- package/dist/tree/identity.d.ts +117 -0
- package/dist/tree/identity.js +145 -0
- package/dist/tree/index.d.ts +21 -0
- package/dist/tree/index.js +21 -0
- package/dist/tree/inverse.d.ts +24 -0
- package/dist/tree/inverse.js +112 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +49 -0
- package/dist/tree/naming.d.ts +4 -0
- package/dist/tree/naming.js +35 -0
- package/dist/tree/navigation.d.ts +38 -0
- package/dist/tree/navigation.js +83 -0
- package/dist/tree/node.d.ts +103 -0
- package/dist/tree/node.js +46 -0
- package/dist/tree/outline.d.ts +28 -0
- package/dist/tree/outline.js +10 -0
- package/dist/tree/tree.d.ts +83 -0
- package/dist/tree/tree.js +62 -0
- package/dist/write/commit.d.ts +124 -0
- package/dist/write/commit.js +234 -0
- package/dist/write/held.d.ts +674 -0
- package/dist/write/held.js +185 -0
- package/dist/write/index.d.ts +11 -0
- package/dist/write/index.js +11 -0
- package/dist/write/liveness.d.ts +132 -0
- package/dist/write/liveness.js +91 -0
- package/dist/write/revert.d.ts +79 -0
- package/dist/write/revert.js +134 -0
- package/package.json +160 -0
|
@@ -0,0 +1,405 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { intentIdSchema, nodeIdSchema, proposalIdSchema, treeIdSchema, } from "../ids.js";
|
|
3
|
+
import { primitiveTypeSchema } from "../primitive-type.js";
|
|
4
|
+
import { assertNever } from "../result.js";
|
|
5
|
+
import { dispositionReasonSchema, dispositionSchema, } from "../runtime/disposition.js";
|
|
6
|
+
import { intentOriginSchema } from "../runtime/intent.js";
|
|
7
|
+
import { policyFingerprintOf } from "../runtime/policy-fingerprint.js";
|
|
8
|
+
import { proposedChangeSchema } from "../runtime/proposal.js";
|
|
9
|
+
import { stakeLevelSchema } from "../runtime/stake-level.js";
|
|
10
|
+
import { describeStoreError } from "../store/errors.js";
|
|
11
|
+
import { describeTreeError } from "../tree/errors.js";
|
|
12
|
+
/**
|
|
13
|
+
* What §6 keeps, and what it deliberately does not.
|
|
14
|
+
*
|
|
15
|
+
* A `RuntimeEvent` is the runtime talking to itself in a single process: it
|
|
16
|
+
* carries whole assessments and whole inverse deltas because the next stage
|
|
17
|
+
* needs them. A telemetry record is what survives the request, so it is a
|
|
18
|
+
* narrowing of that stream rather than a copy of it (0023). Three rules decide
|
|
19
|
+
* what crosses:
|
|
20
|
+
*
|
|
21
|
+
* - **The delta of a proposal is kept.** For a change that was refused, held and
|
|
22
|
+
* discarded, or never applied, this journal is the only record it ever
|
|
23
|
+
* existed — the revision log by construction holds only what was applied.
|
|
24
|
+
* - **Anything the log already holds is dropped.** An applied change's inverse
|
|
25
|
+
* is in the log with its provenance, and storing it twice invites two stores
|
|
26
|
+
* to disagree about the same delta.
|
|
27
|
+
* - **The utterance is not kept.** Telemetry is retained and aggregated; what
|
|
28
|
+
* someone typed is content, and provenance's `promptHash` already exists for
|
|
29
|
+
* hosts that want to group identical asks without keeping their text.
|
|
30
|
+
*
|
|
31
|
+
* The event names mirror `RuntimeEvent` one for one. A stage the runtime
|
|
32
|
+
* narrates but telemetry silently discarded would be a stage nobody could prove
|
|
33
|
+
* ran, so narrowing changes payloads and never membership.
|
|
34
|
+
*
|
|
35
|
+
* A field added after records exist is **optional and never defaulted** (0045).
|
|
36
|
+
* A record written before a field existed did not decline to say it — it could
|
|
37
|
+
* not, and a default would put a number in its mouth.
|
|
38
|
+
*/
|
|
39
|
+
/**
|
|
40
|
+
* A failure, as telemetry stores it: the code, and a sentence the runtime wrote
|
|
41
|
+
* about it. `code` is an open string rather than a mirror of §1/§2/§5's error
|
|
42
|
+
* taxonomies on purpose — adding an error code somewhere else in the codebase
|
|
43
|
+
* must not make records written yesterday fail to parse today.
|
|
44
|
+
*/
|
|
45
|
+
export const telemetryFailureSchema = z.object({
|
|
46
|
+
code: z.string().min(1),
|
|
47
|
+
detail: z.string().min(1),
|
|
48
|
+
});
|
|
49
|
+
/**
|
|
50
|
+
* The intent, minus what was said. Origin, scope and the revision it was aimed
|
|
51
|
+
* at are what an analysis needs; `utteranceLength` keeps "a one-word ask" and
|
|
52
|
+
* "three paragraphs" distinguishable without storing either.
|
|
53
|
+
*
|
|
54
|
+
* `actor` is kept for the same reason `origin` is: it is an identifier a query
|
|
55
|
+
* groups by, not content someone typed. The rule 0023 set is about the
|
|
56
|
+
* utterance, and an identity is on the other side of it.
|
|
57
|
+
*/
|
|
58
|
+
export const intentSummarySchema = z.object({
|
|
59
|
+
intentId: intentIdSchema,
|
|
60
|
+
origin: intentOriginSchema,
|
|
61
|
+
actor: z.string().min(1).optional(),
|
|
62
|
+
baseRevision: z.number().int().nonnegative(),
|
|
63
|
+
scopeNodeId: nodeIdSchema.optional(),
|
|
64
|
+
utteranceLength: z.number().int().nonnegative(),
|
|
65
|
+
observedAt: z.string().datetime(),
|
|
66
|
+
});
|
|
67
|
+
/**
|
|
68
|
+
* What the Gate was looking at, in the shape a query can group by. The
|
|
69
|
+
* disposition that follows says stakes, reversibility and confidence; this says
|
|
70
|
+
* how big the change was and what it touched, which is what makes "the Gate
|
|
71
|
+
* refuses this class of change" measurable rather than anecdotal.
|
|
72
|
+
*/
|
|
73
|
+
export const assessmentSummarySchema = z.object({
|
|
74
|
+
proposalId: proposalIdSchema,
|
|
75
|
+
stakes: stakeLevelSchema,
|
|
76
|
+
reversible: z.boolean(),
|
|
77
|
+
operationCount: z.number().int().nonnegative(),
|
|
78
|
+
insertedNodeCount: z.number().int().nonnegative(),
|
|
79
|
+
removedNodeCount: z.number().int().nonnegative(),
|
|
80
|
+
movedNodeCount: z.number().int().nonnegative(),
|
|
81
|
+
configuredNodeCount: z.number().int().nonnegative(),
|
|
82
|
+
touchedPrimitiveTypes: z.array(primitiveTypeSchema),
|
|
83
|
+
/**
|
|
84
|
+
* Bounded, non-identifying, a subset of the touched types, and the input to
|
|
85
|
+
* the only `critical` stake factor. A corpus that cannot group by "the Gate
|
|
86
|
+
* saw this type destroyed" cannot ask the question the factor exists for.
|
|
87
|
+
*/
|
|
88
|
+
removedPrimitiveTypes: z.array(primitiveTypeSchema).optional(),
|
|
89
|
+
relocatedPrimitiveTypes: z.array(primitiveTypeSchema).optional(),
|
|
90
|
+
relocatedNodeCount: z.number().int().nonnegative().optional(),
|
|
91
|
+
shallowestAffectedDepth: z.number().int().nonnegative(),
|
|
92
|
+
/** Nodes the inverse would have to carry — the content a removal destroyed. */
|
|
93
|
+
retainedNodeCount: z.number().int().nonnegative(),
|
|
94
|
+
irreversibilityReasons: z.array(z.string().min(1)),
|
|
95
|
+
});
|
|
96
|
+
export const telemetryEventSchema = z.discriminatedUnion("type", [
|
|
97
|
+
z.object({ type: z.literal("intent-received"), intent: intentSummarySchema }),
|
|
98
|
+
z.object({
|
|
99
|
+
type: z.literal("policy-resolved"),
|
|
100
|
+
intentId: intentIdSchema,
|
|
101
|
+
policyId: z.string().min(1),
|
|
102
|
+
policyFingerprint: z.string().min(1).optional(),
|
|
103
|
+
}),
|
|
104
|
+
z.object({
|
|
105
|
+
type: z.literal("interpretation-failed"),
|
|
106
|
+
intentId: intentIdSchema,
|
|
107
|
+
failure: telemetryFailureSchema,
|
|
108
|
+
}),
|
|
109
|
+
z.object({ type: z.literal("change-proposed"), proposal: proposedChangeSchema }),
|
|
110
|
+
z.object({
|
|
111
|
+
type: z.literal("assessment-failed"),
|
|
112
|
+
proposalId: proposalIdSchema,
|
|
113
|
+
failure: telemetryFailureSchema,
|
|
114
|
+
}),
|
|
115
|
+
z.object({ type: z.literal("change-assessed"), assessment: assessmentSummarySchema }),
|
|
116
|
+
z.object({
|
|
117
|
+
type: z.literal("disposition-decided"),
|
|
118
|
+
proposalId: proposalIdSchema,
|
|
119
|
+
disposition: dispositionSchema,
|
|
120
|
+
}),
|
|
121
|
+
z.object({
|
|
122
|
+
type: z.literal("repair-requested"),
|
|
123
|
+
refusedProposalId: proposalIdSchema,
|
|
124
|
+
reason: dispositionReasonSchema,
|
|
125
|
+
}),
|
|
126
|
+
z.object({
|
|
127
|
+
type: z.literal("repair-failed"),
|
|
128
|
+
refusedProposalId: proposalIdSchema,
|
|
129
|
+
failure: telemetryFailureSchema,
|
|
130
|
+
}),
|
|
131
|
+
z.object({
|
|
132
|
+
type: z.literal("change-applied"),
|
|
133
|
+
proposalId: proposalIdSchema,
|
|
134
|
+
revision: z.number().int().nonnegative(),
|
|
135
|
+
}),
|
|
136
|
+
z.object({
|
|
137
|
+
type: z.literal("application-failed"),
|
|
138
|
+
proposalId: proposalIdSchema,
|
|
139
|
+
failure: telemetryFailureSchema,
|
|
140
|
+
}),
|
|
141
|
+
z.object({
|
|
142
|
+
type: z.literal("intent-not-writable"),
|
|
143
|
+
intentId: intentIdSchema,
|
|
144
|
+
failure: telemetryFailureSchema,
|
|
145
|
+
}),
|
|
146
|
+
z.object({ type: z.literal("proposal-held"), proposalId: proposalIdSchema }),
|
|
147
|
+
z.object({
|
|
148
|
+
type: z.literal("hold-failed"),
|
|
149
|
+
proposalId: proposalIdSchema,
|
|
150
|
+
failure: telemetryFailureSchema,
|
|
151
|
+
}),
|
|
152
|
+
z.object({
|
|
153
|
+
type: z.literal("hold-confirmed"),
|
|
154
|
+
proposalId: proposalIdSchema,
|
|
155
|
+
actor: z.string().min(1).optional(),
|
|
156
|
+
}),
|
|
157
|
+
z.object({
|
|
158
|
+
type: z.literal("hold-discarded"),
|
|
159
|
+
proposalId: proposalIdSchema,
|
|
160
|
+
actor: z.string().min(1).optional(),
|
|
161
|
+
}),
|
|
162
|
+
z.object({
|
|
163
|
+
type: z.literal("change-committed"),
|
|
164
|
+
proposalId: proposalIdSchema,
|
|
165
|
+
revision: z.number().int().nonnegative(),
|
|
166
|
+
}),
|
|
167
|
+
z.object({
|
|
168
|
+
type: z.literal("commit-failed"),
|
|
169
|
+
proposalId: proposalIdSchema,
|
|
170
|
+
failure: telemetryFailureSchema,
|
|
171
|
+
}),
|
|
172
|
+
]);
|
|
173
|
+
/**
|
|
174
|
+
* Every event the journal can hold, in the order the runtime writes them.
|
|
175
|
+
*
|
|
176
|
+
* `TelemetryEvent` is exhaustive in a `switch` and that is the case it was built
|
|
177
|
+
* for. What it cannot answer is **how many**, and three things ask: a page that
|
|
178
|
+
* says what fraction of the vocabulary it is showing, a dashboard that needs
|
|
179
|
+
* every bucket to exist before the first request rather than discovering them as
|
|
180
|
+
* they arrive, and anything checking a sink against §6. Each of those otherwise
|
|
181
|
+
* keeps its own copy, in its own order, with nothing to fail when a nineteenth
|
|
182
|
+
* lands.
|
|
183
|
+
*
|
|
184
|
+
* The order is the lifecycle rather than the alphabet: an episode reads
|
|
185
|
+
* top to bottom, so a list printed in this order is a story and a list sorted by
|
|
186
|
+
* name is eighteen strings. `event.test.ts` holds it against
|
|
187
|
+
* `telemetryEventSchema`, which is what keeps it complete — the schema is the
|
|
188
|
+
* boundary a record has to cross, so a type the schema accepts and this omits is
|
|
189
|
+
* the drift worth failing over.
|
|
190
|
+
*/
|
|
191
|
+
export const TELEMETRY_EVENT_TYPES = [
|
|
192
|
+
"intent-received",
|
|
193
|
+
"policy-resolved",
|
|
194
|
+
"interpretation-failed",
|
|
195
|
+
"change-proposed",
|
|
196
|
+
"assessment-failed",
|
|
197
|
+
"change-assessed",
|
|
198
|
+
"disposition-decided",
|
|
199
|
+
"repair-requested",
|
|
200
|
+
"repair-failed",
|
|
201
|
+
"change-applied",
|
|
202
|
+
"application-failed",
|
|
203
|
+
"intent-not-writable",
|
|
204
|
+
"proposal-held",
|
|
205
|
+
"hold-failed",
|
|
206
|
+
"hold-confirmed",
|
|
207
|
+
"hold-discarded",
|
|
208
|
+
"change-committed",
|
|
209
|
+
"commit-failed",
|
|
210
|
+
];
|
|
211
|
+
export const telemetryRecordSchema = z.object({
|
|
212
|
+
treeId: treeIdSchema,
|
|
213
|
+
occurredAt: z.string().datetime(),
|
|
214
|
+
event: telemetryEventSchema,
|
|
215
|
+
});
|
|
216
|
+
const summariseIntent = (intent) => ({
|
|
217
|
+
intentId: intent.intentId,
|
|
218
|
+
origin: intent.origin,
|
|
219
|
+
...(intent.actor === undefined ? {} : { actor: intent.actor }),
|
|
220
|
+
baseRevision: intent.baseRevision,
|
|
221
|
+
...(intent.scopeNodeId ? { scopeNodeId: intent.scopeNodeId } : {}),
|
|
222
|
+
utteranceLength: intent.utterance.length,
|
|
223
|
+
observedAt: intent.observedAt,
|
|
224
|
+
});
|
|
225
|
+
const summariseAssessment = (assessment) => ({
|
|
226
|
+
proposalId: assessment.proposal.proposalId,
|
|
227
|
+
stakes: assessment.stakes.level,
|
|
228
|
+
reversible: assessment.reversibility.reversible,
|
|
229
|
+
operationCount: assessment.analysis.operationCount,
|
|
230
|
+
insertedNodeCount: assessment.analysis.insertedNodeCount,
|
|
231
|
+
removedNodeCount: assessment.analysis.removedNodeCount,
|
|
232
|
+
movedNodeCount: assessment.analysis.movedNodeCount,
|
|
233
|
+
configuredNodeCount: assessment.analysis.configuredNodeCount,
|
|
234
|
+
touchedPrimitiveTypes: assessment.analysis.touchedPrimitiveTypes,
|
|
235
|
+
removedPrimitiveTypes: assessment.analysis.removedPrimitiveTypes,
|
|
236
|
+
relocatedPrimitiveTypes: assessment.analysis.relocatedPrimitiveTypes,
|
|
237
|
+
relocatedNodeCount: assessment.analysis.relocatedNodeCount,
|
|
238
|
+
shallowestAffectedDepth: assessment.analysis.shallowestAffectedDepth,
|
|
239
|
+
retainedNodeCount: assessment.reversibility.retainedNodeCount,
|
|
240
|
+
irreversibilityReasons: assessment.reversibility.reasons.map((reason) => reason.code),
|
|
241
|
+
});
|
|
242
|
+
/**
|
|
243
|
+
* The narrowing, as one total function. Every variant is handled and the
|
|
244
|
+
* exhaustiveness guard is what makes adding a `RuntimeEvent` a compile error
|
|
245
|
+
* here rather than an event that silently never reaches the journal.
|
|
246
|
+
*/
|
|
247
|
+
const narrowEvent = (event) => {
|
|
248
|
+
switch (event.type) {
|
|
249
|
+
case "intent-received":
|
|
250
|
+
return { type: "intent-received", intent: summariseIntent(event.intent) };
|
|
251
|
+
/**
|
|
252
|
+
* The name crosses; the values do not. A policy is host configuration that
|
|
253
|
+
* changes rarely and is versioned where the host keeps it, so copying it
|
|
254
|
+
* onto every change would store one document a million times to answer a
|
|
255
|
+
* question the name already answers.
|
|
256
|
+
*
|
|
257
|
+
* The fingerprint is what makes that contract checkable rather than merely
|
|
258
|
+
* stated (0048). It is a digest, not the document: bounded, and it answers
|
|
259
|
+
* "did this name keep meaning one thing" without keeping a copy of the
|
|
260
|
+
* configuration on every change.
|
|
261
|
+
*/
|
|
262
|
+
case "policy-resolved":
|
|
263
|
+
return {
|
|
264
|
+
type: "policy-resolved",
|
|
265
|
+
intentId: event.intentId,
|
|
266
|
+
policyId: event.policy.policyId,
|
|
267
|
+
policyFingerprint: policyFingerprintOf(event.policy),
|
|
268
|
+
};
|
|
269
|
+
case "interpretation-failed":
|
|
270
|
+
return {
|
|
271
|
+
type: "interpretation-failed",
|
|
272
|
+
intentId: event.intent.intentId,
|
|
273
|
+
failure: { code: event.error.code, detail: event.error.detail },
|
|
274
|
+
};
|
|
275
|
+
case "change-proposed":
|
|
276
|
+
return { type: "change-proposed", proposal: event.proposal };
|
|
277
|
+
case "assessment-failed":
|
|
278
|
+
return {
|
|
279
|
+
type: "assessment-failed",
|
|
280
|
+
proposalId: event.proposal.proposalId,
|
|
281
|
+
failure: { code: event.error.code, detail: describeTreeError(event.error) },
|
|
282
|
+
};
|
|
283
|
+
case "change-assessed":
|
|
284
|
+
return { type: "change-assessed", assessment: summariseAssessment(event.assessment) };
|
|
285
|
+
case "disposition-decided":
|
|
286
|
+
return {
|
|
287
|
+
type: "disposition-decided",
|
|
288
|
+
proposalId: event.proposalId,
|
|
289
|
+
disposition: event.disposition,
|
|
290
|
+
};
|
|
291
|
+
case "repair-requested":
|
|
292
|
+
return {
|
|
293
|
+
type: "repair-requested",
|
|
294
|
+
refusedProposalId: event.refusedProposalId,
|
|
295
|
+
reason: event.reason,
|
|
296
|
+
};
|
|
297
|
+
case "repair-failed":
|
|
298
|
+
return {
|
|
299
|
+
type: "repair-failed",
|
|
300
|
+
refusedProposalId: event.refusedProposalId,
|
|
301
|
+
failure: { code: event.error.code, detail: event.error.detail },
|
|
302
|
+
};
|
|
303
|
+
/** The inverse is dropped: it is in the log, attached to the revision named here. */
|
|
304
|
+
case "change-applied":
|
|
305
|
+
return { type: "change-applied", proposalId: event.proposalId, revision: event.revision };
|
|
306
|
+
case "application-failed":
|
|
307
|
+
return {
|
|
308
|
+
type: "application-failed",
|
|
309
|
+
proposalId: event.proposalId,
|
|
310
|
+
failure: { code: event.error.code, detail: describeTreeError(event.error) },
|
|
311
|
+
};
|
|
312
|
+
case "intent-not-writable":
|
|
313
|
+
return {
|
|
314
|
+
type: "intent-not-writable",
|
|
315
|
+
intentId: event.intent.intentId,
|
|
316
|
+
failure: { code: event.error.code, detail: describeStoreError(event.error) },
|
|
317
|
+
};
|
|
318
|
+
case "proposal-held":
|
|
319
|
+
return { type: "proposal-held", proposalId: event.proposalId };
|
|
320
|
+
case "hold-failed":
|
|
321
|
+
return {
|
|
322
|
+
type: "hold-failed",
|
|
323
|
+
proposalId: event.proposalId,
|
|
324
|
+
failure: { code: "hold-failed", detail: event.detail },
|
|
325
|
+
};
|
|
326
|
+
case "hold-confirmed":
|
|
327
|
+
return {
|
|
328
|
+
type: "hold-confirmed",
|
|
329
|
+
proposalId: event.proposalId,
|
|
330
|
+
...(event.actor === undefined ? {} : { actor: event.actor }),
|
|
331
|
+
};
|
|
332
|
+
case "hold-discarded":
|
|
333
|
+
return {
|
|
334
|
+
type: "hold-discarded",
|
|
335
|
+
proposalId: event.proposalId,
|
|
336
|
+
...(event.actor === undefined ? {} : { actor: event.actor }),
|
|
337
|
+
};
|
|
338
|
+
case "change-committed":
|
|
339
|
+
return { type: "change-committed", proposalId: event.proposalId, revision: event.revision };
|
|
340
|
+
case "commit-failed":
|
|
341
|
+
return {
|
|
342
|
+
type: "commit-failed",
|
|
343
|
+
proposalId: event.proposalId,
|
|
344
|
+
failure: { code: event.error.code, detail: describeStoreError(event.error) },
|
|
345
|
+
};
|
|
346
|
+
default:
|
|
347
|
+
return assertNever(event, "narrowEvent");
|
|
348
|
+
}
|
|
349
|
+
};
|
|
350
|
+
export const recordOf = (envelope) => ({
|
|
351
|
+
treeId: envelope.treeId,
|
|
352
|
+
occurredAt: envelope.occurredAt,
|
|
353
|
+
event: narrowEvent(envelope.event),
|
|
354
|
+
});
|
|
355
|
+
/**
|
|
356
|
+
* The proposal an event is about, when it is about one. Used by the fold rather
|
|
357
|
+
* than stored as a column: a query that needs an index on it is a change with a
|
|
358
|
+
* reason behind it, and duplicating a field into a column is how two copies of
|
|
359
|
+
* the same fact start disagreeing.
|
|
360
|
+
*/
|
|
361
|
+
export const proposalIdOf = (event) => {
|
|
362
|
+
switch (event.type) {
|
|
363
|
+
case "change-proposed":
|
|
364
|
+
return event.proposal.proposalId;
|
|
365
|
+
case "change-assessed":
|
|
366
|
+
return event.assessment.proposalId;
|
|
367
|
+
case "repair-requested":
|
|
368
|
+
case "repair-failed":
|
|
369
|
+
return event.refusedProposalId;
|
|
370
|
+
case "assessment-failed":
|
|
371
|
+
case "disposition-decided":
|
|
372
|
+
case "change-applied":
|
|
373
|
+
case "application-failed":
|
|
374
|
+
case "proposal-held":
|
|
375
|
+
case "hold-failed":
|
|
376
|
+
case "hold-confirmed":
|
|
377
|
+
case "hold-discarded":
|
|
378
|
+
case "change-committed":
|
|
379
|
+
case "commit-failed":
|
|
380
|
+
return event.proposalId;
|
|
381
|
+
case "intent-received":
|
|
382
|
+
case "policy-resolved":
|
|
383
|
+
case "interpretation-failed":
|
|
384
|
+
case "intent-not-writable":
|
|
385
|
+
return undefined;
|
|
386
|
+
default:
|
|
387
|
+
return assertNever(event, "proposalIdOf");
|
|
388
|
+
}
|
|
389
|
+
};
|
|
390
|
+
/** The intent an event names directly. Everything else reaches one via its proposal. */
|
|
391
|
+
export const intentIdOf = (event) => {
|
|
392
|
+
switch (event.type) {
|
|
393
|
+
case "intent-received":
|
|
394
|
+
return event.intent.intentId;
|
|
395
|
+
case "policy-resolved":
|
|
396
|
+
case "interpretation-failed":
|
|
397
|
+
case "intent-not-writable":
|
|
398
|
+
return event.intentId;
|
|
399
|
+
case "change-proposed":
|
|
400
|
+
return event.proposal.intentId;
|
|
401
|
+
default:
|
|
402
|
+
return undefined;
|
|
403
|
+
}
|
|
404
|
+
};
|
|
405
|
+
//# sourceMappingURL=event.js.map
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The record of what the runtime did, and what it can be measured against.
|
|
3
|
+
*
|
|
4
|
+
* An append-only journal of narrated events, the fold that turns them back into
|
|
5
|
+
* episodes, and the calibration that compares what a model claimed against what
|
|
6
|
+
* became of the claim.
|
|
7
|
+
*/
|
|
8
|
+
export * from "./calibration.js";
|
|
9
|
+
export * from "./episode.js";
|
|
10
|
+
export * from "./event.js";
|
|
11
|
+
export * from "./journal.js";
|
|
12
|
+
export * from "./memory.js";
|
|
13
|
+
export * from "./retention.js";
|
|
14
|
+
export * from "./sink.js";
|
|
15
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The record of what the runtime did, and what it can be measured against.
|
|
3
|
+
*
|
|
4
|
+
* An append-only journal of narrated events, the fold that turns them back into
|
|
5
|
+
* episodes, and the calibration that compares what a model claimed against what
|
|
6
|
+
* became of the claim.
|
|
7
|
+
*/
|
|
8
|
+
export * from "./calibration.js";
|
|
9
|
+
export * from "./episode.js";
|
|
10
|
+
export * from "./event.js";
|
|
11
|
+
export * from "./journal.js";
|
|
12
|
+
export * from "./memory.js";
|
|
13
|
+
export * from "./retention.js";
|
|
14
|
+
export * from "./sink.js";
|
|
15
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
import type { TreeId } from "../ids.js";
|
|
2
|
+
import { type PageDirection, type PageEnds } from "../paging.js";
|
|
3
|
+
import type { Result } from "../result.js";
|
|
4
|
+
import type { TelemetryRecord } from "./event.js";
|
|
5
|
+
/**
|
|
6
|
+
* Where the narrated runtime goes to be read later.
|
|
7
|
+
*
|
|
8
|
+
* A journal is append-only and answers questions in the order things arrived.
|
|
9
|
+
* It is not the truth about any tree — 0016 already settled that the revision
|
|
10
|
+
* log is — and nothing downstream may reconstruct a tree from it. It is the
|
|
11
|
+
* record of what was proposed, what the Gate decided, and what became of it,
|
|
12
|
+
* including all the changes that never reached the log because they were
|
|
13
|
+
* refused, held, or discarded.
|
|
14
|
+
*/
|
|
15
|
+
/**
|
|
16
|
+
* The only way a journal fails. There is no `not-found`: reading a tree nothing
|
|
17
|
+
* has been recorded about is an empty page, not an error, because a journal
|
|
18
|
+
* makes no claim that a tree exists. There is no conflict either — appending an
|
|
19
|
+
* observation cannot collide with another observation.
|
|
20
|
+
*/
|
|
21
|
+
export type TelemetryError = {
|
|
22
|
+
readonly code: "unavailable";
|
|
23
|
+
readonly detail: string;
|
|
24
|
+
};
|
|
25
|
+
export declare const describeTelemetryError: (error: TelemetryError) => string;
|
|
26
|
+
/**
|
|
27
|
+
* A record as it comes back out, with the position the journal gave it.
|
|
28
|
+
*
|
|
29
|
+
* `seq` orders records by *arrival*, not by `occurredAt`. Those differ, and the
|
|
30
|
+
* arrival order is the one worth exposing: clocks on two serverless instances
|
|
31
|
+
* disagree by more than the gap between two events in the same request, so a
|
|
32
|
+
* cursor built on a timestamp would skip or repeat rows. `seq` is opaque —
|
|
33
|
+
* increasing, but not a count, not dense, and not comparable across journals.
|
|
34
|
+
*/
|
|
35
|
+
export type RecordedTelemetry = TelemetryRecord & {
|
|
36
|
+
readonly seq: number;
|
|
37
|
+
/**
|
|
38
|
+
* When the journal learned of the record, which is not `occurredAt`.
|
|
39
|
+
*
|
|
40
|
+
* Both are here because they answer different questions and only one of them
|
|
41
|
+
* the journal can vouch for. `occurredAt` is what the host said, and a host
|
|
42
|
+
* that sets it wrongly — a skewed serverless clock, a replayed batch — is
|
|
43
|
+
* describing its own timeline. `recordedAt` is stamped on arrival, so it is
|
|
44
|
+
* the only timestamp retention may be measured against: an age a writer can
|
|
45
|
+
* choose is an age a writer can dodge.
|
|
46
|
+
*/
|
|
47
|
+
readonly recordedAt: string;
|
|
48
|
+
};
|
|
49
|
+
export type TelemetryReadRequest = {
|
|
50
|
+
/** Absent reads every tree the handle can see, which is the scope rule (0020). */
|
|
51
|
+
readonly treeId?: TreeId;
|
|
52
|
+
/** A cursor from a previous page's `older`/`newer`, passed back unread. */
|
|
53
|
+
readonly cursor?: string;
|
|
54
|
+
/**
|
|
55
|
+
* Default `newer`, which with no cursor is the oldest page. `older` with no
|
|
56
|
+
* cursor is the newest page — the read a reader almost always wants first.
|
|
57
|
+
*/
|
|
58
|
+
readonly direction?: PageDirection;
|
|
59
|
+
readonly limit?: number;
|
|
60
|
+
};
|
|
61
|
+
export type TelemetryPage = PageEnds & {
|
|
62
|
+
/**
|
|
63
|
+
* Always ascending by `seq`, whichever end the page was taken from.
|
|
64
|
+
*
|
|
65
|
+
* The direction is a property of *which* records a page contains, never of
|
|
66
|
+
* the order they arrive in. `episodesOf` folds a stream in arrival order, and
|
|
67
|
+
* a page that sometimes came back reversed would make every consumer
|
|
68
|
+
* responsible for knowing which — and silently wrong when it guessed.
|
|
69
|
+
*/
|
|
70
|
+
readonly records: readonly RecordedTelemetry[];
|
|
71
|
+
};
|
|
72
|
+
/**
|
|
73
|
+
* Larger than a tree listing's, because these are read to be folded rather than
|
|
74
|
+
* shown: an episode spans a dozen or so records, so a page of 200 is a handful
|
|
75
|
+
* of episodes and a page of 50 would routinely split one across a boundary.
|
|
76
|
+
*/
|
|
77
|
+
export declare const DEFAULT_TELEMETRY_LIMIT = 200;
|
|
78
|
+
export declare const MAX_TELEMETRY_LIMIT = 1000;
|
|
79
|
+
export declare const clampTelemetryLimit: (limit: number | undefined) => number;
|
|
80
|
+
/**
|
|
81
|
+
* What a journal is asked to forget, expressed as a position rather than a rule.
|
|
82
|
+
*
|
|
83
|
+
* Every record below `before` goes; nothing else is touched. A journal is not
|
|
84
|
+
* told about ages, policies, or episodes — deciding *what* may be forgotten is
|
|
85
|
+
* `retention.ts`'s job, and it makes that decision by reading the journal
|
|
86
|
+
* through the same paged contract everyone else uses. This half only knows how
|
|
87
|
+
* to drop a prefix, which is why both implementations of it fit in four lines
|
|
88
|
+
* and cannot disagree about anything more interesting than that.
|
|
89
|
+
*/
|
|
90
|
+
export type ForgetRequest = {
|
|
91
|
+
readonly before: number;
|
|
92
|
+
};
|
|
93
|
+
export type ForgetOutcome = {
|
|
94
|
+
readonly removed: number;
|
|
95
|
+
};
|
|
96
|
+
/**
|
|
97
|
+
* Three operations, and the asymmetry is deliberate: writes arrive in batches
|
|
98
|
+
* because a request narrates several stages and should pay for one round trip
|
|
99
|
+
* (0024), while reads are paged because a journal only grows.
|
|
100
|
+
*
|
|
101
|
+
* `record` takes a batch rather than a single record so that an implementation
|
|
102
|
+
* can make the batch atomic. Half a request's narration is worse than none of
|
|
103
|
+
* it: an episode missing its disposition reads as a change that was proposed
|
|
104
|
+
* and never judged, which is a fault report rather than a gap.
|
|
105
|
+
*
|
|
106
|
+
* `forget` is the only destructive operation anywhere in Loom's storage, and it
|
|
107
|
+
* is on the journal rather than the store for the reason 0016 gives: telemetry
|
|
108
|
+
* is narrowed from a log that keeps the truth, so forgetting it loses history
|
|
109
|
+
* and never loses a tree.
|
|
110
|
+
*/
|
|
111
|
+
export interface TelemetryJournal {
|
|
112
|
+
readonly record: (records: readonly TelemetryRecord[]) => Promise<Result<void, TelemetryError>>;
|
|
113
|
+
readonly read: (request?: TelemetryReadRequest) => Promise<Result<TelemetryPage, TelemetryError>>;
|
|
114
|
+
readonly forget: (request: ForgetRequest) => Promise<Result<ForgetOutcome, TelemetryError>>;
|
|
115
|
+
}
|
|
116
|
+
//# sourceMappingURL=journal.d.ts.map
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { clampLimit } from "../paging.js";
|
|
2
|
+
export const describeTelemetryError = (error) => `telemetry is unavailable: ${error.detail}`;
|
|
3
|
+
/**
|
|
4
|
+
* Larger than a tree listing's, because these are read to be folded rather than
|
|
5
|
+
* shown: an episode spans a dozen or so records, so a page of 200 is a handful
|
|
6
|
+
* of episodes and a page of 50 would routinely split one across a boundary.
|
|
7
|
+
*/
|
|
8
|
+
export const DEFAULT_TELEMETRY_LIMIT = 200;
|
|
9
|
+
export const MAX_TELEMETRY_LIMIT = 1000;
|
|
10
|
+
export const clampTelemetryLimit = (limit) => clampLimit(limit, { fallback: DEFAULT_TELEMETRY_LIMIT, max: MAX_TELEMETRY_LIMIT });
|
|
11
|
+
//# sourceMappingURL=journal.js.map
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { type Clock } from "../runtime/events.js";
|
|
2
|
+
import { type TelemetryJournal } from "./journal.js";
|
|
3
|
+
/**
|
|
4
|
+
* The telemetry journal that keeps its records in the process.
|
|
5
|
+
*
|
|
6
|
+
* It is the implementation the contract is written against, so what it does is
|
|
7
|
+
* what a journal is expected to do.
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* A journal in memory: the reference implementation of the contract, and the
|
|
11
|
+
* one `pnpm dev` runs on.
|
|
12
|
+
*
|
|
13
|
+
* Like the memory store, it is not a test double. The ordering it promises —
|
|
14
|
+
* arrival order, stable across reads, paged by an opaque cursor — is what a SQL
|
|
15
|
+
* implementation is checked against, and `journal-contract.ts` runs the same
|
|
16
|
+
* suite over both so a disagreement is a test failure rather than a surprise in
|
|
17
|
+
* production.
|
|
18
|
+
*
|
|
19
|
+
* The clock is a parameter for the same reason it is one everywhere else: a
|
|
20
|
+
* `recordedAt` this journal read off the wall clock would make every retention
|
|
21
|
+
* test a race against real time.
|
|
22
|
+
*/
|
|
23
|
+
export declare const memoryTelemetryJournal: (clock?: Clock) => TelemetryJournal;
|
|
24
|
+
//# sourceMappingURL=memory.d.ts.map
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import { cursorPosition, pageEnds } from "../paging.js";
|
|
2
|
+
import { ok } from "../result.js";
|
|
3
|
+
import { systemClock } from "../runtime/events.js";
|
|
4
|
+
import { clampTelemetryLimit, } from "./journal.js";
|
|
5
|
+
/**
|
|
6
|
+
* The telemetry journal that keeps its records in the process.
|
|
7
|
+
*
|
|
8
|
+
* It is the implementation the contract is written against, so what it does is
|
|
9
|
+
* what a journal is expected to do.
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* A journal in memory: the reference implementation of the contract, and the
|
|
13
|
+
* one `pnpm dev` runs on.
|
|
14
|
+
*
|
|
15
|
+
* Like the memory store, it is not a test double. The ordering it promises —
|
|
16
|
+
* arrival order, stable across reads, paged by an opaque cursor — is what a SQL
|
|
17
|
+
* implementation is checked against, and `journal-contract.ts` runs the same
|
|
18
|
+
* suite over both so a disagreement is a test failure rather than a surprise in
|
|
19
|
+
* production.
|
|
20
|
+
*
|
|
21
|
+
* The clock is a parameter for the same reason it is one everywhere else: a
|
|
22
|
+
* `recordedAt` this journal read off the wall clock would make every retention
|
|
23
|
+
* test a race against real time.
|
|
24
|
+
*/
|
|
25
|
+
export const memoryTelemetryJournal = (clock = systemClock) => {
|
|
26
|
+
let records = [];
|
|
27
|
+
let nextSeq = 1;
|
|
28
|
+
const positioned = (record) => ({
|
|
29
|
+
...record,
|
|
30
|
+
seq: nextSeq++,
|
|
31
|
+
recordedAt: clock.now(),
|
|
32
|
+
});
|
|
33
|
+
return {
|
|
34
|
+
record: (batch) => {
|
|
35
|
+
/**
|
|
36
|
+
* Appended in one statement, so a reader can never see half a request's
|
|
37
|
+
* narration — the atomicity the contract asks of every implementation.
|
|
38
|
+
*/
|
|
39
|
+
records.push(...batch.map(positioned));
|
|
40
|
+
return Promise.resolve(ok(undefined));
|
|
41
|
+
},
|
|
42
|
+
read: (request) => {
|
|
43
|
+
const limit = clampTelemetryLimit(request?.limit);
|
|
44
|
+
const from = cursorPosition(request?.cursor);
|
|
45
|
+
const direction = request?.direction ?? "newer";
|
|
46
|
+
const matching = records.filter((record) => (request?.treeId === undefined || record.treeId === request.treeId) &&
|
|
47
|
+
(from === undefined || (direction === "older" ? record.seq < from : record.seq > from)));
|
|
48
|
+
/**
|
|
49
|
+
* `older` takes the page from the far end, which is a slice rather than a
|
|
50
|
+
* reverse: the records that come back are still in arrival order, because
|
|
51
|
+
* the contract says a page's order never depends on which end it came from.
|
|
52
|
+
*/
|
|
53
|
+
const page = direction === "older" ? matching.slice(-limit) : matching.slice(0, limit);
|
|
54
|
+
return Promise.resolve(ok({
|
|
55
|
+
records: page,
|
|
56
|
+
...pageEnds(page.map((record) => record.seq), direction, {
|
|
57
|
+
beyond: matching.length > page.length,
|
|
58
|
+
resumed: from !== undefined,
|
|
59
|
+
}),
|
|
60
|
+
}));
|
|
61
|
+
},
|
|
62
|
+
/**
|
|
63
|
+
* `nextSeq` is deliberately not rewound. A forgotten position must never be
|
|
64
|
+
* handed out again: a cursor a reader is holding across a prune would
|
|
65
|
+
* otherwise resume in the middle of records it has already seen.
|
|
66
|
+
*/
|
|
67
|
+
forget: ({ before }) => {
|
|
68
|
+
const kept = records.filter((record) => record.seq >= before);
|
|
69
|
+
const removed = records.length - kept.length;
|
|
70
|
+
records = kept;
|
|
71
|
+
return Promise.resolve(ok({ removed }));
|
|
72
|
+
},
|
|
73
|
+
};
|
|
74
|
+
};
|
|
75
|
+
//# sourceMappingURL=memory.js.map
|