@jam-overture/loom 0.1.0 → 0.2.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.
Files changed (290) hide show
  1. package/README.md +3 -1
  2. package/dist/application/application.d.ts +109 -0
  3. package/dist/application/application.js +97 -0
  4. package/dist/application/memory.d.ts +20 -0
  5. package/dist/application/memory.js +79 -0
  6. package/dist/application/store.d.ts +101 -0
  7. package/dist/application/store.js +25 -0
  8. package/dist/audience/audience.d.ts +36 -0
  9. package/dist/audience/audience.js +41 -0
  10. package/dist/cli/templates.js +19 -0
  11. package/dist/data/plan.js +0 -0
  12. package/dist/data/resolution.d.ts +23 -1
  13. package/dist/data/resolve.d.ts +30 -3
  14. package/dist/data/resolve.js +11 -3
  15. package/dist/ids.d.ts +10 -0
  16. package/dist/ids.js +11 -1
  17. package/dist/index.d.ts +1 -0
  18. package/dist/index.js +1 -0
  19. package/dist/patch.d.ts +54 -0
  20. package/dist/patch.js +44 -0
  21. package/dist/project/closing.d.ts +51 -0
  22. package/dist/project/closing.js +53 -0
  23. package/dist/project/memory.d.ts +20 -0
  24. package/dist/project/memory.js +97 -0
  25. package/dist/project/project.d.ts +90 -0
  26. package/dist/project/project.js +91 -0
  27. package/dist/project/store.d.ts +135 -0
  28. package/dist/project/store.js +41 -0
  29. package/dist/registered.d.ts +64 -0
  30. package/dist/registered.js +118 -0
  31. package/dist/render/behaviour-adjust.d.ts +11 -19
  32. package/dist/render/behaviour-adjust.js +75 -21
  33. package/dist/render/behaviour-present.d.ts +8 -0
  34. package/dist/render/behaviour-present.js +57 -6
  35. package/dist/render/behaviour.d.ts +98 -17
  36. package/dist/render/behaviour.js +91 -26
  37. package/dist/render/control-name.d.ts +68 -0
  38. package/dist/render/control-name.js +37 -0
  39. package/dist/render/diagnostics.d.ts +72 -0
  40. package/dist/render/diagnostics.js +7 -0
  41. package/dist/render/index.d.ts +2 -0
  42. package/dist/render/index.js +2 -0
  43. package/dist/render/reads.d.ts +11 -0
  44. package/dist/render/reads.js +12 -1
  45. package/dist/render/render.js +102 -7
  46. package/dist/render/slots.d.ts +52 -0
  47. package/dist/render/slots.js +24 -0
  48. package/dist/render/theme.d.ts +54 -1
  49. package/dist/render/theme.js +23 -1
  50. package/dist/render/unshown.d.ts +152 -0
  51. package/dist/render/unshown.js +80 -0
  52. package/dist/runtime/analysis.d.ts +94 -9
  53. package/dist/runtime/analysis.js +54 -9
  54. package/dist/runtime/assessment.d.ts +36 -2
  55. package/dist/runtime/assessment.js +27 -2
  56. package/dist/runtime/checks.d.ts +148 -0
  57. package/dist/runtime/checks.js +112 -0
  58. package/dist/runtime/disposition.d.ts +96 -0
  59. package/dist/runtime/disposition.js +46 -0
  60. package/dist/runtime/gate.js +22 -0
  61. package/dist/runtime/index.d.ts +3 -0
  62. package/dist/runtime/index.js +3 -0
  63. package/dist/runtime/irreversibility.d.ts +64 -0
  64. package/dist/runtime/irreversibility.js +45 -0
  65. package/dist/runtime/pipeline.d.ts +43 -0
  66. package/dist/runtime/pipeline.js +10 -2
  67. package/dist/runtime/policy-change.d.ts +93 -0
  68. package/dist/runtime/policy-change.js +299 -0
  69. package/dist/runtime/policy-log.d.ts +406 -0
  70. package/dist/runtime/policy-log.js +285 -0
  71. package/dist/runtime/reversibility.d.ts +11 -9
  72. package/dist/runtime/stakes.d.ts +129 -1
  73. package/dist/runtime/stakes.js +240 -26
  74. package/dist/runtime/vocabulary.d.ts +164 -7
  75. package/dist/runtime/vocabulary.js +181 -8
  76. package/dist/sdk/audit.d.ts +174 -3
  77. package/dist/sdk/audit.js +176 -17
  78. package/dist/sdk/catalogue.d.ts +9 -1
  79. package/dist/sdk/conformance.d.ts +37 -3
  80. package/dist/sdk/conformance.js +25 -4
  81. package/dist/sdk/definition.d.ts +65 -0
  82. package/dist/sdk/definition.js +22 -0
  83. package/dist/sdk/registry.d.ts +29 -2
  84. package/dist/sdk/registry.js +63 -1
  85. package/dist/signals/action-change.d.ts +507 -0
  86. package/dist/signals/action-change.js +265 -0
  87. package/dist/signals/action.d.ts +331 -0
  88. package/dist/signals/action.js +182 -0
  89. package/dist/signals/applied-window.contract.d.ts +23 -0
  90. package/dist/signals/applied-window.contract.js +160 -0
  91. package/dist/signals/arriving.d.ts +210 -0
  92. package/dist/signals/arriving.js +133 -0
  93. package/dist/signals/audiences.d.ts +528 -0
  94. package/dist/signals/audiences.js +255 -0
  95. package/dist/signals/broadcast.d.ts +8 -2
  96. package/dist/signals/broadcast.js +58 -8
  97. package/dist/signals/change.d.ts +378 -0
  98. package/dist/signals/change.js +327 -0
  99. package/dist/signals/collect.d.ts +41 -0
  100. package/dist/signals/collect.js +88 -7
  101. package/dist/signals/copy-change.d.ts +553 -0
  102. package/dist/signals/copy-change.js +377 -0
  103. package/dist/signals/copy.d.ts +337 -0
  104. package/dist/signals/copy.js +211 -0
  105. package/dist/signals/counters.d.ts +46 -0
  106. package/dist/signals/counters.js +102 -0
  107. package/dist/signals/deliver.d.ts +23 -4
  108. package/dist/signals/deliver.js +34 -6
  109. package/dist/signals/deployment-change.d.ts +371 -0
  110. package/dist/signals/deployment-change.js +268 -0
  111. package/dist/signals/deployment.d.ts +265 -0
  112. package/dist/signals/deployment.js +152 -0
  113. package/dist/signals/door.d.ts +92 -0
  114. package/dist/signals/door.js +53 -0
  115. package/dist/signals/fold.d.ts +10 -0
  116. package/dist/signals/fold.js +5 -1
  117. package/dist/signals/form-action.d.ts +302 -0
  118. package/dist/signals/form-action.js +169 -0
  119. package/dist/signals/form-copy.d.ts +523 -0
  120. package/dist/signals/form-copy.js +346 -0
  121. package/dist/signals/forms.d.ts +247 -0
  122. package/dist/signals/forms.js +147 -0
  123. package/dist/signals/funnel-change.d.ts +548 -0
  124. package/dist/signals/funnel-change.js +361 -0
  125. package/dist/signals/funnel.d.ts +532 -0
  126. package/dist/signals/funnel.js +216 -0
  127. package/dist/signals/health.d.ts +497 -0
  128. package/dist/signals/health.js +361 -0
  129. package/dist/signals/index.d.ts +41 -0
  130. package/dist/signals/index.js +41 -0
  131. package/dist/signals/ingest.d.ts +56 -1
  132. package/dist/signals/ingest.js +91 -1
  133. package/dist/signals/journal.d.ts +11 -0
  134. package/dist/signals/kinds.d.ts +8 -6
  135. package/dist/signals/kinds.js +14 -6
  136. package/dist/signals/library-action.d.ts +430 -0
  137. package/dist/signals/library-action.js +336 -0
  138. package/dist/signals/library-change.d.ts +477 -0
  139. package/dist/signals/library-change.js +335 -0
  140. package/dist/signals/library-copy-change.d.ts +498 -0
  141. package/dist/signals/library-copy-change.js +476 -0
  142. package/dist/signals/library-pace.d.ts +319 -0
  143. package/dist/signals/library-pace.js +305 -0
  144. package/dist/signals/library-reach-change.d.ts +636 -0
  145. package/dist/signals/library-reach-change.js +534 -0
  146. package/dist/signals/library-reach.d.ts +377 -0
  147. package/dist/signals/library-reach.js +227 -0
  148. package/dist/signals/library-word-reach-change.d.ts +567 -0
  149. package/dist/signals/library-word-reach-change.js +568 -0
  150. package/dist/signals/library.d.ts +306 -0
  151. package/dist/signals/library.js +178 -0
  152. package/dist/signals/memory.d.ts +9 -0
  153. package/dist/signals/memory.js +105 -14
  154. package/dist/signals/migrate.d.ts +17 -2
  155. package/dist/signals/migrate.js +122 -5
  156. package/dist/signals/notice.d.ts +334 -0
  157. package/dist/signals/notice.js +228 -0
  158. package/dist/signals/pace-change.d.ts +501 -0
  159. package/dist/signals/pace-change.js +310 -0
  160. package/dist/signals/pace.d.ts +296 -0
  161. package/dist/signals/pace.js +291 -0
  162. package/dist/signals/page-views.d.ts +365 -0
  163. package/dist/signals/page-views.js +218 -0
  164. package/dist/signals/parts.d.ts +344 -0
  165. package/dist/signals/parts.js +273 -0
  166. package/dist/signals/postgres.d.ts +16 -2
  167. package/dist/signals/postgres.js +390 -87
  168. package/dist/signals/progress.d.ts +212 -0
  169. package/dist/signals/progress.js +150 -0
  170. package/dist/signals/ratios.d.ts +108 -0
  171. package/dist/signals/ratios.js +40 -0
  172. package/dist/signals/reach.d.ts +309 -0
  173. package/dist/signals/reach.js +93 -0
  174. package/dist/signals/readable.d.ts +34 -0
  175. package/dist/signals/readable.js +34 -0
  176. package/dist/signals/readership.d.ts +381 -0
  177. package/dist/signals/readership.js +308 -0
  178. package/dist/signals/region-pages.d.ts +173 -0
  179. package/dist/signals/region-pages.js +62 -0
  180. package/dist/signals/region.d.ts +287 -0
  181. package/dist/signals/region.js +198 -0
  182. package/dist/signals/retention.d.ts +141 -0
  183. package/dist/signals/retention.js +58 -0
  184. package/dist/signals/rollup.d.ts +67 -3
  185. package/dist/signals/rollup.js +0 -0
  186. package/dist/signals/schema.d.ts +432 -1
  187. package/dist/signals/schema.js +157 -3
  188. package/dist/signals/signal.d.ts +237 -11
  189. package/dist/signals/signal.js +70 -10
  190. package/dist/signals/silence-census.d.ts +205 -0
  191. package/dist/signals/silence-census.js +87 -0
  192. package/dist/signals/silences.d.ts +848 -0
  193. package/dist/signals/silences.js +753 -0
  194. package/dist/signals/tally.d.ts +140 -11
  195. package/dist/signals/window-figures.d.ts +148 -0
  196. package/dist/signals/window-figures.js +42 -0
  197. package/dist/signals/window.d.ts +866 -0
  198. package/dist/signals/window.js +693 -0
  199. package/dist/signals/words.d.ts +24 -0
  200. package/dist/signals/words.js +24 -0
  201. package/dist/store/index.d.ts +19 -0
  202. package/dist/store/index.js +19 -0
  203. package/dist/store/memory.d.ts +2 -1
  204. package/dist/store/memory.js +48 -12
  205. package/dist/store/migrate.d.ts +80 -0
  206. package/dist/store/migrate.js +259 -7
  207. package/dist/store/postgres-applications.d.ts +4 -0
  208. package/dist/store/postgres-applications.js +197 -0
  209. package/dist/store/postgres-holds.d.ts +10 -1
  210. package/dist/store/postgres-holds.js +116 -101
  211. package/dist/store/postgres-policy-log.d.ts +14 -0
  212. package/dist/store/postgres-policy-log.js +240 -0
  213. package/dist/store/postgres-projects.d.ts +4 -0
  214. package/dist/store/postgres-projects.js +217 -0
  215. package/dist/store/postgres.d.ts +16 -1
  216. package/dist/store/postgres.js +59 -9
  217. package/dist/store/replay.d.ts +102 -1
  218. package/dist/store/replay.js +190 -19
  219. package/dist/store/reseed.d.ts +238 -0
  220. package/dist/store/reseed.js +308 -0
  221. package/dist/store/schema.d.ts +450 -2
  222. package/dist/store/schema.js +141 -5
  223. package/dist/store/store.d.ts +29 -6
  224. package/dist/submit/resolve.js +2 -1
  225. package/dist/telemetry/calibration.d.ts +25 -0
  226. package/dist/telemetry/calibration.js +27 -1
  227. package/dist/telemetry/event.d.ts +391 -33
  228. package/dist/telemetry/event.js +84 -20
  229. package/dist/telemetry/index.d.ts +1 -0
  230. package/dist/telemetry/index.js +1 -0
  231. package/dist/telemetry/journal.d.ts +72 -3
  232. package/dist/telemetry/journal.js +9 -0
  233. package/dist/telemetry/lookup.d.ts +27 -0
  234. package/dist/telemetry/lookup.js +18 -0
  235. package/dist/telemetry/memory.js +23 -0
  236. package/dist/telemetry/migrate.js +22 -1
  237. package/dist/telemetry/postgres.d.ts +10 -1
  238. package/dist/telemetry/postgres.js +172 -90
  239. package/dist/telemetry/remeasure.d.ts +78 -0
  240. package/dist/telemetry/remeasure.js +83 -0
  241. package/dist/telemetry/retention.d.ts +2 -2
  242. package/dist/telemetry/schema.d.ts +17 -0
  243. package/dist/telemetry/schema.js +27 -1
  244. package/dist/telemetry/sink.d.ts +2 -2
  245. package/dist/testing/application-contract.d.ts +14 -0
  246. package/dist/testing/application-contract.js +270 -0
  247. package/dist/testing/contracts.d.ts +12 -7
  248. package/dist/testing/contracts.js +12 -7
  249. package/dist/testing/definitions.d.ts +78 -0
  250. package/dist/testing/definitions.js +134 -9
  251. package/dist/testing/doubles.d.ts +103 -0
  252. package/dist/testing/doubles.js +143 -0
  253. package/dist/testing/index.d.ts +2 -2
  254. package/dist/testing/index.js +2 -2
  255. package/dist/testing/journal-contract.js +140 -2
  256. package/dist/testing/model-contract.d.ts +110 -0
  257. package/dist/testing/model-contract.js +150 -0
  258. package/dist/testing/policy-log-contract.d.ts +26 -0
  259. package/dist/testing/policy-log-contract.js +344 -0
  260. package/dist/testing/project-contract.d.ts +14 -0
  261. package/dist/testing/project-contract.js +266 -0
  262. package/dist/testing/reader-signal-contract.d.ts +27 -2
  263. package/dist/testing/reader-signal-contract.js +475 -5
  264. package/dist/testing/store-contract.d.ts +7 -1
  265. package/dist/testing/store-contract.js +84 -3
  266. package/dist/theme/apply.d.ts +20 -1
  267. package/dist/theme/apply.js +5 -3
  268. package/dist/theme/derive.d.ts +22 -0
  269. package/dist/theme/derive.js +54 -1
  270. package/dist/theme/library.js +1 -1
  271. package/dist/theme/measure.d.ts +34 -0
  272. package/dist/theme/measure.js +30 -1
  273. package/dist/theme/palettes.js +7 -7
  274. package/dist/theme/ramp.d.ts +64 -0
  275. package/dist/theme/ramp.js +114 -0
  276. package/dist/theme/registry.d.ts +9 -0
  277. package/dist/theme/registry.js +11 -1
  278. package/dist/theme/separation.d.ts +97 -3
  279. package/dist/theme/separation.js +75 -0
  280. package/dist/tree/compare.d.ts +9 -0
  281. package/dist/tree/compare.js +18 -0
  282. package/dist/write/computed.d.ts +60 -0
  283. package/dist/write/computed.js +61 -0
  284. package/dist/write/held.d.ts +59 -0
  285. package/dist/write/index.d.ts +5 -2
  286. package/dist/write/index.js +5 -2
  287. package/dist/write/reseed.d.ts +151 -0
  288. package/dist/write/reseed.js +184 -0
  289. package/dist/write/revert.js +2 -16
  290. package/package.json +98 -19
