@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,231 @@
|
|
|
1
|
+
import type { ProposalId, TreeId } from "../ids.js";
|
|
2
|
+
import { type PageDirection, type PageEnds } from "../paging.js";
|
|
3
|
+
import type { TreeDelta } from "../tree/delta.js";
|
|
4
|
+
import type { LoomTree } from "../tree/tree.js";
|
|
5
|
+
import type { Provenance } from "../runtime/proposal.js";
|
|
6
|
+
import type { Result } from "../result.js";
|
|
7
|
+
import type { StoreError } from "./errors.js";
|
|
8
|
+
/**
|
|
9
|
+
* Persistence: an append-only log of accepted deltas, and the current tree as a
|
|
10
|
+
* materialised view of it.
|
|
11
|
+
*
|
|
12
|
+
* The log is the truth. Every entry is a delta with the provenance that produced
|
|
13
|
+
* it, which is what makes 0001's claim real rather than aspirational — a stored
|
|
14
|
+
* tree can say what it is, but only a log can say who changed it, when, and why.
|
|
15
|
+
* §6 reads the same entries.
|
|
16
|
+
*
|
|
17
|
+
* The snapshot exists because §3 renders per request on an edge runtime. A pure
|
|
18
|
+
* log would make every render a fold over the whole history, and no cache
|
|
19
|
+
* invalidation fixes that, because the fold *is* the read. It also insures
|
|
20
|
+
* against a subtler problem: a log is a recipe, and replaying it correctly
|
|
21
|
+
* forever requires `applyDelta` to stay bit-stable forever. §1's `move`
|
|
22
|
+
* convention is baked into every stored delta. With a snapshot, replay is only
|
|
23
|
+
* ever needed for audit — see `auditSnapshot`, which is what turns drift from a
|
|
24
|
+
* silent rewrite of history into a test failure.
|
|
25
|
+
*/
|
|
26
|
+
export type StoredRevision = {
|
|
27
|
+
readonly treeId: TreeId;
|
|
28
|
+
/** The revision this entry produced, so `revision - 1` is what it applied to. */
|
|
29
|
+
readonly revision: number;
|
|
30
|
+
readonly proposalId: ProposalId;
|
|
31
|
+
readonly delta: TreeDelta;
|
|
32
|
+
readonly provenance: Provenance;
|
|
33
|
+
/** When the runtime applied it, which is not when the model produced it. */
|
|
34
|
+
readonly appliedAt: string;
|
|
35
|
+
/**
|
|
36
|
+
* Who allowed it, when a human had to (0029).
|
|
37
|
+
*
|
|
38
|
+
* Distinct from `provenance.actor`, which is who *asked*. A hold exists to put
|
|
39
|
+
* a second person in the way of a change, so recording only the asker would
|
|
40
|
+
* make every confirmed change look like somebody waving through their own
|
|
41
|
+
* request.
|
|
42
|
+
*
|
|
43
|
+
* Absent on a change nobody had to allow — one the Gate accepted outright —
|
|
44
|
+
* and absent on everything written before the column existed (0029), which nobody can prove the
|
|
45
|
+
* approver of. It is never back-filled: the log is append-only (0016), and a
|
|
46
|
+
* fact nobody observed does not belong in it.
|
|
47
|
+
*/
|
|
48
|
+
readonly answeredBy?: string;
|
|
49
|
+
};
|
|
50
|
+
export type AppendRequest = {
|
|
51
|
+
readonly proposalId: ProposalId;
|
|
52
|
+
readonly delta: TreeDelta;
|
|
53
|
+
readonly provenance: Provenance;
|
|
54
|
+
readonly appliedAt: string;
|
|
55
|
+
/** Set only by the confirmation path; see `StoredRevision.answeredBy`. */
|
|
56
|
+
readonly answeredBy?: string;
|
|
57
|
+
};
|
|
58
|
+
/**
|
|
59
|
+
* What a listing says about a tree without loading it.
|
|
60
|
+
*
|
|
61
|
+
* `revision` is the whole summary, and it is enough: it starts at 0 and
|
|
62
|
+
* increments once per accepted delta, so it is also the number of entries in the
|
|
63
|
+
* log. There is no timestamp because a `LoomTree` carries none — §1 kept time out
|
|
64
|
+
* of the document deliberately, and a listing that invented one would be a field
|
|
65
|
+
* only some implementations could fill honestly.
|
|
66
|
+
*/
|
|
67
|
+
export type TreeListing = {
|
|
68
|
+
readonly treeId: TreeId;
|
|
69
|
+
readonly revision: number;
|
|
70
|
+
};
|
|
71
|
+
export type ListRequest = {
|
|
72
|
+
/**
|
|
73
|
+
* Opaque to the caller: the previous page's `cursor`, passed back unread.
|
|
74
|
+
* Absent starts at the beginning. A cursor naming a tree that has since been
|
|
75
|
+
* removed is not an error — listing resumes from the next key after it.
|
|
76
|
+
*/
|
|
77
|
+
readonly cursor?: string;
|
|
78
|
+
/** Clamped by the implementation — see `clampListingLimit`. */
|
|
79
|
+
readonly limit?: number;
|
|
80
|
+
};
|
|
81
|
+
export type TreeListPage = {
|
|
82
|
+
readonly trees: readonly TreeListing[];
|
|
83
|
+
/** `null` when this was the last page. */
|
|
84
|
+
readonly cursor: string | null;
|
|
85
|
+
};
|
|
86
|
+
/**
|
|
87
|
+
* How a log is read: a page taken from one end of it, never the whole thing.
|
|
88
|
+
*
|
|
89
|
+
* A revision log grows once per accepted delta and is never compacted, so a read
|
|
90
|
+
* that returns all of it costs more the longer a tree has been edited — fastest
|
|
91
|
+
* exactly when the log is most worth reading. 0025 settled this shape for the
|
|
92
|
+
* telemetry journal; a revision log is the same kind of sequence and reads the
|
|
93
|
+
* same way, so the vocabulary is shared rather than reinvented.
|
|
94
|
+
*/
|
|
95
|
+
/**
|
|
96
|
+
* Where a read begins. Two kinds of position, and they are not interchangeable.
|
|
97
|
+
*
|
|
98
|
+
* A `cursor` is the store's word: opaque, exclusive, and only meaningful because
|
|
99
|
+
* a page handed it back. An `at` is the caller's word: a revision number, which
|
|
100
|
+
* is public, stable, and already the entry's identity — so a caller holding one
|
|
101
|
+
* can name it without having read the page it falls on.
|
|
102
|
+
*
|
|
103
|
+
* They are mutually exclusive in the type rather than by convention, because the
|
|
104
|
+
* only alternative is a precedence rule, and a request that quietly ignores half
|
|
105
|
+
* of what it was asked is the failure mode this contract avoids everywhere else.
|
|
106
|
+
*/
|
|
107
|
+
export type RevisionStart = {
|
|
108
|
+
/** A cursor from a previous page's `older`/`newer`, passed back unread. */
|
|
109
|
+
readonly cursor?: string;
|
|
110
|
+
readonly at?: never;
|
|
111
|
+
} | {
|
|
112
|
+
/**
|
|
113
|
+
* A revision to open at. **Inclusive** — the page contains it — which is
|
|
114
|
+
* the difference that matters: a caller naming this has been sent to a
|
|
115
|
+
* change and wants to see it, not to resume beside it.
|
|
116
|
+
*
|
|
117
|
+
* `direction` still says which way the rest of the page runs: `older`
|
|
118
|
+
* puts the named revision at the newest end of the page, `newer` at the
|
|
119
|
+
* oldest. A revision no entry holds is not an error; the page is whatever
|
|
120
|
+
* falls on the named side of it, which may be empty.
|
|
121
|
+
*/
|
|
122
|
+
readonly at?: number;
|
|
123
|
+
readonly cursor?: never;
|
|
124
|
+
};
|
|
125
|
+
export type RevisionReadRequest = RevisionStart & {
|
|
126
|
+
/**
|
|
127
|
+
* Default `newer`, which with no cursor is the oldest page — the read a fold
|
|
128
|
+
* wants, and the one `auditSnapshot` takes. `older` with no cursor is the
|
|
129
|
+
* newest page, which is what a reader looking at a tree asks for.
|
|
130
|
+
*/
|
|
131
|
+
readonly direction?: PageDirection;
|
|
132
|
+
readonly limit?: number;
|
|
133
|
+
};
|
|
134
|
+
export type RevisionPage = PageEnds & {
|
|
135
|
+
/**
|
|
136
|
+
* Always ascending by `revision`, whichever end the page was taken from.
|
|
137
|
+
*
|
|
138
|
+
* A log is folded by `replayTree` in the order the entries were applied, and a
|
|
139
|
+
* page that sometimes came back reversed would make every consumer responsible
|
|
140
|
+
* for knowing which — and silently wrong when it guessed.
|
|
141
|
+
*/
|
|
142
|
+
readonly revisions: readonly StoredRevision[];
|
|
143
|
+
};
|
|
144
|
+
export declare const DEFAULT_LISTING_LIMIT = 50;
|
|
145
|
+
export declare const MAX_LISTING_LIMIT = 200;
|
|
146
|
+
/**
|
|
147
|
+
* Larger than a tree listing's page and smaller than the journal's. A revision
|
|
148
|
+
* carries a whole delta and its provenance, so a page of these is heavier than a
|
|
149
|
+
* page of listings; but unlike telemetry records, one entry is one complete
|
|
150
|
+
* thing to read, so a page never splits something that has to be folded back
|
|
151
|
+
* together.
|
|
152
|
+
*/
|
|
153
|
+
export declare const DEFAULT_REVISION_LIMIT = 100;
|
|
154
|
+
export declare const MAX_REVISION_LIMIT = 500;
|
|
155
|
+
export declare const clampRevisionLimit: (limit: number | undefined) => number;
|
|
156
|
+
/**
|
|
157
|
+
* The revision the first log entry produces. A tree is created at revision 0 and
|
|
158
|
+
* nothing in the log corresponds to that, so 1 is the oldest position a read can
|
|
159
|
+
* reach — and revisions are dense from there, one per accepted delta (0026).
|
|
160
|
+
*/
|
|
161
|
+
export declare const FIRST_REVISION = 1;
|
|
162
|
+
/**
|
|
163
|
+
* An inclusive revision anchor, as the exclusive bound both implementations
|
|
164
|
+
* already page from.
|
|
165
|
+
*
|
|
166
|
+
* Density is what makes this exact rather than approximate: revisions are
|
|
167
|
+
* consecutive integers, so the position just outside `at` is `at ± 1` and no
|
|
168
|
+
* entry can hide between them. Shared rather than written twice, for the reason
|
|
169
|
+
* `pageEnds` is — it is the part most likely to drift between two backends and
|
|
170
|
+
* least likely to be noticed when it does.
|
|
171
|
+
*/
|
|
172
|
+
export declare const anchorBound: (at: number, direction: PageDirection) => number;
|
|
173
|
+
/**
|
|
174
|
+
* Whether an anchored page leaves entries on the side it pages away from — the
|
|
175
|
+
* `resumed` a cursor gets for free and an anchor does not.
|
|
176
|
+
*
|
|
177
|
+
* A cursor came from a page, so entries exist at the position it names and the
|
|
178
|
+
* far side is bounded by definition. An anchor is *inside* the page it produces,
|
|
179
|
+
* so the far side has to be established rather than assumed: paging `older` from
|
|
180
|
+
* revision 5 leaves entries newer than 5 only if the log has gone past it, and
|
|
181
|
+
* paging `newer` leaves entries older only if 5 is not the first.
|
|
182
|
+
*
|
|
183
|
+
* Both answers come from what the store already knows — the head revision it
|
|
184
|
+
* looked up to answer `not-found`, and the density that makes `FIRST_REVISION`
|
|
185
|
+
* the floor — so neither costs a read.
|
|
186
|
+
*/
|
|
187
|
+
export declare const anchorResumes: (at: number, direction: PageDirection, headRevision: number) => boolean;
|
|
188
|
+
/**
|
|
189
|
+
* Every implementation clamps the same way, so a caller cannot ask a store for
|
|
190
|
+
* everything it holds by omitting a limit or naming a large one. The rule is
|
|
191
|
+
* shared with every other listing in Loom; only the bounds are this one's.
|
|
192
|
+
*/
|
|
193
|
+
export declare const clampListingLimit: (limit: number | undefined) => number;
|
|
194
|
+
/**
|
|
195
|
+
* Three reads and two writes. `head` is the O(1) read §3 needs; `revisions` is
|
|
196
|
+
* the one §6 and the portal's provenance view need; `list` is how a consumer
|
|
197
|
+
* finds a tree it did not create; `append` is the only way a tree ever changes,
|
|
198
|
+
* so nothing can advance a revision without leaving a record of why.
|
|
199
|
+
*
|
|
200
|
+
* Every read is bounded. `head` is one tree, and the other two are pages with a
|
|
201
|
+
* clamped limit — so no caller can ask a store for everything it holds, whether
|
|
202
|
+
* by naming a large limit or by naming none.
|
|
203
|
+
*
|
|
204
|
+
* `list` takes no scope argument because `head` and `revisions` take none
|
|
205
|
+
* either: a store handle *is* the scope it can see. A tenant gets a handle
|
|
206
|
+
* narrowed to its own trees, which is a decision the host makes once when it
|
|
207
|
+
* builds the store rather than one every caller has to remember to pass — and it
|
|
208
|
+
* means listing cannot reach further than reading already could.
|
|
209
|
+
*
|
|
210
|
+
* **Pages are ordered by `treeId`, ascending.** Not by recency, however much a
|
|
211
|
+
* portal would prefer it: ordering has to be total and stable for a cursor to
|
|
212
|
+
* mean anything, and `treeId` is the only key every implementation is guaranteed
|
|
213
|
+
* to have. Recency is a view over data the store does not hold.
|
|
214
|
+
*/
|
|
215
|
+
export interface TreeStore {
|
|
216
|
+
readonly create: (tree: LoomTree) => Promise<Result<LoomTree, StoreError>>;
|
|
217
|
+
readonly head: (treeId: TreeId) => Promise<Result<LoomTree, StoreError>>;
|
|
218
|
+
readonly revisions: (treeId: TreeId, request?: RevisionReadRequest) => Promise<Result<RevisionPage, StoreError>>;
|
|
219
|
+
readonly list: (request?: ListRequest) => Promise<Result<TreeListPage, StoreError>>;
|
|
220
|
+
readonly append: (treeId: TreeId, request: AppendRequest) => Promise<Result<LoomTree, StoreError>>;
|
|
221
|
+
}
|
|
222
|
+
/**
|
|
223
|
+
* The read half, for consumers that never write.
|
|
224
|
+
*
|
|
225
|
+
* Depending on the whole store to read from it is what forces a renderer's tree
|
|
226
|
+
* source, or a snapshot audit, to be handed something that can also append. It
|
|
227
|
+
* also makes every stub grow a method the code under test never calls, which is
|
|
228
|
+
* how a test starts describing the interface instead of the behaviour.
|
|
229
|
+
*/
|
|
230
|
+
export type TreeReader = Pick<TreeStore, "head" | "revisions">;
|
|
231
|
+
//# sourceMappingURL=store.d.ts.map
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import { clampLimit } from "../paging.js";
|
|
2
|
+
export const DEFAULT_LISTING_LIMIT = 50;
|
|
3
|
+
export const MAX_LISTING_LIMIT = 200;
|
|
4
|
+
/**
|
|
5
|
+
* Larger than a tree listing's page and smaller than the journal's. A revision
|
|
6
|
+
* carries a whole delta and its provenance, so a page of these is heavier than a
|
|
7
|
+
* page of listings; but unlike telemetry records, one entry is one complete
|
|
8
|
+
* thing to read, so a page never splits something that has to be folded back
|
|
9
|
+
* together.
|
|
10
|
+
*/
|
|
11
|
+
export const DEFAULT_REVISION_LIMIT = 100;
|
|
12
|
+
export const MAX_REVISION_LIMIT = 500;
|
|
13
|
+
export const clampRevisionLimit = (limit) => clampLimit(limit, { fallback: DEFAULT_REVISION_LIMIT, max: MAX_REVISION_LIMIT });
|
|
14
|
+
/**
|
|
15
|
+
* The revision the first log entry produces. A tree is created at revision 0 and
|
|
16
|
+
* nothing in the log corresponds to that, so 1 is the oldest position a read can
|
|
17
|
+
* reach — and revisions are dense from there, one per accepted delta (0026).
|
|
18
|
+
*/
|
|
19
|
+
export const FIRST_REVISION = 1;
|
|
20
|
+
/**
|
|
21
|
+
* An inclusive revision anchor, as the exclusive bound both implementations
|
|
22
|
+
* already page from.
|
|
23
|
+
*
|
|
24
|
+
* Density is what makes this exact rather than approximate: revisions are
|
|
25
|
+
* consecutive integers, so the position just outside `at` is `at ± 1` and no
|
|
26
|
+
* entry can hide between them. Shared rather than written twice, for the reason
|
|
27
|
+
* `pageEnds` is — it is the part most likely to drift between two backends and
|
|
28
|
+
* least likely to be noticed when it does.
|
|
29
|
+
*/
|
|
30
|
+
export const anchorBound = (at, direction) => direction === "older" ? Math.floor(at) + 1 : Math.ceil(at) - 1;
|
|
31
|
+
/**
|
|
32
|
+
* Whether an anchored page leaves entries on the side it pages away from — the
|
|
33
|
+
* `resumed` a cursor gets for free and an anchor does not.
|
|
34
|
+
*
|
|
35
|
+
* A cursor came from a page, so entries exist at the position it names and the
|
|
36
|
+
* far side is bounded by definition. An anchor is *inside* the page it produces,
|
|
37
|
+
* so the far side has to be established rather than assumed: paging `older` from
|
|
38
|
+
* revision 5 leaves entries newer than 5 only if the log has gone past it, and
|
|
39
|
+
* paging `newer` leaves entries older only if 5 is not the first.
|
|
40
|
+
*
|
|
41
|
+
* Both answers come from what the store already knows — the head revision it
|
|
42
|
+
* looked up to answer `not-found`, and the density that makes `FIRST_REVISION`
|
|
43
|
+
* the floor — so neither costs a read.
|
|
44
|
+
*/
|
|
45
|
+
export const anchorResumes = (at, direction, headRevision) => (direction === "older" ? at < headRevision : at > FIRST_REVISION);
|
|
46
|
+
/**
|
|
47
|
+
* Every implementation clamps the same way, so a caller cannot ask a store for
|
|
48
|
+
* everything it holds by omitting a limit or naming a large one. The rule is
|
|
49
|
+
* shared with every other listing in Loom; only the bounds are this one's.
|
|
50
|
+
*/
|
|
51
|
+
export const clampListingLimit = (limit) => clampLimit(limit, { fallback: DEFAULT_LISTING_LIMIT, max: MAX_LISTING_LIMIT });
|
|
52
|
+
//# sourceMappingURL=store.js.map
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { StoredRevision } from "./store.js";
|
|
2
|
+
/**
|
|
3
|
+
* Which revisions in this stretch of log are put back, and by which entry.
|
|
4
|
+
*
|
|
5
|
+
* The map holds only revisions whose undo still stands, keyed by the revision
|
|
6
|
+
* that was put back. Where more than one standing entry undoes the same
|
|
7
|
+
* revision, the oldest is the one reported: it is the entry that actually put
|
|
8
|
+
* the change back, and the rest re-applied an inverse to a tree that already
|
|
9
|
+
* had it.
|
|
10
|
+
*
|
|
11
|
+
* **Bounded by what it is given.** An undo that lives outside `entries` is not
|
|
12
|
+
* seen, so a page read from the middle of a long log can report a revision as
|
|
13
|
+
* standing that a later page undoes. That is a property of any bounded read
|
|
14
|
+
* (`attributeTree` reports `examinedTo` for the same reason) and the honest
|
|
15
|
+
* reading of an absence here is "not undone within this stretch".
|
|
16
|
+
*/
|
|
17
|
+
export declare const undoneRevisions: (entries: readonly StoredRevision[]) => ReadonlyMap<number, StoredRevision>;
|
|
18
|
+
//# sourceMappingURL=undone.d.ts.map
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which changes in a log have been put back.
|
|
3
|
+
*
|
|
4
|
+
* `Provenance.undoes` makes the link a field, so a surface reading a log it did
|
|
5
|
+
* not write can follow it without parsing the sentence the runtime composed for
|
|
6
|
+
* people. Following it once is not the whole question, though, and the gap
|
|
7
|
+
* between the two is why this is here rather than left to each surface.
|
|
8
|
+
*
|
|
9
|
+
* **An undo is a change, so an undo can be undone.** If revision 5 puts revision
|
|
10
|
+
* 3 back, and revision 7 puts revision 5 back, then 3 is live again — and if 9
|
|
11
|
+
* puts 7 back, 3 is put back once more. Asking `undoes` alone answers "did
|
|
12
|
+
* anything ever undo this", which is a different question from "is this undone
|
|
13
|
+
* now", and the two disagree exactly when a person changed their mind twice. A
|
|
14
|
+
* surface showing a history is asking the second one.
|
|
15
|
+
*
|
|
16
|
+
* So a revision counts as undone only when some entry undoing it **stands** —
|
|
17
|
+
* is not itself undone by an entry that stands. That resolves without recursion:
|
|
18
|
+
* an undo is always appended after what it undoes, so walking newest-first
|
|
19
|
+
* settles every undoer before the entry it acts on.
|
|
20
|
+
*
|
|
21
|
+
* Nothing is read here. This is a fold over entries the caller already has,
|
|
22
|
+
* because the caller — a history screen — has just paged them to draw them, and
|
|
23
|
+
* a second bounded read to answer a question about the page in hand would be the
|
|
24
|
+
* one this module exists to save.
|
|
25
|
+
*/
|
|
26
|
+
/**
|
|
27
|
+
* The entries that claim to undo each revision, newest last.
|
|
28
|
+
*
|
|
29
|
+
* A revision can legally have more than one: two undos of the same change is an
|
|
30
|
+
* odd log rather than an impossible one, and reporting only the first would hide
|
|
31
|
+
* the second from a screen that shows what happened.
|
|
32
|
+
*/
|
|
33
|
+
const undoersByRevision = (entries) => {
|
|
34
|
+
const undoers = new Map();
|
|
35
|
+
for (const entry of entries) {
|
|
36
|
+
const undone = entry.provenance.undoes;
|
|
37
|
+
if (undone === undefined)
|
|
38
|
+
continue;
|
|
39
|
+
const found = undoers.get(undone);
|
|
40
|
+
if (found)
|
|
41
|
+
found.push(entry);
|
|
42
|
+
else
|
|
43
|
+
undoers.set(undone, [entry]);
|
|
44
|
+
}
|
|
45
|
+
return undoers;
|
|
46
|
+
};
|
|
47
|
+
/**
|
|
48
|
+
* Which revisions in this stretch of log are put back, and by which entry.
|
|
49
|
+
*
|
|
50
|
+
* The map holds only revisions whose undo still stands, keyed by the revision
|
|
51
|
+
* that was put back. Where more than one standing entry undoes the same
|
|
52
|
+
* revision, the oldest is the one reported: it is the entry that actually put
|
|
53
|
+
* the change back, and the rest re-applied an inverse to a tree that already
|
|
54
|
+
* had it.
|
|
55
|
+
*
|
|
56
|
+
* **Bounded by what it is given.** An undo that lives outside `entries` is not
|
|
57
|
+
* seen, so a page read from the middle of a long log can report a revision as
|
|
58
|
+
* standing that a later page undoes. That is a property of any bounded read
|
|
59
|
+
* (`attributeTree` reports `examinedTo` for the same reason) and the honest
|
|
60
|
+
* reading of an absence here is "not undone within this stretch".
|
|
61
|
+
*/
|
|
62
|
+
export const undoneRevisions = (entries) => {
|
|
63
|
+
const undoers = undoersByRevision(entries);
|
|
64
|
+
const newestFirst = [...entries].sort((left, right) => right.revision - left.revision);
|
|
65
|
+
/**
|
|
66
|
+
* Whether each entry's own effect is live. Filled newest-first, so every
|
|
67
|
+
* undoer of an entry is already settled when that entry is reached — an undo
|
|
68
|
+
* is appended after what it undoes, always.
|
|
69
|
+
*
|
|
70
|
+
* A log that broke that ordering would leave an undoer unsettled, and an
|
|
71
|
+
* unsettled undoer is read as not standing. That is the conservative answer:
|
|
72
|
+
* it reports a change as live, which is what the tree itself would show.
|
|
73
|
+
*/
|
|
74
|
+
const stands = new Map();
|
|
75
|
+
for (const entry of newestFirst) {
|
|
76
|
+
const against = undoers.get(entry.revision) ?? [];
|
|
77
|
+
stands.set(entry.revision, !against.some((undoer) => stands.get(undoer.revision) ?? false));
|
|
78
|
+
}
|
|
79
|
+
const undone = new Map();
|
|
80
|
+
for (const [revision, against] of undoers) {
|
|
81
|
+
const standing = [...against]
|
|
82
|
+
.sort((left, right) => left.revision - right.revision)
|
|
83
|
+
.find((undoer) => stands.get(undoer.revision) ?? false);
|
|
84
|
+
if (standing)
|
|
85
|
+
undone.set(revision, standing);
|
|
86
|
+
}
|
|
87
|
+
return undone;
|
|
88
|
+
};
|
|
89
|
+
//# sourceMappingURL=undone.js.map
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { EndpointId, EndpointRegistry } from "./endpoint.js";
|
|
2
|
+
/**
|
|
3
|
+
* Where a deployment will accept a submission.
|
|
4
|
+
*
|
|
5
|
+
* The same projection `dataCatalogue` makes for sources, and it exists for the
|
|
6
|
+
* same reason: a model asked to put a contact form on a page can only name an
|
|
7
|
+
* endpoint it was told about. It is deliberately thinner than the data
|
|
8
|
+
* catalogue — an id and a line — because there is nothing else a model may
|
|
9
|
+
* supply. Whether the endpoint posts or gets, where it posts to, and what it
|
|
10
|
+
* carries are all resolved after the choice is made and are none of the model's
|
|
11
|
+
* business.
|
|
12
|
+
*/
|
|
13
|
+
export type CataloguedEndpoint = {
|
|
14
|
+
readonly id: EndpointId;
|
|
15
|
+
/** One line, written by the endpoint's author, about what it receives. */
|
|
16
|
+
readonly description: string;
|
|
17
|
+
};
|
|
18
|
+
export type SubmissionCatalogue = readonly CataloguedEndpoint[];
|
|
19
|
+
export declare const submissionCatalogue: (registry: EndpointRegistry) => SubmissionCatalogue;
|
|
20
|
+
//# sourceMappingURL=catalogue.d.ts.map
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { type Result } from "../result.js";
|
|
2
|
+
import { type EndpointId } from "./endpoint.js";
|
|
3
|
+
/**
|
|
4
|
+
* What a node says about where it posts, as it appears in the tree.
|
|
5
|
+
*
|
|
6
|
+
* ```json
|
|
7
|
+
* "loom:submit": { "to": "contact.enquiry" }
|
|
8
|
+
* ```
|
|
9
|
+
*
|
|
10
|
+
* One key, and deliberately nothing else. A binding carries params because a
|
|
11
|
+
* read genuinely varies — `{ "limit": 6 }` is a different question of the same
|
|
12
|
+
* source — and 0058 accepted the AI-authored surface that comes with it, guarded
|
|
13
|
+
* by a schema the source declares. A write does not vary that way: a deployment
|
|
14
|
+
* with two mailing lists registers two endpoints, which costs one line and makes
|
|
15
|
+
* the allowlist exact. Params here would add an AI-authored channel into the one
|
|
16
|
+
* place a mistake sends a visitor's data somewhere it was not meant to go, and
|
|
17
|
+
* buy nothing that a second registration does not.
|
|
18
|
+
*
|
|
19
|
+
* The object form rather than a bare id string is what leaves room to be wrong
|
|
20
|
+
* about that. `{ "to": … }` can grow a key; `"contact.enquiry"` can only be
|
|
21
|
+
* migrated, and migrating built trees is the cost 0001 arranged the whole delta
|
|
22
|
+
* model to avoid.
|
|
23
|
+
*/
|
|
24
|
+
export type Submission = {
|
|
25
|
+
readonly to: EndpointId;
|
|
26
|
+
};
|
|
27
|
+
export type SubmissionError = {
|
|
28
|
+
/** The path of the offending entry, for a diagnostic a person can act on. */
|
|
29
|
+
readonly path: string;
|
|
30
|
+
readonly message: string;
|
|
31
|
+
};
|
|
32
|
+
export declare const describeSubmissionError: (error: SubmissionError) => string;
|
|
33
|
+
/**
|
|
34
|
+
* Parses the value of `loom:submit`. Total, like every other parse of something
|
|
35
|
+
* that came out of storage: a malformed declaration is reported and the node
|
|
36
|
+
* renders with no target, rather than throwing on a page nobody can then see.
|
|
37
|
+
*/
|
|
38
|
+
export declare const parseSubmission: (declared: unknown) => Result<Submission, SubmissionError>;
|
|
39
|
+
//# sourceMappingURL=declaration.d.ts.map
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { err, ok } from "../result.js";
|
|
3
|
+
import { endpointIdSchema } from "./endpoint.js";
|
|
4
|
+
/**
|
|
5
|
+
* Strict, unlike most parses of stored JSON. Zod's default is to strip what it
|
|
6
|
+
* does not know, and stripping is right for a document that may have been
|
|
7
|
+
* written by an older schema. Here it is not: the one thing this seam exists to
|
|
8
|
+
* keep out of a tree is an address, and a declaration carrying `action` should
|
|
9
|
+
* be refused loudly rather than quietly honoured as if the extra key were not
|
|
10
|
+
* there. A key added later is a key this schema will know about.
|
|
11
|
+
*/
|
|
12
|
+
const submissionSchema = z.object({ to: endpointIdSchema }).strict();
|
|
13
|
+
export const describeSubmissionError = (error) => `${error.path}: ${error.message}`;
|
|
14
|
+
/**
|
|
15
|
+
* Parses the value of `loom:submit`. Total, like every other parse of something
|
|
16
|
+
* that came out of storage: a malformed declaration is reported and the node
|
|
17
|
+
* renders with no target, rather than throwing on a page nobody can then see.
|
|
18
|
+
*/
|
|
19
|
+
export const parseSubmission = (declared) => {
|
|
20
|
+
const parsed = submissionSchema.safeParse(declared);
|
|
21
|
+
if (!parsed.success) {
|
|
22
|
+
const [issue] = parsed.error.issues;
|
|
23
|
+
return err({
|
|
24
|
+
path: issue && issue.path.length > 0 ? issue.path.map(String).join(".") : "loom:submit",
|
|
25
|
+
message: issue?.message ?? "is not an endpoint id under `to`",
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
return ok({ to: parsed.data.to });
|
|
29
|
+
};
|
|
30
|
+
//# sourceMappingURL=declaration.js.map
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import type { JsonObject } from "../json.js";
|
|
3
|
+
import { type Result } 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 declare const endpointIdSchema: z.ZodBranded<z.ZodString, "EndpointId">;
|
|
25
|
+
export type EndpointId = z.infer<typeof endpointIdSchema>;
|
|
26
|
+
/**
|
|
27
|
+
* A hidden input the primitive must render inside the form. A CSRF token is the
|
|
28
|
+
* reason this exists, and it is the reason resolution is allowed to be slow: a
|
|
29
|
+
* token is minted per request, often against a store, and a seam that could not
|
|
30
|
+
* wait for one would push every host into minting it somewhere else and
|
|
31
|
+
* threading it through `context` by hand.
|
|
32
|
+
*/
|
|
33
|
+
export type SubmissionField = {
|
|
34
|
+
readonly name: string;
|
|
35
|
+
readonly value: string;
|
|
36
|
+
};
|
|
37
|
+
/**
|
|
38
|
+
* Where a form posts, as the primitive receives it. Every field here is
|
|
39
|
+
* host-authored; none of it is in the tree, and none of it survives into a
|
|
40
|
+
* delta, a revision or a diff.
|
|
41
|
+
*/
|
|
42
|
+
export type SubmissionTarget = {
|
|
43
|
+
readonly action: string;
|
|
44
|
+
readonly method: "get" | "post";
|
|
45
|
+
/** Rendered as hidden inputs, in order. Empty for an endpoint needing none. */
|
|
46
|
+
readonly fields: readonly SubmissionField[];
|
|
47
|
+
};
|
|
48
|
+
export declare const submissionTargetSchema: z.ZodType<SubmissionTarget, z.ZodTypeDef, unknown>;
|
|
49
|
+
/** What an endpoint says when it cannot give a target. */
|
|
50
|
+
export type SubmissionFailure = {
|
|
51
|
+
/**
|
|
52
|
+
* `unavailable` is "ask again later" — a token store that is down, a
|
|
53
|
+
* dependency that timed out. `refused` is "not for you" — a form this
|
|
54
|
+
* audience may not submit, an endpoint the deployment turned off. Separate
|
|
55
|
+
* because a primitive shows different things for them, and because only one
|
|
56
|
+
* of the two is worth trying again.
|
|
57
|
+
*/
|
|
58
|
+
readonly code: "unavailable" | "refused";
|
|
59
|
+
readonly detail: string;
|
|
60
|
+
};
|
|
61
|
+
export type EndpointRequest = {
|
|
62
|
+
/** The render request's opaque host context — audience, locale, tenant. */
|
|
63
|
+
readonly context: JsonObject | undefined;
|
|
64
|
+
/**
|
|
65
|
+
* Aborted once the render has stopped waiting for this endpoint, which it
|
|
66
|
+
* will (0140). Pass it to whatever does the IO and the connection is let go;
|
|
67
|
+
* ignore it and the page is still answered on time, but the socket is not.
|
|
68
|
+
*/
|
|
69
|
+
readonly signal: AbortSignal | undefined;
|
|
70
|
+
};
|
|
71
|
+
export interface SubmissionEndpoint {
|
|
72
|
+
readonly target: (request: EndpointRequest) => Promise<Result<SubmissionTarget, SubmissionFailure>>;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Why a node has no target. Each is something a primitive may be told about and
|
|
76
|
+
* a diagnostic says out loud; none of them is an exception anyone catches.
|
|
77
|
+
*/
|
|
78
|
+
export type SubmissionUnavailable = {
|
|
79
|
+
readonly reason: "no-such-endpoint" | "invalid-target" | "endpoint-threw" | SubmissionFailure["code"];
|
|
80
|
+
readonly detail: string;
|
|
81
|
+
};
|
|
82
|
+
export declare const describeSubmissionUnavailable: (unavailable: SubmissionUnavailable) => string;
|
|
83
|
+
export type EndpointDefinition = {
|
|
84
|
+
readonly id: string;
|
|
85
|
+
/**
|
|
86
|
+
* One line, for the catalogue. A model choosing where a form posts has this
|
|
87
|
+
* and the id to go on, and nothing else — which is the point.
|
|
88
|
+
*/
|
|
89
|
+
readonly description: string;
|
|
90
|
+
readonly endpoint: SubmissionEndpoint;
|
|
91
|
+
};
|
|
92
|
+
/**
|
|
93
|
+
* A definition with the host's own types erased, which is what a heterogeneous
|
|
94
|
+
* registry can hold. `defineEndpoint` is the only way to build one, so the
|
|
95
|
+
* validation of what the host answered happens in exactly one place.
|
|
96
|
+
*/
|
|
97
|
+
export type EndpointEntry = {
|
|
98
|
+
readonly id: string;
|
|
99
|
+
readonly description: string;
|
|
100
|
+
/** Total: calls, catches, validates. Never rejects. */
|
|
101
|
+
readonly resolve: (context: JsonObject | undefined, signal?: AbortSignal) => Promise<Result<SubmissionTarget, SubmissionUnavailable>>;
|
|
102
|
+
};
|
|
103
|
+
/**
|
|
104
|
+
* Declares an endpoint. The target it answers with is validated even though the
|
|
105
|
+
* host typed it, for the reason `defineSource` validates an answer: the type is
|
|
106
|
+
* a claim made when the code was written, and the schema is what makes the
|
|
107
|
+
* claim true on the day the route moved.
|
|
108
|
+
*/
|
|
109
|
+
export declare const defineEndpoint: (definition: EndpointDefinition) => EndpointEntry;
|
|
110
|
+
export type RegisteredEndpoint = EndpointEntry & {
|
|
111
|
+
readonly id: EndpointId;
|
|
112
|
+
};
|
|
113
|
+
export type EndpointRegistryError = {
|
|
114
|
+
readonly code: "invalid-endpoint-id";
|
|
115
|
+
readonly id: string;
|
|
116
|
+
} | {
|
|
117
|
+
readonly code: "duplicate-endpoint-id";
|
|
118
|
+
readonly id: string;
|
|
119
|
+
};
|
|
120
|
+
export declare const describeEndpointRegistryError: (error: EndpointRegistryError) => string;
|
|
121
|
+
export interface EndpointRegistry {
|
|
122
|
+
readonly endpoint: (id: EndpointId) => RegisteredEndpoint | undefined;
|
|
123
|
+
/** In registration order, so a catalogue reads predictably. */
|
|
124
|
+
readonly endpoints: readonly RegisteredEndpoint[];
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* Building the registry is pure and calls no endpoint, so registering cannot
|
|
128
|
+
* mint a token as a side effect of an import.
|
|
129
|
+
*/
|
|
130
|
+
export declare const createEndpointRegistry: (entries: readonly EndpointEntry[]) => Result<EndpointRegistry, EndpointRegistryError>;
|
|
131
|
+
//# sourceMappingURL=endpoint.d.ts.map
|