@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
|
@@ -0,0 +1,406 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { type PageDirection, type PageEnds } from "../paging.js";
|
|
3
|
+
import { type Result } from "../result.js";
|
|
4
|
+
import { type PolicyChange } from "./policy-change.js";
|
|
5
|
+
import { type GatePolicy } from "./policy.js";
|
|
6
|
+
/**
|
|
7
|
+
* One policy, as it was, with who made it that and when.
|
|
8
|
+
*
|
|
9
|
+
* `fingerprint` is stored rather than derived on read, and it is the only
|
|
10
|
+
* denormalised field here. The reason is the join it exists for: a `Disposition`
|
|
11
|
+
* carries a fingerprint, and finding the revision it names has to be a seek
|
|
12
|
+
* rather than a fold that rehashes every policy the deployment ever held. It is
|
|
13
|
+
* checked against the policy beside it on the way in, so the two cannot drift —
|
|
14
|
+
* see `recordPolicy`.
|
|
15
|
+
*
|
|
16
|
+
* `revision` is 1-based and dense per `policyId`, which is what makes the
|
|
17
|
+
* sequence foldable: `policyHistoryOf` reads adjacent pairs, and a gap would make
|
|
18
|
+
* it describe a change nobody made.
|
|
19
|
+
*/
|
|
20
|
+
export type PolicyRevision = {
|
|
21
|
+
readonly policyId: string;
|
|
22
|
+
readonly revision: number;
|
|
23
|
+
readonly fingerprint: string;
|
|
24
|
+
readonly policy: GatePolicy;
|
|
25
|
+
/**
|
|
26
|
+
* Who made this the policy. Host-declared, like `policyId` itself and like
|
|
27
|
+
* `Provenance.interpreter`: the runtime cannot know what names a person in a
|
|
28
|
+
* host's own directory, and a name the host chose is one it can look up.
|
|
29
|
+
*/
|
|
30
|
+
readonly actor: string;
|
|
31
|
+
readonly recordedAt: string;
|
|
32
|
+
/** Why, when somebody said. Prose for a reader, and never read by anything. */
|
|
33
|
+
readonly note?: string;
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* The same shape, as something a stored row can be checked against.
|
|
37
|
+
*
|
|
38
|
+
* Held here rather than in a backend for the reason `heldProposalSchema` gives:
|
|
39
|
+
* a revision outlives the process that wrote it, and every implementation has to
|
|
40
|
+
* read one back the same way — a second store that parsed loosely would disagree
|
|
41
|
+
* with the first about what is storable, and a contract suite would not catch it
|
|
42
|
+
* because both would still round-trip their own writes.
|
|
43
|
+
*/
|
|
44
|
+
export declare const policyRevisionSchema: z.ZodObject<{
|
|
45
|
+
policyId: z.ZodString;
|
|
46
|
+
revision: z.ZodNumber;
|
|
47
|
+
fingerprint: z.ZodString;
|
|
48
|
+
policy: z.ZodObject<{
|
|
49
|
+
policyId: z.ZodDefault<z.ZodString>;
|
|
50
|
+
protectedPrimitiveTypes: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodBranded<z.ZodString, "PrimitiveType">, "many">>>;
|
|
51
|
+
outOfTreeEffectTypes: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodBranded<z.ZodString, "PrimitiveType">, "many">>>;
|
|
52
|
+
protectedPropKeys: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
|
|
53
|
+
interactiveTypes: z.ZodDefault<z.ZodType<Readonly<Record<string, import("../interactivity.js").InteractiveWhen | undefined>>, z.ZodTypeDef, unknown>>;
|
|
54
|
+
registeredPrimitiveTypes: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodBranded<z.ZodString, "PrimitiveType">, "many">>>;
|
|
55
|
+
removalThresholds: z.ZodDefault<z.ZodObject<{
|
|
56
|
+
medium: z.ZodNumber;
|
|
57
|
+
high: z.ZodNumber;
|
|
58
|
+
}, "strip", z.ZodTypeAny, {
|
|
59
|
+
medium: number;
|
|
60
|
+
high: number;
|
|
61
|
+
}, {
|
|
62
|
+
medium: number;
|
|
63
|
+
high: number;
|
|
64
|
+
}>>;
|
|
65
|
+
breadthThreshold: z.ZodDefault<z.ZodNumber>;
|
|
66
|
+
shallowDepthThreshold: z.ZodDefault<z.ZodNumber>;
|
|
67
|
+
inverseRetentionBudget: z.ZodDefault<z.ZodNumber>;
|
|
68
|
+
minimumConfidence: z.ZodDefault<z.ZodNumber>;
|
|
69
|
+
confidenceFloor: z.ZodDefault<z.ZodNumber>;
|
|
70
|
+
autoApplyCeiling: z.ZodDefault<z.ZodRecord<z.ZodEnum<["user-instruction", "system-signal", "scheduled-adaptation", "developer"]>, z.ZodUnion<[z.ZodLiteral<"nothing">, z.ZodEnum<["low", "medium", "high", "critical"]>]>>>;
|
|
71
|
+
refusalFloor: z.ZodDefault<z.ZodEnum<["low", "medium", "high", "critical"]>>;
|
|
72
|
+
}, "strip", z.ZodTypeAny, {
|
|
73
|
+
policyId: string;
|
|
74
|
+
protectedPrimitiveTypes: readonly (string & z.BRAND<"PrimitiveType">)[];
|
|
75
|
+
outOfTreeEffectTypes: readonly (string & z.BRAND<"PrimitiveType">)[];
|
|
76
|
+
protectedPropKeys: readonly string[];
|
|
77
|
+
interactiveTypes: Readonly<Record<string, import("../interactivity.js").InteractiveWhen | undefined>>;
|
|
78
|
+
registeredPrimitiveTypes: readonly (string & z.BRAND<"PrimitiveType">)[];
|
|
79
|
+
removalThresholds: {
|
|
80
|
+
medium: number;
|
|
81
|
+
high: number;
|
|
82
|
+
};
|
|
83
|
+
breadthThreshold: number;
|
|
84
|
+
shallowDepthThreshold: number;
|
|
85
|
+
inverseRetentionBudget: number;
|
|
86
|
+
minimumConfidence: number;
|
|
87
|
+
confidenceFloor: number;
|
|
88
|
+
autoApplyCeiling: Partial<Record<"user-instruction" | "system-signal" | "scheduled-adaptation" | "developer", "low" | "medium" | "high" | "critical" | "nothing">>;
|
|
89
|
+
refusalFloor: "low" | "medium" | "high" | "critical";
|
|
90
|
+
}, {
|
|
91
|
+
policyId?: string | undefined;
|
|
92
|
+
protectedPrimitiveTypes?: readonly string[] | undefined;
|
|
93
|
+
outOfTreeEffectTypes?: readonly string[] | undefined;
|
|
94
|
+
protectedPropKeys?: readonly string[] | undefined;
|
|
95
|
+
interactiveTypes?: unknown;
|
|
96
|
+
registeredPrimitiveTypes?: readonly string[] | undefined;
|
|
97
|
+
removalThresholds?: {
|
|
98
|
+
medium: number;
|
|
99
|
+
high: number;
|
|
100
|
+
} | undefined;
|
|
101
|
+
breadthThreshold?: number | undefined;
|
|
102
|
+
shallowDepthThreshold?: number | undefined;
|
|
103
|
+
inverseRetentionBudget?: number | undefined;
|
|
104
|
+
minimumConfidence?: number | undefined;
|
|
105
|
+
confidenceFloor?: number | undefined;
|
|
106
|
+
autoApplyCeiling?: Partial<Record<"user-instruction" | "system-signal" | "scheduled-adaptation" | "developer", "low" | "medium" | "high" | "critical" | "nothing">> | undefined;
|
|
107
|
+
refusalFloor?: "low" | "medium" | "high" | "critical" | undefined;
|
|
108
|
+
}>;
|
|
109
|
+
actor: z.ZodString;
|
|
110
|
+
recordedAt: z.ZodString;
|
|
111
|
+
note: z.ZodOptional<z.ZodString>;
|
|
112
|
+
}, "strip", z.ZodTypeAny, {
|
|
113
|
+
revision: number;
|
|
114
|
+
fingerprint: string;
|
|
115
|
+
actor: string;
|
|
116
|
+
policyId: string;
|
|
117
|
+
policy: {
|
|
118
|
+
policyId: string;
|
|
119
|
+
protectedPrimitiveTypes: readonly (string & z.BRAND<"PrimitiveType">)[];
|
|
120
|
+
outOfTreeEffectTypes: readonly (string & z.BRAND<"PrimitiveType">)[];
|
|
121
|
+
protectedPropKeys: readonly string[];
|
|
122
|
+
interactiveTypes: Readonly<Record<string, import("../interactivity.js").InteractiveWhen | undefined>>;
|
|
123
|
+
registeredPrimitiveTypes: readonly (string & z.BRAND<"PrimitiveType">)[];
|
|
124
|
+
removalThresholds: {
|
|
125
|
+
medium: number;
|
|
126
|
+
high: number;
|
|
127
|
+
};
|
|
128
|
+
breadthThreshold: number;
|
|
129
|
+
shallowDepthThreshold: number;
|
|
130
|
+
inverseRetentionBudget: number;
|
|
131
|
+
minimumConfidence: number;
|
|
132
|
+
confidenceFloor: number;
|
|
133
|
+
autoApplyCeiling: Partial<Record<"user-instruction" | "system-signal" | "scheduled-adaptation" | "developer", "low" | "medium" | "high" | "critical" | "nothing">>;
|
|
134
|
+
refusalFloor: "low" | "medium" | "high" | "critical";
|
|
135
|
+
};
|
|
136
|
+
recordedAt: string;
|
|
137
|
+
note?: string | undefined;
|
|
138
|
+
}, {
|
|
139
|
+
revision: number;
|
|
140
|
+
fingerprint: string;
|
|
141
|
+
actor: string;
|
|
142
|
+
policyId: string;
|
|
143
|
+
policy: {
|
|
144
|
+
policyId?: string | undefined;
|
|
145
|
+
protectedPrimitiveTypes?: readonly string[] | undefined;
|
|
146
|
+
outOfTreeEffectTypes?: readonly string[] | undefined;
|
|
147
|
+
protectedPropKeys?: readonly string[] | undefined;
|
|
148
|
+
interactiveTypes?: unknown;
|
|
149
|
+
registeredPrimitiveTypes?: readonly string[] | undefined;
|
|
150
|
+
removalThresholds?: {
|
|
151
|
+
medium: number;
|
|
152
|
+
high: number;
|
|
153
|
+
} | undefined;
|
|
154
|
+
breadthThreshold?: number | undefined;
|
|
155
|
+
shallowDepthThreshold?: number | undefined;
|
|
156
|
+
inverseRetentionBudget?: number | undefined;
|
|
157
|
+
minimumConfidence?: number | undefined;
|
|
158
|
+
confidenceFloor?: number | undefined;
|
|
159
|
+
autoApplyCeiling?: Partial<Record<"user-instruction" | "system-signal" | "scheduled-adaptation" | "developer", "low" | "medium" | "high" | "critical" | "nothing">> | undefined;
|
|
160
|
+
refusalFloor?: "low" | "medium" | "high" | "critical" | undefined;
|
|
161
|
+
};
|
|
162
|
+
recordedAt: string;
|
|
163
|
+
note?: string | undefined;
|
|
164
|
+
}>;
|
|
165
|
+
export type PolicyLogError =
|
|
166
|
+
/** Nothing has ever been recorded under this name. */
|
|
167
|
+
{
|
|
168
|
+
readonly code: "no-such-policy";
|
|
169
|
+
readonly policyId: string;
|
|
170
|
+
}
|
|
171
|
+
/**
|
|
172
|
+
* The revision the caller expected to be current is not the one that is, so
|
|
173
|
+
* somebody else recorded in between. The write is refused rather than applied
|
|
174
|
+
* on top, because the caller's edit was made against rules that have moved.
|
|
175
|
+
*/
|
|
176
|
+
| {
|
|
177
|
+
readonly code: "out-of-date";
|
|
178
|
+
readonly policyId: string;
|
|
179
|
+
readonly expected: number;
|
|
180
|
+
readonly current: number;
|
|
181
|
+
}
|
|
182
|
+
/** The log did not answer. Nothing is known, and a moment later may succeed. */
|
|
183
|
+
| {
|
|
184
|
+
readonly code: "unavailable";
|
|
185
|
+
readonly detail: string;
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* The log answered, and something it returned is not a revision this build can
|
|
189
|
+
* read. Separate from `unavailable` for the reason `HoldError` separates them:
|
|
190
|
+
* a store that did not answer is waited out, and a row that did not parse is
|
|
191
|
+
* gone and looked at.
|
|
192
|
+
*/
|
|
193
|
+
| {
|
|
194
|
+
readonly code: "unreadable";
|
|
195
|
+
readonly detail: string;
|
|
196
|
+
};
|
|
197
|
+
export declare const describePolicyLogError: (error: PolicyLogError) => string;
|
|
198
|
+
/**
|
|
199
|
+
* Reads a revision back out of storage, or says why it could not.
|
|
200
|
+
*
|
|
201
|
+
* The assertion is about the shape of optionality and never about validity, for
|
|
202
|
+
* the reason `parseHeldProposal` gives: Zod infers an optional field as
|
|
203
|
+
* `T | undefined`, which `exactOptionalPropertyTypes` distinguishes from an
|
|
204
|
+
* absent key, and JSON has no `undefined` at all.
|
|
205
|
+
*/
|
|
206
|
+
export declare const parsePolicyRevision: (row: unknown) => Result<PolicyRevision, PolicyLogError>;
|
|
207
|
+
export type RecordPolicyRequest = {
|
|
208
|
+
readonly policy: GatePolicy;
|
|
209
|
+
readonly actor: string;
|
|
210
|
+
readonly recordedAt: string;
|
|
211
|
+
readonly note?: string;
|
|
212
|
+
/**
|
|
213
|
+
* The revision the caller believes is current, or `0` for *nothing is*.
|
|
214
|
+
*
|
|
215
|
+
* Optional, and the difference is which failure the caller is protected from.
|
|
216
|
+
* Omitted, a concurrent recorder wins and this one appends after it. Named, a
|
|
217
|
+
* recorder that lost the race is told so and nothing is written — which is
|
|
218
|
+
* what a screen editing a policy wants, because the person was editing the
|
|
219
|
+
* text of a revision that is no longer the head.
|
|
220
|
+
*/
|
|
221
|
+
readonly expectedRevision?: number;
|
|
222
|
+
};
|
|
223
|
+
/**
|
|
224
|
+
* What recording did, which is not always *appended*.
|
|
225
|
+
*
|
|
226
|
+
* Three outcomes rather than one revision, because the three want different
|
|
227
|
+
* sentences on a screen and a caller that could not tell them apart would
|
|
228
|
+
* report a deployment restart as a policy edit.
|
|
229
|
+
*/
|
|
230
|
+
export type PolicyRecorded =
|
|
231
|
+
/** Nothing was recorded under this name before. There is no change to describe. */
|
|
232
|
+
{
|
|
233
|
+
readonly outcome: "first";
|
|
234
|
+
readonly revision: PolicyRevision;
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* An edit. `from` is the revision it replaced and `change` is what moved,
|
|
238
|
+
* derived here rather than stored — the view, over a log that is the truth.
|
|
239
|
+
*/
|
|
240
|
+
| {
|
|
241
|
+
readonly outcome: "changed";
|
|
242
|
+
readonly revision: PolicyRevision;
|
|
243
|
+
readonly from: PolicyRevision;
|
|
244
|
+
readonly change: PolicyChange;
|
|
245
|
+
}
|
|
246
|
+
/**
|
|
247
|
+
* The head already says this, so nothing was appended and the revision
|
|
248
|
+
* returned is the one that was already there.
|
|
249
|
+
*
|
|
250
|
+
* Compared against the head alone, never against the whole log: a policy
|
|
251
|
+
* edited to B and then back to A **is** a change somebody made at a time, and
|
|
252
|
+
* recording it has to append. Idempotence against the head is what stops a
|
|
253
|
+
* boot from writing; idempotence against history would lose a revert.
|
|
254
|
+
*/
|
|
255
|
+
| {
|
|
256
|
+
readonly outcome: "unchanged";
|
|
257
|
+
readonly revision: PolicyRevision;
|
|
258
|
+
};
|
|
259
|
+
/**
|
|
260
|
+
* Which recorded revision a judgment ran under.
|
|
261
|
+
*
|
|
262
|
+
* The join the finding asked for, and the reason `fingerprint` is a column: a
|
|
263
|
+
* `Disposition` carries one, and this turns it into the policy text it was made
|
|
264
|
+
* under. Three outcomes, and the second is the one a single-answer signature
|
|
265
|
+
* would have got wrong.
|
|
266
|
+
*/
|
|
267
|
+
export type PolicyProvenance = {
|
|
268
|
+
readonly outcome: "recorded";
|
|
269
|
+
readonly revision: PolicyRevision;
|
|
270
|
+
}
|
|
271
|
+
/**
|
|
272
|
+
* Several revisions carry this fingerprint, so the judgment ran under one of
|
|
273
|
+
* them and nothing can say which.
|
|
274
|
+
*
|
|
275
|
+
* A policy edited to B and back to A has two revisions with one fingerprint,
|
|
276
|
+
* which is correct — they are the same rules — and a reader asking *when* has
|
|
277
|
+
* no answer. Returning the oldest, or the newest, would be a confident wrong
|
|
278
|
+
* one. Oldest first, so a caller showing a range shows it in order.
|
|
279
|
+
*/
|
|
280
|
+
| {
|
|
281
|
+
readonly outcome: "ambiguous";
|
|
282
|
+
readonly revisions: readonly PolicyRevision[];
|
|
283
|
+
}
|
|
284
|
+
/**
|
|
285
|
+
* No recorded revision carries it. `heldShapes` is what the log does hold, so
|
|
286
|
+
* a reader can tell *nothing was ever recorded under this name* from *every
|
|
287
|
+
* revision recorded here came from a different build of Loom* — which
|
|
288
|
+
* `policyShapeOf` makes a fact rather than a guess, and which is the difference
|
|
289
|
+
* between a gap in the log and a gap in the comparison.
|
|
290
|
+
*/
|
|
291
|
+
| {
|
|
292
|
+
readonly outcome: "unrecorded";
|
|
293
|
+
readonly policyId: string;
|
|
294
|
+
readonly fingerprint: string;
|
|
295
|
+
readonly heldShapes: readonly string[];
|
|
296
|
+
};
|
|
297
|
+
/**
|
|
298
|
+
* Smaller than a tree revision page. A policy has tens of revisions over a
|
|
299
|
+
* deployment's life rather than thousands, and each one carries a whole policy;
|
|
300
|
+
* a page is sized for a screen showing a history, which is what reads this.
|
|
301
|
+
*/
|
|
302
|
+
export declare const DEFAULT_POLICY_REVISION_LIMIT = 25;
|
|
303
|
+
export declare const MAX_POLICY_REVISION_LIMIT = 100;
|
|
304
|
+
export declare const clampPolicyRevisionLimit: (limit: number | undefined) => number;
|
|
305
|
+
export type PolicyRevisionReadRequest = {
|
|
306
|
+
/** A cursor from a previous page's `older`/`newer`, passed back unread. */
|
|
307
|
+
readonly cursor?: string;
|
|
308
|
+
/**
|
|
309
|
+
* Default `newer`, which with no cursor is the oldest page — the read
|
|
310
|
+
* `policyHistoryOf` wants, because a history is folded in the order the edits
|
|
311
|
+
* were made. `older` with no cursor is the newest page, which is what a screen
|
|
312
|
+
* showing *what changed recently* asks for.
|
|
313
|
+
*/
|
|
314
|
+
readonly direction?: PageDirection;
|
|
315
|
+
readonly limit?: number;
|
|
316
|
+
};
|
|
317
|
+
export type PolicyRevisionPage = PageEnds & {
|
|
318
|
+
/**
|
|
319
|
+
* Always ascending by `revision`, whichever end the page was taken from — the
|
|
320
|
+
* rule `RevisionPage` keeps, and for the same reason: a page that sometimes
|
|
321
|
+
* came back reversed would make every consumer responsible for knowing which,
|
|
322
|
+
* and silently wrong when it guessed.
|
|
323
|
+
*/
|
|
324
|
+
readonly revisions: readonly PolicyRevision[];
|
|
325
|
+
};
|
|
326
|
+
/**
|
|
327
|
+
* One write and three reads.
|
|
328
|
+
*
|
|
329
|
+
* `record` is the only way the log ever grows, so a policy cannot change without
|
|
330
|
+
* leaving a record of who changed it. `current` is the O(1) read a host takes at
|
|
331
|
+
* boot. `revisions` is the paged read a history screen takes. `judgedUnder` is
|
|
332
|
+
* the fingerprint join, on the interface rather than derived from a page because
|
|
333
|
+
* a backend can index it — folding a page to find it would be correct and would
|
|
334
|
+
* only work for the revisions that happened to be on that page.
|
|
335
|
+
*
|
|
336
|
+
* Every read is bounded. `current` is one revision, `judgedUnder` is the
|
|
337
|
+
* revisions matching one digest, and `revisions` is a page with a clamped limit.
|
|
338
|
+
*
|
|
339
|
+
* A log handle **is** the scope it can see, as a store handle is: there is no
|
|
340
|
+
* `list` of policy names, because a deployment knows the names of its own
|
|
341
|
+
* policies and a reader that could enumerate them could reach past the handle
|
|
342
|
+
* it was given.
|
|
343
|
+
*/
|
|
344
|
+
export interface PolicyLog {
|
|
345
|
+
readonly record: (request: RecordPolicyRequest) => Promise<Result<PolicyRecorded, PolicyLogError>>;
|
|
346
|
+
readonly current: (policyId: string) => Promise<Result<PolicyRevision, PolicyLogError>>;
|
|
347
|
+
readonly revisions: (policyId: string, request?: PolicyRevisionReadRequest) => Promise<Result<PolicyRevisionPage, PolicyLogError>>;
|
|
348
|
+
readonly judgedUnder: (policyId: string, fingerprint: string) => Promise<Result<PolicyProvenance, PolicyLogError>>;
|
|
349
|
+
}
|
|
350
|
+
/** The read half, for consumers that never record. */
|
|
351
|
+
export type PolicyLogReader = Pick<PolicyLog, "current" | "revisions" | "judgedUnder">;
|
|
352
|
+
/**
|
|
353
|
+
* One edit, as a reader of a history sees it.
|
|
354
|
+
*
|
|
355
|
+
* The pair and the change between them, rather than a change alone: a screen
|
|
356
|
+
* showing *what happened on the 14th* needs the actor and the instant, and both
|
|
357
|
+
* are on the revision rather than in the comparison.
|
|
358
|
+
*/
|
|
359
|
+
export type PolicyEdit = {
|
|
360
|
+
readonly from: PolicyRevision;
|
|
361
|
+
readonly to: PolicyRevision;
|
|
362
|
+
readonly change: PolicyChange;
|
|
363
|
+
};
|
|
364
|
+
/**
|
|
365
|
+
* A run of revisions, folded into the edits between them.
|
|
366
|
+
*
|
|
367
|
+
* Pure, and over whatever page the caller has: the view that makes a calibration
|
|
368
|
+
* window straddling a policy change legible, which is the thing
|
|
369
|
+
* `rulesetContinuityOf` can report and cannot explain. Pairs are adjacent in the
|
|
370
|
+
* input, so a caller holding a page reads the edits inside it and the edit into
|
|
371
|
+
* the page is the one the previous page ends on.
|
|
372
|
+
*
|
|
373
|
+
* **Non-adjacent revisions are skipped rather than compared.** A page is dense
|
|
374
|
+
* by construction, but a caller may hand this the result of filtering one — and a
|
|
375
|
+
* comparison across a gap would describe a single edit that nobody made, folding
|
|
376
|
+
* several together and attributing the lot to whoever made the last.
|
|
377
|
+
*/
|
|
378
|
+
export declare const policyHistoryOf: (revisions: readonly PolicyRevision[]) => readonly PolicyEdit[];
|
|
379
|
+
/**
|
|
380
|
+
* The revisions a digest names, as a `PolicyProvenance`.
|
|
381
|
+
*
|
|
382
|
+
* Shared by every implementation, because *what does a set of matches mean* is a
|
|
383
|
+
* property of the join rather than of a backend — and it is the part most likely
|
|
384
|
+
* to drift between two of them. `heldShapes` is only read when nothing matched,
|
|
385
|
+
* so a backend passes what it can cheaply know: the shapes of the revisions it
|
|
386
|
+
* holds for that name.
|
|
387
|
+
*/
|
|
388
|
+
export declare const policyProvenanceOf: (policyId: string, fingerprint: string, matches: readonly PolicyRevision[], heldShapes: readonly string[]) => PolicyProvenance;
|
|
389
|
+
/**
|
|
390
|
+
* What a `record` call should do, given the head it is appending after.
|
|
391
|
+
*
|
|
392
|
+
* Shared rather than written per backend, because the three outcomes and the
|
|
393
|
+
* staleness check are the contract and not an implementation detail. A backend
|
|
394
|
+
* supplies the head and applies the answer; the rules live here, so two of them
|
|
395
|
+
* cannot disagree about whether a boot is an edit.
|
|
396
|
+
*/
|
|
397
|
+
export declare const recordOutcomeOf: (request: RecordPolicyRequest, head: PolicyRevision | undefined) => Result<PolicyRecorded, PolicyLogError>;
|
|
398
|
+
/**
|
|
399
|
+
* The reference implementation, and the one a host's tests run against.
|
|
400
|
+
*
|
|
401
|
+
* Keyed by `policyId` because that is what every read is scoped by, and the
|
|
402
|
+
* revisions under one name are a dense ascending list — the invariant
|
|
403
|
+
* `policyHistoryOf` folds on, enforced here by construction rather than checked.
|
|
404
|
+
*/
|
|
405
|
+
export declare const memoryPolicyLog: () => PolicyLog;
|
|
406
|
+
//# sourceMappingURL=policy-log.d.ts.map
|
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { clampLimit, cursorPosition, pageEnds, } from "../paging.js";
|
|
3
|
+
import { err, ok } from "../result.js";
|
|
4
|
+
import { policyChangeOf } from "./policy-change.js";
|
|
5
|
+
import { policyFingerprintOf, policyShapeOf } from "./policy-fingerprint.js";
|
|
6
|
+
import { gatePolicySchema } from "./policy.js";
|
|
7
|
+
/**
|
|
8
|
+
* The policy's own log.
|
|
9
|
+
*
|
|
10
|
+
* Everything else in Loom is built on the premise that a change to a page is
|
|
11
|
+
* logged, judged and reversible — and until this existed, **the policy was the
|
|
12
|
+
* one object in the system that could change silently.** A `Disposition` records
|
|
13
|
+
* `policyId` and `policyFingerprint`, so a reader can learn that two judgments
|
|
14
|
+
* ran under different rules and can learn nothing about what the rules were. A
|
|
15
|
+
* host that nudged a threshold in a config file and forgot left a corpus whose
|
|
16
|
+
* every record claims to have been judged by a name that no longer means what it
|
|
17
|
+
* meant.
|
|
18
|
+
*
|
|
19
|
+
* 0200 decides that a change to policy is a change a person made, recorded as
|
|
20
|
+
* one. This is where it is recorded. The relationship is 0016's, applied to the
|
|
21
|
+
* thing doing the judging rather than to the thing being judged: **the log is the
|
|
22
|
+
* truth and every reading of it is a view.**
|
|
23
|
+
*
|
|
24
|
+
* Three properties are deliberate.
|
|
25
|
+
*
|
|
26
|
+
* **It stores whole policies, never diffs.** `policyChangeOf` derives what moved
|
|
27
|
+
* between two of them, so there is no recorded description free to disagree with
|
|
28
|
+
* the policies it describes — and a reader may ask about a pair nobody
|
|
29
|
+
* anticipated, which a stored diff could not answer.
|
|
30
|
+
*
|
|
31
|
+
* **An actor is required and the runtime never supplies one.** A log whose whole
|
|
32
|
+
* point is *who did this* cannot have that field be optional; a revision nobody
|
|
33
|
+
* can be named for is not a record of a decision. The one unattributable case —
|
|
34
|
+
* judgments written before this log existed — is answered by the absence of a
|
|
35
|
+
* revision rather than by an invented one.
|
|
36
|
+
*
|
|
37
|
+
* **Recording what is already current is not a revision.** A host builds its
|
|
38
|
+
* policy at boot and `fixedPolicy` closes over it, so a deployment that records
|
|
39
|
+
* on start would otherwise append one revision per process. The log answers
|
|
40
|
+
* `unchanged` and hands back the head it already held.
|
|
41
|
+
*
|
|
42
|
+
* It is **not on the decision path.** `policy-source.ts` requires resolution to
|
|
43
|
+
* be synchronous and pure, and these are promises over storage; a host loads its
|
|
44
|
+
* policy, records it here, and closes over the value it already has.
|
|
45
|
+
*/
|
|
46
|
+
const recordedAtSchema = z.string().datetime();
|
|
47
|
+
/**
|
|
48
|
+
* The same shape, as something a stored row can be checked against.
|
|
49
|
+
*
|
|
50
|
+
* Held here rather than in a backend for the reason `heldProposalSchema` gives:
|
|
51
|
+
* a revision outlives the process that wrote it, and every implementation has to
|
|
52
|
+
* read one back the same way — a second store that parsed loosely would disagree
|
|
53
|
+
* with the first about what is storable, and a contract suite would not catch it
|
|
54
|
+
* because both would still round-trip their own writes.
|
|
55
|
+
*/
|
|
56
|
+
export const policyRevisionSchema = z.object({
|
|
57
|
+
policyId: z.string().min(1),
|
|
58
|
+
revision: z.number().int().positive(),
|
|
59
|
+
fingerprint: z.string().min(1),
|
|
60
|
+
policy: gatePolicySchema,
|
|
61
|
+
actor: z.string().min(1),
|
|
62
|
+
recordedAt: recordedAtSchema,
|
|
63
|
+
note: z.string().min(1).optional(),
|
|
64
|
+
});
|
|
65
|
+
export const describePolicyLogError = (error) => {
|
|
66
|
+
switch (error.code) {
|
|
67
|
+
case "no-such-policy":
|
|
68
|
+
return `no policy has been recorded under ${error.policyId}`;
|
|
69
|
+
case "out-of-date":
|
|
70
|
+
return `${error.policyId} is at revision ${error.current}, not ${error.expected}; somebody recorded a change in between`;
|
|
71
|
+
case "unavailable":
|
|
72
|
+
return `the policy log is unavailable: ${error.detail}`;
|
|
73
|
+
case "unreadable":
|
|
74
|
+
return `the policy log returned something this build cannot read: ${error.detail}`;
|
|
75
|
+
}
|
|
76
|
+
};
|
|
77
|
+
/**
|
|
78
|
+
* Reads a revision back out of storage, or says why it could not.
|
|
79
|
+
*
|
|
80
|
+
* The assertion is about the shape of optionality and never about validity, for
|
|
81
|
+
* the reason `parseHeldProposal` gives: Zod infers an optional field as
|
|
82
|
+
* `T | undefined`, which `exactOptionalPropertyTypes` distinguishes from an
|
|
83
|
+
* absent key, and JSON has no `undefined` at all.
|
|
84
|
+
*/
|
|
85
|
+
export const parsePolicyRevision = (row) => {
|
|
86
|
+
const parsed = policyRevisionSchema.safeParse(row);
|
|
87
|
+
return parsed.success
|
|
88
|
+
? ok(parsed.data)
|
|
89
|
+
: err({
|
|
90
|
+
code: "unreadable",
|
|
91
|
+
detail: `a stored policy revision did not parse: ${parsed.error.issues[0]?.path.join(".") ?? "unknown"}`,
|
|
92
|
+
});
|
|
93
|
+
};
|
|
94
|
+
/**
|
|
95
|
+
* Smaller than a tree revision page. A policy has tens of revisions over a
|
|
96
|
+
* deployment's life rather than thousands, and each one carries a whole policy;
|
|
97
|
+
* a page is sized for a screen showing a history, which is what reads this.
|
|
98
|
+
*/
|
|
99
|
+
export const DEFAULT_POLICY_REVISION_LIMIT = 25;
|
|
100
|
+
export const MAX_POLICY_REVISION_LIMIT = 100;
|
|
101
|
+
export const clampPolicyRevisionLimit = (limit) => clampLimit(limit, {
|
|
102
|
+
fallback: DEFAULT_POLICY_REVISION_LIMIT,
|
|
103
|
+
max: MAX_POLICY_REVISION_LIMIT,
|
|
104
|
+
});
|
|
105
|
+
/**
|
|
106
|
+
* A run of revisions, folded into the edits between them.
|
|
107
|
+
*
|
|
108
|
+
* Pure, and over whatever page the caller has: the view that makes a calibration
|
|
109
|
+
* window straddling a policy change legible, which is the thing
|
|
110
|
+
* `rulesetContinuityOf` can report and cannot explain. Pairs are adjacent in the
|
|
111
|
+
* input, so a caller holding a page reads the edits inside it and the edit into
|
|
112
|
+
* the page is the one the previous page ends on.
|
|
113
|
+
*
|
|
114
|
+
* **Non-adjacent revisions are skipped rather than compared.** A page is dense
|
|
115
|
+
* by construction, but a caller may hand this the result of filtering one — and a
|
|
116
|
+
* comparison across a gap would describe a single edit that nobody made, folding
|
|
117
|
+
* several together and attributing the lot to whoever made the last.
|
|
118
|
+
*/
|
|
119
|
+
export const policyHistoryOf = (revisions) => {
|
|
120
|
+
const ordered = [...revisions].sort((left, right) => left.revision - right.revision);
|
|
121
|
+
return ordered.flatMap((to, index) => {
|
|
122
|
+
const from = index === 0 ? undefined : ordered[index - 1];
|
|
123
|
+
if (from === undefined || to.revision !== from.revision + 1)
|
|
124
|
+
return [];
|
|
125
|
+
return [{ from, to, change: policyChangeOf(from.policy, to.policy) }];
|
|
126
|
+
});
|
|
127
|
+
};
|
|
128
|
+
/**
|
|
129
|
+
* The revisions a digest names, as a `PolicyProvenance`.
|
|
130
|
+
*
|
|
131
|
+
* Shared by every implementation, because *what does a set of matches mean* is a
|
|
132
|
+
* property of the join rather than of a backend — and it is the part most likely
|
|
133
|
+
* to drift between two of them. `heldShapes` is only read when nothing matched,
|
|
134
|
+
* so a backend passes what it can cheaply know: the shapes of the revisions it
|
|
135
|
+
* holds for that name.
|
|
136
|
+
*/
|
|
137
|
+
export const policyProvenanceOf = (policyId, fingerprint, matches, heldShapes) => {
|
|
138
|
+
const ordered = [...matches].sort((left, right) => left.revision - right.revision);
|
|
139
|
+
const first = ordered.at(0);
|
|
140
|
+
if (first === undefined) {
|
|
141
|
+
return {
|
|
142
|
+
outcome: "unrecorded",
|
|
143
|
+
policyId,
|
|
144
|
+
fingerprint,
|
|
145
|
+
heldShapes: Array.from(new Set(heldShapes)).sort(),
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
return ordered.length === 1
|
|
149
|
+
? { outcome: "recorded", revision: first }
|
|
150
|
+
: { outcome: "ambiguous", revisions: ordered };
|
|
151
|
+
};
|
|
152
|
+
/**
|
|
153
|
+
* A revision built from a policy and the facts around it.
|
|
154
|
+
*
|
|
155
|
+
* The fingerprint is computed here and never accepted from a caller, which is
|
|
156
|
+
* what keeps the one denormalised column honest: a caller that could supply it
|
|
157
|
+
* could supply a wrong one, and the whole value of the join is that the digest
|
|
158
|
+
* on a revision is the digest *of* that revision.
|
|
159
|
+
*/
|
|
160
|
+
const revisionOf = (request, revision) => {
|
|
161
|
+
const parsed = policyRevisionSchema.safeParse({
|
|
162
|
+
policyId: request.policy.policyId,
|
|
163
|
+
revision,
|
|
164
|
+
fingerprint: policyFingerprintOf(request.policy),
|
|
165
|
+
policy: request.policy,
|
|
166
|
+
actor: request.actor,
|
|
167
|
+
recordedAt: request.recordedAt,
|
|
168
|
+
...(request.note === undefined ? {} : { note: request.note }),
|
|
169
|
+
});
|
|
170
|
+
return parsed.success
|
|
171
|
+
? ok(parsed.data)
|
|
172
|
+
: err({
|
|
173
|
+
code: "unreadable",
|
|
174
|
+
detail: `a policy revision could not be recorded: ${parsed.error.issues[0]?.path.join(".") ?? "unknown"}`,
|
|
175
|
+
});
|
|
176
|
+
};
|
|
177
|
+
/**
|
|
178
|
+
* What a `record` call should do, given the head it is appending after.
|
|
179
|
+
*
|
|
180
|
+
* Shared rather than written per backend, because the three outcomes and the
|
|
181
|
+
* staleness check are the contract and not an implementation detail. A backend
|
|
182
|
+
* supplies the head and applies the answer; the rules live here, so two of them
|
|
183
|
+
* cannot disagree about whether a boot is an edit.
|
|
184
|
+
*/
|
|
185
|
+
export const recordOutcomeOf = (request, head) => {
|
|
186
|
+
const expected = request.expectedRevision;
|
|
187
|
+
const current = head?.revision ?? 0;
|
|
188
|
+
if (expected !== undefined && expected !== current) {
|
|
189
|
+
return err({
|
|
190
|
+
code: "out-of-date",
|
|
191
|
+
policyId: request.policy.policyId,
|
|
192
|
+
expected,
|
|
193
|
+
current,
|
|
194
|
+
});
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* The content test is the fingerprint and not the name: a rename *is* an edit,
|
|
198
|
+
* and `policyFingerprintOf` excludes the name, so the two conditions are both
|
|
199
|
+
* needed and neither is redundant (0033).
|
|
200
|
+
*/
|
|
201
|
+
if (head !== undefined &&
|
|
202
|
+
head.fingerprint === policyFingerprintOf(request.policy) &&
|
|
203
|
+
head.policyId === request.policy.policyId) {
|
|
204
|
+
return ok({ outcome: "unchanged", revision: head });
|
|
205
|
+
}
|
|
206
|
+
const built = revisionOf(request, current + 1);
|
|
207
|
+
if (!built.ok)
|
|
208
|
+
return built;
|
|
209
|
+
return ok(head === undefined
|
|
210
|
+
? { outcome: "first", revision: built.value }
|
|
211
|
+
: {
|
|
212
|
+
outcome: "changed",
|
|
213
|
+
revision: built.value,
|
|
214
|
+
from: head,
|
|
215
|
+
change: policyChangeOf(head.policy, built.value.policy),
|
|
216
|
+
});
|
|
217
|
+
};
|
|
218
|
+
/**
|
|
219
|
+
* The reference implementation, and the one a host's tests run against.
|
|
220
|
+
*
|
|
221
|
+
* Keyed by `policyId` because that is what every read is scoped by, and the
|
|
222
|
+
* revisions under one name are a dense ascending list — the invariant
|
|
223
|
+
* `policyHistoryOf` folds on, enforced here by construction rather than checked.
|
|
224
|
+
*/
|
|
225
|
+
export const memoryPolicyLog = () => {
|
|
226
|
+
const logs = new Map();
|
|
227
|
+
const entriesFor = (policyId) => logs.get(policyId) ?? [];
|
|
228
|
+
return {
|
|
229
|
+
record: (request) => {
|
|
230
|
+
const policyId = request.policy.policyId;
|
|
231
|
+
const entries = logs.get(policyId) ?? [];
|
|
232
|
+
const outcome = recordOutcomeOf(request, entries.at(-1));
|
|
233
|
+
if (!outcome.ok || outcome.value.outcome === "unchanged")
|
|
234
|
+
return Promise.resolve(outcome);
|
|
235
|
+
logs.set(policyId, [...entries, outcome.value.revision]);
|
|
236
|
+
return Promise.resolve(outcome);
|
|
237
|
+
},
|
|
238
|
+
current: (policyId) => {
|
|
239
|
+
const head = entriesFor(policyId).at(-1);
|
|
240
|
+
return Promise.resolve(head === undefined ? err({ code: "no-such-policy", policyId }) : ok(head));
|
|
241
|
+
},
|
|
242
|
+
revisions: (policyId, request) => {
|
|
243
|
+
const entries = entriesFor(policyId);
|
|
244
|
+
if (entries.length === 0) {
|
|
245
|
+
return Promise.resolve(err({ code: "no-such-policy", policyId }));
|
|
246
|
+
}
|
|
247
|
+
const direction = request?.direction ?? "newer";
|
|
248
|
+
const limit = clampPolicyRevisionLimit(request?.limit);
|
|
249
|
+
const from = cursorPosition(request?.cursor);
|
|
250
|
+
const remaining = entries.filter((entry) => from === undefined
|
|
251
|
+
? true
|
|
252
|
+
: direction === "older"
|
|
253
|
+
? entry.revision < from
|
|
254
|
+
: entry.revision > from);
|
|
255
|
+
/**
|
|
256
|
+
* `older` takes from the newest end and `newer` from the oldest, and both
|
|
257
|
+
* hand back an ascending page — so the `older` slice is taken off the tail
|
|
258
|
+
* rather than reversed and reversed back.
|
|
259
|
+
*/
|
|
260
|
+
const page = direction === "older"
|
|
261
|
+
? remaining.slice(Math.max(0, remaining.length - limit))
|
|
262
|
+
: remaining.slice(0, limit);
|
|
263
|
+
return Promise.resolve(ok({
|
|
264
|
+
revisions: page,
|
|
265
|
+
...pageEnds(page.map((entry) => entry.revision), direction, { beyond: remaining.length > page.length, resumed: from !== undefined }),
|
|
266
|
+
}));
|
|
267
|
+
},
|
|
268
|
+
judgedUnder: (policyId, fingerprint) => {
|
|
269
|
+
const entries = entriesFor(policyId);
|
|
270
|
+
return Promise.resolve(ok(policyProvenanceOf(policyId, fingerprint,
|
|
271
|
+
/**
|
|
272
|
+
* Bounded like the Postgres implementation, and the bound cannot
|
|
273
|
+
* change the answer: two or more matches is `ambiguous` whether or
|
|
274
|
+
* not the list is complete, because the verdict is *nothing can say
|
|
275
|
+
* which* either way.
|
|
276
|
+
*/
|
|
277
|
+
entries
|
|
278
|
+
.filter((entry) => entry.fingerprint === fingerprint)
|
|
279
|
+
.slice(0, MAX_POLICY_REVISION_LIMIT), entries
|
|
280
|
+
.slice(0, MAX_POLICY_REVISION_LIMIT)
|
|
281
|
+
.map((entry) => policyShapeOf(entry.fingerprint)))));
|
|
282
|
+
},
|
|
283
|
+
};
|
|
284
|
+
};
|
|
285
|
+
//# sourceMappingURL=policy-log.js.map
|