@@ -1,4 +1,6 @@
1
1
  import { z } from "zod";
2
+ import { type WriteCheck } from "./checks.js";
3
+ import { type IrreversibilityReason } from "./irreversibility.js";
2
4
  import { type StakeLevel } from "./stake-level.js";
3
5
  /**
4
6
  * What the Gate decided, and why. The rationale is structured rather than
@@ -66,6 +68,71 @@ export declare const dispositionSchema: z.ZodObject<{
66
68
  * to check.
67
69
  */
68
70
  policyFingerprint: z.ZodOptional<z.ZodString>;
71
+ /**
72
+ * And which of the write path's optional checks were in place, beside what the
73
+ * rules were.
74
+ *
75
+ * A fingerprint proves the rules held; it says nothing about the two seams a
76
+ * composition root hands over separately, either of which can turn an
77
+ * `accepted` into a `rejected` (0179, 0208). Without this, a deployment that
78
+ * wired a registry into the write path on Tuesday produced Wednesday's
79
+ * judgments under a byte-identical fingerprint, and a reader comparing the two
80
+ * weeks was told nothing had changed.
81
+ *
82
+ * **The empty list is written rather than omitted**, which is the opposite of
83
+ * `irreversibilityReasons` below, and the difference is that nothing else here
84
+ * disambiguates the absence. `reversible` says whether any reason could have
85
+ * fired; no field says whether this runtime was asked about its seams. So an
86
+ * empty array is *asked, and none were wired*, and the field being absent is
87
+ * *judged before the Gate recorded this* — the same two states `policyId` and
88
+ * `policyFingerprint` keep apart, by the same means.
89
+ */
90
+ wiredChecks: z.ZodOptional<z.ZodArray<z.ZodEnum<["props", "bindings", "regions"]>, "many">>;
91
+ /**
92
+ * Why it cannot be taken back, for the one screen that has to ask somebody.
93
+ *
94
+ * `reversible` above says *whether*, and `reason.detail` says why in a
95
+ * sentence — and a sentence is the wrong thing to read, because the two
96
+ * reasons ask opposite things of the person holding the decision. One sends
97
+ * them to go and look at a payment flow; the other asks whether some content
98
+ * is worth keeping. The detail line is prose written for a reader and
99
+ * documented as such, so a consumer recovering the codes out of it would be
100
+ * parsing somebody else's wording, and would break silently the first time
101
+ * anybody improved it.
102
+ *
103
+ * Absent and never defaulted (0045), and omitted rather than empty when
104
+ * nothing fired. `reversible` is what disambiguates the absence, which leaves
105
+ * three states readable and the fourth impossible:
106
+ *
107
+ * | `reversible` | this field | what it means |
108
+ * | --- | --- | --- |
109
+ * | `true` | absent | nothing fired, which is what `true` already said |
110
+ * | `false` | present | these are the reasons |
111
+ * | `false` | absent | judged before this field existed |
112
+ * | `true` | present | never written; asserted in `gate.test.ts` |
113
+ */
114
+ irreversibilityReasons: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<"code", [z.ZodObject<{
115
+ code: z.ZodLiteral<"out-of-tree-effect">;
116
+ primitiveTypes: z.ZodArray<z.ZodBranded<z.ZodString, "PrimitiveType">, "many">;
117
+ }, "strip", z.ZodTypeAny, {
118
+ code: "out-of-tree-effect";
119
+ primitiveTypes: (string & z.BRAND<"PrimitiveType">)[];
120
+ }, {
121
+ code: "out-of-tree-effect";
122
+ primitiveTypes: string[];
123
+ }>, z.ZodObject<{
124
+ code: z.ZodLiteral<"retention-budget-exceeded">;
125
+ retainedNodeCount: z.ZodNumber;
126
+ budget: z.ZodNumber;
127
+ }, "strip", z.ZodTypeAny, {
128
+ code: "retention-budget-exceeded";
129
+ retainedNodeCount: number;
130
+ budget: number;
131
+ }, {
132
+ code: "retention-budget-exceeded";
133
+ retainedNodeCount: number;
134
+ budget: number;
135
+ }>]>, "many">>;
69
136
  }, "strip", z.ZodTypeAny, {
70
137
  kind: "rejected" | "accepted" | "requires-confirmation";
71
138
  confidence: number;
@@ -77,6 +144,15 @@ export declare const dispositionSchema: z.ZodObject<{
77
144
  stakes: "low" | "medium" | "high" | "critical";
78
145
  reversible: boolean;
79
146
  policyFingerprint?: string | undefined;
147
+ wiredChecks?: ("props" | "bindings" | "regions")[] | undefined;
148
+ irreversibilityReasons?: ({
149
+ code: "out-of-tree-effect";
150
+ primitiveTypes: (string & z.BRAND<"PrimitiveType">)[];
151
+ } | {
152
+ code: "retention-budget-exceeded";
153
+ retainedNodeCount: number;
154
+ budget: number;
155
+ })[] | undefined;
80
156
  }, {
81
157
  kind: "rejected" | "accepted" | "requires-confirmation";
82
158
  confidence: number;
@@ -88,6 +164,15 @@ export declare const dispositionSchema: z.ZodObject<{
88
164
  reversible: boolean;
89
165
  policyId?: string | undefined;
90
166
  policyFingerprint?: string | undefined;
167
+ wiredChecks?: ("props" | "bindings" | "regions")[] | undefined;
168
+ irreversibilityReasons?: ({
169
+ code: "out-of-tree-effect";
170
+ primitiveTypes: string[];
171
+ } | {
172
+ code: "retention-budget-exceeded";
173
+ retainedNodeCount: number;
174
+ budget: number;
175
+ })[] | undefined;
91
176
  }>;
92
177
  export type Disposition = {
93
178
  readonly kind: DispositionKind;
@@ -98,5 +183,16 @@ export type Disposition = {
98
183
  readonly policyId: string;
99
184
  /** Absent on a judgment recorded before the Gate fingerprinted policies. */
100
185
  readonly policyFingerprint?: string;
186
+ /**
187
+ * Absent on a judgment recorded before the Gate wrote down which checks were
188
+ * wired. Empty means it was asked and none were; the schema above says why the
189
+ * two are kept apart here and folded together elsewhere.
190
+ */
191
+ readonly wiredChecks?: readonly WriteCheck[];
192
+ /**
193
+ * Absent when nothing fired, and on a judgment recorded before the field
194
+ * existed. The schema above says which absence is which.
195
+ */
196
+ readonly irreversibilityReasons?: readonly IrreversibilityReason[];
101
197
  };
102
198
  //# sourceMappingURL=disposition.d.ts.map
@@ -1,4 +1,6 @@
1
1
  import { z } from "zod";
2
+ import { writeCheckSchema } from "./checks.js";
3
+ import { irreversibilityReasonSchema } from "./irreversibility.js";
2
4
  import { stakeLevelSchema } from "./stake-level.js";
3
5
  /**
4
6
  * What the Gate decided, and why. The rationale is structured rather than
@@ -55,5 +57,49 @@ export const dispositionSchema = z.object({
55
57
  * to check.
56
58
  */
57
59
  policyFingerprint: z.string().min(1).optional(),
60
+ /**
61
+ * And which of the write path's optional checks were in place, beside what the
62
+ * rules were.
63
+ *
64
+ * A fingerprint proves the rules held; it says nothing about the two seams a
65
+ * composition root hands over separately, either of which can turn an
66
+ * `accepted` into a `rejected` (0179, 0208). Without this, a deployment that
67
+ * wired a registry into the write path on Tuesday produced Wednesday's
68
+ * judgments under a byte-identical fingerprint, and a reader comparing the two
69
+ * weeks was told nothing had changed.
70
+ *
71
+ * **The empty list is written rather than omitted**, which is the opposite of
72
+ * `irreversibilityReasons` below, and the difference is that nothing else here
73
+ * disambiguates the absence. `reversible` says whether any reason could have
74
+ * fired; no field says whether this runtime was asked about its seams. So an
75
+ * empty array is *asked, and none were wired*, and the field being absent is
76
+ * *judged before the Gate recorded this* — the same two states `policyId` and
77
+ * `policyFingerprint` keep apart, by the same means.
78
+ */
79
+ wiredChecks: z.array(writeCheckSchema).optional(),
80
+ /**
81
+ * Why it cannot be taken back, for the one screen that has to ask somebody.
82
+ *
83
+ * `reversible` above says *whether*, and `reason.detail` says why in a
84
+ * sentence — and a sentence is the wrong thing to read, because the two
85
+ * reasons ask opposite things of the person holding the decision. One sends
86
+ * them to go and look at a payment flow; the other asks whether some content
87
+ * is worth keeping. The detail line is prose written for a reader and
88
+ * documented as such, so a consumer recovering the codes out of it would be
89
+ * parsing somebody else's wording, and would break silently the first time
90
+ * anybody improved it.
91
+ *
92
+ * Absent and never defaulted (0045), and omitted rather than empty when
93
+ * nothing fired. `reversible` is what disambiguates the absence, which leaves
94
+ * three states readable and the fourth impossible:
95
+ *
96
+ * | `reversible` | this field | what it means |
97
+ * | --- | --- | --- |
98
+ * | `true` | absent | nothing fired, which is what `true` already said |
99
+ * | `false` | present | these are the reasons |
100
+ * | `false` | absent | judged before this field existed |
101
+ * | `true` | present | never written; asserted in `gate.test.ts` |
102
+ */
103
+ irreversibilityReasons: z.array(irreversibilityReasonSchema).optional(),
58
104
  });
59
105
  //# sourceMappingURL=disposition.js.map
@@ -21,6 +21,28 @@ const decide = (assessment, policy, kind, reason) => ({
21
21
  * means what it meant. Neither is trustworthy from the caller.
22
22
  */
23
23
  policyFingerprint: policyFingerprintOf(policy),
24
+ /**
25
+ * And which optional checks were in place while it was judged, read off the
26
+ * assessment rather than taken from a caller — the assessment is what was
27
+ * handed the seams, so it is the only thing here that can say.
28
+ *
29
+ * Stamped on every disposition, including the accepted ones, and that is the
30
+ * point rather than an oversight. A check that fires leaves a refusal a reader
31
+ * can see; a check that was *never wired* leaves nothing at all, and the whole
32
+ * gap this closes is the silent case.
33
+ */
34
+ wiredChecks: assessment.wiredChecks,
35
+ /**
36
+ * Stamped on every disposition rather than only on the one
37
+ * `confirmIrreversible` produced. Which rung fired and why a change cannot be
38
+ * taken back are separate facts: a change can be held for discarding later
39
+ * work *and* be irreversible, and the rung that won says nothing about the
40
+ * second. Reading it off the assessment here is what keeps a reader of the
41
+ * record from inferring one from the other.
42
+ */
43
+ ...(assessment.reversibility.reasons.length > 0
44
+ ? { irreversibilityReasons: assessment.reversibility.reasons }
45
+ : {}),
24
46
  });
25
47
  /** Too unsure to act on at all — asking the user to confirm a guess is noise. */
26
48
  const rejectBelowConfidenceFloor = {
@@ -7,6 +7,7 @@
7
7
  */
8
8
  export * from "./analysis.js";
9
9
  export * from "./assessment.js";
10
+ export * from "./checks.js";
10
11
  export * from "./disposition.js";
11
12
  export * from "./events.js";
12
13
  export * from "./gate.js";
@@ -15,7 +16,9 @@ export * from "./interpreter.js";
15
16
  export * from "./inverse.js";
16
17
  export * from "./nesting.js";
17
18
  export * from "./pipeline.js";
19
+ export * from "./policy-change.js";
18
20
  export * from "./policy-fingerprint.js";
21
+ export * from "./policy-log.js";
19
22
  export * from "./policy-source.js";
20
23
  export * from "./policy.js";
21
24
  export * from "./proposal.js";
@@ -7,6 +7,7 @@
7
7
  */
8
8
  export * from "./analysis.js";
9
9
  export * from "./assessment.js";
10
+ export * from "./checks.js";
10
11
  export * from "./disposition.js";
11
12
  export * from "./events.js";
12
13
  export * from "./gate.js";
@@ -15,7 +16,9 @@ export * from "./interpreter.js";
15
16
  export * from "./inverse.js";
16
17
  export * from "./nesting.js";
17
18
  export * from "./pipeline.js";
19
+ export * from "./policy-change.js";
18
20
  export * from "./policy-fingerprint.js";
21
+ export * from "./policy-log.js";
19
22
  export * from "./policy-source.js";
20
23
  export * from "./policy.js";
21
24
  export * from "./proposal.js";
@@ -0,0 +1,64 @@
1
+ import { z } from "zod";
2
+ import { type PrimitiveType } from "../primitive-type.js";
3
+ /**
4
+ * Why a change cannot be taken back, as data.
5
+ *
6
+ * Its own module rather than `reversibility.ts` because of who has to import
7
+ * it. The reason is *computed* there, against a tree, a policy and an inverse
8
+ * delta; it is *stored* by `disposition.ts`, which §6 reads back out of a holds
9
+ * table and validates like anything else that crossed a wire or a year. A leaf
10
+ * holding nothing but the shape lets the second import it without pulling the
11
+ * tree engine in behind it, and keeps the direction of the dependency honest:
12
+ * the stored shape does not know how it was derived.
13
+ *
14
+ * The two members ask opposite things of whoever reads them, which is why a
15
+ * code is worth keeping beside the prose. `out-of-tree-effect` means the page
16
+ * is recoverable and reality is not — go and look at the part that takes the
17
+ * payment. `retention-budget-exceeded` means reality is fine and the page is
18
+ * not — decide whether the content is worth keeping, because the rest of it
19
+ * will not come back.
20
+ */
21
+ export declare const irreversibilityReasonSchema: z.ZodDiscriminatedUnion<"code", [z.ZodObject<{
22
+ code: z.ZodLiteral<"out-of-tree-effect">;
23
+ /**
24
+ * Which of the types the change touched this policy declared reach outside
25
+ * the tree. A type name is vocabulary the deployment registered rather than
26
+ * anything a visitor typed, which is why a stored record may carry it.
27
+ */
28
+ primitiveTypes: z.ZodArray<z.ZodBranded<z.ZodString, "PrimitiveType">, "many">;
29
+ }, "strip", z.ZodTypeAny, {
30
+ code: "out-of-tree-effect";
31
+ primitiveTypes: (string & z.BRAND<"PrimitiveType">)[];
32
+ }, {
33
+ code: "out-of-tree-effect";
34
+ primitiveTypes: string[];
35
+ }>, z.ZodObject<{
36
+ code: z.ZodLiteral<"retention-budget-exceeded">;
37
+ retainedNodeCount: z.ZodNumber;
38
+ budget: z.ZodNumber;
39
+ }, "strip", z.ZodTypeAny, {
40
+ code: "retention-budget-exceeded";
41
+ retainedNodeCount: number;
42
+ budget: number;
43
+ }, {
44
+ code: "retention-budget-exceeded";
45
+ retainedNodeCount: number;
46
+ budget: number;
47
+ }>]>;
48
+ export type IrreversibilityReason = {
49
+ readonly code: "out-of-tree-effect";
50
+ readonly primitiveTypes: readonly PrimitiveType[];
51
+ } | {
52
+ readonly code: "retention-budget-exceeded";
53
+ readonly retainedNodeCount: number;
54
+ readonly budget: number;
55
+ };
56
+ /**
57
+ * The types a reason list blames, empty when no out-of-tree reason fired.
58
+ *
59
+ * Here rather than at each of its two call sites because both of them are
60
+ * narrowing a reason list on the way into a stored record, and the narrowing is
61
+ * the part a reader has to be able to check.
62
+ */
63
+ export declare const outOfTreeEffectTypesOf: (reasons: readonly IrreversibilityReason[]) => readonly PrimitiveType[];
64
+ //# sourceMappingURL=irreversibility.d.ts.map
@@ -0,0 +1,45 @@
1
+ import { z } from "zod";
2
+ import { primitiveTypeSchema } from "../primitive-type.js";
3
+ /**
4
+ * Why a change cannot be taken back, as data.
5
+ *
6
+ * Its own module rather than `reversibility.ts` because of who has to import
7
+ * it. The reason is *computed* there, against a tree, a policy and an inverse
8
+ * delta; it is *stored* by `disposition.ts`, which §6 reads back out of a holds
9
+ * table and validates like anything else that crossed a wire or a year. A leaf
10
+ * holding nothing but the shape lets the second import it without pulling the
11
+ * tree engine in behind it, and keeps the direction of the dependency honest:
12
+ * the stored shape does not know how it was derived.
13
+ *
14
+ * The two members ask opposite things of whoever reads them, which is why a
15
+ * code is worth keeping beside the prose. `out-of-tree-effect` means the page
16
+ * is recoverable and reality is not — go and look at the part that takes the
17
+ * payment. `retention-budget-exceeded` means reality is fine and the page is
18
+ * not — decide whether the content is worth keeping, because the rest of it
19
+ * will not come back.
20
+ */
21
+ export const irreversibilityReasonSchema = z.discriminatedUnion("code", [
22
+ z.object({
23
+ code: z.literal("out-of-tree-effect"),
24
+ /**
25
+ * Which of the types the change touched this policy declared reach outside
26
+ * the tree. A type name is vocabulary the deployment registered rather than
27
+ * anything a visitor typed, which is why a stored record may carry it.
28
+ */
29
+ primitiveTypes: z.array(primitiveTypeSchema),
30
+ }),
31
+ z.object({
32
+ code: z.literal("retention-budget-exceeded"),
33
+ retainedNodeCount: z.number().int().nonnegative(),
34
+ budget: z.number().int().nonnegative(),
35
+ }),
36
+ ]);
37
+ /**
38
+ * The types a reason list blames, empty when no out-of-tree reason fired.
39
+ *
40
+ * Here rather than at each of its two call sites because both of them are
41
+ * narrowing a reason list on the way into a stored record, and the narrowing is
42
+ * the part a reader has to be able to check.
43
+ */
44
+ export const outOfTreeEffectTypesOf = (reasons) => reasons.flatMap((reason) => (reason.code === "out-of-tree-effect" ? reason.primitiveTypes : []));
45
+ //# sourceMappingURL=irreversibility.js.map
@@ -1,4 +1,6 @@
1
1
  import type { IdFactory } from "../ids.js";
2
+ import type { BindingReader } from "../render/reads.js";
3
+ import type { SlotPlacer } from "../render/slots.js";
2
4
  import type { TreeDelta } from "../tree/delta.js";
3
5
  import type { TreeError } from "../tree/errors.js";
4
6
  import type { LoomTree } from "../tree/tree.js";
@@ -48,8 +50,49 @@ export type CompositionRuntime = {
48
50
  * with a registry hands the same object to both seams and the two cannot
49
51
  * disagree about what is drawable. `propsVocabularyFor(registry)` in the SDK
50
52
  * is how one is obtained without hand-keeping it.
53
+ *
54
+ * Handing this over is recorded on every judgment it makes, as the `props`
55
+ * member of `Disposition.wiredChecks` (0248) — the policy fingerprint cannot
56
+ * see a seam, so wiring one would otherwise move a deployment's refusal rate
57
+ * and leave nothing behind that says which day it moved.
51
58
  */
52
59
  readonly propsVocabulary?: PropsVocabulary;
60
+ /**
61
+ * What this deployment's primitives read an answer under, checked before a
62
+ * delta is judged. Optional and absent by default, for every reason
63
+ * `propsVocabulary` above gives — a runtime handed none cannot tell a question
64
+ * nothing reads from one something does, and refusing on that ground is a
65
+ * choice made at the composition root rather than inherited (0179, 0208).
66
+ *
67
+ * Deliberately the renderer's own `BindingReader` rather than a second shape,
68
+ * so what the walk reports as `data-unread` is what the write path refuses. An
69
+ * SDK registry satisfies it already, which is why there is no
70
+ * `bindingReaderFor(registry)` beside `propsVocabularyFor`: the registry **is**
71
+ * one, and a helper that wrapped it would only be a place for the two to
72
+ * disagree.
73
+ *
74
+ * Recorded as the `bindings` member of `Disposition.wiredChecks`, for the
75
+ * reason above.
76
+ */
77
+ readonly bindingReader?: BindingReader;
78
+ /**
79
+ * What this deployment's primitives place a named region for, checked before
80
+ * a delta is judged. Optional and absent by default, for every reason
81
+ * `propsVocabulary` and `bindingReader` above give: a runtime handed none
82
+ * cannot tell a region a primitive places from one it drops on the floor
83
+ * (0051, 0249), and refusing on that ground is a choice made at the
84
+ * composition root rather than inherited (0179, 0252).
85
+ *
86
+ * Deliberately the renderer's own `SlotPlacer` rather than a second shape, so
87
+ * what the walk reports as `slot-unplaced` is what the write path refuses. An
88
+ * SDK registry satisfies it already, which is why there is no
89
+ * `slotPlacerFor(registry)` beside `propsVocabularyFor` — the registry **is**
90
+ * one, which is the arrangement `bindingReader` already has and for its
91
+ * reason.
92
+ *
93
+ * Recorded as the `regions` member of `Disposition.wiredChecks` (0248).
94
+ */
95
+ readonly slotPlacer?: SlotPlacer;
53
96
  };
54
97
  export type CompositionOutcome = {
55
98
  readonly kind: "applied";
@@ -68,7 +68,11 @@ const dispositionOutcome = (runtime, tree, assessment, disposition) => {
68
68
  const judgeProposal = (runtime, tree, proposal, policy) => {
69
69
  const emit = emitter(runtime, tree);
70
70
  emit({ type: "change-proposed", proposal });
71
- const assessed = assessChange(tree, proposal, policy, runtime.idFactory.deltaId(), runtime.propsVocabulary);
71
+ const assessed = assessChange(tree, proposal, policy, runtime.idFactory.deltaId(), {
72
+ propsVocabulary: runtime.propsVocabulary,
73
+ bindingReader: runtime.bindingReader,
74
+ slotPlacer: runtime.slotPlacer,
75
+ });
72
76
  if (!assessed.ok) {
73
77
  emit({ type: "assessment-failed", proposal, error: assessed.error });
74
78
  return { kind: "not-applicable", proposal, error: assessed.error };
@@ -161,7 +165,11 @@ export const confirmChange = (runtime, tree, proposal, intent) => {
161
165
  */
162
166
  const policy = runtime.policySource.resolve({ tree, intent });
163
167
  emit({ type: "policy-resolved", intentId: intent.intentId, policy });
164
- const assessed = assessChange(tree, proposal, policy, runtime.idFactory.deltaId(), runtime.propsVocabulary);
168
+ const assessed = assessChange(tree, proposal, policy, runtime.idFactory.deltaId(), {
169
+ propsVocabulary: runtime.propsVocabulary,
170
+ bindingReader: runtime.bindingReader,
171
+ slotPlacer: runtime.slotPlacer,
172
+ });
165
173
  if (!assessed.ok) {
166
174
  emit({ type: "assessment-failed", proposal, error: assessed.error });
167
175
  return { kind: "not-applicable", proposal, error: assessed.error };
@@ -0,0 +1,93 @@
1
+ import type { GatePolicy } from "./policy.js";
2
+ /**
3
+ * What one policy edit did, field by field.
4
+ *
5
+ * `policyFingerprintOf` can prove two judgments ran under different rules and
6
+ * can say nothing about *how* they differed, because a digest has no middle: two
7
+ * fingerprints either match or they do not. That is the whole of what a reader
8
+ * of a changed policy is asking — a refusal rate that moved the week somebody
9
+ * edited a policy is either explained by the edit or is a fault, and a hash
10
+ * cannot tell those apart.
11
+ *
12
+ * So this is the fingerprint's other half, and it is deliberately *derived*
13
+ * rather than stored. 0016's relationship one level up: the log is the truth and
14
+ * the reading is a view. A policy log keeps whole policies and this says what
15
+ * happened between two of them, so there is never a recorded diff free to
16
+ * disagree with the policies it claims to describe.
17
+ *
18
+ * It is pure, synchronous and reads nothing but its two arguments — the
19
+ * properties `policy-source.ts` requires of everything on the decision path, so
20
+ * a host may call this while judging rather than only while reporting.
21
+ */
22
+ /**
23
+ * Which way an edit moved the Gate.
24
+ *
25
+ * The question every reader of a policy change actually has, and the reason this
26
+ * module is more than a key-by-key comparison: *did it get easier or harder for
27
+ * a change to get through.* A calibration window that straddles an edit is
28
+ * legible exactly when this is known, and uninterpretable when it is not.
29
+ *
30
+ * - `stricter` — fewer changes get applied without asking, or more are refused.
31
+ * - `looser` — the opposite.
32
+ * - `mixed` — both, within one field. A set that gained a member and lost one
33
+ * is the common case, and reporting it as either would be a guess.
34
+ * - `incomparable` — the field has no order. Renaming the policy or editing a
35
+ * host's own vocabulary into a different, equally large list is a change with
36
+ * no direction to it, and inventing one is worse than saying so.
37
+ */
38
+ export type PolicyDirection = "stricter" | "looser" | "mixed" | "incomparable";
39
+ /** One field of `GatePolicy` that is not what it was, and what it is now. */
40
+ export type PolicyFieldChange = {
41
+ readonly field: keyof GatePolicy;
42
+ readonly direction: PolicyDirection;
43
+ /**
44
+ * What moved, in that field's own terms, for a reader.
45
+ *
46
+ * Prose, and documented as prose: a consumer that needs the values reads them
47
+ * off the two policies it already has. The same rule `Disposition.reason`
48
+ * keeps — a sentence is for a screen and never for a parser.
49
+ */
50
+ readonly detail: string;
51
+ };
52
+ /**
53
+ * What an edit did, and whether it is an edit at all.
54
+ *
55
+ * `fingerprints` is carried rather than recomputed by callers because the pair
56
+ * is what joins this reading to the judgments either side of it: a `Disposition`
57
+ * records the fingerprint it ran under, so a reader holding a change can find
58
+ * the records on both sides of it without hashing anything itself.
59
+ */
60
+ export type PolicyChange = {
61
+ /** False when the two policies differ in nothing the Gate consults. */
62
+ readonly changed: boolean;
63
+ /**
64
+ * True when the two have different names, which a host editing a policy's
65
+ * contents is under contract to produce (0033).
66
+ */
67
+ readonly renamed: boolean;
68
+ readonly fields: readonly PolicyFieldChange[];
69
+ /**
70
+ * The direction of the whole edit, folded over the fields that have one.
71
+ *
72
+ * `incomparable` fields are skipped rather than counted: an edit that tightened
73
+ * a threshold and rewrote a host vocabulary list is *stricter* in the only
74
+ * respect anything can be ordered by, and calling the pair `mixed` would hide
75
+ * the one half that is knowable. An edit whose every field is incomparable is
76
+ * itself `incomparable`, which is the honest answer and not a fallback.
77
+ */
78
+ readonly direction: PolicyDirection;
79
+ readonly fingerprints: {
80
+ readonly was: string;
81
+ readonly now: string;
82
+ };
83
+ };
84
+ /**
85
+ * What changed between two policies, and which way it moved the Gate.
86
+ *
87
+ * Takes two whole policies rather than two fingerprints, because a digest is
88
+ * one-way: the pair is the only thing that can answer this, and a log that kept
89
+ * diffs instead of policies could not answer it about a pair it had not
90
+ * anticipated.
91
+ */
92
+ export declare const policyChangeOf: (was: GatePolicy, now: GatePolicy) => PolicyChange;
93
+ //# sourceMappingURL=policy-change.d.ts.map