@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,160 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { NAMESPACED_ID_PATTERN } from "../primitive-type.js";
|
|
3
|
+
import { err, ok } from "../result.js";
|
|
4
|
+
/**
|
|
5
|
+
* The host's half of the submission seam: where a form's contents go.
|
|
6
|
+
*
|
|
7
|
+
* A data source answers a question the tree asked. An endpoint is the other
|
|
8
|
+
* direction — it is where a *visitor's* data is sent — and that difference is
|
|
9
|
+
* the whole reason this is a separate seam rather than a source that happens to
|
|
10
|
+
* answer with a URL. A read that goes to the wrong place shows the wrong page;
|
|
11
|
+
* a write that goes to the wrong place sends someone's name, email and message
|
|
12
|
+
* to whoever owns that address.
|
|
13
|
+
*
|
|
14
|
+
* So the address is never in the tree. A proposal may name an endpoint the
|
|
15
|
+
* deployment registered and may do nothing else: it cannot compose one, cannot
|
|
16
|
+
* append to one, and cannot pass anything that reaches one. The registry is the
|
|
17
|
+
* allowlist, exactly as it is for sources and for primitives.
|
|
18
|
+
*/
|
|
19
|
+
/**
|
|
20
|
+
* The identifier of a registered endpoint — the contract between `loom:submit`
|
|
21
|
+
* in the tree and whatever receives the submission. `contact.enquiry`,
|
|
22
|
+
* `newsletter.subscribe`.
|
|
23
|
+
*/
|
|
24
|
+
export const endpointIdSchema = z.string().regex(NAMESPACED_ID_PATTERN).brand();
|
|
25
|
+
/**
|
|
26
|
+
* A path that stays on this origin, as distinct from one that merely starts
|
|
27
|
+
* with a slash.
|
|
28
|
+
*
|
|
29
|
+
* `//host` is scheme-relative: it begins with `/` and reaches another origin
|
|
30
|
+
* entirely, so a check for a leading slash accepts it. `/\host` is the same
|
|
31
|
+
* thing with a backslash, which browsers normalise to `//host` when resolving —
|
|
32
|
+
* `new URL("/\\evil.example", "https://site.example")` is `https://evil.example/`.
|
|
33
|
+
*
|
|
34
|
+
* Both are refused here. A form action is where a visitor's typed data is sent,
|
|
35
|
+
* so a target that quietly leaves the origin is the most costly version of the
|
|
36
|
+
* composition mistake this schema exists to catch, and the one least likely to
|
|
37
|
+
* be noticed in review: it looks like a path.
|
|
38
|
+
*/
|
|
39
|
+
const isSameOriginPath = (value) => value.startsWith("/") && value[1] !== "/" && value[1] !== "\\";
|
|
40
|
+
/**
|
|
41
|
+
* An action is either a same-origin path or an absolute `http(s)` URL.
|
|
42
|
+
*
|
|
43
|
+
* The host wrote it, so this is not the check `linkUrlSchema` makes about
|
|
44
|
+
* AI-authored URLs — it is the check that a host's own composition mistake does
|
|
45
|
+
* not become a live `javascript:` form action, that an empty string does not
|
|
46
|
+
* silently mean "post to this page", and that a path-shaped action does not post
|
|
47
|
+
* off the origin. A relative path with no leading `/` is refused for a related
|
|
48
|
+
* reason: it resolves against whatever route the form happens to be rendered on,
|
|
49
|
+
* which is not a decision anybody made.
|
|
50
|
+
*
|
|
51
|
+
* Leaving the origin is still allowed — but only by saying so, as a full
|
|
52
|
+
* `https://` URL. The rule is that crossing an origin is explicit, not that it
|
|
53
|
+
* is forbidden.
|
|
54
|
+
*/
|
|
55
|
+
const actionSchema = z.string().superRefine((value, context) => {
|
|
56
|
+
if (isSameOriginPath(value))
|
|
57
|
+
return;
|
|
58
|
+
const parsed = (() => {
|
|
59
|
+
try {
|
|
60
|
+
return new URL(value);
|
|
61
|
+
}
|
|
62
|
+
catch {
|
|
63
|
+
return undefined;
|
|
64
|
+
}
|
|
65
|
+
})();
|
|
66
|
+
if (!parsed || !["http:", "https:"].includes(parsed.protocol)) {
|
|
67
|
+
context.addIssue({
|
|
68
|
+
code: z.ZodIssueCode.custom,
|
|
69
|
+
message: "must be a same-origin path or an absolute http(s) URL",
|
|
70
|
+
});
|
|
71
|
+
}
|
|
72
|
+
});
|
|
73
|
+
export const submissionTargetSchema = z.object({
|
|
74
|
+
action: actionSchema,
|
|
75
|
+
method: z.enum(["get", "post"]),
|
|
76
|
+
fields: z
|
|
77
|
+
.array(z.object({ name: z.string().min(1), value: z.string() }))
|
|
78
|
+
.readonly()
|
|
79
|
+
.default([]),
|
|
80
|
+
});
|
|
81
|
+
export const describeSubmissionUnavailable = (unavailable) => {
|
|
82
|
+
switch (unavailable.reason) {
|
|
83
|
+
case "no-such-endpoint":
|
|
84
|
+
return `no endpoint is registered for it — ${unavailable.detail}`;
|
|
85
|
+
case "invalid-target":
|
|
86
|
+
return `the endpoint answered with a target the seam refuses — ${unavailable.detail}`;
|
|
87
|
+
case "endpoint-threw":
|
|
88
|
+
return `the endpoint threw instead of answering — ${unavailable.detail}`;
|
|
89
|
+
case "unavailable":
|
|
90
|
+
return `the endpoint could not be reached — ${unavailable.detail}`;
|
|
91
|
+
case "refused":
|
|
92
|
+
return `the endpoint refused — ${unavailable.detail}`;
|
|
93
|
+
}
|
|
94
|
+
};
|
|
95
|
+
const firstIssue = (error) => {
|
|
96
|
+
const [issue] = error.issues;
|
|
97
|
+
if (!issue)
|
|
98
|
+
return "refused, without saying why";
|
|
99
|
+
const path = issue.path.length === 0 ? "" : `${issue.path.map(String).join(".")}: `;
|
|
100
|
+
return `${path}${issue.message}`;
|
|
101
|
+
};
|
|
102
|
+
/**
|
|
103
|
+
* Declares an endpoint. The target it answers with is validated even though the
|
|
104
|
+
* host typed it, for the reason `defineSource` validates an answer: the type is
|
|
105
|
+
* a claim made when the code was written, and the schema is what makes the
|
|
106
|
+
* claim true on the day the route moved.
|
|
107
|
+
*/
|
|
108
|
+
export const defineEndpoint = (definition) => ({
|
|
109
|
+
id: definition.id,
|
|
110
|
+
description: definition.description,
|
|
111
|
+
resolve: async (context, signal) => {
|
|
112
|
+
/**
|
|
113
|
+
* The same single `try` the data seam makes, for the same reason: an
|
|
114
|
+
* endpoint is not Loom's code, and a rejected promise from one host's token
|
|
115
|
+
* store must not be why a whole page 500s.
|
|
116
|
+
*/
|
|
117
|
+
let answered;
|
|
118
|
+
try {
|
|
119
|
+
answered = await definition.endpoint.target({ context, signal });
|
|
120
|
+
}
|
|
121
|
+
catch (thrown) {
|
|
122
|
+
return err({
|
|
123
|
+
reason: "endpoint-threw",
|
|
124
|
+
detail: thrown instanceof Error ? thrown.message : String(thrown),
|
|
125
|
+
});
|
|
126
|
+
}
|
|
127
|
+
if (!answered.ok)
|
|
128
|
+
return err({ reason: answered.error.code, detail: answered.error.detail });
|
|
129
|
+
const target = submissionTargetSchema.safeParse(answered.value);
|
|
130
|
+
return target.success
|
|
131
|
+
? ok(target.data)
|
|
132
|
+
: err({ reason: "invalid-target", detail: firstIssue(target.error) });
|
|
133
|
+
},
|
|
134
|
+
});
|
|
135
|
+
export const describeEndpointRegistryError = (error) => error.code === "invalid-endpoint-id"
|
|
136
|
+
? `"${error.id}" is not a valid endpoint id — expected dot-namespaced kebab-case, like "contact.enquiry"`
|
|
137
|
+
: `"${error.id}" is registered twice; a form naming it would post to whichever registration won`;
|
|
138
|
+
/**
|
|
139
|
+
* Building the registry is pure and calls no endpoint, so registering cannot
|
|
140
|
+
* mint a token as a side effect of an import.
|
|
141
|
+
*/
|
|
142
|
+
export const createEndpointRegistry = (entries) => {
|
|
143
|
+
const endpoints = [];
|
|
144
|
+
const byId = new Map();
|
|
145
|
+
for (const entry of entries) {
|
|
146
|
+
const id = endpointIdSchema.safeParse(entry.id);
|
|
147
|
+
if (!id.success)
|
|
148
|
+
return err({ code: "invalid-endpoint-id", id: entry.id });
|
|
149
|
+
if (byId.has(id.data))
|
|
150
|
+
return err({ code: "duplicate-endpoint-id", id: entry.id });
|
|
151
|
+
const registered = { ...entry, id: id.data };
|
|
152
|
+
byId.set(id.data, registered);
|
|
153
|
+
endpoints.push(registered);
|
|
154
|
+
}
|
|
155
|
+
return ok({
|
|
156
|
+
endpoint: (id) => byId.get(id),
|
|
157
|
+
endpoints: Object.freeze(endpoints),
|
|
158
|
+
});
|
|
159
|
+
};
|
|
160
|
+
//# sourceMappingURL=endpoint.js.map
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where a form posts.
|
|
3
|
+
*
|
|
4
|
+
* A tree names an endpoint and never carries an address; a deployment registers
|
|
5
|
+
* what that name reaches. This module is both halves of that seam.
|
|
6
|
+
*/
|
|
7
|
+
export * from "./catalogue.js";
|
|
8
|
+
export * from "./declaration.js";
|
|
9
|
+
export * from "./endpoint.js";
|
|
10
|
+
export * from "./plan.js";
|
|
11
|
+
export * from "./resolution.js";
|
|
12
|
+
export * from "./resolve.js";
|
|
13
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where a form posts.
|
|
3
|
+
*
|
|
4
|
+
* A tree names an endpoint and never carries an address; a deployment registers
|
|
5
|
+
* what that name reaches. This module is both halves of that seam.
|
|
6
|
+
*/
|
|
7
|
+
export * from "./catalogue.js";
|
|
8
|
+
export * from "./declaration.js";
|
|
9
|
+
export * from "./endpoint.js";
|
|
10
|
+
export * from "./plan.js";
|
|
11
|
+
export * from "./resolution.js";
|
|
12
|
+
export * from "./resolve.js";
|
|
13
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import type { NodeId } from "../ids.js";
|
|
2
|
+
import type { LoomNode } from "../tree/node.js";
|
|
3
|
+
import type { LoomTree } from "../tree/tree.js";
|
|
4
|
+
import { type SubmissionError } from "./declaration.js";
|
|
5
|
+
import type { EndpointId } from "./endpoint.js";
|
|
6
|
+
/**
|
|
7
|
+
* Which endpoints a tree points at, worked out before any of them is asked.
|
|
8
|
+
*
|
|
9
|
+
* Planning is a pure function of the tree, for the reason `data/plan.ts` gives:
|
|
10
|
+
* `renderLoomTree` is synchronous and does no IO, and minting a token is IO. So
|
|
11
|
+
* the tree is read once, in a pass that only reads, and the asking happens
|
|
12
|
+
* outside the renderer entirely.
|
|
13
|
+
*/
|
|
14
|
+
export type PlannedSubmission = {
|
|
15
|
+
readonly nodeId: NodeId;
|
|
16
|
+
readonly to: EndpointId;
|
|
17
|
+
};
|
|
18
|
+
/** A node whose `loom:submit` could not be read at all. */
|
|
19
|
+
export type SubmissionProblem = {
|
|
20
|
+
readonly nodeId: NodeId;
|
|
21
|
+
readonly error: SubmissionError;
|
|
22
|
+
};
|
|
23
|
+
export type SubmissionPlan = {
|
|
24
|
+
/** Deduplicated endpoint ids, in first-encountered order. */
|
|
25
|
+
readonly endpoints: readonly EndpointId[];
|
|
26
|
+
readonly submissions: readonly PlannedSubmission[];
|
|
27
|
+
readonly problems: readonly SubmissionProblem[];
|
|
28
|
+
};
|
|
29
|
+
export declare const submissionPlanIsEmpty: (plan: SubmissionPlan) => boolean;
|
|
30
|
+
/**
|
|
31
|
+
* Two forms naming one endpoint are resolved once and share a target. That is
|
|
32
|
+
* the rule that identical questions are asked once (0058), applied to a question
|
|
33
|
+
* that has no params to differ by, and it is also the behaviour a reader would
|
|
34
|
+
* expect: two
|
|
35
|
+
* newsletter forms on one page post to the same place, and a per-form nonce
|
|
36
|
+
* would break the second one every time somebody used the first.
|
|
37
|
+
*/
|
|
38
|
+
export declare const planTreeSubmissions: (tree: LoomTree) => SubmissionPlan;
|
|
39
|
+
/**
|
|
40
|
+
* The same plan, for a root that is not a stored tree.
|
|
41
|
+
*
|
|
42
|
+
* The runtime needs one for a tree that exists only as the result of applying a
|
|
43
|
+
* delta — nothing has minted an id for it and nothing ever will, so it is a node
|
|
44
|
+
* and not a `LoomTree`. Reading the destinations twice would be two walks that
|
|
45
|
+
* had to agree about which declarations are readable, and the second one would
|
|
46
|
+
* drift.
|
|
47
|
+
*/
|
|
48
|
+
export declare const planSubmissionsIn: (root: LoomNode) => SubmissionPlan;
|
|
49
|
+
//# sourceMappingURL=plan.d.ts.map
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { SUBMIT_PROP_KEY } from "../reserved-props.js";
|
|
2
|
+
import { walkTree } from "../tree/navigation.js";
|
|
3
|
+
import { parseSubmission } from "./declaration.js";
|
|
4
|
+
export const submissionPlanIsEmpty = (plan) => plan.endpoints.length === 0 && plan.problems.length === 0;
|
|
5
|
+
/**
|
|
6
|
+
* Two forms naming one endpoint are resolved once and share a target. That is
|
|
7
|
+
* the rule that identical questions are asked once (0058), applied to a question
|
|
8
|
+
* that has no params to differ by, and it is also the behaviour a reader would
|
|
9
|
+
* expect: two
|
|
10
|
+
* newsletter forms on one page post to the same place, and a per-form nonce
|
|
11
|
+
* would break the second one every time somebody used the first.
|
|
12
|
+
*/
|
|
13
|
+
export const planTreeSubmissions = (tree) => planSubmissionsIn(tree.root);
|
|
14
|
+
/**
|
|
15
|
+
* The same plan, for a root that is not a stored tree.
|
|
16
|
+
*
|
|
17
|
+
* The runtime needs one for a tree that exists only as the result of applying a
|
|
18
|
+
* delta — nothing has minted an id for it and nothing ever will, so it is a node
|
|
19
|
+
* and not a `LoomTree`. Reading the destinations twice would be two walks that
|
|
20
|
+
* had to agree about which declarations are readable, and the second one would
|
|
21
|
+
* drift.
|
|
22
|
+
*/
|
|
23
|
+
export const planSubmissionsIn = (root) => {
|
|
24
|
+
const endpoints = [];
|
|
25
|
+
const submissions = [];
|
|
26
|
+
const problems = [];
|
|
27
|
+
const seen = new Set();
|
|
28
|
+
for (const node of walkTree(root)) {
|
|
29
|
+
if (node.kind !== "element")
|
|
30
|
+
continue;
|
|
31
|
+
const declared = node.props[SUBMIT_PROP_KEY];
|
|
32
|
+
if (declared === undefined)
|
|
33
|
+
continue;
|
|
34
|
+
const parsed = parseSubmission(declared);
|
|
35
|
+
if (!parsed.ok) {
|
|
36
|
+
problems.push({ nodeId: node.id, error: parsed.error });
|
|
37
|
+
continue;
|
|
38
|
+
}
|
|
39
|
+
if (!seen.has(parsed.value.to)) {
|
|
40
|
+
seen.add(parsed.value.to);
|
|
41
|
+
endpoints.push(parsed.value.to);
|
|
42
|
+
}
|
|
43
|
+
submissions.push({ nodeId: node.id, to: parsed.value.to });
|
|
44
|
+
}
|
|
45
|
+
return { endpoints, submissions, problems };
|
|
46
|
+
};
|
|
47
|
+
//# sourceMappingURL=plan.js.map
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import type { NodeId } from "../ids.js";
|
|
2
|
+
import type { Result } from "../result.js";
|
|
3
|
+
import type { SubmissionError } from "./declaration.js";
|
|
4
|
+
import type { EndpointId, SubmissionTarget, SubmissionUnavailable } from "./endpoint.js";
|
|
5
|
+
import type { SubmissionPlan } from "./plan.js";
|
|
6
|
+
/**
|
|
7
|
+
* The targets, indexed the way a render walk needs them.
|
|
8
|
+
*
|
|
9
|
+
* Nothing here knows about React. The seam is asking a host where its own forms
|
|
10
|
+
* post, which is not a rendering concern, so a cache warmer or a static export
|
|
11
|
+
* can plan and resolve without loading the renderer.
|
|
12
|
+
*/
|
|
13
|
+
/**
|
|
14
|
+
* A node that declared a submission either has a target or has a named reason it
|
|
15
|
+
* does not. There is no third state here, and in particular no way to express
|
|
16
|
+
* "no target, and that is fine": a form primitive shows something different for
|
|
17
|
+
* "we cannot take this right now" than for a form that works, and a shape that
|
|
18
|
+
* cannot tell them apart guarantees it eventually shows a submit button that
|
|
19
|
+
* quietly goes nowhere.
|
|
20
|
+
*/
|
|
21
|
+
export type SubmissionOutcome = {
|
|
22
|
+
readonly status: "ready";
|
|
23
|
+
readonly target: SubmissionTarget;
|
|
24
|
+
} | {
|
|
25
|
+
readonly status: "unavailable";
|
|
26
|
+
readonly unavailable: SubmissionUnavailable;
|
|
27
|
+
};
|
|
28
|
+
/** What a node's submission could not do, in the seam's own vocabulary. */
|
|
29
|
+
export type NodeSubmissionProblem = {
|
|
30
|
+
readonly kind: "misdeclared";
|
|
31
|
+
readonly error: SubmissionError;
|
|
32
|
+
} | {
|
|
33
|
+
readonly kind: "unavailable";
|
|
34
|
+
readonly to: EndpointId;
|
|
35
|
+
readonly unavailable: SubmissionUnavailable;
|
|
36
|
+
};
|
|
37
|
+
export interface SubmissionResolution {
|
|
38
|
+
/**
|
|
39
|
+
* `undefined` for the overwhelming majority of nodes, which declare none — and
|
|
40
|
+
* for that reason it is not a way to say "I have no target for you". A node that
|
|
41
|
+
* declares `loom:submit` and gets `undefined` with no problem beside it earns a
|
|
42
|
+
* `submit-unresolved` diagnostic from the walk, for the reason the data seam's
|
|
43
|
+
* twin gives at length.
|
|
44
|
+
*/
|
|
45
|
+
readonly lookup: (nodeId: NodeId) => SubmissionOutcome | undefined;
|
|
46
|
+
readonly problemsFor: (nodeId: NodeId) => readonly NodeSubmissionProblem[];
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* The resolution of a plan in which nothing posts anywhere, which is the only
|
|
50
|
+
* tree it is correct for. `EMPTY_DATA_RESOLUTION` has the same shape, the same
|
|
51
|
+
* purpose and the same trap.
|
|
52
|
+
*/
|
|
53
|
+
export declare const EMPTY_SUBMISSION_RESOLUTION: SubmissionResolution;
|
|
54
|
+
/**
|
|
55
|
+
* Folds a plan and its answers into the two lookups the walk uses. Separated
|
|
56
|
+
* from resolution because it is pure: given the same answers it builds the same
|
|
57
|
+
* result, which is what makes every failure path testable without a fake
|
|
58
|
+
* endpoint for each one.
|
|
59
|
+
*/
|
|
60
|
+
export declare const buildSubmissionResolution: (plan: SubmissionPlan, answers: ReadonlyMap<EndpointId, Result<SubmissionTarget, SubmissionUnavailable>>) => SubmissionResolution;
|
|
61
|
+
//# sourceMappingURL=resolution.d.ts.map
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
const NO_PROBLEMS = Object.freeze([]);
|
|
2
|
+
/**
|
|
3
|
+
* The resolution of a plan in which nothing posts anywhere, which is the only
|
|
4
|
+
* tree it is correct for. `EMPTY_DATA_RESOLUTION` has the same shape, the same
|
|
5
|
+
* purpose and the same trap.
|
|
6
|
+
*/
|
|
7
|
+
export const EMPTY_SUBMISSION_RESOLUTION = {
|
|
8
|
+
lookup: () => undefined,
|
|
9
|
+
problemsFor: () => NO_PROBLEMS,
|
|
10
|
+
};
|
|
11
|
+
/**
|
|
12
|
+
* Folds a plan and its answers into the two lookups the walk uses. Separated
|
|
13
|
+
* from resolution because it is pure: given the same answers it builds the same
|
|
14
|
+
* result, which is what makes every failure path testable without a fake
|
|
15
|
+
* endpoint for each one.
|
|
16
|
+
*/
|
|
17
|
+
export const buildSubmissionResolution = (plan, answers) => {
|
|
18
|
+
const outcomes = new Map();
|
|
19
|
+
const problems = new Map();
|
|
20
|
+
const problemsOn = (nodeId) => {
|
|
21
|
+
const existing = problems.get(nodeId);
|
|
22
|
+
if (existing)
|
|
23
|
+
return existing;
|
|
24
|
+
const created = [];
|
|
25
|
+
problems.set(nodeId, created);
|
|
26
|
+
return created;
|
|
27
|
+
};
|
|
28
|
+
for (const problem of plan.problems) {
|
|
29
|
+
problemsOn(problem.nodeId).push({ kind: "misdeclared", error: problem.error });
|
|
30
|
+
}
|
|
31
|
+
for (const submission of plan.submissions) {
|
|
32
|
+
const answer = answers.get(submission.to);
|
|
33
|
+
/**
|
|
34
|
+
* A planned submission with no answer is a caller that resolved a different
|
|
35
|
+
* plan than the one it is rendering. Reported as unavailable rather than
|
|
36
|
+
* ignored: a form whose target silently went missing is the failure this
|
|
37
|
+
* module is arranged to prevent.
|
|
38
|
+
*/
|
|
39
|
+
const outcome = !answer
|
|
40
|
+
? {
|
|
41
|
+
status: "unavailable",
|
|
42
|
+
unavailable: {
|
|
43
|
+
reason: "no-such-endpoint",
|
|
44
|
+
detail: "this submission was never resolved",
|
|
45
|
+
},
|
|
46
|
+
}
|
|
47
|
+
: answer.ok
|
|
48
|
+
? { status: "ready", target: answer.value }
|
|
49
|
+
: { status: "unavailable", unavailable: answer.error };
|
|
50
|
+
outcomes.set(submission.nodeId, outcome);
|
|
51
|
+
if (outcome.status === "unavailable") {
|
|
52
|
+
problemsOn(submission.nodeId).push({
|
|
53
|
+
kind: "unavailable",
|
|
54
|
+
to: submission.to,
|
|
55
|
+
unavailable: outcome.unavailable,
|
|
56
|
+
});
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
return {
|
|
60
|
+
lookup: (nodeId) => outcomes.get(nodeId),
|
|
61
|
+
problemsFor: (nodeId) => problems.get(nodeId) ?? NO_PROBLEMS,
|
|
62
|
+
};
|
|
63
|
+
};
|
|
64
|
+
//# sourceMappingURL=resolution.js.map
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import type { JsonObject } from "../json.js";
|
|
2
|
+
import type { LoomTree } from "../tree/tree.js";
|
|
3
|
+
import type { EndpointRegistry } from "./endpoint.js";
|
|
4
|
+
import { type SubmissionPlan } from "./plan.js";
|
|
5
|
+
import { type SubmissionResolution } from "./resolution.js";
|
|
6
|
+
/**
|
|
7
|
+
* The second step in serving a page that may do IO, and the only one that talks
|
|
8
|
+
* to a host about where a form posts.
|
|
9
|
+
*
|
|
10
|
+
* Every endpoint in the plan is asked at once. They are independent by
|
|
11
|
+
* construction, so asking in sequence would make a page's latency the sum of its
|
|
12
|
+
* forms rather than the slowest of them. Nothing here rejects: each failure is
|
|
13
|
+
* captured against its own id, so a token store having a bad afternoon costs the
|
|
14
|
+
* forms on the page rather than the page.
|
|
15
|
+
*
|
|
16
|
+
* That holds for a token store that says no. It did not hold for one that says
|
|
17
|
+
* nothing at all until 13 September, which is what the ceiling is for (0140): a
|
|
18
|
+
* `Promise.all` waits for the slowest of its questions, and an endpoint that
|
|
19
|
+
* never answers is not slow — it is the page, held, with no diagnostic, because
|
|
20
|
+
* nothing had decided it had waited long enough.
|
|
21
|
+
*/
|
|
22
|
+
export type ResolveSubmissionsOptions = {
|
|
23
|
+
readonly registry: EndpointRegistry;
|
|
24
|
+
/** Passed through to every endpoint — the render request's host context. */
|
|
25
|
+
readonly context?: JsonObject;
|
|
26
|
+
/**
|
|
27
|
+
* How long any one endpoint is given, each independently of the others.
|
|
28
|
+
* Defaults to `DEFAULT_ENDPOINT_CEILING_MS`; there is no way to wait forever
|
|
29
|
+
* (0140).
|
|
30
|
+
*/
|
|
31
|
+
readonly ceilingMs?: number;
|
|
32
|
+
};
|
|
33
|
+
/**
|
|
34
|
+
* Ten seconds, the data seam's number and for its reason: this is a page being
|
|
35
|
+
* served, and a reader is waiting for it.
|
|
36
|
+
*
|
|
37
|
+
* The seam's own documentation says resolution *"is allowed to be slow"*, and
|
|
38
|
+
* that is still true — a token minted against a store is exactly what this
|
|
39
|
+
* budget is for. What it is not allowed to be is unbounded.
|
|
40
|
+
*/
|
|
41
|
+
export declare const DEFAULT_ENDPOINT_CEILING_MS = 10000;
|
|
42
|
+
export declare const resolveSubmissionPlan: (plan: SubmissionPlan, options: ResolveSubmissionsOptions) => Promise<SubmissionResolution>;
|
|
43
|
+
/** Plan and resolve in one step, for the ordinary caller that does both. */
|
|
44
|
+
export declare const resolveTreeSubmissions: (tree: LoomTree, options: ResolveSubmissionsOptions) => Promise<SubmissionResolution>;
|
|
45
|
+
//# sourceMappingURL=resolve.d.ts.map
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { ceilingOf, describeCeiling, withCeiling } from "../deadline.js";
|
|
2
|
+
import { err } from "../result.js";
|
|
3
|
+
import { planTreeSubmissions, submissionPlanIsEmpty } from "./plan.js";
|
|
4
|
+
import { buildSubmissionResolution, EMPTY_SUBMISSION_RESOLUTION, } from "./resolution.js";
|
|
5
|
+
/**
|
|
6
|
+
* Ten seconds, the data seam's number and for its reason: this is a page being
|
|
7
|
+
* served, and a reader is waiting for it.
|
|
8
|
+
*
|
|
9
|
+
* The seam's own documentation says resolution *"is allowed to be slow"*, and
|
|
10
|
+
* that is still true — a token minted against a store is exactly what this
|
|
11
|
+
* budget is for. What it is not allowed to be is unbounded.
|
|
12
|
+
*/
|
|
13
|
+
export const DEFAULT_ENDPOINT_CEILING_MS = 10_000;
|
|
14
|
+
const askOne = async (to, options) => {
|
|
15
|
+
const registered = options.registry.endpoint(to);
|
|
16
|
+
if (!registered) {
|
|
17
|
+
return err({
|
|
18
|
+
reason: "no-such-endpoint",
|
|
19
|
+
detail: `registered: ${options.registry.endpoints.map((entry) => entry.id).join(", ") || "none"}`,
|
|
20
|
+
});
|
|
21
|
+
}
|
|
22
|
+
const ceiling = ceilingOf(options.ceilingMs, DEFAULT_ENDPOINT_CEILING_MS);
|
|
23
|
+
return withCeiling(ceiling, () => err({ reason: "unavailable", detail: `no answer in ${describeCeiling(ceiling)}` }), (signal) => registered.resolve(options.context, signal));
|
|
24
|
+
};
|
|
25
|
+
export const resolveSubmissionPlan = async (plan, options) => {
|
|
26
|
+
if (submissionPlanIsEmpty(plan))
|
|
27
|
+
return EMPTY_SUBMISSION_RESOLUTION;
|
|
28
|
+
const answered = await Promise.all(plan.endpoints.map(async (to) => [
|
|
29
|
+
to,
|
|
30
|
+
await askOne(to, options),
|
|
31
|
+
]));
|
|
32
|
+
return buildSubmissionResolution(plan, new Map(answered));
|
|
33
|
+
};
|
|
34
|
+
/** Plan and resolve in one step, for the ordinary caller that does both. */
|
|
35
|
+
export const resolveTreeSubmissions = async (tree, options) => resolveSubmissionPlan(planTreeSubmissions(tree), options);
|
|
36
|
+
//# sourceMappingURL=resolve.js.map
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
import type { EpisodeFold, ProposalEpisode } from "./episode.js";
|
|
2
|
+
/**
|
|
3
|
+
* Confidence is self-graded and trusted on purpose, on one condition: that it
|
|
4
|
+
* be calibrated (0007). This is the measurement half of that promise. It
|
|
5
|
+
* compares what the model claimed against what became of the claim, and it
|
|
6
|
+
* changes nothing — no threshold moves, no policy reads it.
|
|
7
|
+
*
|
|
8
|
+
* That separation is deliberate rather than incremental. A runtime that adjusts
|
|
9
|
+
* its own gate from its own record of its own judgments can drift somewhere no
|
|
10
|
+
* one chose, and the only defence is that the drift was proposed to a human
|
|
11
|
+
* first. Measuring is the part that is safe to do unsupervised.
|
|
12
|
+
*/
|
|
13
|
+
/** What became of a proposal, once it is something a claim can be scored against. */
|
|
14
|
+
export type CalibrationVerdict = "survived" | "rejected";
|
|
15
|
+
/**
|
|
16
|
+
* Why a proposal yielded no verdict. Kept apart from `rejected` on purpose: a
|
|
17
|
+
* commit that failed on the database says nothing about whether the model was
|
|
18
|
+
* right, and folding those into the rejections would make the runtime look
|
|
19
|
+
* overconfident every time infrastructure broke.
|
|
20
|
+
*/
|
|
21
|
+
export type UnjudgedReason = "awaiting-answer" | "failed" | "unsettled";
|
|
22
|
+
/**
|
|
23
|
+
* The buckets a fold has to open before the first proposal arrives, so a reason
|
|
24
|
+
* nobody hit still reads as zero rather than as missing.
|
|
25
|
+
*
|
|
26
|
+
* Checked where it is written because nothing else could: this union has no
|
|
27
|
+
* schema to hold it against, one consumer, and a member added without a bucket
|
|
28
|
+
* costs a telemetry row that never appears — the quietest way a list goes stale.
|
|
29
|
+
* `src/tree/delta.ts` has named it an exemplar of that remedy since it was
|
|
30
|
+
* written, which until now it was not.
|
|
31
|
+
*/
|
|
32
|
+
export declare const UNJUDGED_REASONS: readonly UnjudgedReason[];
|
|
33
|
+
/**
|
|
34
|
+
* A repair (0006) is scored as its own proposal, not merged into the one it
|
|
35
|
+
* replaced. Both graded themselves, and the refusal that prompted the repair is
|
|
36
|
+
* exactly the case where the grade was wrong — averaging it away would hide the
|
|
37
|
+
* datapoint calibration exists to collect.
|
|
38
|
+
*/
|
|
39
|
+
export declare const verdictOf: (proposal: ProposalEpisode) => CalibrationVerdict | UnjudgedReason;
|
|
40
|
+
export declare const CALIBRATION_BUCKET_COUNT = 10;
|
|
41
|
+
export type CalibrationScore = {
|
|
42
|
+
readonly judged: number;
|
|
43
|
+
readonly survived: number;
|
|
44
|
+
/** null when nothing was judged — zero out of zero is not zero. */
|
|
45
|
+
readonly observedRate: number | null;
|
|
46
|
+
readonly meanConfidence: number | null;
|
|
47
|
+
/**
|
|
48
|
+
* `meanConfidence - observedRate`. Positive means the model claimed more than
|
|
49
|
+
* it delivered. null when there is nothing to compare.
|
|
50
|
+
*/
|
|
51
|
+
readonly gap: number | null;
|
|
52
|
+
};
|
|
53
|
+
/** Half-open `[lower, upper)`, except the last bucket, which is closed so 1 has a home. */
|
|
54
|
+
export type ConfidenceBucket = CalibrationScore & {
|
|
55
|
+
readonly lower: number;
|
|
56
|
+
readonly upper: number;
|
|
57
|
+
};
|
|
58
|
+
/**
|
|
59
|
+
* A calibration reading confined to the claims one policy judged.
|
|
60
|
+
*
|
|
61
|
+
* The overall report answers "is a 0.9 actually a 0.9". It can only answer that
|
|
62
|
+
* for one gate at a time, because `observedRate` is not a property of the model
|
|
63
|
+
* alone: survival is what the Gate and the human between them allowed, and a
|
|
64
|
+
* host that tightened `minimumConfidence` moves the rate without the model
|
|
65
|
+
* having changed at all. Pooling two policies produces a number that moved for a
|
|
66
|
+
* reason the report cannot name.
|
|
67
|
+
*/
|
|
68
|
+
export type PolicyCalibration = {
|
|
69
|
+
/**
|
|
70
|
+
* Which policy judged these claims, as its own dispositions named it (0033).
|
|
71
|
+
*
|
|
72
|
+
* `null` means this window never saw the judgment — the page opened after the
|
|
73
|
+
* disposition and before the commit, say. Distinct from the recorded string
|
|
74
|
+
* `UNATTRIBUTED_POLICY_ID`, which is a judgment that really was made before the
|
|
75
|
+
* Gate wrote down which policy made it. One is a gap in the reader, the other
|
|
76
|
+
* is a gap in the record, and merging them would let a fixed record look like a
|
|
77
|
+
* short page.
|
|
78
|
+
*/
|
|
79
|
+
readonly policyId: string | null;
|
|
80
|
+
readonly overall: CalibrationScore;
|
|
81
|
+
readonly buckets: readonly ConfidenceBucket[];
|
|
82
|
+
/**
|
|
83
|
+
* The distinct fingerprints the judgments in this segment named, sorted.
|
|
84
|
+
*
|
|
85
|
+
* A name is host-declared, and hosts are asked to rename a policy they edit (0033).
|
|
86
|
+
* More than one fingerprint under one name means that did not happen, and this
|
|
87
|
+
* row is pooling gates that differ by more than what they are called — the same
|
|
88
|
+
* error the segments exist to correct, one level down. `rulesetContinuityOf`
|
|
89
|
+
* reads this list; the list itself is carried so a host can match a digest to
|
|
90
|
+
* the configuration it is looking at.
|
|
91
|
+
*/
|
|
92
|
+
readonly fingerprints: readonly string[];
|
|
93
|
+
/**
|
|
94
|
+
* Judged claims in this segment whose disposition named no fingerprint. Kept
|
|
95
|
+
* beside the list rather than folded into it: one fingerprint plus twelve
|
|
96
|
+
* unfingerprinted judgments is not a segment shown to be constant, and a list
|
|
97
|
+
* of length one would say it was.
|
|
98
|
+
*/
|
|
99
|
+
readonly unfingerprinted: number;
|
|
100
|
+
};
|
|
101
|
+
export type CalibrationReport = {
|
|
102
|
+
readonly overall: CalibrationScore;
|
|
103
|
+
readonly buckets: readonly ConfidenceBucket[];
|
|
104
|
+
/**
|
|
105
|
+
* The same claims again, split by the policy that judged each one. Every
|
|
106
|
+
* judged proposal appears in exactly one segment, so the segments sum to
|
|
107
|
+
* `overall` — the split is a partition, not a sample.
|
|
108
|
+
*
|
|
109
|
+
* Ordered by policy name, with the unrecorded segment last, so a reader
|
|
110
|
+
* comparing two windows is comparing rows in the same order.
|
|
111
|
+
*/
|
|
112
|
+
readonly byPolicy: readonly PolicyCalibration[];
|
|
113
|
+
/** Proposals that produced no verdict, by why. Never in a denominator. */
|
|
114
|
+
readonly unjudged: Readonly<Record<UnjudgedReason, number>>;
|
|
115
|
+
/**
|
|
116
|
+
* Records the fold could not attribute to a proposal, carried through rather
|
|
117
|
+
* than dropped — the same reason `EpisodeFold` returns them. A rate computed
|
|
118
|
+
* over a window that silently lost records is a rate over a denominator it
|
|
119
|
+
* changed without saying so.
|
|
120
|
+
*/
|
|
121
|
+
readonly unattributed: number;
|
|
122
|
+
/**
|
|
123
|
+
* Proposals the runtime authored rather than a model — the inverse behind a
|
|
124
|
+
* revert, say. Segmented rather than dropped: they carry a confidence because
|
|
125
|
+
* every proposal does, but nobody graded it, so scoring them would measure the
|
|
126
|
+
* constant the runtime stamps. Reporting the count keeps that visible instead
|
|
127
|
+
* of leaving a reader to wonder where the undos went.
|
|
128
|
+
*/
|
|
129
|
+
readonly runtimeAuthored: number;
|
|
130
|
+
};
|
|
131
|
+
export declare const calibrationOf: (fold: EpisodeFold) => CalibrationReport;
|
|
132
|
+
//# sourceMappingURL=calibration.d.ts.map
|