@jam-overture/loom 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +743 -0
- package/dist/catalogue.d.ts +70 -0
- package/dist/catalogue.js +88 -0
- package/dist/cli/args.d.ts +17 -0
- package/dist/cli/args.js +83 -0
- package/dist/cli/filesystem.d.ts +15 -0
- package/dist/cli/filesystem.js +31 -0
- package/dist/cli/index.d.ts +12 -0
- package/dist/cli/index.js +12 -0
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.js +30 -0
- package/dist/cli/namespace.d.ts +40 -0
- package/dist/cli/namespace.js +40 -0
- package/dist/cli/plan.d.ts +84 -0
- package/dist/cli/plan.js +113 -0
- package/dist/cli/run.d.ts +17 -0
- package/dist/cli/run.js +75 -0
- package/dist/cli/templates.d.ts +43 -0
- package/dist/cli/templates.js +134 -0
- package/dist/closed-set.d.ts +34 -0
- package/dist/closed-set.js +34 -0
- package/dist/data/adapter.d.ts +123 -0
- package/dist/data/adapter.js +91 -0
- package/dist/data/binding.d.ts +48 -0
- package/dist/data/binding.js +39 -0
- package/dist/data/catalogue.d.ts +26 -0
- package/dist/data/catalogue.js +6 -0
- package/dist/data/index.d.ts +14 -0
- package/dist/data/index.js +14 -0
- package/dist/data/plan.d.ts +58 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +91 -0
- package/dist/data/resolution.js +96 -0
- package/dist/data/resolve.d.ts +46 -0
- package/dist/data/resolve.js +37 -0
- package/dist/data/source.d.ts +40 -0
- package/dist/data/source.js +45 -0
- package/dist/deadline.d.ts +57 -0
- package/dist/deadline.js +78 -0
- package/dist/frame/catalogue.d.ts +24 -0
- package/dist/frame/catalogue.js +5 -0
- package/dist/frame/index.d.ts +12 -0
- package/dist/frame/index.js +12 -0
- package/dist/frame/origin.d.ts +87 -0
- package/dist/frame/origin.js +114 -0
- package/dist/frame/resolution.d.ts +85 -0
- package/dist/frame/resolution.js +79 -0
- package/dist/grammar.d.ts +26 -0
- package/dist/grammar.js +28 -0
- package/dist/ids.d.ts +57 -0
- package/dist/ids.js +104 -0
- package/dist/index.d.ts +26 -0
- package/dist/index.js +26 -0
- package/dist/interactivity.d.ts +50 -0
- package/dist/interactivity.js +22 -0
- package/dist/interpretation/anthropic.d.ts +22 -0
- package/dist/interpretation/anthropic.js +76 -0
- package/dist/interpretation/client.d.ts +83 -0
- package/dist/interpretation/client.js +2 -0
- package/dist/interpretation/draft.d.ts +234 -0
- package/dist/interpretation/draft.js +84 -0
- package/dist/interpretation/index.d.ts +15 -0
- package/dist/interpretation/index.js +15 -0
- package/dist/interpretation/interpreter.d.ts +62 -0
- package/dist/interpretation/interpreter.js +151 -0
- package/dist/interpretation/materialize.d.ts +42 -0
- package/dist/interpretation/materialize.js +107 -0
- package/dist/interpretation/prompt.d.ts +229 -0
- package/dist/interpretation/prompt.js +285 -0
- package/dist/interpretation/render.d.ts +76 -0
- package/dist/interpretation/render.js +272 -0
- package/dist/interpretation/schema.d.ts +49 -0
- package/dist/interpretation/schema.js +131 -0
- package/dist/json.d.ts +35 -0
- package/dist/json.js +11 -0
- package/dist/paging.d.ts +60 -0
- package/dist/paging.js +49 -0
- package/dist/primitive-type.d.ts +32 -0
- package/dist/primitive-type.js +39 -0
- package/dist/render/addressing.d.ts +59 -0
- package/dist/render/addressing.js +60 -0
- package/dist/render/anchor.d.ts +105 -0
- package/dist/render/anchor.js +84 -0
- package/dist/render/behaviour-adjust.d.ts +62 -0
- package/dist/render/behaviour-adjust.js +78 -0
- package/dist/render/behaviour-copy.d.ts +53 -0
- package/dist/render/behaviour-copy.js +75 -0
- package/dist/render/behaviour-disclose.d.ts +74 -0
- package/dist/render/behaviour-disclose.js +77 -0
- package/dist/render/behaviour-present.d.ts +123 -0
- package/dist/render/behaviour-present.js +173 -0
- package/dist/render/behaviour.d.ts +243 -0
- package/dist/render/behaviour.js +284 -0
- package/dist/render/control.d.ts +81 -0
- package/dist/render/control.js +80 -0
- package/dist/render/decorative.d.ts +62 -0
- package/dist/render/decorative.js +2 -0
- package/dist/render/diagnostics.d.ts +260 -0
- package/dist/render/diagnostics.js +61 -0
- package/dist/render/disclosed.d.ts +37 -0
- package/dist/render/disclosed.js +37 -0
- package/dist/render/editable.d.ts +34 -0
- package/dist/render/editable.js +35 -0
- package/dist/render/frame.d.ts +42 -0
- package/dist/render/frame.js +31 -0
- package/dist/render/index.d.ts +35 -0
- package/dist/render/index.js +35 -0
- package/dist/render/inline-variables.d.ts +77 -0
- package/dist/render/inline-variables.js +220 -0
- package/dist/render/presented.d.ts +82 -0
- package/dist/render/presented.js +82 -0
- package/dist/render/primitive.d.ts +228 -0
- package/dist/render/primitive.js +36 -0
- package/dist/render/props.d.ts +48 -0
- package/dist/render/props.js +2 -0
- package/dist/render/reads.d.ts +73 -0
- package/dist/render/reads.js +45 -0
- package/dist/render/render.d.ts +164 -0
- package/dist/render/render.js +571 -0
- package/dist/render/request.d.ts +111 -0
- package/dist/render/request.js +60 -0
- package/dist/render/text.d.ts +91 -0
- package/dist/render/text.js +44 -0
- package/dist/render/theme.d.ts +61 -0
- package/dist/render/theme.js +52 -0
- package/dist/reserved-props.d.ts +35 -0
- package/dist/reserved-props.js +45 -0
- package/dist/result.d.ts +27 -0
- package/dist/result.js +30 -0
- package/dist/role.d.ts +71 -0
- package/dist/role.js +22 -0
- package/dist/runtime/analysis.d.ts +149 -0
- package/dist/runtime/analysis.js +187 -0
- package/dist/runtime/assessment.d.ts +35 -0
- package/dist/runtime/assessment.js +13 -0
- package/dist/runtime/disposition.d.ts +102 -0
- package/dist/runtime/disposition.js +59 -0
- package/dist/runtime/events.d.ts +187 -0
- package/dist/runtime/events.js +7 -0
- package/dist/runtime/gate.d.ts +43 -0
- package/dist/runtime/gate.js +169 -0
- package/dist/runtime/index.d.ts +27 -0
- package/dist/runtime/index.js +27 -0
- package/dist/runtime/intent.d.ts +60 -0
- package/dist/runtime/intent.js +36 -0
- package/dist/runtime/interpreter.d.ts +117 -0
- package/dist/runtime/interpreter.js +46 -0
- package/dist/runtime/inverse-interpreter.d.ts +90 -0
- package/dist/runtime/inverse-interpreter.js +56 -0
- package/dist/runtime/inverse.d.ts +87 -0
- package/dist/runtime/inverse.js +48 -0
- package/dist/runtime/narration.d.ts +24 -0
- package/dist/runtime/narration.js +36 -0
- package/dist/runtime/nesting.d.ts +31 -0
- package/dist/runtime/nesting.js +46 -0
- package/dist/runtime/pipeline.d.ts +124 -0
- package/dist/runtime/pipeline.js +178 -0
- package/dist/runtime/policy-fingerprint.d.ts +29 -0
- package/dist/runtime/policy-fingerprint.js +119 -0
- package/dist/runtime/policy-source.d.ts +42 -0
- package/dist/runtime/policy-source.js +8 -0
- package/dist/runtime/policy.d.ts +156 -0
- package/dist/runtime/policy.js +107 -0
- package/dist/runtime/proposal.d.ts +423 -0
- package/dist/runtime/proposal.js +109 -0
- package/dist/runtime/redirection.d.ts +53 -0
- package/dist/runtime/redirection.js +38 -0
- package/dist/runtime/repointing.d.ts +71 -0
- package/dist/runtime/repointing.js +0 -0
- package/dist/runtime/reversibility.d.ts +36 -0
- package/dist/runtime/reversibility.js +39 -0
- package/dist/runtime/stake-level.d.ts +33 -0
- package/dist/runtime/stake-level.js +58 -0
- package/dist/runtime/stakes.d.ts +47 -0
- package/dist/runtime/stakes.js +305 -0
- package/dist/runtime/vocabulary.d.ts +122 -0
- package/dist/runtime/vocabulary.js +87 -0
- package/dist/sdk/audit.d.ts +195 -0
- package/dist/sdk/audit.js +128 -0
- package/dist/sdk/catalogue.d.ts +37 -0
- package/dist/sdk/catalogue.js +16 -0
- package/dist/sdk/conformance.d.ts +342 -0
- package/dist/sdk/conformance.js +494 -0
- package/dist/sdk/copy.d.ts +105 -0
- package/dist/sdk/copy.js +90 -0
- package/dist/sdk/definition.d.ts +242 -0
- package/dist/sdk/definition.js +64 -0
- package/dist/sdk/index.d.ts +19 -0
- package/dist/sdk/index.js +19 -0
- package/dist/sdk/interactivity.d.ts +29 -0
- package/dist/sdk/interactivity.js +34 -0
- package/dist/sdk/pairings.d.ts +124 -0
- package/dist/sdk/pairings.js +81 -0
- package/dist/sdk/registry.d.ts +162 -0
- package/dist/sdk/registry.js +329 -0
- package/dist/sdk/selection.d.ts +46 -0
- package/dist/sdk/selection.js +24 -0
- package/dist/sdk/text.d.ts +100 -0
- package/dist/sdk/text.js +105 -0
- package/dist/sdk/vocabulary.d.ts +39 -0
- package/dist/sdk/vocabulary.js +36 -0
- package/dist/signals/broadcast.d.ts +134 -0
- package/dist/signals/broadcast.js +451 -0
- package/dist/signals/collect.d.ts +184 -0
- package/dist/signals/collect.js +196 -0
- package/dist/signals/deliver.d.ts +64 -0
- package/dist/signals/deliver.js +85 -0
- package/dist/signals/fold.d.ts +112 -0
- package/dist/signals/fold.js +76 -0
- package/dist/signals/index.d.ts +31 -0
- package/dist/signals/index.js +31 -0
- package/dist/signals/ingest.d.ts +51 -0
- package/dist/signals/ingest.js +70 -0
- package/dist/signals/intake.d.ts +149 -0
- package/dist/signals/intake.js +154 -0
- package/dist/signals/journal.d.ts +94 -0
- package/dist/signals/journal.js +11 -0
- package/dist/signals/kinds.d.ts +22 -0
- package/dist/signals/kinds.js +22 -0
- package/dist/signals/ledger.d.ts +46 -0
- package/dist/signals/ledger.js +81 -0
- package/dist/signals/memory.d.ts +17 -0
- package/dist/signals/memory.js +99 -0
- package/dist/signals/migrate.d.ts +27 -0
- package/dist/signals/migrate.js +78 -0
- package/dist/signals/postgres.d.ts +7 -0
- package/dist/signals/postgres.js +295 -0
- package/dist/signals/rollup.d.ts +142 -0
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +534 -0
- package/dist/signals/schema.js +92 -0
- package/dist/signals/signal.d.ts +381 -0
- package/dist/signals/signal.js +150 -0
- package/dist/signals/tally.d.ts +70 -0
- package/dist/signals/tally.js +2 -0
- package/dist/signals/view.d.ts +51 -0
- package/dist/signals/view.js +54 -0
- package/dist/store/attribution.d.ts +125 -0
- package/dist/store/attribution.js +116 -0
- package/dist/store/database.d.ts +14 -0
- package/dist/store/database.js +2 -0
- package/dist/store/driver.d.ts +29 -0
- package/dist/store/driver.js +39 -0
- package/dist/store/errors.d.ts +56 -0
- package/dist/store/errors.js +37 -0
- package/dist/store/index.d.ts +16 -0
- package/dist/store/index.js +16 -0
- package/dist/store/memory.d.ts +3 -0
- package/dist/store/memory.js +115 -0
- package/dist/store/migrate.d.ts +54 -0
- package/dist/store/migrate.js +122 -0
- package/dist/store/postgres-holds.d.ts +4 -0
- package/dist/store/postgres-holds.js +192 -0
- package/dist/store/postgres.d.ts +8 -0
- package/dist/store/postgres.js +262 -0
- package/dist/store/replay.d.ts +94 -0
- package/dist/store/replay.js +82 -0
- package/dist/store/revert.d.ts +116 -0
- package/dist/store/revert.js +243 -0
- package/dist/store/schema.d.ts +371 -0
- package/dist/store/schema.js +78 -0
- package/dist/store/source.d.ts +23 -0
- package/dist/store/source.js +37 -0
- package/dist/store/store.d.ts +231 -0
- package/dist/store/store.js +52 -0
- package/dist/store/undone.d.ts +18 -0
- package/dist/store/undone.js +89 -0
- package/dist/submit/catalogue.d.ts +20 -0
- package/dist/submit/catalogue.js +5 -0
- package/dist/submit/declaration.d.ts +39 -0
- package/dist/submit/declaration.js +30 -0
- package/dist/submit/endpoint.d.ts +131 -0
- package/dist/submit/endpoint.js +160 -0
- package/dist/submit/index.d.ts +13 -0
- package/dist/submit/index.js +13 -0
- package/dist/submit/plan.d.ts +49 -0
- package/dist/submit/plan.js +47 -0
- package/dist/submit/resolution.d.ts +61 -0
- package/dist/submit/resolution.js +64 -0
- package/dist/submit/resolve.d.ts +45 -0
- package/dist/submit/resolve.js +36 -0
- package/dist/telemetry/calibration.d.ts +132 -0
- package/dist/telemetry/calibration.js +151 -0
- package/dist/telemetry/episode.d.ts +140 -0
- package/dist/telemetry/episode.js +272 -0
- package/dist/telemetry/event.d.ts +2310 -0
- package/dist/telemetry/event.js +405 -0
- package/dist/telemetry/index.d.ts +15 -0
- package/dist/telemetry/index.js +15 -0
- package/dist/telemetry/journal.d.ts +116 -0
- package/dist/telemetry/journal.js +11 -0
- package/dist/telemetry/memory.d.ts +24 -0
- package/dist/telemetry/memory.js +75 -0
- package/dist/telemetry/migrate.d.ts +26 -0
- package/dist/telemetry/migrate.js +40 -0
- package/dist/telemetry/postgres.d.ts +6 -0
- package/dist/telemetry/postgres.js +139 -0
- package/dist/telemetry/retention.d.ts +131 -0
- package/dist/telemetry/retention.js +217 -0
- package/dist/telemetry/schema.d.ts +113 -0
- package/dist/telemetry/schema.js +33 -0
- package/dist/telemetry/sink.d.ts +42 -0
- package/dist/telemetry/sink.js +61 -0
- package/dist/testing/contracts.d.ts +34 -0
- package/dist/testing/contracts.js +34 -0
- package/dist/testing/definitions.d.ts +15 -0
- package/dist/testing/definitions.js +48 -0
- package/dist/testing/doubles.d.ts +94 -0
- package/dist/testing/doubles.js +141 -0
- package/dist/testing/episode-harness.d.ts +49 -0
- package/dist/testing/episode-harness.js +65 -0
- package/dist/testing/filesystem.d.ts +17 -0
- package/dist/testing/filesystem.js +17 -0
- package/dist/testing/fixtures.d.ts +57 -0
- package/dist/testing/fixtures.js +84 -0
- package/dist/testing/hold-contract.d.ts +19 -0
- package/dist/testing/hold-contract.js +374 -0
- package/dist/testing/index.d.ts +41 -0
- package/dist/testing/index.js +41 -0
- package/dist/testing/journal-contract.d.ts +17 -0
- package/dist/testing/journal-contract.js +353 -0
- package/dist/testing/model-replies.d.ts +34 -0
- package/dist/testing/model-replies.js +101 -0
- package/dist/testing/primitives.d.ts +7 -0
- package/dist/testing/primitives.js +29 -0
- package/dist/testing/reader-signal-contract.d.ts +38 -0
- package/dist/testing/reader-signal-contract.js +318 -0
- package/dist/testing/row-security.d.ts +17 -0
- package/dist/testing/row-security.js +21 -0
- package/dist/testing/store-contract.d.ts +25 -0
- package/dist/testing/store-contract.js +500 -0
- package/dist/theme/apply.d.ts +17 -0
- package/dist/theme/apply.js +60 -0
- package/dist/theme/contrast.d.ts +197 -0
- package/dist/theme/contrast.js +259 -0
- package/dist/theme/derive.d.ts +77 -0
- package/dist/theme/derive.js +167 -0
- package/dist/theme/faces.d.ts +73 -0
- package/dist/theme/faces.js +119 -0
- package/dist/theme/font-packs.d.ts +25 -0
- package/dist/theme/font-packs.js +257 -0
- package/dist/theme/index.d.ts +20 -0
- package/dist/theme/index.js +20 -0
- package/dist/theme/lab.d.ts +30 -0
- package/dist/theme/lab.js +46 -0
- package/dist/theme/library.d.ts +114 -0
- package/dist/theme/library.js +300 -0
- package/dist/theme/measure.d.ts +144 -0
- package/dist/theme/measure.js +145 -0
- package/dist/theme/palettes.d.ts +64 -0
- package/dist/theme/palettes.js +497 -0
- package/dist/theme/registry.d.ts +59 -0
- package/dist/theme/registry.js +60 -0
- package/dist/theme/separation.d.ts +177 -0
- package/dist/theme/separation.js +203 -0
- package/dist/theme/style-presets.d.ts +60 -0
- package/dist/theme/style-presets.js +124 -0
- package/dist/theme/theme.d.ts +253 -0
- package/dist/theme/theme.js +171 -0
- package/dist/tree/apply.d.ts +16 -0
- package/dist/tree/apply.js +104 -0
- package/dist/tree/builders.d.ts +19 -0
- package/dist/tree/builders.js +20 -0
- package/dist/tree/compare.d.ts +68 -0
- package/dist/tree/compare.js +75 -0
- package/dist/tree/configuration.d.ts +25 -0
- package/dist/tree/configuration.js +108 -0
- package/dist/tree/delta.d.ts +288 -0
- package/dist/tree/delta.js +88 -0
- package/dist/tree/errors.d.ts +69 -0
- package/dist/tree/errors.js +34 -0
- package/dist/tree/identity.d.ts +117 -0
- package/dist/tree/identity.js +145 -0
- package/dist/tree/index.d.ts +21 -0
- package/dist/tree/index.js +21 -0
- package/dist/tree/inverse.d.ts +24 -0
- package/dist/tree/inverse.js +112 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +49 -0
- package/dist/tree/naming.d.ts +4 -0
- package/dist/tree/naming.js +35 -0
- package/dist/tree/navigation.d.ts +38 -0
- package/dist/tree/navigation.js +83 -0
- package/dist/tree/node.d.ts +103 -0
- package/dist/tree/node.js +46 -0
- package/dist/tree/outline.d.ts +28 -0
- package/dist/tree/outline.js +10 -0
- package/dist/tree/tree.d.ts +83 -0
- package/dist/tree/tree.js +62 -0
- package/dist/write/commit.d.ts +124 -0
- package/dist/write/commit.js +234 -0
- package/dist/write/held.d.ts +674 -0
- package/dist/write/held.js +185 -0
- package/dist/write/index.d.ts +11 -0
- package/dist/write/index.js +11 -0
- package/dist/write/liveness.d.ts +132 -0
- package/dist/write/liveness.js +91 -0
- package/dist/write/revert.d.ts +79 -0
- package/dist/write/revert.js +134 -0
- package/package.json +160 -0
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { proposalIdSchema, treeIdSchema } from "../ids.js";
|
|
3
|
+
import { clampLimit } from "../paging.js";
|
|
4
|
+
import { err, ok } from "../result.js";
|
|
5
|
+
import { dispositionSchema } from "../runtime/disposition.js";
|
|
6
|
+
import { editIntentSchema } from "../runtime/intent.js";
|
|
7
|
+
import { proposedChangeSchema } from "../runtime/proposal.js";
|
|
8
|
+
/**
|
|
9
|
+
* The same shape, as something a stored row can be checked against.
|
|
10
|
+
*
|
|
11
|
+
* It exists for the reason `dispositionSchema`'s comment gives: a hold outlives
|
|
12
|
+
* the process that created it, and a judgment restored from storage is validated
|
|
13
|
+
* at that boundary like anything else that crossed a wire or a year. Held here
|
|
14
|
+
* rather than in a backend so that every implementation reads a hold back the
|
|
15
|
+
* same way — a second store that parsed loosely would disagree with the first
|
|
16
|
+
* about what is storable, and the contract suite would not catch it because both
|
|
17
|
+
* would still round-trip their own writes.
|
|
18
|
+
*/
|
|
19
|
+
/**
|
|
20
|
+
* Named rather than inlined because a cursor carries one back: a page of holds
|
|
21
|
+
* resumes from an instant and an id, and the instant it resumes from has to be
|
|
22
|
+
* held to the same shape on the way in as it was on the way out.
|
|
23
|
+
*/
|
|
24
|
+
const heldAtSchema = z.string().datetime();
|
|
25
|
+
export const heldProposalSchema = z.object({
|
|
26
|
+
proposalId: proposalIdSchema,
|
|
27
|
+
treeId: treeIdSchema,
|
|
28
|
+
baseRevision: z.number().int().nonnegative(),
|
|
29
|
+
intent: editIntentSchema,
|
|
30
|
+
proposal: proposedChangeSchema,
|
|
31
|
+
disposition: dispositionSchema,
|
|
32
|
+
heldAt: heldAtSchema,
|
|
33
|
+
});
|
|
34
|
+
export const describeHoldError = (error) => {
|
|
35
|
+
switch (error.code) {
|
|
36
|
+
case "not-held":
|
|
37
|
+
return `no proposal is held under ${error.proposalId}; it may already have been answered`;
|
|
38
|
+
case "already-held":
|
|
39
|
+
return `${error.proposalId} is already held`;
|
|
40
|
+
case "unavailable":
|
|
41
|
+
return `the holding store is unavailable: ${error.detail}`;
|
|
42
|
+
case "unreadable":
|
|
43
|
+
return `the holding store returned something this build cannot read: ${error.detail}`;
|
|
44
|
+
}
|
|
45
|
+
};
|
|
46
|
+
/**
|
|
47
|
+
* Reads a hold back out of storage, or says why it could not.
|
|
48
|
+
*
|
|
49
|
+
* The assertion is about the shape of optionality and never about validity — the
|
|
50
|
+
* schema above establishes that. Zod infers an optional field as `T | undefined`,
|
|
51
|
+
* which `exactOptionalPropertyTypes` distinguishes from an absent key, while JSON
|
|
52
|
+
* has no `undefined` at all: a stored hold either carries `actor` or omits it,
|
|
53
|
+
* and never holds it as an explicit nothing. So the parsed value already has the
|
|
54
|
+
* shape the type asks for, and this is the one place that has to say so.
|
|
55
|
+
*/
|
|
56
|
+
export const parseHeldProposal = (row) => {
|
|
57
|
+
const parsed = heldProposalSchema.safeParse(row);
|
|
58
|
+
return parsed.success
|
|
59
|
+
? ok(parsed.data)
|
|
60
|
+
: err({
|
|
61
|
+
code: "unreadable",
|
|
62
|
+
detail: `a stored hold did not parse: ${parsed.error.issues[0]?.path.join(".") ?? "unknown"}`,
|
|
63
|
+
});
|
|
64
|
+
};
|
|
65
|
+
const compareStrings = (left, right) => {
|
|
66
|
+
if (left < right)
|
|
67
|
+
return -1;
|
|
68
|
+
return left > right ? 1 : 0;
|
|
69
|
+
};
|
|
70
|
+
/**
|
|
71
|
+
* The order both listings are in: oldest first, then by id.
|
|
72
|
+
*
|
|
73
|
+
* Written once and shared for the reason `pageEnds` and `anchorBound` are — it
|
|
74
|
+
* is the part most likely to drift between two backends and least likely to be
|
|
75
|
+
* noticed when it does. `postgresHoldStore` is the one caller that cannot use
|
|
76
|
+
* it, because ordering has to happen in the statement for an index to be usable;
|
|
77
|
+
* its `ORDER BY` names this function, and the contract suite is what holds the
|
|
78
|
+
* two to the same answer.
|
|
79
|
+
*/
|
|
80
|
+
export const compareHolds = (left, right) => compareStrings(left.heldAt, right.heldAt) || compareStrings(left.proposalId, right.proposalId);
|
|
81
|
+
const CURSOR_SEPARATOR = " ";
|
|
82
|
+
export const holdCursor = (position) => `${position.heldAt}${CURSOR_SEPARATOR}${position.proposalId}`;
|
|
83
|
+
/**
|
|
84
|
+
* Reads a cursor back into the position it names, or says it cannot.
|
|
85
|
+
*
|
|
86
|
+
* Unreadable means the same thing here as everywhere else in Loom (see
|
|
87
|
+
* `cursorPosition`): start at the beginning, rather than one implementation
|
|
88
|
+
* refusing what another silently accepts. Both halves are checked, because a
|
|
89
|
+
* cursor that survived a URL is a value from outside — and a position built
|
|
90
|
+
* from an instant that is not one would compare against nonsense and page from
|
|
91
|
+
* somewhere no caller asked for. The separator is a space, which neither an
|
|
92
|
+
* RFC 3339 instant nor an id can contain.
|
|
93
|
+
*/
|
|
94
|
+
export const holdCursorPosition = (cursor) => {
|
|
95
|
+
if (cursor === undefined)
|
|
96
|
+
return undefined;
|
|
97
|
+
const separator = cursor.indexOf(CURSOR_SEPARATOR);
|
|
98
|
+
if (separator === -1)
|
|
99
|
+
return undefined;
|
|
100
|
+
return holdPosition({
|
|
101
|
+
heldAt: cursor.slice(0, separator),
|
|
102
|
+
proposalId: cursor.slice(separator + 1),
|
|
103
|
+
});
|
|
104
|
+
};
|
|
105
|
+
/**
|
|
106
|
+
* The two columns a page is ordered by, checked, or nothing.
|
|
107
|
+
*
|
|
108
|
+
* Separate from reading a whole hold because it is a strictly smaller question
|
|
109
|
+
* and it is the one a listing cannot proceed without. A backend that skips the
|
|
110
|
+
* rows it could not read still has to page past them, and it can only do that
|
|
111
|
+
* if it can position them — so the position is parsed first and on its own,
|
|
112
|
+
* and a row that has one is a row the queue can always name and always get
|
|
113
|
+
* beyond, whatever its payload turned out to be.
|
|
114
|
+
*/
|
|
115
|
+
export const holdPosition = (row) => {
|
|
116
|
+
const heldAt = heldAtSchema.safeParse(row.heldAt);
|
|
117
|
+
const proposalId = proposalIdSchema.safeParse(row.proposalId);
|
|
118
|
+
return heldAt.success && proposalId.success
|
|
119
|
+
? { heldAt: heldAt.data, proposalId: proposalId.data }
|
|
120
|
+
: undefined;
|
|
121
|
+
};
|
|
122
|
+
/**
|
|
123
|
+
* Smaller than a tree listing's page, because a held proposal is the heaviest
|
|
124
|
+
* row this store keeps: a whole delta, the intent that asked for it, and the
|
|
125
|
+
* judgment that held it back. A reviewer reads them one at a time, so a page is
|
|
126
|
+
* sized for a screen rather than for a fold.
|
|
127
|
+
*/
|
|
128
|
+
export const DEFAULT_HOLD_LIMIT = 25;
|
|
129
|
+
export const MAX_HOLD_LIMIT = 100;
|
|
130
|
+
export const clampHoldLimit = (limit) => clampLimit(limit, { fallback: DEFAULT_HOLD_LIMIT, max: MAX_HOLD_LIMIT });
|
|
131
|
+
/**
|
|
132
|
+
* The reference implementation. Both listings are in `compareHolds` order, so a
|
|
133
|
+
* queue reads oldest-first: a change that has been waiting longest is the one
|
|
134
|
+
* most likely to be about to go stale.
|
|
135
|
+
*/
|
|
136
|
+
export const memoryHoldStore = () => {
|
|
137
|
+
const held = new Map();
|
|
138
|
+
return {
|
|
139
|
+
hold: (proposal) => Promise.resolve(held.has(proposal.proposalId)
|
|
140
|
+
? err({ code: "already-held", proposalId: proposal.proposalId })
|
|
141
|
+
: (() => {
|
|
142
|
+
held.set(proposal.proposalId, proposal);
|
|
143
|
+
return ok(proposal);
|
|
144
|
+
})()),
|
|
145
|
+
get: (proposalId) => {
|
|
146
|
+
const found = held.get(proposalId);
|
|
147
|
+
return Promise.resolve(found ? ok(found) : err({ code: "not-held", proposalId }));
|
|
148
|
+
},
|
|
149
|
+
forTree: (treeId) => Promise.resolve(ok({
|
|
150
|
+
held: Array.from(held.values())
|
|
151
|
+
.filter((proposal) => proposal.treeId === treeId)
|
|
152
|
+
.sort(compareHolds),
|
|
153
|
+
/**
|
|
154
|
+
* Always empty, and not because this implementation is careless: it
|
|
155
|
+
* holds parsed values rather than rows, so there is no such thing
|
|
156
|
+
* here as a hold it cannot read. The field is present so that a
|
|
157
|
+
* caller written against the contract reads the same shape from both
|
|
158
|
+
* stores and never branches on which one it was handed.
|
|
159
|
+
*/
|
|
160
|
+
unreadable: [],
|
|
161
|
+
})),
|
|
162
|
+
waiting: (request) => {
|
|
163
|
+
const limit = clampHoldLimit(request?.limit);
|
|
164
|
+
const from = holdCursorPosition(request?.cursor);
|
|
165
|
+
const remaining = Array.from(held.values())
|
|
166
|
+
.sort(compareHolds)
|
|
167
|
+
.filter((proposal) => from === undefined || compareHolds(proposal, from) > 0);
|
|
168
|
+
const page = remaining.slice(0, limit);
|
|
169
|
+
const last = page.at(-1);
|
|
170
|
+
return Promise.resolve(ok({
|
|
171
|
+
held: page,
|
|
172
|
+
unreadable: [],
|
|
173
|
+
cursor: last !== undefined && remaining.length > page.length ? holdCursor(last) : null,
|
|
174
|
+
}));
|
|
175
|
+
},
|
|
176
|
+
release: (proposalId) => {
|
|
177
|
+
const found = held.get(proposalId);
|
|
178
|
+
if (!found)
|
|
179
|
+
return Promise.resolve(err({ code: "not-held", proposalId }));
|
|
180
|
+
held.delete(proposalId);
|
|
181
|
+
return Promise.resolve(ok(found));
|
|
182
|
+
},
|
|
183
|
+
};
|
|
184
|
+
};
|
|
185
|
+
//# sourceMappingURL=held.js.map
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Committing a judged change, and taking one back.
|
|
3
|
+
*
|
|
4
|
+
* The three operations that move a tree forward or backward in the store once the
|
|
5
|
+
* gate has had its say.
|
|
6
|
+
*/
|
|
7
|
+
export * from "./commit.js";
|
|
8
|
+
export * from "./held.js";
|
|
9
|
+
export * from "./liveness.js";
|
|
10
|
+
export * from "./revert.js";
|
|
11
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Committing a judged change, and taking one back.
|
|
3
|
+
*
|
|
4
|
+
* The three operations that move a tree forward or backward in the store once the
|
|
5
|
+
* gate has had its say.
|
|
6
|
+
*/
|
|
7
|
+
export * from "./commit.js";
|
|
8
|
+
export * from "./held.js";
|
|
9
|
+
export * from "./liveness.js";
|
|
10
|
+
export * from "./revert.js";
|
|
11
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
import type { TreeId } from "../ids.js";
|
|
2
|
+
import type { StoreError } from "../store/errors.js";
|
|
3
|
+
import type { TreeReader } from "../store/store.js";
|
|
4
|
+
import type { HeldProposal } from "./held.js";
|
|
5
|
+
/**
|
|
6
|
+
* Which of the changes waiting for an answer can still happen.
|
|
7
|
+
*
|
|
8
|
+
* `confirmHeld` compares the revision a proposal was judged against to the head
|
|
9
|
+
* it would land on, and when they differ it releases the hold and reports
|
|
10
|
+
* `revision-conflict` — dead rather than stale, because the delta can never
|
|
11
|
+
* apply again and a second attempt at something impossible is worse than no
|
|
12
|
+
* attempt. That is the right behaviour and it arrives too late to be useful to
|
|
13
|
+
* the person doing the answering.
|
|
14
|
+
*
|
|
15
|
+
* Nothing said so beforehand. `forTree` hands back every waiting proposal with
|
|
16
|
+
* no reference to where the page has got to, and `waiting` does the same across
|
|
17
|
+
* a deployment, so a review queue built the documented way lists dead changes
|
|
18
|
+
* and live ones together, oldest first, indistinguishable. The only way to find
|
|
19
|
+
* out which is which was to answer one: read the change, decide, click yes, and
|
|
20
|
+
* be told it never could have worked. Filed by `Loom docs` on 7 September, who
|
|
21
|
+
* met it writing *When something looks wrong* and taught it on the page because
|
|
22
|
+
* it was true.
|
|
23
|
+
*
|
|
24
|
+
* The comparison is one line, which is the reason it belongs here rather than in
|
|
25
|
+
* every host: it has a direction, `confirmHeld` already fixed which one, and a
|
|
26
|
+
* queue that got it backwards would badge exactly the wrong half.
|
|
27
|
+
*/
|
|
28
|
+
/**
|
|
29
|
+
* What can be said about a hold, given what is known about its tree.
|
|
30
|
+
*
|
|
31
|
+
* `unknown` is a third answer rather than an optimistic `live` because the
|
|
32
|
+
* question is asked over a page of holds spanning many trees, and a head that
|
|
33
|
+
* could not be read is not evidence that nothing moved. A queue that shows no
|
|
34
|
+
* badge is honest; one that shows *live* on a tree nobody could reach is the
|
|
35
|
+
* failure this module exists to remove, restated one level up.
|
|
36
|
+
*/
|
|
37
|
+
export type HoldLiveness = "live" | "dead" | "unknown";
|
|
38
|
+
/**
|
|
39
|
+
* The three answers, as a list a host can walk.
|
|
40
|
+
*
|
|
41
|
+
* The shape settled in `closed-set.ts`, here for the usual reason: a queue wants
|
|
42
|
+
* a bucket per answer to exist before the first row arrives, and a legend wants
|
|
43
|
+
* to describe all three without keeping its own copy of them.
|
|
44
|
+
*/
|
|
45
|
+
export declare const HOLD_LIVENESS: readonly HoldLiveness[];
|
|
46
|
+
/**
|
|
47
|
+
* The one comparison, in the direction `confirmHeld` makes it.
|
|
48
|
+
*
|
|
49
|
+
* Inequality rather than `headRevision > hold.baseRevision`, deliberately: the
|
|
50
|
+
* write path refuses any head that is not the exact revision the Gate judged
|
|
51
|
+
* against, so a hold naming a revision ahead of head — which a log cannot
|
|
52
|
+
* produce, and a restored backup or a mistyped fixture can — is dead by the same
|
|
53
|
+
* rule that will refuse it. A helper that judged it live would disagree with the
|
|
54
|
+
* only opinion that matters.
|
|
55
|
+
*
|
|
56
|
+
* A head of `undefined` means the caller has no revision for this tree, and the
|
|
57
|
+
* answer is `unknown`. It is not an error: the two listings are unpaged and
|
|
58
|
+
* paged respectively, and a caller assembling heads for a page of holds may
|
|
59
|
+
* legitimately be missing one.
|
|
60
|
+
*/
|
|
61
|
+
export declare const holdLiveness: (hold: HeldProposal, headRevision: number | undefined) => HoldLiveness;
|
|
62
|
+
/**
|
|
63
|
+
* A hold and what is known about whether answering it could work.
|
|
64
|
+
*
|
|
65
|
+
* `headRevision` is carried rather than left for the caller to look up again
|
|
66
|
+
* because a queue that badges a row wants to say what it compared — *held
|
|
67
|
+
* against 3, the page is at 4* is the sentence that stops a reviewer wondering
|
|
68
|
+
* whether the badge is a bug.
|
|
69
|
+
*/
|
|
70
|
+
export type MarkedHold = {
|
|
71
|
+
readonly held: HeldProposal;
|
|
72
|
+
readonly liveness: HoldLiveness;
|
|
73
|
+
/** Absent exactly when `liveness` is `unknown`. */
|
|
74
|
+
readonly headRevision?: number;
|
|
75
|
+
};
|
|
76
|
+
/**
|
|
77
|
+
* Marks a page of holds against the revisions the caller already knows.
|
|
78
|
+
*
|
|
79
|
+
* Pure, and total: every hold comes back marked, in the order it arrived, so a
|
|
80
|
+
* queue keeps `compareHolds` order and gains a column. Holds against a tree the
|
|
81
|
+
* map does not name are `unknown` rather than dropped — a listing that quietly
|
|
82
|
+
* lost rows because a head was missing would be a worse failure than the one
|
|
83
|
+
* this fixes.
|
|
84
|
+
*/
|
|
85
|
+
export declare const markHolds: (holds: readonly HeldProposal[], heads: ReadonlyMap<TreeId, number>) => readonly MarkedHold[];
|
|
86
|
+
/**
|
|
87
|
+
* The trees a page of holds is waiting on, each named once, in first-seen order.
|
|
88
|
+
*
|
|
89
|
+
* A queue reads one head per tree and not one per hold: three changes held
|
|
90
|
+
* against the same page are three rows and one question. First-seen order rather
|
|
91
|
+
* than sorted, so the reads a caller issues follow the order the holds are shown
|
|
92
|
+
* in and the first row on screen is the first one answered.
|
|
93
|
+
*/
|
|
94
|
+
export declare const treesAwaitingAnswer: (holds: readonly HeldProposal[]) => readonly TreeId[];
|
|
95
|
+
/**
|
|
96
|
+
* The same page of holds, marked against heads read from the store.
|
|
97
|
+
*
|
|
98
|
+
* What a host would otherwise write, and the reason to write it once: read each
|
|
99
|
+
* distinct head, compare in the direction the write path compares, keep the
|
|
100
|
+
* order.
|
|
101
|
+
*/
|
|
102
|
+
export type MarkedHolds = {
|
|
103
|
+
readonly marked: readonly MarkedHold[];
|
|
104
|
+
/**
|
|
105
|
+
* One per tree whose head could not be read. Those holds are `unknown`, and
|
|
106
|
+
* the errors are handed back rather than swallowed so a host can log them or
|
|
107
|
+
* say so on the page.
|
|
108
|
+
*/
|
|
109
|
+
readonly unreadable: readonly StoreError[];
|
|
110
|
+
};
|
|
111
|
+
/**
|
|
112
|
+
* Reads what it needs and never fails.
|
|
113
|
+
*
|
|
114
|
+
* A `Result` was the first shape and is the wrong one. A queue over every page
|
|
115
|
+
* of a deployment spans many trees, and one tree being unavailable is not a
|
|
116
|
+
* reason for a reviewer to see nothing: the honest answer is the rest of the
|
|
117
|
+
* queue badged and that tree's rows unbadged. Fail-fast would have made this
|
|
118
|
+
* module's own point — *say what you cannot say, rather than guessing* —
|
|
119
|
+
* unavailable to the caller in exactly the case it was written for.
|
|
120
|
+
*
|
|
121
|
+
* `not-found` is `unknown` and not `dead`, which is the one classification here
|
|
122
|
+
* worth arguing with. A hold against a tree that is not there cannot be
|
|
123
|
+
* confirmed either — but it fails as `not-found`, not as a revision conflict,
|
|
124
|
+
* and a badge reading *the page moved on* about a page that is gone would be a
|
|
125
|
+
* true-sounding sentence about the wrong fault. This predicate answers one
|
|
126
|
+
* question and declines the neighbouring one.
|
|
127
|
+
*
|
|
128
|
+
* `TreeReader` rather than `TreeStore`, because badging a queue is a read and
|
|
129
|
+
* nothing here should be handed something that can append.
|
|
130
|
+
*/
|
|
131
|
+
export declare const markHoldsFromStore: (reader: TreeReader, holds: readonly HeldProposal[]) => Promise<MarkedHolds>;
|
|
132
|
+
//# sourceMappingURL=liveness.d.ts.map
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import { everyMemberOf } from "../closed-set.js";
|
|
2
|
+
/**
|
|
3
|
+
* The three answers, as a list a host can walk.
|
|
4
|
+
*
|
|
5
|
+
* The shape settled in `closed-set.ts`, here for the usual reason: a queue wants
|
|
6
|
+
* a bucket per answer to exist before the first row arrives, and a legend wants
|
|
7
|
+
* to describe all three without keeping its own copy of them.
|
|
8
|
+
*/
|
|
9
|
+
export const HOLD_LIVENESS = everyMemberOf()([
|
|
10
|
+
"live",
|
|
11
|
+
"dead",
|
|
12
|
+
"unknown",
|
|
13
|
+
]);
|
|
14
|
+
/**
|
|
15
|
+
* The one comparison, in the direction `confirmHeld` makes it.
|
|
16
|
+
*
|
|
17
|
+
* Inequality rather than `headRevision > hold.baseRevision`, deliberately: the
|
|
18
|
+
* write path refuses any head that is not the exact revision the Gate judged
|
|
19
|
+
* against, so a hold naming a revision ahead of head — which a log cannot
|
|
20
|
+
* produce, and a restored backup or a mistyped fixture can — is dead by the same
|
|
21
|
+
* rule that will refuse it. A helper that judged it live would disagree with the
|
|
22
|
+
* only opinion that matters.
|
|
23
|
+
*
|
|
24
|
+
* A head of `undefined` means the caller has no revision for this tree, and the
|
|
25
|
+
* answer is `unknown`. It is not an error: the two listings are unpaged and
|
|
26
|
+
* paged respectively, and a caller assembling heads for a page of holds may
|
|
27
|
+
* legitimately be missing one.
|
|
28
|
+
*/
|
|
29
|
+
export const holdLiveness = (hold, headRevision) => {
|
|
30
|
+
if (headRevision === undefined)
|
|
31
|
+
return "unknown";
|
|
32
|
+
return headRevision === hold.baseRevision ? "live" : "dead";
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* Marks a page of holds against the revisions the caller already knows.
|
|
36
|
+
*
|
|
37
|
+
* Pure, and total: every hold comes back marked, in the order it arrived, so a
|
|
38
|
+
* queue keeps `compareHolds` order and gains a column. Holds against a tree the
|
|
39
|
+
* map does not name are `unknown` rather than dropped — a listing that quietly
|
|
40
|
+
* lost rows because a head was missing would be a worse failure than the one
|
|
41
|
+
* this fixes.
|
|
42
|
+
*/
|
|
43
|
+
export const markHolds = (holds, heads) => holds.map((held) => {
|
|
44
|
+
const headRevision = heads.get(held.treeId);
|
|
45
|
+
const liveness = holdLiveness(held, headRevision);
|
|
46
|
+
return headRevision === undefined ? { held, liveness } : { held, liveness, headRevision };
|
|
47
|
+
});
|
|
48
|
+
/**
|
|
49
|
+
* The trees a page of holds is waiting on, each named once, in first-seen order.
|
|
50
|
+
*
|
|
51
|
+
* A queue reads one head per tree and not one per hold: three changes held
|
|
52
|
+
* against the same page are three rows and one question. First-seen order rather
|
|
53
|
+
* than sorted, so the reads a caller issues follow the order the holds are shown
|
|
54
|
+
* in and the first row on screen is the first one answered.
|
|
55
|
+
*/
|
|
56
|
+
export const treesAwaitingAnswer = (holds) => [
|
|
57
|
+
...new Set(holds.map((held) => held.treeId)),
|
|
58
|
+
];
|
|
59
|
+
/**
|
|
60
|
+
* Reads what it needs and never fails.
|
|
61
|
+
*
|
|
62
|
+
* A `Result` was the first shape and is the wrong one. A queue over every page
|
|
63
|
+
* of a deployment spans many trees, and one tree being unavailable is not a
|
|
64
|
+
* reason for a reviewer to see nothing: the honest answer is the rest of the
|
|
65
|
+
* queue badged and that tree's rows unbadged. Fail-fast would have made this
|
|
66
|
+
* module's own point — *say what you cannot say, rather than guessing* —
|
|
67
|
+
* unavailable to the caller in exactly the case it was written for.
|
|
68
|
+
*
|
|
69
|
+
* `not-found` is `unknown` and not `dead`, which is the one classification here
|
|
70
|
+
* worth arguing with. A hold against a tree that is not there cannot be
|
|
71
|
+
* confirmed either — but it fails as `not-found`, not as a revision conflict,
|
|
72
|
+
* and a badge reading *the page moved on* about a page that is gone would be a
|
|
73
|
+
* true-sounding sentence about the wrong fault. This predicate answers one
|
|
74
|
+
* question and declines the neighbouring one.
|
|
75
|
+
*
|
|
76
|
+
* `TreeReader` rather than `TreeStore`, because badging a queue is a read and
|
|
77
|
+
* nothing here should be handed something that can append.
|
|
78
|
+
*/
|
|
79
|
+
export const markHoldsFromStore = async (reader, holds) => {
|
|
80
|
+
const heads = new Map();
|
|
81
|
+
const unreadable = [];
|
|
82
|
+
for (const treeId of treesAwaitingAnswer(holds)) {
|
|
83
|
+
const head = await reader.head(treeId);
|
|
84
|
+
if (head.ok)
|
|
85
|
+
heads.set(treeId, head.value.revision);
|
|
86
|
+
else
|
|
87
|
+
unreadable.push(head.error);
|
|
88
|
+
}
|
|
89
|
+
return { marked: markHolds(holds, heads), unreadable };
|
|
90
|
+
};
|
|
91
|
+
//# sourceMappingURL=liveness.js.map
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import type { IdFactory, TreeId } from "../ids.js";
|
|
2
|
+
import type { Clock } from "../runtime/events.js";
|
|
3
|
+
import type { IntentOrigin } from "../runtime/intent.js";
|
|
4
|
+
import type { ChangeInterpreter } from "../runtime/interpreter.js";
|
|
5
|
+
import { type RevertPlan, type UnrevertablePlan } from "../store/revert.js";
|
|
6
|
+
import type { LoomTree } from "../tree/tree.js";
|
|
7
|
+
import { type WriteOutcome, type WritePath } from "./commit.js";
|
|
8
|
+
/**
|
|
9
|
+
* Undo, as a change like any other.
|
|
10
|
+
*
|
|
11
|
+
* The runtime has always been able to *say* a change is reversible — the
|
|
12
|
+
* inverse delta is computed at assessment time and carried through the
|
|
13
|
+
* pipeline. Nothing applied it, so "reversible" was a claim the runtime made
|
|
14
|
+
* about itself and never had to honour.
|
|
15
|
+
*
|
|
16
|
+
* This honours it without giving undo a private route. A revert is interpreted
|
|
17
|
+
* (deterministically), proposed, assessed, gated, applied, and appended to the
|
|
18
|
+
* log as a new revision — the same seven steps every other change takes. It is
|
|
19
|
+
* therefore attributable to whoever asked for it, refusable by the Gate,
|
|
20
|
+
* holdable for confirmation, visible to telemetry, and itself revertable.
|
|
21
|
+
*
|
|
22
|
+
* The alternative — rewinding the log, or applying the inverse straight to the
|
|
23
|
+
* store — would make undo the one operation that changes a tree without being
|
|
24
|
+
* judged, and the log the one record with a hole in it (0032).
|
|
25
|
+
*
|
|
26
|
+
* An undo whose target was built on afterwards is offered rather than refused
|
|
27
|
+
* (0035). What made it refusable was that the Gate could not see the difference
|
|
28
|
+
* between a clean undo and one that writes over later work; now the plan says so
|
|
29
|
+
* and the proposal carries the declaration, so the Gate holds it for a person
|
|
30
|
+
* instead of the runtime deciding on their behalf that they may not have it.
|
|
31
|
+
*/
|
|
32
|
+
/** What produced the delta, for `Provenance.interpreter`. Not a model. */
|
|
33
|
+
export declare const REVERT_INTERPRETER = "loom/revert";
|
|
34
|
+
export type RevertablePlan = Extract<RevertPlan, {
|
|
35
|
+
readonly outcome: "revertable";
|
|
36
|
+
}>;
|
|
37
|
+
/**
|
|
38
|
+
* The same interpreter every undo uses, with the log's half filled in.
|
|
39
|
+
*
|
|
40
|
+
* Everything specific to a revert is here — the stamp that says this came off a
|
|
41
|
+
* log, the rationale that names the revision and what it costs, and the work the
|
|
42
|
+
* plan found to declare. What is left is `inverseInterpreter`, which a surface
|
|
43
|
+
* with no store reaches for directly: the head check, the provenance of a
|
|
44
|
+
* computed change, and the shape of the proposal are one implementation rather
|
|
45
|
+
* than two that drift.
|
|
46
|
+
*/
|
|
47
|
+
export declare const revertInterpreter: (plan: RevertablePlan, idFactory: IdFactory, clock: Clock) => ChangeInterpreter;
|
|
48
|
+
export type RevertRequest = {
|
|
49
|
+
readonly treeId: TreeId;
|
|
50
|
+
/** The revision to undo. */
|
|
51
|
+
readonly revision: number;
|
|
52
|
+
/** Replayed from, to recover the tree the target's delta observed (0028). */
|
|
53
|
+
readonly seed: LoomTree;
|
|
54
|
+
readonly origin: IntentOrigin;
|
|
55
|
+
readonly actor?: string;
|
|
56
|
+
};
|
|
57
|
+
export type RevertOutcome = WriteOutcome
|
|
58
|
+
/**
|
|
59
|
+
* Nothing was proposed, because no undo could be computed: the revision is
|
|
60
|
+
* outside the span the seed reaches, the log does not replay, or the delta does
|
|
61
|
+
* not invert. Work the undo would write over is not one of these — that is a
|
|
62
|
+
* proposal the Gate holds, not a plan that failed (0035).
|
|
63
|
+
*/
|
|
64
|
+
| {
|
|
65
|
+
readonly kind: "not-revertable";
|
|
66
|
+
readonly plan: UnrevertablePlan;
|
|
67
|
+
};
|
|
68
|
+
export declare const describeRevertOutcome: (outcome: RevertOutcome) => string;
|
|
69
|
+
/**
|
|
70
|
+
* Undoes a revision, if the log allows it and the Gate agrees.
|
|
71
|
+
*
|
|
72
|
+
* The intent is synthesised here rather than taken from the caller, because the
|
|
73
|
+
* utterance behind a revert is not a sentence someone typed — it is the
|
|
74
|
+
* revision number they named. `origin` and `actor` are the caller's, and they
|
|
75
|
+
* are what the Gate weighs and what provenance records: undoing a change is
|
|
76
|
+
* still someone asking for a change.
|
|
77
|
+
*/
|
|
78
|
+
export declare const revertRevision: (path: WritePath, request: RevertRequest) => Promise<RevertOutcome>;
|
|
79
|
+
//# sourceMappingURL=revert.d.ts.map
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
import { inverseInterpreter } from "../runtime/inverse.js";
|
|
2
|
+
import { describeRevertPlan, planRevert } from "../store/revert.js";
|
|
3
|
+
import { commitIntent, describeWriteOutcome } from "./commit.js";
|
|
4
|
+
/**
|
|
5
|
+
* Undo, as a change like any other.
|
|
6
|
+
*
|
|
7
|
+
* The runtime has always been able to *say* a change is reversible — the
|
|
8
|
+
* inverse delta is computed at assessment time and carried through the
|
|
9
|
+
* pipeline. Nothing applied it, so "reversible" was a claim the runtime made
|
|
10
|
+
* about itself and never had to honour.
|
|
11
|
+
*
|
|
12
|
+
* This honours it without giving undo a private route. A revert is interpreted
|
|
13
|
+
* (deterministically), proposed, assessed, gated, applied, and appended to the
|
|
14
|
+
* log as a new revision — the same seven steps every other change takes. It is
|
|
15
|
+
* therefore attributable to whoever asked for it, refusable by the Gate,
|
|
16
|
+
* holdable for confirmation, visible to telemetry, and itself revertable.
|
|
17
|
+
*
|
|
18
|
+
* The alternative — rewinding the log, or applying the inverse straight to the
|
|
19
|
+
* store — would make undo the one operation that changes a tree without being
|
|
20
|
+
* judged, and the log the one record with a hole in it (0032).
|
|
21
|
+
*
|
|
22
|
+
* An undo whose target was built on afterwards is offered rather than refused
|
|
23
|
+
* (0035). What made it refusable was that the Gate could not see the difference
|
|
24
|
+
* between a clean undo and one that writes over later work; now the plan says so
|
|
25
|
+
* and the proposal carries the declaration, so the Gate holds it for a person
|
|
26
|
+
* instead of the runtime deciding on their behalf that they may not have it.
|
|
27
|
+
*/
|
|
28
|
+
/** What produced the delta, for `Provenance.interpreter`. Not a model. */
|
|
29
|
+
export const REVERT_INTERPRETER = "loom/revert";
|
|
30
|
+
/**
|
|
31
|
+
* What the undo is for, and — when there is one — what it costs.
|
|
32
|
+
*
|
|
33
|
+
* The cost is spelled out in the rationale as well as declared in `discards`,
|
|
34
|
+
* because the two are read by different readers: the Gate reads the declaration,
|
|
35
|
+
* and the person answering the hold reads this (0019 — the portal shows a
|
|
36
|
+
* reviewer the reason, not a verdict).
|
|
37
|
+
*/
|
|
38
|
+
const rationaleFor = (plan) => {
|
|
39
|
+
const undoes = `Undoes revision ${plan.target.revision}, applied ${plan.target.appliedAt} from proposal ${plan.target.proposalId}.`;
|
|
40
|
+
if (plan.discards.length === 0)
|
|
41
|
+
return undoes;
|
|
42
|
+
const revisions = plan.discards.map((discarded) => discarded.revision).join(", ");
|
|
43
|
+
return `${undoes} Revision${plan.discards.length === 1 ? "" : "s"} ${revisions} changed nodes this undo touches, and applying it writes over what they did.`;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* The same interpreter every undo uses, with the log's half filled in.
|
|
47
|
+
*
|
|
48
|
+
* Everything specific to a revert is here — the stamp that says this came off a
|
|
49
|
+
* log, the rationale that names the revision and what it costs, and the work the
|
|
50
|
+
* plan found to declare. What is left is `inverseInterpreter`, which a surface
|
|
51
|
+
* with no store reaches for directly: the head check, the provenance of a
|
|
52
|
+
* computed change, and the shape of the proposal are one implementation rather
|
|
53
|
+
* than two that drift.
|
|
54
|
+
*/
|
|
55
|
+
export const revertInterpreter = (plan, idFactory, clock) => inverseInterpreter({
|
|
56
|
+
operations: plan.operations,
|
|
57
|
+
/**
|
|
58
|
+
* The plan's contest check was made against one head. Judging it at a
|
|
59
|
+
* different one would be judging a different question, so the interpreter
|
|
60
|
+
* declines rather than proposing something whose reasoning has expired.
|
|
61
|
+
* The write path refuses a moved head before reaching here; this is what
|
|
62
|
+
* keeps the interpreter safe to wire into a runtime directly.
|
|
63
|
+
*/
|
|
64
|
+
headRevision: plan.headRevision,
|
|
65
|
+
interpreter: REVERT_INTERPRETER,
|
|
66
|
+
rationale: rationaleFor(plan),
|
|
67
|
+
/**
|
|
68
|
+
* The same number the rationale states in a sentence, as a field. The
|
|
69
|
+
* sentence is for the person answering a hold; this is for the surface
|
|
70
|
+
* reading the log afterwards, which until now could only have the sentence.
|
|
71
|
+
*/
|
|
72
|
+
undoes: plan.target.revision,
|
|
73
|
+
/**
|
|
74
|
+
* Declared only when there is something to declare, so absence keeps
|
|
75
|
+
* meaning "nobody looked at a log" rather than "a log was checked and was
|
|
76
|
+
* clean" (0035).
|
|
77
|
+
*/
|
|
78
|
+
...(plan.discards.length === 0 ? {} : { discards: plan.discards }),
|
|
79
|
+
}, idFactory, clock);
|
|
80
|
+
export const describeRevertOutcome = (outcome) => outcome.kind === "not-revertable"
|
|
81
|
+
? `not revertable: ${describeRevertPlan(outcome.plan)}`
|
|
82
|
+
: describeWriteOutcome(outcome);
|
|
83
|
+
/**
|
|
84
|
+
* The same runtime, interpreting reverts.
|
|
85
|
+
*
|
|
86
|
+
* Built field by field rather than spread, so that dropping the repairer is a
|
|
87
|
+
* statement instead of an omission: repair (0006) exists to let a model try a
|
|
88
|
+
* smaller version of what the Gate refused, and there is no smaller version of
|
|
89
|
+
* an undo. A revert the Gate refuses is refused.
|
|
90
|
+
*/
|
|
91
|
+
const revertingRuntime = (runtime, interpreter) => ({
|
|
92
|
+
interpreter,
|
|
93
|
+
policySource: runtime.policySource,
|
|
94
|
+
events: runtime.events,
|
|
95
|
+
clock: runtime.clock,
|
|
96
|
+
idFactory: runtime.idFactory,
|
|
97
|
+
});
|
|
98
|
+
/**
|
|
99
|
+
* Undoes a revision, if the log allows it and the Gate agrees.
|
|
100
|
+
*
|
|
101
|
+
* The intent is synthesised here rather than taken from the caller, because the
|
|
102
|
+
* utterance behind a revert is not a sentence someone typed — it is the
|
|
103
|
+
* revision number they named. `origin` and `actor` are the caller's, and they
|
|
104
|
+
* are what the Gate weighs and what provenance records: undoing a change is
|
|
105
|
+
* still someone asking for a change.
|
|
106
|
+
*/
|
|
107
|
+
export const revertRevision = async (path, request) => {
|
|
108
|
+
const planned = await planRevert(path.store, {
|
|
109
|
+
treeId: request.treeId,
|
|
110
|
+
revision: request.revision,
|
|
111
|
+
seed: request.seed,
|
|
112
|
+
});
|
|
113
|
+
if (!planned.ok)
|
|
114
|
+
return { kind: "not-written", error: planned.error };
|
|
115
|
+
if (planned.value.outcome !== "revertable")
|
|
116
|
+
return { kind: "not-revertable", plan: planned.value };
|
|
117
|
+
const plan = planned.value;
|
|
118
|
+
const { idFactory, clock } = path.runtime;
|
|
119
|
+
const intent = {
|
|
120
|
+
intentId: idFactory.intentId(),
|
|
121
|
+
treeId: request.treeId,
|
|
122
|
+
baseRevision: plan.headRevision,
|
|
123
|
+
origin: request.origin,
|
|
124
|
+
...(request.actor === undefined ? {} : { actor: request.actor }),
|
|
125
|
+
utterance: `Undo revision ${request.revision}.`,
|
|
126
|
+
observedAt: clock.now(),
|
|
127
|
+
};
|
|
128
|
+
return commitIntent({
|
|
129
|
+
store: path.store,
|
|
130
|
+
holds: path.holds,
|
|
131
|
+
runtime: revertingRuntime(path.runtime, revertInterpreter(plan, idFactory, clock)),
|
|
132
|
+
}, intent);
|
|
133
|
+
};
|
|
134
|
+
//# sourceMappingURL=revert.js.map
|