@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,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whose documents a page may frame.
|
|
3
|
+
*
|
|
4
|
+
* A tree names a URL, because which video belongs on a page is a content
|
|
5
|
+
* decision. A deployment names the origins it is willing to put inside an
|
|
6
|
+
* `iframe`, because who may run a script inside its pages is not. This module
|
|
7
|
+
* is both halves of that seam (0095).
|
|
8
|
+
*/
|
|
9
|
+
export * from "./catalogue.js";
|
|
10
|
+
export * from "./origin.js";
|
|
11
|
+
export * from "./resolution.js";
|
|
12
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whose documents a page may frame.
|
|
3
|
+
*
|
|
4
|
+
* A tree names a URL, because which video belongs on a page is a content
|
|
5
|
+
* decision. A deployment names the origins it is willing to put inside an
|
|
6
|
+
* `iframe`, because who may run a script inside its pages is not. This module
|
|
7
|
+
* is both halves of that seam (0095).
|
|
8
|
+
*/
|
|
9
|
+
export * from "./catalogue.js";
|
|
10
|
+
export * from "./origin.js";
|
|
11
|
+
export * from "./resolution.js";
|
|
12
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { type Result } from "../result.js";
|
|
3
|
+
/**
|
|
4
|
+
* The host's half of the framing seam: whose documents this deployment is
|
|
5
|
+
* willing to put inside an `iframe`.
|
|
6
|
+
*
|
|
7
|
+
* [0053](../../decisions/0053-a-url-in-the-tree-is-checked-against-a-scheme-allowlist.md)
|
|
8
|
+
* holds every AI-authored URL in the library to a scheme allowlist, and for an
|
|
9
|
+
* `href` or an `img src` that has been enough — the worst a bad `https:` link
|
|
10
|
+
* does is disappoint whoever clicks it. A frame is different in kind: it is a
|
|
11
|
+
* whole document with a script host in it, running inside the page, named by a
|
|
12
|
+
* model. `https:` says nothing at all about who is on the other end.
|
|
13
|
+
*
|
|
14
|
+
* So this seam is shaped unlike the submission seam it is modelled on, in one
|
|
15
|
+
* way that matters. A form's address never appears in the tree at all (0065),
|
|
16
|
+
* because nothing about *where* a visitor's data goes is a content decision. A
|
|
17
|
+
* frame's URL is entirely a content decision — which video, which map, which
|
|
18
|
+
* prototype — and a registry of whole URLs would be a deployment registering
|
|
19
|
+
* every video it might ever show. What a deployment can say once, and mean
|
|
20
|
+
* forever, is **whose documents it will frame**. So the tree keeps the URL and
|
|
21
|
+
* the registry holds the origins.
|
|
22
|
+
*/
|
|
23
|
+
/**
|
|
24
|
+
* A host-authored origin — scheme, host and port, and nothing else.
|
|
25
|
+
*
|
|
26
|
+
* Normalised through `URL` rather than compared as text, so `HTTPS://Example.com`
|
|
27
|
+
* and `https://example.com:443/` are the one registration they obviously are.
|
|
28
|
+
* A path is refused rather than ignored: `https://example.com/embed` looks like
|
|
29
|
+
* it narrows the allowlist to a directory and would not, and an allowlist that
|
|
30
|
+
* silently permits more than it appears to is worse than no allowlist.
|
|
31
|
+
*/
|
|
32
|
+
export declare const frameOriginSchema: z.ZodBranded<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, "FrameOrigin">;
|
|
33
|
+
export type FrameOrigin = z.infer<typeof frameOriginSchema>;
|
|
34
|
+
/**
|
|
35
|
+
* What a deployment says about one origin it will frame.
|
|
36
|
+
*
|
|
37
|
+
* The description is here for the same reason an endpoint's is: it reaches the
|
|
38
|
+
* catalogue a model reads. A model asked to put a product video on a page can
|
|
39
|
+
* only sensibly name a URL on an origin it was told about, and being told is
|
|
40
|
+
* cheaper for everyone than being refused afterwards.
|
|
41
|
+
*/
|
|
42
|
+
export type FrameOriginDefinition = {
|
|
43
|
+
readonly origin: string;
|
|
44
|
+
/** One line, for the catalogue — "Vimeo player embeds". */
|
|
45
|
+
readonly description: string;
|
|
46
|
+
/**
|
|
47
|
+
* Whether this origin is the deployment's own.
|
|
48
|
+
*
|
|
49
|
+
* It changes nothing about whether a frame is permitted and everything about
|
|
50
|
+
* what the frame is worth. A primitive's `sandbox` is only a sandbox at all
|
|
51
|
+
* *because* the framed document is cross-origin: `allow-scripts` beside
|
|
52
|
+
* `allow-same-origin` on a document from this very origin re-grants the
|
|
53
|
+
* document full access to the page that framed it. Nothing in a render could
|
|
54
|
+
* previously tell — this is the one place that can, because it is the only
|
|
55
|
+
* place that knows what "own" means for this deployment.
|
|
56
|
+
*/
|
|
57
|
+
readonly self?: boolean;
|
|
58
|
+
};
|
|
59
|
+
export type RegisteredFrameOrigin = {
|
|
60
|
+
readonly origin: FrameOrigin;
|
|
61
|
+
readonly description: string;
|
|
62
|
+
readonly self: boolean;
|
|
63
|
+
};
|
|
64
|
+
export type FrameOriginRegistryError = {
|
|
65
|
+
readonly code: "invalid-frame-origin";
|
|
66
|
+
readonly origin: string;
|
|
67
|
+
readonly detail: string;
|
|
68
|
+
} | {
|
|
69
|
+
readonly code: "duplicate-frame-origin";
|
|
70
|
+
readonly origin: string;
|
|
71
|
+
};
|
|
72
|
+
export declare const describeFrameOriginRegistryError: (error: FrameOriginRegistryError) => string;
|
|
73
|
+
export interface FrameOriginRegistry {
|
|
74
|
+
/** `undefined` when nothing registered covers the URL's origin. */
|
|
75
|
+
readonly origin: (url: URL) => RegisteredFrameOrigin | undefined;
|
|
76
|
+
/** In registration order, so a catalogue reads predictably. */
|
|
77
|
+
readonly origins: readonly RegisteredFrameOrigin[];
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Building the registry is pure and reaches nothing. An allowlist is a static
|
|
81
|
+
* fact about a deployment — it does not vary by visitor, it is not minted per
|
|
82
|
+
* request, and there is nothing to await — which is why this seam has no plan
|
|
83
|
+
* and no resolve step, unlike the submission seam whose shape it otherwise
|
|
84
|
+
* borrows (0095).
|
|
85
|
+
*/
|
|
86
|
+
export declare const createFrameOriginRegistry: (definitions: readonly FrameOriginDefinition[]) => Result<FrameOriginRegistry, FrameOriginRegistryError>;
|
|
87
|
+
//# sourceMappingURL=origin.d.ts.map
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { err, ok } from "../result.js";
|
|
3
|
+
/**
|
|
4
|
+
* The host's half of the framing seam: whose documents this deployment is
|
|
5
|
+
* willing to put inside an `iframe`.
|
|
6
|
+
*
|
|
7
|
+
* [0053](../../decisions/0053-a-url-in-the-tree-is-checked-against-a-scheme-allowlist.md)
|
|
8
|
+
* holds every AI-authored URL in the library to a scheme allowlist, and for an
|
|
9
|
+
* `href` or an `img src` that has been enough — the worst a bad `https:` link
|
|
10
|
+
* does is disappoint whoever clicks it. A frame is different in kind: it is a
|
|
11
|
+
* whole document with a script host in it, running inside the page, named by a
|
|
12
|
+
* model. `https:` says nothing at all about who is on the other end.
|
|
13
|
+
*
|
|
14
|
+
* So this seam is shaped unlike the submission seam it is modelled on, in one
|
|
15
|
+
* way that matters. A form's address never appears in the tree at all (0065),
|
|
16
|
+
* because nothing about *where* a visitor's data goes is a content decision. A
|
|
17
|
+
* frame's URL is entirely a content decision — which video, which map, which
|
|
18
|
+
* prototype — and a registry of whole URLs would be a deployment registering
|
|
19
|
+
* every video it might ever show. What a deployment can say once, and mean
|
|
20
|
+
* forever, is **whose documents it will frame**. So the tree keeps the URL and
|
|
21
|
+
* the registry holds the origins.
|
|
22
|
+
*/
|
|
23
|
+
/**
|
|
24
|
+
* A host-authored origin — scheme, host and port, and nothing else.
|
|
25
|
+
*
|
|
26
|
+
* Normalised through `URL` rather than compared as text, so `HTTPS://Example.com`
|
|
27
|
+
* and `https://example.com:443/` are the one registration they obviously are.
|
|
28
|
+
* A path is refused rather than ignored: `https://example.com/embed` looks like
|
|
29
|
+
* it narrows the allowlist to a directory and would not, and an allowlist that
|
|
30
|
+
* silently permits more than it appears to is worse than no allowlist.
|
|
31
|
+
*/
|
|
32
|
+
export const frameOriginSchema = z
|
|
33
|
+
.string()
|
|
34
|
+
.superRefine((value, context) => {
|
|
35
|
+
const parsed = parseOrigin(value);
|
|
36
|
+
if (!parsed.ok) {
|
|
37
|
+
context.addIssue({ code: z.ZodIssueCode.custom, message: parsed.error });
|
|
38
|
+
}
|
|
39
|
+
})
|
|
40
|
+
.transform((value) => {
|
|
41
|
+
const parsed = parseOrigin(value);
|
|
42
|
+
/**
|
|
43
|
+
* `superRefine` has already refused everything this cannot parse, so the
|
|
44
|
+
* fallback is unreachable. It is written rather than asserted away because
|
|
45
|
+
* a non-null assertion here would be a claim about two functions staying in
|
|
46
|
+
* step, and the whole point of this module is not making claims like that.
|
|
47
|
+
*/
|
|
48
|
+
return parsed.ok ? parsed.value : value;
|
|
49
|
+
})
|
|
50
|
+
.brand();
|
|
51
|
+
const parseOrigin = (value) => {
|
|
52
|
+
let url;
|
|
53
|
+
try {
|
|
54
|
+
url = new URL(value);
|
|
55
|
+
}
|
|
56
|
+
catch {
|
|
57
|
+
return err("must be an absolute http(s) origin, like \"https://player.vimeo.com\"");
|
|
58
|
+
}
|
|
59
|
+
if (!["http:", "https:"].includes(url.protocol)) {
|
|
60
|
+
return err(`must be an http(s) origin; "${url.protocol}" is not one`);
|
|
61
|
+
}
|
|
62
|
+
if (url.pathname !== "/" || url.search !== "" || url.hash !== "") {
|
|
63
|
+
return err("must be an origin and nothing else — no path, query or fragment");
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* `new URL("https://user:secret@example.com")` parses, and its `origin` drops
|
|
67
|
+
* the credentials silently. Registering one would be a deployment believing
|
|
68
|
+
* it had scoped an allowlist to an authenticated host when it had not.
|
|
69
|
+
*/
|
|
70
|
+
if (url.username !== "" || url.password !== "") {
|
|
71
|
+
return err("must carry no credentials");
|
|
72
|
+
}
|
|
73
|
+
return ok(url.origin);
|
|
74
|
+
};
|
|
75
|
+
export const describeFrameOriginRegistryError = (error) => error.code === "invalid-frame-origin"
|
|
76
|
+
? `"${error.origin}" is not a framable origin — ${error.detail}`
|
|
77
|
+
: `"${error.origin}" is registered twice; the second registration could only disagree with the first about whether it is this deployment's own`;
|
|
78
|
+
const firstIssue = (error) => error.issues[0]?.message ?? "was refused, without saying why";
|
|
79
|
+
/**
|
|
80
|
+
* Building the registry is pure and reaches nothing. An allowlist is a static
|
|
81
|
+
* fact about a deployment — it does not vary by visitor, it is not minted per
|
|
82
|
+
* request, and there is nothing to await — which is why this seam has no plan
|
|
83
|
+
* and no resolve step, unlike the submission seam whose shape it otherwise
|
|
84
|
+
* borrows (0095).
|
|
85
|
+
*/
|
|
86
|
+
export const createFrameOriginRegistry = (definitions) => {
|
|
87
|
+
const origins = [];
|
|
88
|
+
const byOrigin = new Map();
|
|
89
|
+
for (const definition of definitions) {
|
|
90
|
+
const parsed = frameOriginSchema.safeParse(definition.origin);
|
|
91
|
+
if (!parsed.success) {
|
|
92
|
+
return err({
|
|
93
|
+
code: "invalid-frame-origin",
|
|
94
|
+
origin: definition.origin,
|
|
95
|
+
detail: firstIssue(parsed.error),
|
|
96
|
+
});
|
|
97
|
+
}
|
|
98
|
+
if (byOrigin.has(parsed.data)) {
|
|
99
|
+
return err({ code: "duplicate-frame-origin", origin: definition.origin });
|
|
100
|
+
}
|
|
101
|
+
const registered = {
|
|
102
|
+
origin: parsed.data,
|
|
103
|
+
description: definition.description,
|
|
104
|
+
self: definition.self ?? false,
|
|
105
|
+
};
|
|
106
|
+
byOrigin.set(parsed.data, registered);
|
|
107
|
+
origins.push(registered);
|
|
108
|
+
}
|
|
109
|
+
return ok({
|
|
110
|
+
origin: (url) => byOrigin.get(url.origin),
|
|
111
|
+
origins: Object.freeze(origins),
|
|
112
|
+
});
|
|
113
|
+
};
|
|
114
|
+
//# sourceMappingURL=origin.js.map
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import type { JsonValue } from "../json.js";
|
|
2
|
+
import type { FrameOrigin, FrameOriginRegistry } from "./origin.js";
|
|
3
|
+
/**
|
|
4
|
+
* The verdict on a URL a page means to put inside a frame, and the shape a
|
|
5
|
+
* primitive reads it in.
|
|
6
|
+
*
|
|
7
|
+
* Nothing here knows about React, and nothing here reaches the network. The
|
|
8
|
+
* whole seam is a URL parse against a list somebody wrote down, which is what
|
|
9
|
+
* lets it happen inside a render rather than before one.
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* What a primitive is told about a URL it means to frame.
|
|
13
|
+
*
|
|
14
|
+
* Two states, and deliberately not three. A submission has `ready` and
|
|
15
|
+
* `unavailable` and a third state expressed by absence — a form that was never
|
|
16
|
+
* given a target at all — because "the tree said nothing" is a different fault
|
|
17
|
+
* from "the deployment could not answer". A frame has no equivalent: the URL is
|
|
18
|
+
* in the props, so a node either carries one or renders no frame, and there is
|
|
19
|
+
* nothing for a primitive to distinguish. Either it may be framed or it may not,
|
|
20
|
+
* and when it may not the refusal says why.
|
|
21
|
+
*/
|
|
22
|
+
export type FrameOutcome = {
|
|
23
|
+
readonly status: "allowed";
|
|
24
|
+
/**
|
|
25
|
+
* The URL to place, normalised through `URL`. Normalised rather than
|
|
26
|
+
* echoed so that what the browser resolves is what this seam checked —
|
|
27
|
+
* a `src` that differed from the string the allowlist was matched against
|
|
28
|
+
* would make the check advisory.
|
|
29
|
+
*/
|
|
30
|
+
readonly url: string;
|
|
31
|
+
readonly origin: FrameOrigin;
|
|
32
|
+
/**
|
|
33
|
+
* The framed document is this deployment's own, so the primitive's
|
|
34
|
+
* `sandbox` grants it nothing: `allow-scripts` with `allow-same-origin`
|
|
35
|
+
* is only a boundary between two origins. Permitted — a host that
|
|
36
|
+
* registered its own origin meant to — and said out loud, in the render's
|
|
37
|
+
* diagnostics and here, because it is the one thing about a frame that
|
|
38
|
+
* looks safe and is not.
|
|
39
|
+
*/
|
|
40
|
+
readonly sameOrigin: boolean;
|
|
41
|
+
} | {
|
|
42
|
+
readonly status: "refused";
|
|
43
|
+
readonly refusal: FrameRefusal;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* Why a URL will not be framed. Each is something a primitive may be told about
|
|
47
|
+
* and a diagnostic says out loud; none of them is an exception anybody catches.
|
|
48
|
+
*/
|
|
49
|
+
export type FrameRefusal = {
|
|
50
|
+
readonly reason: /** No allowlist was wired, so this deployment frames nothing. */ "no-registry" | /** Parsed, and nobody registered its origin. */ "unlisted-origin" | /** Not an absolute http(s) URL at all — so it has no origin to check. */ "unframeable";
|
|
51
|
+
readonly detail: string;
|
|
52
|
+
};
|
|
53
|
+
export declare const describeFrameRefusal: (refusal: FrameRefusal) => string;
|
|
54
|
+
/**
|
|
55
|
+
* The whole check, as a pure function of a registry and a value.
|
|
56
|
+
*
|
|
57
|
+
* Total, like every other reading of something a model wrote: a prop that is
|
|
58
|
+
* not a string, or is a string that is not a URL, is refused with a reason
|
|
59
|
+
* rather than thrown over. The tree is AI-authored and the renderer is a total
|
|
60
|
+
* projection (0008) — a page cannot be lost because a proposal put a number
|
|
61
|
+
* where a URL goes.
|
|
62
|
+
*
|
|
63
|
+
* A missing registry refuses rather than permits, which is the same way the
|
|
64
|
+
* submission seam fails and for the same reason: the registry *is* the
|
|
65
|
+
* allowlist, so a deployment that has not written one has not decided to frame
|
|
66
|
+
* anybody, and defaulting to "frame it" would make the seam a formality that
|
|
67
|
+
* every host has to remember to switch on.
|
|
68
|
+
*/
|
|
69
|
+
export declare const resolveFrame: (declared: JsonValue | undefined, registry: FrameOriginRegistry | undefined) => FrameOutcome;
|
|
70
|
+
/**
|
|
71
|
+
* A node's frames, by the prop name that carried each one.
|
|
72
|
+
*
|
|
73
|
+
* Keyed by prop name rather than by anything this seam invented, because the
|
|
74
|
+
* prop is what the primitive already reads and what its schema already names.
|
|
75
|
+
* A primitive that declared `src` reads `loom.frames.src` and gets an outcome
|
|
76
|
+
* whenever the node carries that prop at all — including when what it carries
|
|
77
|
+
* is nonsense, which is the case a refusal exists for.
|
|
78
|
+
*
|
|
79
|
+
* The map has a null prototype, for the reason `NO_SLOTS` gives: a prop may be
|
|
80
|
+
* named `constructor`, and an ordinary object would answer that with a function
|
|
81
|
+
* off `Object.prototype`.
|
|
82
|
+
*/
|
|
83
|
+
export type NodeFrames = Readonly<Record<string, FrameOutcome | undefined>>;
|
|
84
|
+
export declare const NO_FRAMES: NodeFrames;
|
|
85
|
+
//# sourceMappingURL=resolution.d.ts.map
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
export const describeFrameRefusal = (refusal) => {
|
|
2
|
+
switch (refusal.reason) {
|
|
3
|
+
case "no-registry":
|
|
4
|
+
return `this render was given no framable origins — ${refusal.detail}`;
|
|
5
|
+
case "unlisted-origin":
|
|
6
|
+
return `no registered origin covers it — ${refusal.detail}`;
|
|
7
|
+
case "unframeable":
|
|
8
|
+
return `it is not an absolute http(s) URL — ${refusal.detail}`;
|
|
9
|
+
}
|
|
10
|
+
};
|
|
11
|
+
/**
|
|
12
|
+
* The whole check, as a pure function of a registry and a value.
|
|
13
|
+
*
|
|
14
|
+
* Total, like every other reading of something a model wrote: a prop that is
|
|
15
|
+
* not a string, or is a string that is not a URL, is refused with a reason
|
|
16
|
+
* rather than thrown over. The tree is AI-authored and the renderer is a total
|
|
17
|
+
* projection (0008) — a page cannot be lost because a proposal put a number
|
|
18
|
+
* where a URL goes.
|
|
19
|
+
*
|
|
20
|
+
* A missing registry refuses rather than permits, which is the same way the
|
|
21
|
+
* submission seam fails and for the same reason: the registry *is* the
|
|
22
|
+
* allowlist, so a deployment that has not written one has not decided to frame
|
|
23
|
+
* anybody, and defaulting to "frame it" would make the seam a formality that
|
|
24
|
+
* every host has to remember to switch on.
|
|
25
|
+
*/
|
|
26
|
+
export const resolveFrame = (declared, registry) => {
|
|
27
|
+
if (typeof declared !== "string") {
|
|
28
|
+
return {
|
|
29
|
+
status: "refused",
|
|
30
|
+
refusal: {
|
|
31
|
+
reason: "unframeable",
|
|
32
|
+
detail: declared === undefined ? "no value was given" : `got ${typeof declared}`,
|
|
33
|
+
},
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
let url;
|
|
37
|
+
try {
|
|
38
|
+
url = new URL(declared);
|
|
39
|
+
}
|
|
40
|
+
catch {
|
|
41
|
+
return {
|
|
42
|
+
status: "refused",
|
|
43
|
+
refusal: { reason: "unframeable", detail: `"${declared}" does not parse as a URL` },
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
if (!["http:", "https:"].includes(url.protocol)) {
|
|
47
|
+
return {
|
|
48
|
+
status: "refused",
|
|
49
|
+
refusal: { reason: "unframeable", detail: `"${url.protocol}" is not an http(s) scheme` },
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Checked after parsing rather than before, so a `javascript:` src is refused
|
|
54
|
+
* as unframeable on every deployment — including one that wired no allowlist
|
|
55
|
+
* — rather than being lumped in with the ordinary video nobody has permitted
|
|
56
|
+
* yet. The two are the same outcome and very different faults.
|
|
57
|
+
*/
|
|
58
|
+
if (!registry) {
|
|
59
|
+
return {
|
|
60
|
+
status: "refused",
|
|
61
|
+
refusal: { reason: "no-registry", detail: `"${url.origin}" was not checked against anything` },
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
const registered = registry.origin(url);
|
|
65
|
+
if (!registered) {
|
|
66
|
+
return {
|
|
67
|
+
status: "refused",
|
|
68
|
+
refusal: { reason: "unlisted-origin", detail: `"${url.origin}" is not registered` },
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
return {
|
|
72
|
+
status: "allowed",
|
|
73
|
+
url: url.href,
|
|
74
|
+
origin: registered.origin,
|
|
75
|
+
sameOrigin: registered.self,
|
|
76
|
+
};
|
|
77
|
+
};
|
|
78
|
+
export const NO_FRAMES = Object.freeze(Object.create(null));
|
|
79
|
+
//# sourceMappingURL=resolution.js.map
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The grammar of Loom's identifiers, as plain patterns and nothing else.
|
|
3
|
+
*
|
|
4
|
+
* The schemas in `ids.ts` and `primitive-type.ts` are built from these, so there
|
|
5
|
+
* is one definition of what a node id or a primitive type looks like. They live
|
|
6
|
+
* apart from the schemas for one reader: code that runs in a visitor's browser —
|
|
7
|
+
* the reader-signal broadcaster — needs to recognise an id without shipping the
|
|
8
|
+
* schema library to every page that asks for signals (0136).
|
|
9
|
+
*/
|
|
10
|
+
export declare const ID_BODY_MAX_LENGTH = 32;
|
|
11
|
+
export declare const ID_BODY_ALPHABET = "[0-9a-z]";
|
|
12
|
+
/** The pattern for one kind of id: its one-character prefix, an underscore, and the body. */
|
|
13
|
+
export declare const idPattern: (prefix: string) => RegExp;
|
|
14
|
+
export declare const NODE_ID_PATTERN: RegExp;
|
|
15
|
+
export declare const TREE_ID_PATTERN: RegExp;
|
|
16
|
+
/**
|
|
17
|
+
* The grammar of every name a tree uses to reach something a deployment
|
|
18
|
+
* registered: a primitive, a data source, a submission endpoint. Dot-namespaced
|
|
19
|
+
* kebab-case — `stack`, `commerce.product-card`, `contact.enquiry`.
|
|
20
|
+
*
|
|
21
|
+
* One pattern rather than one per registry, because the sameness is the point.
|
|
22
|
+
* A tree names a capability and a registry decides what that name reaches; a
|
|
23
|
+
* second grammar would say those are different kinds of name when they are not.
|
|
24
|
+
*/
|
|
25
|
+
export declare const NAMESPACED_ID_PATTERN: RegExp;
|
|
26
|
+
//# sourceMappingURL=grammar.d.ts.map
|
package/dist/grammar.js
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The grammar of Loom's identifiers, as plain patterns and nothing else.
|
|
3
|
+
*
|
|
4
|
+
* The schemas in `ids.ts` and `primitive-type.ts` are built from these, so there
|
|
5
|
+
* is one definition of what a node id or a primitive type looks like. They live
|
|
6
|
+
* apart from the schemas for one reader: code that runs in a visitor's browser —
|
|
7
|
+
* the reader-signal broadcaster — needs to recognise an id without shipping the
|
|
8
|
+
* schema library to every page that asks for signals (0136).
|
|
9
|
+
*/
|
|
10
|
+
export const ID_BODY_MAX_LENGTH = 32;
|
|
11
|
+
export const ID_BODY_ALPHABET = "[0-9a-z]";
|
|
12
|
+
const ID_BODY = `${ID_BODY_ALPHABET}{1,${ID_BODY_MAX_LENGTH}}`;
|
|
13
|
+
/** The pattern for one kind of id: its one-character prefix, an underscore, and the body. */
|
|
14
|
+
export const idPattern = (prefix) => new RegExp(`^${prefix}_${ID_BODY}$`);
|
|
15
|
+
export const NODE_ID_PATTERN = idPattern("n");
|
|
16
|
+
export const TREE_ID_PATTERN = idPattern("t");
|
|
17
|
+
const SEGMENT = "[a-z][a-z0-9]*(?:-[a-z0-9]+)*";
|
|
18
|
+
/**
|
|
19
|
+
* The grammar of every name a tree uses to reach something a deployment
|
|
20
|
+
* registered: a primitive, a data source, a submission endpoint. Dot-namespaced
|
|
21
|
+
* kebab-case — `stack`, `commerce.product-card`, `contact.enquiry`.
|
|
22
|
+
*
|
|
23
|
+
* One pattern rather than one per registry, because the sameness is the point.
|
|
24
|
+
* A tree names a capability and a registry decides what that name reaches; a
|
|
25
|
+
* second grammar would say those are different kinds of name when they are not.
|
|
26
|
+
*/
|
|
27
|
+
export const NAMESPACED_ID_PATTERN = new RegExp(`^${SEGMENT}(?:\\.${SEGMENT})*$`);
|
|
28
|
+
//# sourceMappingURL=grammar.js.map
|
package/dist/ids.d.ts
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
/**
|
|
3
|
+
* Identity scheme.
|
|
4
|
+
*
|
|
5
|
+
* A NodeId is minted once, when the node is first inserted, and never changes
|
|
6
|
+
* again — not on move, not on configure, not on re-render. Positional paths are
|
|
7
|
+
* derived views; the id is the ground truth. Every downstream system (deltas,
|
|
8
|
+
* provenance, telemetry, the editable decorator) addresses nodes by id, so id
|
|
9
|
+
* stability is what makes an edit to a live tree meaningful over time.
|
|
10
|
+
*
|
|
11
|
+
* Stability is not the same as uniqueness over time. A node that is removed
|
|
12
|
+
* takes its id out of the live tree, and what stops that id being minted again
|
|
13
|
+
* for a different node is `tree/identity.ts`, not this module — enforced within
|
|
14
|
+
* a delta and reported by the audit across a log (0038).
|
|
15
|
+
*
|
|
16
|
+
* Ids are opaque strings with a one-character kind prefix. The prefix is a
|
|
17
|
+
* debugging affordance and a cheap guard against passing a DeltaId where a
|
|
18
|
+
* NodeId belongs; the brand types are the real enforcement.
|
|
19
|
+
*/
|
|
20
|
+
export declare const nodeIdSchema: z.ZodBranded<z.ZodString, "NodeId">;
|
|
21
|
+
export type NodeId = z.infer<typeof nodeIdSchema>;
|
|
22
|
+
export declare const treeIdSchema: z.ZodBranded<z.ZodString, "TreeId">;
|
|
23
|
+
export type TreeId = z.infer<typeof treeIdSchema>;
|
|
24
|
+
export declare const deltaIdSchema: z.ZodBranded<z.ZodString, "DeltaId">;
|
|
25
|
+
export type DeltaId = z.infer<typeof deltaIdSchema>;
|
|
26
|
+
export declare const intentIdSchema: z.ZodBranded<z.ZodString, "IntentId">;
|
|
27
|
+
export type IntentId = z.infer<typeof intentIdSchema>;
|
|
28
|
+
export declare const proposalIdSchema: z.ZodBranded<z.ZodString, "ProposalId">;
|
|
29
|
+
export type ProposalId = z.infer<typeof proposalIdSchema>;
|
|
30
|
+
/**
|
|
31
|
+
* Id minting is a side effect, so it enters the runtime through this seam
|
|
32
|
+
* rather than being called directly from pure code. Tests and replay tooling
|
|
33
|
+
* inject a deterministic factory; production injects the random one.
|
|
34
|
+
*/
|
|
35
|
+
export interface IdFactory {
|
|
36
|
+
readonly nodeId: () => NodeId;
|
|
37
|
+
readonly treeId: () => TreeId;
|
|
38
|
+
readonly deltaId: () => DeltaId;
|
|
39
|
+
readonly intentId: () => IntentId;
|
|
40
|
+
readonly proposalId: () => ProposalId;
|
|
41
|
+
}
|
|
42
|
+
export declare const randomIdFactory: IdFactory;
|
|
43
|
+
/**
|
|
44
|
+
* Deterministic ids for tests and for replaying a recorded session. Counters
|
|
45
|
+
* are per-kind so a tree and its deltas read as `n_1, n_2 … d_1, d_2`. The
|
|
46
|
+
* namespace keeps two independent factories from minting the same id — a test
|
|
47
|
+
* that builds nodes for an existing tree passes one.
|
|
48
|
+
*
|
|
49
|
+
* The namespace is checked here rather than at the first mint. Interpolating it
|
|
50
|
+
* and validating only the result is what a lessons page hit with `set-n-q1`:
|
|
51
|
+
* the factory accepted it, and the failure arrived later as a bare Zod regex
|
|
52
|
+
* error inside whichever builder happened to run first, naming neither the
|
|
53
|
+
* namespace nor this call. Every id the factory would go on to mint is decided
|
|
54
|
+
* the moment the namespace is given, so this is the moment it can be refused.
|
|
55
|
+
*/
|
|
56
|
+
export declare const sequentialIdFactory: (namespace?: string) => IdFactory;
|
|
57
|
+
//# sourceMappingURL=ids.d.ts.map
|
package/dist/ids.js
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { ID_BODY_ALPHABET, ID_BODY_MAX_LENGTH, idPattern } from "./grammar.js";
|
|
3
|
+
/**
|
|
4
|
+
* Identity scheme.
|
|
5
|
+
*
|
|
6
|
+
* A NodeId is minted once, when the node is first inserted, and never changes
|
|
7
|
+
* again — not on move, not on configure, not on re-render. Positional paths are
|
|
8
|
+
* derived views; the id is the ground truth. Every downstream system (deltas,
|
|
9
|
+
* provenance, telemetry, the editable decorator) addresses nodes by id, so id
|
|
10
|
+
* stability is what makes an edit to a live tree meaningful over time.
|
|
11
|
+
*
|
|
12
|
+
* Stability is not the same as uniqueness over time. A node that is removed
|
|
13
|
+
* takes its id out of the live tree, and what stops that id being minted again
|
|
14
|
+
* for a different node is `tree/identity.ts`, not this module — enforced within
|
|
15
|
+
* a delta and reported by the audit across a log (0038).
|
|
16
|
+
*
|
|
17
|
+
* Ids are opaque strings with a one-character kind prefix. The prefix is a
|
|
18
|
+
* debugging affordance and a cheap guard against passing a DeltaId where a
|
|
19
|
+
* NodeId belongs; the brand types are the real enforcement.
|
|
20
|
+
*/
|
|
21
|
+
export const nodeIdSchema = z
|
|
22
|
+
.string()
|
|
23
|
+
.regex(idPattern("n"))
|
|
24
|
+
.brand();
|
|
25
|
+
export const treeIdSchema = z
|
|
26
|
+
.string()
|
|
27
|
+
.regex(idPattern("t"))
|
|
28
|
+
.brand();
|
|
29
|
+
export const deltaIdSchema = z
|
|
30
|
+
.string()
|
|
31
|
+
.regex(idPattern("d"))
|
|
32
|
+
.brand();
|
|
33
|
+
export const intentIdSchema = z
|
|
34
|
+
.string()
|
|
35
|
+
.regex(idPattern("i"))
|
|
36
|
+
.brand();
|
|
37
|
+
export const proposalIdSchema = z
|
|
38
|
+
.string()
|
|
39
|
+
.regex(idPattern("p"))
|
|
40
|
+
.brand();
|
|
41
|
+
const RANDOM_ID_LENGTH = 20;
|
|
42
|
+
const BASE36_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
|
|
43
|
+
const randomBody = () => {
|
|
44
|
+
const bytes = new Uint8Array(RANDOM_ID_LENGTH);
|
|
45
|
+
globalThis.crypto.getRandomValues(bytes);
|
|
46
|
+
return Array.from(bytes, (byte) => BASE36_ALPHABET[byte % BASE36_ALPHABET.length] ?? "0").join("");
|
|
47
|
+
};
|
|
48
|
+
export const randomIdFactory = {
|
|
49
|
+
nodeId: () => nodeIdSchema.parse(`n_${randomBody()}`),
|
|
50
|
+
treeId: () => treeIdSchema.parse(`t_${randomBody()}`),
|
|
51
|
+
deltaId: () => deltaIdSchema.parse(`d_${randomBody()}`),
|
|
52
|
+
intentId: () => intentIdSchema.parse(`i_${randomBody()}`),
|
|
53
|
+
proposalId: () => proposalIdSchema.parse(`p_${randomBody()}`),
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* The counter is appended to the namespace and the pair has to fit an id body,
|
|
57
|
+
* so the namespace cannot have all of it. Eight characters of headroom is a
|
|
58
|
+
* hundred million ids per kind, which is more than a deterministic run will ever
|
|
59
|
+
* mint, and it means a namespace that is legal at the first node is still legal
|
|
60
|
+
* at the last one — a bound that holds only until the counter grows a digit is
|
|
61
|
+
* the same fault with a longer fuse.
|
|
62
|
+
*/
|
|
63
|
+
const NAMESPACE_COUNTER_HEADROOM = 8;
|
|
64
|
+
const NAMESPACE_MAX_LENGTH = ID_BODY_MAX_LENGTH - NAMESPACE_COUNTER_HEADROOM;
|
|
65
|
+
const namespacePattern = new RegExp(`^${ID_BODY_ALPHABET}{0,${NAMESPACE_MAX_LENGTH}}$`);
|
|
66
|
+
/**
|
|
67
|
+
* The nearest legal namespace to the one that was refused, so the message ends
|
|
68
|
+
* in something to paste rather than in a rule to re-read. A namespace with
|
|
69
|
+
* nothing legal left in it has no repair to offer, and the caller is told to
|
|
70
|
+
* drop the argument instead.
|
|
71
|
+
*/
|
|
72
|
+
const suggestNamespace = (namespace) => {
|
|
73
|
+
const repaired = namespace.toLowerCase().replace(/[^0-9a-z]/g, "").slice(0, NAMESPACE_MAX_LENGTH);
|
|
74
|
+
return repaired === "" ? "pass no namespace at all" : JSON.stringify(repaired);
|
|
75
|
+
};
|
|
76
|
+
/**
|
|
77
|
+
* Deterministic ids for tests and for replaying a recorded session. Counters
|
|
78
|
+
* are per-kind so a tree and its deltas read as `n_1, n_2 … d_1, d_2`. The
|
|
79
|
+
* namespace keeps two independent factories from minting the same id — a test
|
|
80
|
+
* that builds nodes for an existing tree passes one.
|
|
81
|
+
*
|
|
82
|
+
* The namespace is checked here rather than at the first mint. Interpolating it
|
|
83
|
+
* and validating only the result is what a lessons page hit with `set-n-q1`:
|
|
84
|
+
* the factory accepted it, and the failure arrived later as a bare Zod regex
|
|
85
|
+
* error inside whichever builder happened to run first, naming neither the
|
|
86
|
+
* namespace nor this call. Every id the factory would go on to mint is decided
|
|
87
|
+
* the moment the namespace is given, so this is the moment it can be refused.
|
|
88
|
+
*/
|
|
89
|
+
export const sequentialIdFactory = (namespace = "") => {
|
|
90
|
+
if (!namespacePattern.test(namespace)) {
|
|
91
|
+
throw new Error(`loom: sequentialIdFactory was given the namespace ${JSON.stringify(namespace)}, which cannot appear in an id. ` +
|
|
92
|
+
`A namespace is lowercase letters and digits only, at most ${NAMESPACE_MAX_LENGTH} of them — no hyphens, ` +
|
|
93
|
+
`underscores or capitals. Try ${suggestNamespace(namespace)}.`);
|
|
94
|
+
}
|
|
95
|
+
const counters = { node: 0, tree: 0, delta: 0, intent: 0, proposal: 0 };
|
|
96
|
+
return {
|
|
97
|
+
nodeId: () => nodeIdSchema.parse(`n_${namespace}${(counters.node += 1)}`),
|
|
98
|
+
treeId: () => treeIdSchema.parse(`t_${namespace}${(counters.tree += 1)}`),
|
|
99
|
+
deltaId: () => deltaIdSchema.parse(`d_${namespace}${(counters.delta += 1)}`),
|
|
100
|
+
intentId: () => intentIdSchema.parse(`i_${namespace}${(counters.intent += 1)}`),
|
|
101
|
+
proposalId: () => proposalIdSchema.parse(`p_${namespace}${(counters.proposal += 1)}`),
|
|
102
|
+
};
|
|
103
|
+
};
|
|
104
|
+
//# sourceMappingURL=ids.js.map
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The whole of Loom that a host imports by name.
|
|
3
|
+
*
|
|
4
|
+
* Everything re-exported here is public: the tree and its deltas, the runtime that
|
|
5
|
+
* judges a change, the interpretation seam, and the vocabularies the three share.
|
|
6
|
+
* The narrower entry points exist so a host can take a part of it without the
|
|
7
|
+
* rest.
|
|
8
|
+
*/
|
|
9
|
+
export * from "./catalogue.js";
|
|
10
|
+
export * from "./data/index.js";
|
|
11
|
+
export * from "./deadline.js";
|
|
12
|
+
export * from "./frame/index.js";
|
|
13
|
+
export * from "./ids.js";
|
|
14
|
+
export * from "./interactivity.js";
|
|
15
|
+
export * from "./interpretation/index.js";
|
|
16
|
+
export * from "./json.js";
|
|
17
|
+
export * from "./paging.js";
|
|
18
|
+
export * from "./primitive-type.js";
|
|
19
|
+
export * from "./reserved-props.js";
|
|
20
|
+
export * from "./result.js";
|
|
21
|
+
export * from "./role.js";
|
|
22
|
+
export * from "./runtime/index.js";
|
|
23
|
+
export * from "./submit/index.js";
|
|
24
|
+
export * from "./theme/index.js";
|
|
25
|
+
export * from "./tree/index.js";
|
|
26
|
+
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The whole of Loom that a host imports by name.
|
|
3
|
+
*
|
|
4
|
+
* Everything re-exported here is public: the tree and its deltas, the runtime that
|
|
5
|
+
* judges a change, the interpretation seam, and the vocabularies the three share.
|
|
6
|
+
* The narrower entry points exist so a host can take a part of it without the
|
|
7
|
+
* rest.
|
|
8
|
+
*/
|
|
9
|
+
export * from "./catalogue.js";
|
|
10
|
+
export * from "./data/index.js";
|
|
11
|
+
export * from "./deadline.js";
|
|
12
|
+
export * from "./frame/index.js";
|
|
13
|
+
export * from "./ids.js";
|
|
14
|
+
export * from "./interactivity.js";
|
|
15
|
+
export * from "./interpretation/index.js";
|
|
16
|
+
export * from "./json.js";
|
|
17
|
+
export * from "./paging.js";
|
|
18
|
+
export * from "./primitive-type.js";
|
|
19
|
+
export * from "./reserved-props.js";
|
|
20
|
+
export * from "./result.js";
|
|
21
|
+
export * from "./role.js";
|
|
22
|
+
export * from "./runtime/index.js";
|
|
23
|
+
export * from "./submit/index.js";
|
|
24
|
+
export * from "./theme/index.js";
|
|
25
|
+
export * from "./tree/index.js";
|
|
26
|
+
//# sourceMappingURL=index.js.map
|