@jam-overture/loom 0.1.0 → 0.3.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/README.md +3 -1
- package/dist/application/application.d.ts +109 -0
- package/dist/application/application.js +97 -0
- package/dist/application/memory.d.ts +20 -0
- package/dist/application/memory.js +79 -0
- package/dist/application/store.d.ts +101 -0
- package/dist/application/store.js +25 -0
- package/dist/audience/audience.d.ts +36 -0
- package/dist/audience/audience.js +41 -0
- package/dist/audience/compose.d.ts +112 -0
- package/dist/audience/compose.js +134 -0
- package/dist/audience/memory.d.ts +14 -0
- package/dist/audience/memory.js +71 -0
- package/dist/audience/overlay-store.d.ts +343 -0
- package/dist/audience/overlay-store.js +217 -0
- package/dist/audience/rule.d.ts +121 -0
- package/dist/audience/rule.js +78 -0
- package/dist/cli/index.d.ts +3 -4
- package/dist/cli/index.js +3 -4
- package/dist/cli/templates.js +19 -0
- package/dist/data/adapter.d.ts +9 -1
- package/dist/data/adapter.js +2 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +23 -1
- package/dist/data/resolve.d.ts +31 -4
- package/dist/data/resolve.js +11 -3
- package/dist/ids.d.ts +10 -0
- package/dist/ids.js +11 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/interpretation/anthropic.d.ts +1 -1
- package/dist/interpretation/anthropic.js +2 -22
- package/dist/interpretation/client.d.ts +1 -1
- package/dist/interpretation/materialize.js +67 -22
- package/dist/interpretation/openai-compatible.d.ts +36 -0
- package/dist/interpretation/openai-compatible.js +79 -0
- package/dist/interpretation/status.d.ts +19 -0
- package/dist/interpretation/status.js +26 -0
- package/dist/live/index.d.ts +73 -0
- package/dist/live/index.js +73 -0
- package/dist/live/pages.d.ts +187 -0
- package/dist/live/pages.js +161 -0
- package/dist/live/pull.d.ts +147 -0
- package/dist/live/pull.js +398 -0
- package/dist/live/pulling.d.ts +79 -0
- package/dist/live/pulling.js +117 -0
- package/dist/live/window.d.ts +129 -0
- package/dist/live/window.js +132 -0
- package/dist/patch.d.ts +54 -0
- package/dist/patch.js +44 -0
- package/dist/project/closing.d.ts +51 -0
- package/dist/project/closing.js +53 -0
- package/dist/project/memory.d.ts +20 -0
- package/dist/project/memory.js +97 -0
- package/dist/project/project.d.ts +90 -0
- package/dist/project/project.js +91 -0
- package/dist/project/store.d.ts +135 -0
- package/dist/project/store.js +41 -0
- package/dist/registered.d.ts +64 -0
- package/dist/registered.js +118 -0
- package/dist/render/addressed.d.ts +35 -0
- package/dist/render/addressed.js +79 -0
- package/dist/render/behaviour-adjust.d.ts +11 -19
- package/dist/render/behaviour-adjust.js +75 -21
- package/dist/render/behaviour-present.d.ts +8 -0
- package/dist/render/behaviour-present.js +57 -6
- package/dist/render/behaviour.d.ts +98 -17
- package/dist/render/behaviour.js +91 -26
- package/dist/render/control-name.d.ts +68 -0
- package/dist/render/control-name.js +37 -0
- package/dist/render/diagnostics.d.ts +72 -0
- package/dist/render/diagnostics.js +7 -0
- package/dist/render/document-theme.d.ts +70 -0
- package/dist/render/document-theme.js +139 -0
- package/dist/render/editable.d.ts +15 -1
- package/dist/render/editable.js +13 -1
- package/dist/render/expected.d.ts +98 -0
- package/dist/render/expected.js +88 -0
- package/dist/render/index.d.ts +4 -0
- package/dist/render/index.js +4 -0
- package/dist/render/reads.d.ts +11 -0
- package/dist/render/reads.js +12 -1
- package/dist/render/render.d.ts +11 -0
- package/dist/render/render.js +294 -53
- package/dist/render/request.d.ts +8 -1
- package/dist/render/request.js +1 -0
- package/dist/render/slots.d.ts +52 -0
- package/dist/render/slots.js +24 -0
- package/dist/render/theme.d.ts +54 -1
- package/dist/render/theme.js +23 -1
- package/dist/render/unshown.d.ts +152 -0
- package/dist/render/unshown.js +80 -0
- package/dist/runtime/analysis.d.ts +94 -9
- package/dist/runtime/analysis.js +54 -9
- package/dist/runtime/assessment.d.ts +36 -2
- package/dist/runtime/assessment.js +27 -2
- package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
- package/dist/runtime/auto-apply-ceiling.js +66 -0
- package/dist/runtime/checks.d.ts +148 -0
- package/dist/runtime/checks.js +112 -0
- package/dist/runtime/disposition.d.ts +96 -0
- package/dist/runtime/disposition.js +46 -0
- package/dist/runtime/gate.js +91 -10
- package/dist/runtime/index.d.ts +4 -0
- package/dist/runtime/index.js +4 -0
- package/dist/runtime/irreversibility.d.ts +64 -0
- package/dist/runtime/irreversibility.js +45 -0
- package/dist/runtime/nesting.d.ts +13 -1
- package/dist/runtime/nesting.js +41 -24
- package/dist/runtime/pipeline.d.ts +43 -0
- package/dist/runtime/pipeline.js +10 -2
- package/dist/runtime/policy-change.d.ts +93 -0
- package/dist/runtime/policy-change.js +305 -0
- package/dist/runtime/policy-log.d.ts +406 -0
- package/dist/runtime/policy-log.js +285 -0
- package/dist/runtime/policy.d.ts +8 -6
- package/dist/runtime/policy.js +5 -2
- package/dist/runtime/repointing.js +0 -0
- package/dist/runtime/reversibility.d.ts +11 -9
- package/dist/runtime/stakes.d.ts +129 -1
- package/dist/runtime/stakes.js +240 -26
- package/dist/runtime/vocabulary.d.ts +164 -7
- package/dist/runtime/vocabulary.js +181 -8
- package/dist/sdk/audit.d.ts +174 -3
- package/dist/sdk/audit.js +176 -17
- package/dist/sdk/catalogue.d.ts +9 -1
- package/dist/sdk/conformance.d.ts +37 -3
- package/dist/sdk/conformance.js +25 -4
- package/dist/sdk/definition.d.ts +129 -5
- package/dist/sdk/definition.js +66 -0
- package/dist/sdk/registry.d.ts +45 -2
- package/dist/sdk/registry.js +102 -1
- package/dist/signals/acted.contract.d.ts +21 -0
- package/dist/signals/acted.contract.js +236 -0
- package/dist/signals/acted.d.ts +359 -0
- package/dist/signals/acted.js +135 -0
- package/dist/signals/action-change.d.ts +507 -0
- package/dist/signals/action-change.js +265 -0
- package/dist/signals/action.d.ts +331 -0
- package/dist/signals/action.js +182 -0
- package/dist/signals/agenda.d.ts +585 -0
- package/dist/signals/agenda.js +295 -0
- package/dist/signals/applied-window.contract.d.ts +23 -0
- package/dist/signals/applied-window.contract.js +160 -0
- package/dist/signals/arrivals.contract.d.ts +21 -0
- package/dist/signals/arrivals.contract.js +180 -0
- package/dist/signals/arrivals.d.ts +375 -0
- package/dist/signals/arrivals.js +254 -0
- package/dist/signals/arriving.d.ts +210 -0
- package/dist/signals/arriving.js +133 -0
- package/dist/signals/audiences.d.ts +528 -0
- package/dist/signals/audiences.js +255 -0
- package/dist/signals/broadcast.d.ts +33 -17
- package/dist/signals/broadcast.js +255 -32
- package/dist/signals/change.d.ts +378 -0
- package/dist/signals/change.js +327 -0
- package/dist/signals/collect.d.ts +169 -34
- package/dist/signals/collect.js +186 -38
- package/dist/signals/conversion.d.ts +348 -0
- package/dist/signals/conversion.js +235 -0
- package/dist/signals/copy-change.d.ts +553 -0
- package/dist/signals/copy-change.js +377 -0
- package/dist/signals/copy.d.ts +337 -0
- package/dist/signals/copy.js +211 -0
- package/dist/signals/correlated.contract.d.ts +24 -0
- package/dist/signals/correlated.contract.js +94 -0
- package/dist/signals/counters.d.ts +97 -0
- package/dist/signals/counters.js +160 -0
- package/dist/signals/deliver.d.ts +23 -4
- package/dist/signals/deliver.js +34 -6
- package/dist/signals/deployment-change.d.ts +395 -0
- package/dist/signals/deployment-change.js +309 -0
- package/dist/signals/deployment.d.ts +278 -0
- package/dist/signals/deployment.js +178 -0
- package/dist/signals/door.d.ts +114 -0
- package/dist/signals/door.js +77 -0
- package/dist/signals/expire.d.ts +192 -0
- package/dist/signals/expire.js +213 -0
- package/dist/signals/fold.d.ts +10 -0
- package/dist/signals/fold.js +5 -1
- package/dist/signals/form-action.d.ts +302 -0
- package/dist/signals/form-action.js +169 -0
- package/dist/signals/form-copy.d.ts +523 -0
- package/dist/signals/form-copy.js +346 -0
- package/dist/signals/forms.d.ts +247 -0
- package/dist/signals/forms.js +147 -0
- package/dist/signals/frontier.d.ts +268 -0
- package/dist/signals/frontier.js +145 -0
- package/dist/signals/funnel-change.d.ts +548 -0
- package/dist/signals/funnel-change.js +361 -0
- package/dist/signals/funnel-hours.contract.d.ts +21 -0
- package/dist/signals/funnel-hours.contract.js +221 -0
- package/dist/signals/funnel-hours.d.ts +293 -0
- package/dist/signals/funnel-hours.js +99 -0
- package/dist/signals/funnel.d.ts +592 -0
- package/dist/signals/funnel.js +231 -0
- package/dist/signals/health.d.ts +694 -0
- package/dist/signals/health.js +573 -0
- package/dist/signals/index.d.ts +60 -0
- package/dist/signals/index.js +60 -0
- package/dist/signals/ingest.d.ts +56 -1
- package/dist/signals/ingest.js +91 -1
- package/dist/signals/inside.d.ts +190 -0
- package/dist/signals/inside.js +263 -0
- package/dist/signals/join.d.ts +56 -0
- package/dist/signals/join.js +60 -0
- package/dist/signals/journal.d.ts +123 -9
- package/dist/signals/kept.contract.d.ts +22 -0
- package/dist/signals/kept.contract.js +111 -0
- package/dist/signals/kinds.d.ts +8 -6
- package/dist/signals/kinds.js +14 -6
- package/dist/signals/library-action.d.ts +430 -0
- package/dist/signals/library-action.js +336 -0
- package/dist/signals/library-agenda-change.d.ts +324 -0
- package/dist/signals/library-agenda-change.js +199 -0
- package/dist/signals/library-agenda.d.ts +258 -0
- package/dist/signals/library-agenda.js +167 -0
- package/dist/signals/library-change.d.ts +477 -0
- package/dist/signals/library-change.js +335 -0
- package/dist/signals/library-copy-change.d.ts +498 -0
- package/dist/signals/library-copy-change.js +476 -0
- package/dist/signals/library-pace.d.ts +319 -0
- package/dist/signals/library-pace.js +305 -0
- package/dist/signals/library-reach-change.d.ts +646 -0
- package/dist/signals/library-reach-change.js +542 -0
- package/dist/signals/library-reach.d.ts +377 -0
- package/dist/signals/library-reach.js +227 -0
- package/dist/signals/library-senders-change.d.ts +457 -0
- package/dist/signals/library-senders-change.js +367 -0
- package/dist/signals/library-senders-reach-change.d.ts +486 -0
- package/dist/signals/library-senders-reach-change.js +538 -0
- package/dist/signals/library-senders-reach.d.ts +340 -0
- package/dist/signals/library-senders-reach.js +252 -0
- package/dist/signals/library-senders.d.ts +271 -0
- package/dist/signals/library-senders.js +180 -0
- package/dist/signals/library-word-reach-change.d.ts +567 -0
- package/dist/signals/library-word-reach-change.js +564 -0
- package/dist/signals/library.d.ts +306 -0
- package/dist/signals/library.js +178 -0
- package/dist/signals/memory.d.ts +9 -0
- package/dist/signals/memory.js +246 -14
- package/dist/signals/migrate.d.ts +20 -4
- package/dist/signals/migrate.js +269 -8
- package/dist/signals/notice.d.ts +389 -0
- package/dist/signals/notice.js +250 -0
- package/dist/signals/pace-change.d.ts +501 -0
- package/dist/signals/pace-change.js +310 -0
- package/dist/signals/pace.d.ts +296 -0
- package/dist/signals/pace.js +291 -0
- package/dist/signals/page-views.d.ts +365 -0
- package/dist/signals/page-views.js +218 -0
- package/dist/signals/part-pace.d.ts +378 -0
- package/dist/signals/part-pace.js +333 -0
- package/dist/signals/parts.d.ts +354 -0
- package/dist/signals/parts.js +232 -0
- package/dist/signals/postgres.d.ts +16 -2
- package/dist/signals/postgres.js +753 -76
- package/dist/signals/progress.d.ts +212 -0
- package/dist/signals/progress.js +150 -0
- package/dist/signals/ratios.d.ts +108 -0
- package/dist/signals/ratios.js +40 -0
- package/dist/signals/reach.d.ts +309 -0
- package/dist/signals/reach.js +93 -0
- package/dist/signals/readable.d.ts +34 -0
- package/dist/signals/readable.js +34 -0
- package/dist/signals/readership.d.ts +381 -0
- package/dist/signals/readership.js +308 -0
- package/dist/signals/region-pages.d.ts +173 -0
- package/dist/signals/region-pages.js +62 -0
- package/dist/signals/region.d.ts +287 -0
- package/dist/signals/region.js +198 -0
- package/dist/signals/retention.d.ts +163 -0
- package/dist/signals/retention.js +75 -0
- package/dist/signals/rhythm.d.ts +302 -0
- package/dist/signals/rhythm.js +262 -0
- package/dist/signals/rollup.d.ts +194 -4
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +1069 -1
- package/dist/signals/schema.js +393 -3
- package/dist/signals/signal.d.ts +237 -11
- package/dist/signals/signal.js +70 -10
- package/dist/signals/silence-census.d.ts +205 -0
- package/dist/signals/silence-census.js +87 -0
- package/dist/signals/silences.d.ts +1147 -0
- package/dist/signals/silences.js +996 -0
- package/dist/signals/subtrees.d.ts +123 -0
- package/dist/signals/subtrees.js +102 -0
- package/dist/signals/tally.d.ts +262 -12
- package/dist/signals/unread.d.ts +292 -0
- package/dist/signals/unread.js +137 -0
- package/dist/signals/window-agenda.d.ts +276 -0
- package/dist/signals/window-agenda.js +83 -0
- package/dist/signals/window-figures.d.ts +148 -0
- package/dist/signals/window-figures.js +42 -0
- package/dist/signals/window-funnels.d.ts +88 -0
- package/dist/signals/window-funnels.js +47 -0
- package/dist/signals/window.d.ts +866 -0
- package/dist/signals/window.js +693 -0
- package/dist/signals/words.d.ts +24 -0
- package/dist/signals/words.js +24 -0
- package/dist/store/cache.d.ts +101 -0
- package/dist/store/cache.js +149 -0
- package/dist/store/history.d.ts +82 -0
- package/dist/store/history.js +36 -0
- package/dist/store/index.d.ts +30 -0
- package/dist/store/index.js +30 -0
- package/dist/store/memory.d.ts +2 -1
- package/dist/store/memory.js +48 -12
- package/dist/store/migrate.d.ts +106 -0
- package/dist/store/migrate.js +323 -7
- package/dist/store/postgres-applications.d.ts +4 -0
- package/dist/store/postgres-applications.js +197 -0
- package/dist/store/postgres-audience.d.ts +14 -0
- package/dist/store/postgres-audience.js +272 -0
- package/dist/store/postgres-holds.d.ts +10 -1
- package/dist/store/postgres-holds.js +116 -101
- package/dist/store/postgres-policy-log.d.ts +14 -0
- package/dist/store/postgres-policy-log.js +240 -0
- package/dist/store/postgres-projects.d.ts +4 -0
- package/dist/store/postgres-projects.js +217 -0
- package/dist/store/postgres.d.ts +17 -1
- package/dist/store/postgres.js +60 -9
- package/dist/store/replay.d.ts +102 -1
- package/dist/store/replay.js +190 -19
- package/dist/store/reseed.d.ts +238 -0
- package/dist/store/reseed.js +308 -0
- package/dist/store/schema.d.ts +762 -2
- package/dist/store/schema.js +218 -5
- package/dist/store/source.d.ts +57 -1
- package/dist/store/source.js +65 -1
- package/dist/store/store.d.ts +29 -6
- package/dist/submit/resolve.d.ts +1 -1
- package/dist/submit/resolve.js +2 -1
- package/dist/telemetry/calibration.d.ts +25 -0
- package/dist/telemetry/calibration.js +27 -1
- package/dist/telemetry/event.d.ts +391 -33
- package/dist/telemetry/event.js +84 -20
- package/dist/telemetry/index.d.ts +2 -0
- package/dist/telemetry/index.js +2 -0
- package/dist/telemetry/journal.d.ts +104 -3
- package/dist/telemetry/journal.js +9 -0
- package/dist/telemetry/lookup.d.ts +27 -0
- package/dist/telemetry/lookup.js +18 -0
- package/dist/telemetry/memory.js +33 -1
- package/dist/telemetry/migrate.js +22 -1
- package/dist/telemetry/postgres.d.ts +10 -1
- package/dist/telemetry/postgres.js +188 -90
- package/dist/telemetry/remeasure.d.ts +78 -0
- package/dist/telemetry/remeasure.js +83 -0
- package/dist/telemetry/retention.d.ts +2 -2
- package/dist/telemetry/schema.d.ts +17 -0
- package/dist/telemetry/schema.js +27 -1
- package/dist/telemetry/sink.d.ts +2 -2
- package/dist/telemetry/window.d.ts +135 -0
- package/dist/telemetry/window.js +101 -0
- package/dist/testing/application-contract.d.ts +14 -0
- package/dist/testing/application-contract.js +270 -0
- package/dist/testing/audience-overlay-contract.d.ts +31 -0
- package/dist/testing/audience-overlay-contract.js +354 -0
- package/dist/testing/contracts.d.ts +13 -7
- package/dist/testing/contracts.js +13 -7
- package/dist/testing/definitions.d.ts +78 -0
- package/dist/testing/definitions.js +134 -9
- package/dist/testing/doubles.d.ts +103 -0
- package/dist/testing/doubles.js +143 -0
- package/dist/testing/index.d.ts +2 -2
- package/dist/testing/index.js +2 -2
- package/dist/testing/journal-contract.js +297 -6
- package/dist/testing/model-contract.d.ts +110 -0
- package/dist/testing/model-contract.js +150 -0
- package/dist/testing/policy-log-contract.d.ts +26 -0
- package/dist/testing/policy-log-contract.js +344 -0
- package/dist/testing/project-contract.d.ts +14 -0
- package/dist/testing/project-contract.js +266 -0
- package/dist/testing/reader-signal-contract.d.ts +27 -2
- package/dist/testing/reader-signal-contract.js +475 -5
- package/dist/testing/store-contract.d.ts +7 -1
- package/dist/testing/store-contract.js +84 -3
- package/dist/theme/apply.d.ts +20 -1
- package/dist/theme/apply.js +5 -3
- package/dist/theme/contrast.d.ts +19 -14
- package/dist/theme/contrast.js +181 -17
- package/dist/theme/derive.d.ts +22 -0
- package/dist/theme/derive.js +54 -1
- package/dist/theme/library.js +1 -1
- package/dist/theme/measure.d.ts +34 -0
- package/dist/theme/measure.js +30 -1
- package/dist/theme/palettes.js +7 -7
- package/dist/theme/ramp.d.ts +64 -0
- package/dist/theme/ramp.js +114 -0
- package/dist/theme/registry.d.ts +9 -0
- package/dist/theme/registry.js +11 -1
- package/dist/theme/separation.d.ts +97 -3
- package/dist/theme/separation.js +75 -0
- package/dist/tree/apply.js +13 -0
- package/dist/tree/compare.d.ts +9 -0
- package/dist/tree/compare.js +18 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +24 -12
- package/dist/tree/navigation.d.ts +5 -0
- package/dist/tree/navigation.js +32 -10
- package/dist/tree/outline.d.ts +7 -0
- package/dist/tree/outline.js +9 -5
- package/dist/write/computed.d.ts +60 -0
- package/dist/write/computed.js +61 -0
- package/dist/write/held.d.ts +59 -0
- package/dist/write/index.d.ts +5 -2
- package/dist/write/index.js +5 -2
- package/dist/write/reseed.d.ts +151 -0
- package/dist/write/reseed.js +184 -0
- package/dist/write/revert.js +2 -16
- package/package.json +25 -3
- package/dist/runtime/inverse-interpreter.d.ts +0 -90
- package/dist/runtime/inverse-interpreter.js +0 -56
package/README.md
CHANGED
|
@@ -436,7 +436,9 @@ The runtime compiles to `dist/` and every entry point resolves there (0030), so
|
|
|
436
436
|
the application consumes it as an ordinary Node package rather than as TypeScript
|
|
437
437
|
source. `apps/loom` builds the runtime before its own typecheck and build,
|
|
438
438
|
because a clean clone has no `dist` and a build order that is not written down is
|
|
439
|
-
one that fails somewhere else.
|
|
439
|
+
one that fails somewhere else. Its `verify` runs the build first and then calls
|
|
440
|
+
`tsc` directly rather than `pnpm typecheck`, because the build has just compiled
|
|
441
|
+
the runtime and compiling it a second time bought nothing.
|
|
440
442
|
|
|
441
443
|
## Deploying
|
|
442
444
|
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The thing a customer registers with Loom, and the unit everything is stored
|
|
3
|
+
* and governed under.
|
|
4
|
+
*
|
|
5
|
+
* A deployment used to be one registry, one policy source and one store wired
|
|
6
|
+
* at a composition root, with no identifier anywhere for the thing that owned
|
|
7
|
+
* them — there had only ever been one per process (0220). An application is
|
|
8
|
+
* that identifier, and every tree, revision, hold and signal sits inside one. A
|
|
9
|
+
* tree id is unique within its application and says nothing about any other.
|
|
10
|
+
*
|
|
11
|
+
* It is the third of three levels: an **account** holds **projects**, and a
|
|
12
|
+
* project holds **applications** (0269). The level above this one is a grouping
|
|
13
|
+
* and owns nothing yet, which is why nothing here defers to it but the
|
|
14
|
+
* `projectId` an application carries.
|
|
15
|
+
*/
|
|
16
|
+
import { z } from "zod";
|
|
17
|
+
export declare const applicationIdSchema: z.ZodBranded<z.ZodString, "ApplicationId">;
|
|
18
|
+
export type ApplicationId = z.infer<typeof applicationIdSchema>;
|
|
19
|
+
/**
|
|
20
|
+
* A new application's id, minted when somebody registers one.
|
|
21
|
+
*
|
|
22
|
+
* Random rather than derived from the name: a name is editable and not unique,
|
|
23
|
+
* and an id that was derived from one would either change when it is renamed or
|
|
24
|
+
* preserve a name somebody wanted gone. It is also the value a person pastes
|
|
25
|
+
* into their own configuration, so it must not say anything about them.
|
|
26
|
+
*/
|
|
27
|
+
export declare const newApplicationId: () => ApplicationId;
|
|
28
|
+
/**
|
|
29
|
+
* The application every row written before applications existed belongs to.
|
|
30
|
+
*
|
|
31
|
+
* Nothing is migrated by guessing (0260). The rows that exist belong to the
|
|
32
|
+
* deployment that wrote them, so they go into one application named for it rather
|
|
33
|
+
* than into a distribution somebody invented. It is also what a store
|
|
34
|
+
* built without an application uses, which is what keeps every existing caller —
|
|
35
|
+
* the demo, the documentation's worked examples, the eight thousand tests —
|
|
36
|
+
* meaning exactly what it meant before.
|
|
37
|
+
*
|
|
38
|
+
* **It is not a null.** Every read filters on it and every write sets it, so
|
|
39
|
+
* it is an application like any other; what makes it the default is only that it is
|
|
40
|
+
* the one a caller gets by saying nothing.
|
|
41
|
+
*/
|
|
42
|
+
export declare const DEFAULT_APPLICATION_ID: ApplicationId;
|
|
43
|
+
/**
|
|
44
|
+
* What a deployment knows about one of its applications.
|
|
45
|
+
*
|
|
46
|
+
* Deliberately thin. The registry, the policy and the ingest credential are
|
|
47
|
+
* each their own concern with their own store — this is the row that says the
|
|
48
|
+
* application exists and what a person calls it, and nothing that another module
|
|
49
|
+
* already owns.
|
|
50
|
+
*/
|
|
51
|
+
export declare const applicationSchema: z.ZodObject<{
|
|
52
|
+
applicationId: z.ZodBranded<z.ZodString, "ApplicationId">;
|
|
53
|
+
/**
|
|
54
|
+
* The project it is grouped under, which every application has exactly one
|
|
55
|
+
* of. The grouping is organisational and nothing else yet — a project owns
|
|
56
|
+
* no policy and no members, so nothing reads this but a screen deciding
|
|
57
|
+
* which heading to put the application under. When it does own something,
|
|
58
|
+
* this is the edge that inheritance travels along.
|
|
59
|
+
*/
|
|
60
|
+
projectId: z.ZodBranded<z.ZodString, "ProjectId">;
|
|
61
|
+
/** What a person calls it. Not unique, not an identifier, and editable. */
|
|
62
|
+
name: z.ZodString;
|
|
63
|
+
createdAt: z.ZodString;
|
|
64
|
+
/**
|
|
65
|
+
* Where the application lives, when it has said so. Used to tell a reader
|
|
66
|
+
* which application they are looking at, and to decide which origin may
|
|
67
|
+
* post its readers' signals — that one exactly, when it is set (0298).
|
|
68
|
+
*/
|
|
69
|
+
host: z.ZodOptional<z.ZodString>;
|
|
70
|
+
/**
|
|
71
|
+
* When it was closed, or absent while it is open (0289). See
|
|
72
|
+
* `Project.closedAt`, which this follows in every respect but one: an
|
|
73
|
+
* application is closed *by* its project closing, and is not reopened by
|
|
74
|
+
* its project reopening.
|
|
75
|
+
*
|
|
76
|
+
* A closed application takes no signals. That is enforced where ingest
|
|
77
|
+
* learns which application is posting, which is the host's door rather
|
|
78
|
+
* than this schema (0298).
|
|
79
|
+
*/
|
|
80
|
+
closedAt: z.ZodOptional<z.ZodString>;
|
|
81
|
+
}, "strict", z.ZodTypeAny, {
|
|
82
|
+
name: string;
|
|
83
|
+
projectId: string & z.BRAND<"ProjectId">;
|
|
84
|
+
createdAt: string;
|
|
85
|
+
applicationId: string & z.BRAND<"ApplicationId">;
|
|
86
|
+
closedAt?: string | undefined;
|
|
87
|
+
host?: string | undefined;
|
|
88
|
+
}, {
|
|
89
|
+
name: string;
|
|
90
|
+
projectId: string;
|
|
91
|
+
createdAt: string;
|
|
92
|
+
applicationId: string;
|
|
93
|
+
closedAt?: string | undefined;
|
|
94
|
+
host?: string | undefined;
|
|
95
|
+
}>;
|
|
96
|
+
export type Application = z.infer<typeof applicationSchema>;
|
|
97
|
+
/**
|
|
98
|
+
* The application a store handle speaks for.
|
|
99
|
+
*
|
|
100
|
+
* A handle is scoped at construction rather than every method taking a
|
|
101
|
+
* application, which is the cheaper of the two shapes that were priced (0220):
|
|
102
|
+
* it leaves every signature in `@jam-overture/loom/store` alone, and
|
|
103
|
+
* it makes *spanning two applications* unexpressible rather than merely forbidden.
|
|
104
|
+
* A caller that wants two holds two handles.
|
|
105
|
+
*/
|
|
106
|
+
export type StoreScope = {
|
|
107
|
+
readonly application?: ApplicationId;
|
|
108
|
+
};
|
|
109
|
+
//# sourceMappingURL=application.d.ts.map
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The thing a customer registers with Loom, and the unit everything is stored
|
|
3
|
+
* and governed under.
|
|
4
|
+
*
|
|
5
|
+
* A deployment used to be one registry, one policy source and one store wired
|
|
6
|
+
* at a composition root, with no identifier anywhere for the thing that owned
|
|
7
|
+
* them — there had only ever been one per process (0220). An application is
|
|
8
|
+
* that identifier, and every tree, revision, hold and signal sits inside one. A
|
|
9
|
+
* tree id is unique within its application and says nothing about any other.
|
|
10
|
+
*
|
|
11
|
+
* It is the third of three levels: an **account** holds **projects**, and a
|
|
12
|
+
* project holds **applications** (0269). The level above this one is a grouping
|
|
13
|
+
* and owns nothing yet, which is why nothing here defers to it but the
|
|
14
|
+
* `projectId` an application carries.
|
|
15
|
+
*/
|
|
16
|
+
import { z } from "zod";
|
|
17
|
+
import { idPattern } from "../grammar.js";
|
|
18
|
+
import { randomIdBody } from "../ids.js";
|
|
19
|
+
import { projectIdSchema } from "../project/project.js";
|
|
20
|
+
/*
|
|
21
|
+
* `app` and not `a`: every other id in `ids.ts` wears a single letter, and an
|
|
22
|
+
* application id is the one identifier here that a person reads off a screen
|
|
23
|
+
* and pastes into their own configuration — so it is spelled rather than
|
|
24
|
+
* initialled, like the hosts that do the same job. It carried `prj` until the
|
|
25
|
+
* hierarchy was settled on 12 October, when *project* turned out to name the
|
|
26
|
+
* grouping above this rather than this.
|
|
27
|
+
*/
|
|
28
|
+
export const applicationIdSchema = z
|
|
29
|
+
.string()
|
|
30
|
+
.regex(idPattern("app"))
|
|
31
|
+
.brand();
|
|
32
|
+
/**
|
|
33
|
+
* A new application's id, minted when somebody registers one.
|
|
34
|
+
*
|
|
35
|
+
* Random rather than derived from the name: a name is editable and not unique,
|
|
36
|
+
* and an id that was derived from one would either change when it is renamed or
|
|
37
|
+
* preserve a name somebody wanted gone. It is also the value a person pastes
|
|
38
|
+
* into their own configuration, so it must not say anything about them.
|
|
39
|
+
*/
|
|
40
|
+
export const newApplicationId = () => applicationIdSchema.parse(`app_${randomIdBody()}`);
|
|
41
|
+
/**
|
|
42
|
+
* The application every row written before applications existed belongs to.
|
|
43
|
+
*
|
|
44
|
+
* Nothing is migrated by guessing (0260). The rows that exist belong to the
|
|
45
|
+
* deployment that wrote them, so they go into one application named for it rather
|
|
46
|
+
* than into a distribution somebody invented. It is also what a store
|
|
47
|
+
* built without an application uses, which is what keeps every existing caller —
|
|
48
|
+
* the demo, the documentation's worked examples, the eight thousand tests —
|
|
49
|
+
* meaning exactly what it meant before.
|
|
50
|
+
*
|
|
51
|
+
* **It is not a null.** Every read filters on it and every write sets it, so
|
|
52
|
+
* it is an application like any other; what makes it the default is only that it is
|
|
53
|
+
* the one a caller gets by saying nothing.
|
|
54
|
+
*/
|
|
55
|
+
export const DEFAULT_APPLICATION_ID = applicationIdSchema.parse("app_default");
|
|
56
|
+
/**
|
|
57
|
+
* What a deployment knows about one of its applications.
|
|
58
|
+
*
|
|
59
|
+
* Deliberately thin. The registry, the policy and the ingest credential are
|
|
60
|
+
* each their own concern with their own store — this is the row that says the
|
|
61
|
+
* application exists and what a person calls it, and nothing that another module
|
|
62
|
+
* already owns.
|
|
63
|
+
*/
|
|
64
|
+
export const applicationSchema = z
|
|
65
|
+
.object({
|
|
66
|
+
applicationId: applicationIdSchema,
|
|
67
|
+
/**
|
|
68
|
+
* The project it is grouped under, which every application has exactly one
|
|
69
|
+
* of. The grouping is organisational and nothing else yet — a project owns
|
|
70
|
+
* no policy and no members, so nothing reads this but a screen deciding
|
|
71
|
+
* which heading to put the application under. When it does own something,
|
|
72
|
+
* this is the edge that inheritance travels along.
|
|
73
|
+
*/
|
|
74
|
+
projectId: projectIdSchema,
|
|
75
|
+
/** What a person calls it. Not unique, not an identifier, and editable. */
|
|
76
|
+
name: z.string().min(1).max(200),
|
|
77
|
+
createdAt: z.string().datetime(),
|
|
78
|
+
/**
|
|
79
|
+
* Where the application lives, when it has said so. Used to tell a reader
|
|
80
|
+
* which application they are looking at, and to decide which origin may
|
|
81
|
+
* post its readers' signals — that one exactly, when it is set (0298).
|
|
82
|
+
*/
|
|
83
|
+
host: z.string().min(1).max(253).optional(),
|
|
84
|
+
/**
|
|
85
|
+
* When it was closed, or absent while it is open (0289). See
|
|
86
|
+
* `Project.closedAt`, which this follows in every respect but one: an
|
|
87
|
+
* application is closed *by* its project closing, and is not reopened by
|
|
88
|
+
* its project reopening.
|
|
89
|
+
*
|
|
90
|
+
* A closed application takes no signals. That is enforced where ingest
|
|
91
|
+
* learns which application is posting, which is the host's door rather
|
|
92
|
+
* than this schema (0298).
|
|
93
|
+
*/
|
|
94
|
+
closedAt: z.string().datetime().optional(),
|
|
95
|
+
})
|
|
96
|
+
.strict();
|
|
97
|
+
//# sourceMappingURL=application.js.map
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { type Application } from "./application.js";
|
|
2
|
+
import type { ApplicationStore } from "./store.js";
|
|
3
|
+
/**
|
|
4
|
+
* A `ApplicationStore` in a `Map`, for a test and for a deployment with no database.
|
|
5
|
+
*
|
|
6
|
+
* The counterpart to `memoryStore`, and it carries the same warning: a `Map`
|
|
7
|
+
* keeps nothing across a process, so on the serverless hosts §3 targets it
|
|
8
|
+
* keeps nothing at all. What it is honestly for is the suite, a lesson, and the
|
|
9
|
+
* first run of an application that has not been given a `DATABASE_URL` yet —
|
|
10
|
+
* where seeing one application called *your application* beats seeing an error.
|
|
11
|
+
*
|
|
12
|
+
* The listing sorts, and the first draft of this file did not — its comment
|
|
13
|
+
* claimed insertion order "happens to be oldest first", which confuses the
|
|
14
|
+
* order rows were *written* with the order they were *created*. An application
|
|
15
|
+
* recorded today with yesterday's `createdAt` is ordinary: it is what importing
|
|
16
|
+
* one, or seeding the default beside applications that already exist, produces. The
|
|
17
|
+
* shared contract writes three out of order and caught it.
|
|
18
|
+
*/
|
|
19
|
+
export declare const memoryApplicationStore: (seed?: readonly Application[]) => ApplicationStore;
|
|
20
|
+
//# sourceMappingURL=memory.d.ts.map
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import { applyPatch } from "../patch.js";
|
|
2
|
+
import { err, ok } from "../result.js";
|
|
3
|
+
import { matchesListing } from "../project/store.js";
|
|
4
|
+
import { applicationSchema } from "./application.js";
|
|
5
|
+
/**
|
|
6
|
+
* A `ApplicationStore` in a `Map`, for a test and for a deployment with no database.
|
|
7
|
+
*
|
|
8
|
+
* The counterpart to `memoryStore`, and it carries the same warning: a `Map`
|
|
9
|
+
* keeps nothing across a process, so on the serverless hosts §3 targets it
|
|
10
|
+
* keeps nothing at all. What it is honestly for is the suite, a lesson, and the
|
|
11
|
+
* first run of an application that has not been given a `DATABASE_URL` yet —
|
|
12
|
+
* where seeing one application called *your application* beats seeing an error.
|
|
13
|
+
*
|
|
14
|
+
* The listing sorts, and the first draft of this file did not — its comment
|
|
15
|
+
* claimed insertion order "happens to be oldest first", which confuses the
|
|
16
|
+
* order rows were *written* with the order they were *created*. An application
|
|
17
|
+
* recorded today with yesterday's `createdAt` is ordinary: it is what importing
|
|
18
|
+
* one, or seeding the default beside applications that already exist, produces. The
|
|
19
|
+
* shared contract writes three out of order and caught it.
|
|
20
|
+
*/
|
|
21
|
+
export const memoryApplicationStore = (seed = []) => {
|
|
22
|
+
const applications = new Map(seed.map((application) => [application.applicationId, application]));
|
|
23
|
+
const read = (applicationId) => {
|
|
24
|
+
const found = applications.get(applicationId);
|
|
25
|
+
return found === undefined ? err({ code: "not-found", applicationId }) : ok(found);
|
|
26
|
+
};
|
|
27
|
+
return {
|
|
28
|
+
create: async (application) => {
|
|
29
|
+
if (applications.has(application.applicationId)) {
|
|
30
|
+
return err({ code: "already-exists", applicationId: application.applicationId });
|
|
31
|
+
}
|
|
32
|
+
applications.set(application.applicationId, application);
|
|
33
|
+
return ok(application);
|
|
34
|
+
},
|
|
35
|
+
get: async (applicationId) => read(applicationId),
|
|
36
|
+
list: async (listing) => ok([...applications.values()]
|
|
37
|
+
.filter((application) => matchesListing(application.closedAt, listing))
|
|
38
|
+
.sort((left, right) => left.createdAt.localeCompare(right.createdAt))),
|
|
39
|
+
rename: async (applicationId, to) => {
|
|
40
|
+
const found = read(applicationId);
|
|
41
|
+
if (!found.ok)
|
|
42
|
+
return found;
|
|
43
|
+
/**
|
|
44
|
+
* Parsed rather than spread, so a name this store would accept and the
|
|
45
|
+
* database would refuse cannot be told apart by which one you used. The
|
|
46
|
+
* two stores agree about what an application is because they both ask
|
|
47
|
+
* `applicationSchema`, and they agree about what a patch means because
|
|
48
|
+
* they both apply it with `applyPatch`.
|
|
49
|
+
*/
|
|
50
|
+
const next = applicationSchema.safeParse(applyPatch(found.value, to));
|
|
51
|
+
if (!next.success) {
|
|
52
|
+
return err({ code: "unreadable", applicationId, detail: next.error.issues[0]?.message ?? "invalid" });
|
|
53
|
+
}
|
|
54
|
+
applications.set(applicationId, next.data);
|
|
55
|
+
return ok(next.data);
|
|
56
|
+
},
|
|
57
|
+
/** Idempotent, and the instant does not move (0289). */
|
|
58
|
+
close: async (applicationId, at) => {
|
|
59
|
+
const found = read(applicationId);
|
|
60
|
+
if (!found.ok)
|
|
61
|
+
return found;
|
|
62
|
+
if (found.value.closedAt !== undefined)
|
|
63
|
+
return ok(found.value);
|
|
64
|
+
const next = { ...found.value, closedAt: at };
|
|
65
|
+
applications.set(applicationId, next);
|
|
66
|
+
return ok(next);
|
|
67
|
+
},
|
|
68
|
+
reopen: async (applicationId) => {
|
|
69
|
+
const found = read(applicationId);
|
|
70
|
+
if (!found.ok)
|
|
71
|
+
return found;
|
|
72
|
+
/** Spelled as a removal rather than `closedAt: undefined`, which a strict parse refuses. */
|
|
73
|
+
const { closedAt: _was, ...open } = found.value;
|
|
74
|
+
applications.set(applicationId, open);
|
|
75
|
+
return ok(open);
|
|
76
|
+
},
|
|
77
|
+
};
|
|
78
|
+
};
|
|
79
|
+
//# sourceMappingURL=memory.js.map
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import type { Patch } from "../patch.js";
|
|
2
|
+
import type { Listing } from "../project/store.js";
|
|
3
|
+
import type { Result } from "../result.js";
|
|
4
|
+
import type { Application, ApplicationId } from "./application.js";
|
|
5
|
+
/**
|
|
6
|
+
* Custody of the applications a deployment has.
|
|
7
|
+
*
|
|
8
|
+
* Five tables carry an application's id, so a tree, a hold, a policy revision
|
|
9
|
+
* and a journal entry each know which application they belong to — and for a
|
|
10
|
+
* day nothing stored the application itself. `Application` was a type nothing
|
|
11
|
+
* wrote and `DEFAULT_APPLICATION_ID` was the only one that could be named, so a
|
|
12
|
+
* portal whose first screen lists the applications you have had nothing to
|
|
13
|
+
* list. The maintainer's own sentence — *"the whole portal is geared toward one
|
|
14
|
+
* app when I can have many"* — stayed true of the data after it had stopped
|
|
15
|
+
* being true of the schema.
|
|
16
|
+
*
|
|
17
|
+
* This is the row that makes an application nameable, and it is deliberately
|
|
18
|
+
* thin for the reason `applicationSchema` gives: the registry, the policy and
|
|
19
|
+
* the ingest credential are each already somebody's, so this says only that the
|
|
20
|
+
* application exists, what a person calls it, and which project it is in
|
|
21
|
+
* ([0269](../../decisions/0269-an-application-is-the-unit-loom-governs-and-a-project-groups-them.md)).
|
|
22
|
+
*/
|
|
23
|
+
export type ApplicationStoreError =
|
|
24
|
+
/** No application under this id. */
|
|
25
|
+
{
|
|
26
|
+
readonly code: "not-found";
|
|
27
|
+
readonly applicationId: ApplicationId;
|
|
28
|
+
} | {
|
|
29
|
+
readonly code: "already-exists";
|
|
30
|
+
readonly applicationId: ApplicationId;
|
|
31
|
+
}
|
|
32
|
+
/** A row the current code cannot parse, which is a row an older one wrote. */
|
|
33
|
+
| {
|
|
34
|
+
readonly code: "unreadable";
|
|
35
|
+
readonly applicationId: ApplicationId;
|
|
36
|
+
readonly detail: string;
|
|
37
|
+
} | {
|
|
38
|
+
readonly code: "unavailable";
|
|
39
|
+
readonly detail: string;
|
|
40
|
+
};
|
|
41
|
+
export type ApplicationStoreErrorCode = ApplicationStoreError["code"];
|
|
42
|
+
/**
|
|
43
|
+
* The four codes, in the order a deployment meets them, for the same reason
|
|
44
|
+
* `storeErrorCodes` exists: anything that walks the taxonomy rather than
|
|
45
|
+
* reacting to one member otherwise keeps a copy that is silently wrong the day
|
|
46
|
+
* a fifth lands.
|
|
47
|
+
*/
|
|
48
|
+
export declare const applicationStoreErrorCodes: readonly ApplicationStoreErrorCode[];
|
|
49
|
+
export declare const describeApplicationStoreError: (error: ApplicationStoreError) => string;
|
|
50
|
+
/**
|
|
51
|
+
* Six methods, and still **no delete**.
|
|
52
|
+
*
|
|
53
|
+
* That is the same refusal `TreeStore` makes and for a stronger reason here: a
|
|
54
|
+
* application's rows are its trees, its revisions, its holds, its policy history
|
|
55
|
+
* and its journal, and a delete would either orphan all of them or cascade
|
|
56
|
+
* through the governance record this product exists to keep. *The application says
|
|
57
|
+
* it was closed* is a better answer than *the application is gone* — and closing is
|
|
58
|
+
* not built here either, because nothing can close what nothing has yet opened.
|
|
59
|
+
* When it is wanted it is a column and a filter, not a `DELETE`.
|
|
60
|
+
*/
|
|
61
|
+
export type ApplicationStore = {
|
|
62
|
+
/**
|
|
63
|
+
* Record an application. Refuses an id already taken rather than overwriting,
|
|
64
|
+
* because the thing under that id owns rows.
|
|
65
|
+
*/
|
|
66
|
+
readonly create: (application: Application) => Promise<Result<Application, ApplicationStoreError>>;
|
|
67
|
+
/** One application. */
|
|
68
|
+
readonly get: (applicationId: ApplicationId) => Promise<Result<Application, ApplicationStoreError>>;
|
|
69
|
+
/**
|
|
70
|
+
* Every application, oldest first.
|
|
71
|
+
*
|
|
72
|
+
* Unpaginated, and that is a judgement rather than an oversight: this is the
|
|
73
|
+
* list a person scans on one screen, and a deployment whose application count
|
|
74
|
+
* needs a cursor has a different screen's problem. `TreeStore.list` takes a
|
|
75
|
+
* limit because pages are unbounded in a way applications are not.
|
|
76
|
+
*/
|
|
77
|
+
readonly list: (listing?: Listing) => Promise<Result<readonly Application[], ApplicationStoreError>>;
|
|
78
|
+
/**
|
|
79
|
+
* Change what a person calls it, and where they say it lives.
|
|
80
|
+
*
|
|
81
|
+
* A field left out is left alone, and `host: null` removes it — the three
|
|
82
|
+
* states `Patch` spells, because an application that has been given a host
|
|
83
|
+
* has to be able to have it taken away. A name has no third state: it is
|
|
84
|
+
* required, so there is nothing for clearing it to mean and the type does not
|
|
85
|
+
* offer it.
|
|
86
|
+
*/
|
|
87
|
+
readonly rename: (applicationId: ApplicationId, to: {
|
|
88
|
+
readonly name?: string;
|
|
89
|
+
readonly host?: Patch<string>;
|
|
90
|
+
}) => Promise<Result<Application, ApplicationStoreError>>;
|
|
91
|
+
/**
|
|
92
|
+
* Stop it, without losing it (0289). Closed by its own id, or by its project
|
|
93
|
+
* closing — `ProjectStore.close` does this to every application it holds.
|
|
94
|
+
*
|
|
95
|
+
* Idempotent on one already closed: the instant stays where it was.
|
|
96
|
+
*/
|
|
97
|
+
readonly close: (applicationId: ApplicationId, at: string) => Promise<Result<Application, ApplicationStoreError>>;
|
|
98
|
+
/** The inverse, one application at a time. See `ProjectStore.reopen`. */
|
|
99
|
+
readonly reopen: (applicationId: ApplicationId) => Promise<Result<Application, ApplicationStoreError>>;
|
|
100
|
+
};
|
|
101
|
+
//# sourceMappingURL=store.d.ts.map
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The four codes, in the order a deployment meets them, for the same reason
|
|
3
|
+
* `storeErrorCodes` exists: anything that walks the taxonomy rather than
|
|
4
|
+
* reacting to one member otherwise keeps a copy that is silently wrong the day
|
|
5
|
+
* a fifth lands.
|
|
6
|
+
*/
|
|
7
|
+
export const applicationStoreErrorCodes = [
|
|
8
|
+
"not-found",
|
|
9
|
+
"already-exists",
|
|
10
|
+
"unreadable",
|
|
11
|
+
"unavailable",
|
|
12
|
+
];
|
|
13
|
+
export const describeApplicationStoreError = (error) => {
|
|
14
|
+
switch (error.code) {
|
|
15
|
+
case "not-found":
|
|
16
|
+
return `no application ${error.applicationId}`;
|
|
17
|
+
case "already-exists":
|
|
18
|
+
return `application ${error.applicationId} already exists`;
|
|
19
|
+
case "unreadable":
|
|
20
|
+
return `application ${error.applicationId} could not be read: ${error.detail}`;
|
|
21
|
+
case "unavailable":
|
|
22
|
+
return `the application store is unavailable: ${error.detail}`;
|
|
23
|
+
}
|
|
24
|
+
};
|
|
25
|
+
//# sourceMappingURL=store.js.map
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The group of readers a form of a page was served to.
|
|
3
|
+
*
|
|
4
|
+
* An audience is a **predicate over the opaque render context** — site, region,
|
|
5
|
+
* locale, cohort, flag, whatever the host puts in `RenderRequest.context` — and
|
|
6
|
+
* the match is evaluated in the customer's own process, per request, with
|
|
7
|
+
* nothing about the reader leaving it (0263 clauses 1 and 4).
|
|
8
|
+
*
|
|
9
|
+
* **None of that predicate is here.** What this module holds is the *name* a
|
|
10
|
+
* signal carries once the deciding is done: an opaque id, on the terms
|
|
11
|
+
* [0284](../../decisions/0284-a-signal-names-the-audience-it-was-collected-under-and-the-predicate-stays-in-the-control-plane.md)
|
|
12
|
+
* settles. What an `aud_` means is the control plane's to say, exactly as what
|
|
13
|
+
* an `app_` means is — so this file is an identity and a default, which is the
|
|
14
|
+
* whole of what a dimension needs to be measurable.
|
|
15
|
+
*/
|
|
16
|
+
import { z } from "zod";
|
|
17
|
+
export declare const audienceIdSchema: z.ZodBranded<z.ZodString, "AudienceId">;
|
|
18
|
+
export type AudienceId = z.infer<typeof audienceIdSchema>;
|
|
19
|
+
/** A new audience's id, minted when somebody defines one. Random, as every other is. */
|
|
20
|
+
export declare const newAudienceId: () => AudienceId;
|
|
21
|
+
/**
|
|
22
|
+
* The audience that matches every reader.
|
|
23
|
+
*
|
|
24
|
+
* What a deployment serving one form of every page has always been doing
|
|
25
|
+
* without having a word for it, which is why it is also what a signal naming
|
|
26
|
+
* no audience is filed under. Rows written before this dimension existed read
|
|
27
|
+
* as this one, and that is true of them rather than a guess (0260): there was
|
|
28
|
+
* one form of every page, so every reader was in the same group.
|
|
29
|
+
*
|
|
30
|
+
* **It is not a null.** Every read filters on it and every write sets it; what
|
|
31
|
+
* makes it the default is only that it is the one a sender gets by saying
|
|
32
|
+
* nothing. A nullable dimension would make every counter read a two-case
|
|
33
|
+
* question, one of whose cases no sender can produce (0284).
|
|
34
|
+
*/
|
|
35
|
+
export declare const DEFAULT_AUDIENCE_ID: AudienceId;
|
|
36
|
+
//# sourceMappingURL=audience.d.ts.map
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The group of readers a form of a page was served to.
|
|
3
|
+
*
|
|
4
|
+
* An audience is a **predicate over the opaque render context** — site, region,
|
|
5
|
+
* locale, cohort, flag, whatever the host puts in `RenderRequest.context` — and
|
|
6
|
+
* the match is evaluated in the customer's own process, per request, with
|
|
7
|
+
* nothing about the reader leaving it (0263 clauses 1 and 4).
|
|
8
|
+
*
|
|
9
|
+
* **None of that predicate is here.** What this module holds is the *name* a
|
|
10
|
+
* signal carries once the deciding is done: an opaque id, on the terms
|
|
11
|
+
* [0284](../../decisions/0284-a-signal-names-the-audience-it-was-collected-under-and-the-predicate-stays-in-the-control-plane.md)
|
|
12
|
+
* settles. What an `aud_` means is the control plane's to say, exactly as what
|
|
13
|
+
* an `app_` means is — so this file is an identity and a default, which is the
|
|
14
|
+
* whole of what a dimension needs to be measurable.
|
|
15
|
+
*/
|
|
16
|
+
import { z } from "zod";
|
|
17
|
+
import { idPattern } from "../grammar.js";
|
|
18
|
+
import { randomIdBody } from "../ids.js";
|
|
19
|
+
/*
|
|
20
|
+
* `aud`, spelled rather than initialled, for the reason an application id is:
|
|
21
|
+
* it is a value a person reads off a screen and puts into their own rules.
|
|
22
|
+
*/
|
|
23
|
+
export const audienceIdSchema = z.string().regex(idPattern("aud")).brand();
|
|
24
|
+
/** A new audience's id, minted when somebody defines one. Random, as every other is. */
|
|
25
|
+
export const newAudienceId = () => audienceIdSchema.parse(`aud_${randomIdBody()}`);
|
|
26
|
+
/**
|
|
27
|
+
* The audience that matches every reader.
|
|
28
|
+
*
|
|
29
|
+
* What a deployment serving one form of every page has always been doing
|
|
30
|
+
* without having a word for it, which is why it is also what a signal naming
|
|
31
|
+
* no audience is filed under. Rows written before this dimension existed read
|
|
32
|
+
* as this one, and that is true of them rather than a guess (0260): there was
|
|
33
|
+
* one form of every page, so every reader was in the same group.
|
|
34
|
+
*
|
|
35
|
+
* **It is not a null.** Every read filters on it and every write sets it; what
|
|
36
|
+
* makes it the default is only that it is the one a sender gets by saying
|
|
37
|
+
* nothing. A nullable dimension would make every counter read a two-case
|
|
38
|
+
* question, one of whose cases no sender can produce (0284).
|
|
39
|
+
*/
|
|
40
|
+
export const DEFAULT_AUDIENCE_ID = audienceIdSchema.parse("aud_everyone");
|
|
41
|
+
//# sourceMappingURL=audience.js.map
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A page as the reader in front of it gets it: the base tree, plus the deltas
|
|
3
|
+
* the audiences they are in have earned.
|
|
4
|
+
*
|
|
5
|
+
* This is
|
|
6
|
+
* [0263](../../decisions/0263-a-page-is-a-base-tree-and-the-deltas-an-audience-earns.md)
|
|
7
|
+
* clause 4 — *base plus matched deltas, locally, with no call to the control
|
|
8
|
+
* plane* — and it is a **pure function of a tree, a set of rules and a
|
|
9
|
+
* context**, which is what lets it run on every request in the customer's own
|
|
10
|
+
* process beside the render it feeds.
|
|
11
|
+
*
|
|
12
|
+
* **What comes out is a projection of a revision and not a revision of its
|
|
13
|
+
* own.** The composed tree keeps the base's `treeId` and the base's `revision`,
|
|
14
|
+
* and nothing about it is appended anywhere. Three reasons, and the third is
|
|
15
|
+
* the one that decided it:
|
|
16
|
+
*
|
|
17
|
+
* - A revision is a thing the log can replay and attribute. A composition is
|
|
18
|
+
* derived from one, per request, from rules that may change between two
|
|
19
|
+
* requests; it has no author, no timestamp and no place in the history.
|
|
20
|
+
* - Bumping the number would make a reader's revision depend on which audience
|
|
21
|
+
* they fell into, so two readers of the same published page would report
|
|
22
|
+
* different revisions for it.
|
|
23
|
+
* - **The measurement joins on it.** 0284 made a counter's identity
|
|
24
|
+
* `(application, audience, tree, revision)`. If a composition carried its own
|
|
25
|
+
* revision, the audience dimension and the revision dimension would move
|
|
26
|
+
* together and *compare these two audiences on this revision* — the whole
|
|
27
|
+
* point of serving two — would have nothing to compare.
|
|
28
|
+
*
|
|
29
|
+
* So the base revision is what a signal names, and the audience is what tells
|
|
30
|
+
* two forms of it apart. That is the shape 0284 already built the tables for.
|
|
31
|
+
*/
|
|
32
|
+
import type { JsonObject } from "../json.js";
|
|
33
|
+
import { type Result } from "../result.js";
|
|
34
|
+
import type { TreeDelta } from "../tree/delta.js";
|
|
35
|
+
import type { LoomTree } from "../tree/tree.js";
|
|
36
|
+
import type { AudienceId } from "./audience.js";
|
|
37
|
+
import { type AudienceRule } from "./rule.js";
|
|
38
|
+
/** The delta one audience earns, against the base it was authored on. */
|
|
39
|
+
export type AudienceForm = {
|
|
40
|
+
readonly audienceId: AudienceId;
|
|
41
|
+
readonly delta: TreeDelta;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* Everything a deployment needs to serve one page to more than one audience:
|
|
45
|
+
* the rules that sort readers, and the delta each audience earns.
|
|
46
|
+
*
|
|
47
|
+
* Both halves are **cacheable beside the base** (0263 clause 3), which is why
|
|
48
|
+
* they are one value rather than two lookups — a host caching the base and
|
|
49
|
+
* re-fetching the rules per request has paid for the call this record exists to
|
|
50
|
+
* avoid.
|
|
51
|
+
*/
|
|
52
|
+
export type AudienceOverlay = {
|
|
53
|
+
readonly rules: readonly AudienceRule[];
|
|
54
|
+
readonly forms: readonly AudienceForm[];
|
|
55
|
+
};
|
|
56
|
+
export type ComposeError =
|
|
57
|
+
/** A rule matched an audience the overlay has no delta for. */
|
|
58
|
+
{
|
|
59
|
+
readonly code: "no-form";
|
|
60
|
+
readonly audienceId: AudienceId;
|
|
61
|
+
}
|
|
62
|
+
/** The base moved and this delta was authored against an older revision. */
|
|
63
|
+
| {
|
|
64
|
+
readonly code: "stale-form";
|
|
65
|
+
readonly audienceId: AudienceId;
|
|
66
|
+
readonly expected: number;
|
|
67
|
+
readonly actual: number;
|
|
68
|
+
}
|
|
69
|
+
/** The delta is for another page. */
|
|
70
|
+
| {
|
|
71
|
+
readonly code: "form-mismatch";
|
|
72
|
+
readonly audienceId: AudienceId;
|
|
73
|
+
readonly treeId: string;
|
|
74
|
+
}
|
|
75
|
+
/** The operations did not apply, or what they produced is not a tree. */
|
|
76
|
+
| {
|
|
77
|
+
readonly code: "unapplicable";
|
|
78
|
+
readonly audienceId: AudienceId;
|
|
79
|
+
readonly detail: string;
|
|
80
|
+
};
|
|
81
|
+
/** The tree this reader gets, and the audiences that made it that. */
|
|
82
|
+
export type ComposedTree = {
|
|
83
|
+
readonly tree: LoomTree;
|
|
84
|
+
/**
|
|
85
|
+
* In the order the rules gave them, which is the order the deltas were
|
|
86
|
+
* applied in. A caller names this on the signals the page sends, so that what
|
|
87
|
+
* was measured and what was served are the same claim.
|
|
88
|
+
*/
|
|
89
|
+
readonly audiences: readonly AudienceId[];
|
|
90
|
+
};
|
|
91
|
+
export declare const describeComposeError: (error: ComposeError) => string;
|
|
92
|
+
/**
|
|
93
|
+
* The page this context earns, or why it cannot be served.
|
|
94
|
+
*
|
|
95
|
+
* **It refuses rather than falling back to the base, and that is the decision
|
|
96
|
+
* in this function.** A composition that quietly dropped a stale delta would
|
|
97
|
+
* serve the base tree to a reader the deployment has already decided is in
|
|
98
|
+
* `aud_eu`, and the signals that page sends would be filed under `aud_eu`
|
|
99
|
+
* anyway — so the comparison 0263 clause 5 exists for would be between one
|
|
100
|
+
* audience's form and another audience's *name over the base's form*. A
|
|
101
|
+
* measurement that is quietly wrong is worse than a page that is honestly
|
|
102
|
+
* missing, which is the same argument `origins` is closed by default on.
|
|
103
|
+
*
|
|
104
|
+
* It is all-or-nothing per request for the same reason: two matched deltas of
|
|
105
|
+
* which one applied is a form nobody authored, judged or asked for.
|
|
106
|
+
*
|
|
107
|
+
* A context matching nothing is **not** a failure — it is the base tree, which
|
|
108
|
+
* is what every deployment that has never heard of an audience is already
|
|
109
|
+
* being served.
|
|
110
|
+
*/
|
|
111
|
+
export declare const composeTreeForContext: (base: LoomTree, overlay: AudienceOverlay, context: JsonObject | undefined) => Result<ComposedTree, ComposeError>;
|
|
112
|
+
//# sourceMappingURL=compose.d.ts.map
|