iterate-kernel 0.1.4 → 0.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -7
- package/dist/convergence.d.ts +90 -0
- package/dist/convergence.d.ts.map +1 -0
- package/dist/convergence.js +97 -0
- package/dist/convergence.js.map +1 -0
- package/dist/decision-log-entry.d.ts +46 -0
- package/dist/decision-log-entry.d.ts.map +1 -1
- package/dist/decision-log-entry.js +44 -1
- package/dist/decision-log-entry.js.map +1 -1
- package/dist/decision-log-transcribe.d.ts +77 -0
- package/dist/decision-log-transcribe.d.ts.map +1 -0
- package/dist/decision-log-transcribe.js +200 -0
- package/dist/decision-log-transcribe.js.map +1 -0
- package/dist/decision-log.d.ts +16 -0
- package/dist/decision-log.d.ts.map +1 -1
- package/dist/decision-log.js +12 -0
- package/dist/decision-log.js.map +1 -1
- package/dist/dimension-context.d.ts +10 -10
- package/dist/errors.d.ts +15 -0
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +7 -0
- package/dist/errors.js.map +1 -1
- package/dist/evidence-pack.d.ts +38 -38
- package/dist/index.d.ts +7 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -3
- package/dist/index.js.map +1 -1
- package/dist/invariant-report.d.ts +271 -0
- package/dist/invariant-report.d.ts.map +1 -0
- package/dist/invariant-report.js +145 -0
- package/dist/invariant-report.js.map +1 -0
- package/dist/parse.d.ts +7 -0
- package/dist/parse.d.ts.map +1 -1
- package/dist/parse.js +18 -10
- package/dist/parse.js.map +1 -1
- package/dist/provider-registration.d.ts +132 -0
- package/dist/provider-registration.d.ts.map +1 -0
- package/dist/provider-registration.js +119 -0
- package/dist/provider-registration.js.map +1 -0
- package/dist/schemas.d.ts +8 -0
- package/dist/schemas.d.ts.map +1 -1
- package/dist/schemas.js +8 -0
- package/dist/schemas.js.map +1 -1
- package/fixtures/convergence.ok-01.json +252 -0
- package/fixtures/decision-log-entry.ok-02.json +20 -0
- package/fixtures/decision-record-transcription.ok-01.json +260 -0
- package/fixtures/invariant-report.ok-01.json +306 -0
- package/fixtures/provider-registration.ok-01.json +309 -0
- package/fixtures/run-plan.ok-01.json +1 -1
- package/package.json +17 -1
- package/schemas/convergence-round-state.schema.json +37 -0
- package/schemas/decision-log-entry.schema.json +20 -0
- package/schemas/invariant-report.schema.json +108 -0
- package/schemas/provider-registration.schema.json +63 -0
- package/schemas/reverification-request.schema.json +89 -0
package/README.md
CHANGED
|
@@ -34,9 +34,13 @@ APIs it actually uses.
|
|
|
34
34
|
| --- | --- |
|
|
35
35
|
| `evidence-pack` / `parse` | the evidence pack shape, and parsing/validating one |
|
|
36
36
|
| `evidence-decision` | the **transcription**: evidence (attribution level, circuit-breaker level, pass/fail/inconclusive) → a decision outcome and a human summary. It reads fields the engine already decided; it never infers. |
|
|
37
|
-
| `decision-log-entry` / `decision-log` | the append-only decision-log entry and the `opID ↔ entry` hash chain that makes it auditable |
|
|
37
|
+
| `decision-log-entry` / `decision-log` | the append-only decision-log entry and the `opID ↔ entry` hash chain that makes it auditable. The entry carries the producer's own `kind`, its `round`, the `dimension` a decision served and a bounded `payload` — all optional, so chains written before them keep their bytes and their digests. |
|
|
38
|
+
| `decision-log-transcribe` | the mapping from a decision record that the iterate ledgers already write (`{timestamp, round, type, data}` JSONL, produced independently in Python and TypeScript) onto a canonical draft. Rules live in `fixtures/decision-record-transcription.ok-01.json` so the second implementation is coded from the fixture, not from this package. |
|
|
38
39
|
| `dimension-context` / `parse` | the dimension-coverage transcription: a plan plus what the engine actually recorded → verified / unverified / unplanned, and one line to put in a summary. It validates id *shape*, never which ids exist — that list belongs to whoever configured the run. |
|
|
39
40
|
| `run-plan` / `parse` | the plan that `dimension-context` needs and refuses to invent: which dimensions a run intends to cover, in the caller's order, with the declared source. It carries a **digest** (`rp_` + sha256 of the canonical form) so a ledger line can state which plan a run was held to, and a reader can notice the plan changed mid-run. Nothing here reads a config file — producing a plan is whoever configures the run's job, and that keeps the kernel from learning a consumer's file format. |
|
|
41
|
+
| `invariant-report` / `parse` | what the invariant runner may state about its own checks, and the re-verification a failure asks for. It refuses a report that says `pass` while carrying a failed check, and it turns an `error` (a check that could not run) into **no** request: re-verifying the app would answer a question nobody measured. |
|
|
42
|
+
| `convergence` | the rules for what the loop does next, from stated inputs only. A tripped breaker, a spent round budget, and an errored check each `halt`; unlooked-or-unmeasured states `verify`, never `converged`. Both harnesses read one idea of "done" instead of growing two. |
|
|
43
|
+
| `provider-registration` | metadata for a judgement producer — who offers which method, and what it requires. Registering an existing id is refused rather than silently overridden, and resolution never guesses. |
|
|
40
44
|
| `errors` / `schemas` / `canonical-json` / `recipe-config` | `KernelSchemaError`, the JSON Schemas, canonical serialisation, recipe validation |
|
|
41
45
|
|
|
42
46
|
## A runnable example
|
|
@@ -108,12 +112,17 @@ not a contract; it is a note nobody reads.
|
|
|
108
112
|
|
|
109
113
|
## Consumers
|
|
110
114
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
-
|
|
115
|
+
A consumer's kernel is this package, pinned. There is no second copy of the source anywhere:
|
|
116
|
+
the GlassPane Harness fork used to vendor `kernel/src` under `packages/opencode/vendor/kernel`
|
|
117
|
+
with a probe that asked whether the canonical branch had moved, and that arrangement was retired
|
|
118
|
+
in favour of the npm dependency — its `script/kernel-pin.mjs` now checks the installed version,
|
|
119
|
+
the lockfile integrity hash, and the per-file sha256 of the shipped corpus against
|
|
120
|
+
`contracts/kernel-pin.json`, and `script/kernel-conformance.mjs` runs the fixtures against the
|
|
121
|
+
installed `dist/`.
|
|
122
|
+
|
|
123
|
+
The Python side still cannot import TypeScript, so it vendors the *corpus* (fixtures and schemas)
|
|
124
|
+
and implements the rules itself from the fixture `comment` fields; that is what the paragraph
|
|
125
|
+
above describes, and `scripts/check_kernel_fixtures.py` is what keeps the two copies byte-agreed.
|
|
117
126
|
|
|
118
127
|
Either way, run the fixtures: they are how you find out that the kernel you have is not the
|
|
119
128
|
kernel you think you have.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
/**
|
|
3
|
+
* Convergence rules: what happens after a round, decided from stated inputs
|
|
4
|
+
* (5.7 R40 scenario 4 — a GlassPane fix finishing hands the next step to the
|
|
5
|
+
* invariant review, and only then does the loop consider re-verifying).
|
|
6
|
+
*
|
|
7
|
+
* This is the piece §8.5 puts **inside** the kernel ("收敛规则"), and it is policy
|
|
8
|
+
* arithmetic, not verification: every input is a verdict somebody else produced. The
|
|
9
|
+
* rules exist so the two harnesses do not each grow a private idea of "done" — the
|
|
10
|
+
* asymmetry that makes a loop stop in one product and keep running in the other.
|
|
11
|
+
*/
|
|
12
|
+
export declare const CONVERGENCE_SCHEMA_VERSION: "iterate.convergence/0.1";
|
|
13
|
+
export declare const InvariantStateSchema: z.ZodEnum<["pass", "fail", "error", "unmeasured"]>;
|
|
14
|
+
export type InvariantState = z.infer<typeof InvariantStateSchema>;
|
|
15
|
+
/** What a caller states about the round that just finished. */
|
|
16
|
+
export declare const RoundStateSchema: z.ZodObject<{
|
|
17
|
+
schemaVersion: z.ZodOptional<z.ZodLiteral<"iterate.convergence/0.1">>;
|
|
18
|
+
round: z.ZodNumber;
|
|
19
|
+
maxRounds: z.ZodNumber;
|
|
20
|
+
invariantState: z.ZodEnum<["pass", "fail", "error", "unmeasured"]>;
|
|
21
|
+
openFindings: z.ZodNumber;
|
|
22
|
+
/** False when the engine never got to evidence something (refused, crashed, unattached). */
|
|
23
|
+
evidenceComplete: z.ZodBoolean;
|
|
24
|
+
/** The engine's own circuit-breaker level for this run; 3 is tripped. */
|
|
25
|
+
breakerLevel: z.ZodNumber;
|
|
26
|
+
}, "strict", z.ZodTypeAny, {
|
|
27
|
+
round: number;
|
|
28
|
+
maxRounds: number;
|
|
29
|
+
invariantState: "pass" | "fail" | "error" | "unmeasured";
|
|
30
|
+
openFindings: number;
|
|
31
|
+
evidenceComplete: boolean;
|
|
32
|
+
breakerLevel: number;
|
|
33
|
+
schemaVersion?: "iterate.convergence/0.1" | undefined;
|
|
34
|
+
}, {
|
|
35
|
+
round: number;
|
|
36
|
+
maxRounds: number;
|
|
37
|
+
invariantState: "pass" | "fail" | "error" | "unmeasured";
|
|
38
|
+
openFindings: number;
|
|
39
|
+
evidenceComplete: boolean;
|
|
40
|
+
breakerLevel: number;
|
|
41
|
+
schemaVersion?: "iterate.convergence/0.1" | undefined;
|
|
42
|
+
}>;
|
|
43
|
+
export type RoundState = z.infer<typeof RoundStateSchema>;
|
|
44
|
+
export declare const ConvergenceActionSchema: z.ZodEnum<["fix", "verify", "converged", "halt"]>;
|
|
45
|
+
export type ConvergenceAction = z.infer<typeof ConvergenceActionSchema>;
|
|
46
|
+
export declare const CONVERGENCE_REASONS: {
|
|
47
|
+
readonly breakerTripped: "circuit-breaker-tripped";
|
|
48
|
+
readonly budgetExhausted: "round-budget-exhausted";
|
|
49
|
+
readonly invariantErrored: "invariant-check-errored";
|
|
50
|
+
readonly openFindings: "open-findings";
|
|
51
|
+
readonly invariantsFailed: "invariants-failed";
|
|
52
|
+
readonly evidenceIncomplete: "evidence-incomplete";
|
|
53
|
+
readonly invariantsUnmeasured: "invariants-unmeasured";
|
|
54
|
+
readonly allGatesGreen: "all-gates-green";
|
|
55
|
+
};
|
|
56
|
+
export type ConvergenceReason = (typeof CONVERGENCE_REASONS)[keyof typeof CONVERGENCE_REASONS];
|
|
57
|
+
export declare const ConvergenceDecisionSchema: z.ZodObject<{
|
|
58
|
+
action: z.ZodEnum<["fix", "verify", "converged", "halt"]>;
|
|
59
|
+
reason: z.ZodEnum<["circuit-breaker-tripped", "round-budget-exhausted", "invariant-check-errored", "open-findings", "invariants-failed", "evidence-incomplete", "invariants-unmeasured", "all-gates-green"]>;
|
|
60
|
+
round: z.ZodNumber;
|
|
61
|
+
maxRounds: z.ZodNumber;
|
|
62
|
+
}, "strict", z.ZodTypeAny, {
|
|
63
|
+
round: number;
|
|
64
|
+
maxRounds: number;
|
|
65
|
+
action: "fix" | "verify" | "converged" | "halt";
|
|
66
|
+
reason: "circuit-breaker-tripped" | "round-budget-exhausted" | "invariant-check-errored" | "open-findings" | "invariants-failed" | "evidence-incomplete" | "invariants-unmeasured" | "all-gates-green";
|
|
67
|
+
}, {
|
|
68
|
+
round: number;
|
|
69
|
+
maxRounds: number;
|
|
70
|
+
action: "fix" | "verify" | "converged" | "halt";
|
|
71
|
+
reason: "circuit-breaker-tripped" | "round-budget-exhausted" | "invariant-check-errored" | "open-findings" | "invariants-failed" | "evidence-incomplete" | "invariants-unmeasured" | "all-gates-green";
|
|
72
|
+
}>;
|
|
73
|
+
export type ConvergenceDecision = z.infer<typeof ConvergenceDecisionSchema>;
|
|
74
|
+
/**
|
|
75
|
+
* Precedence, and why it is this order:
|
|
76
|
+
*
|
|
77
|
+
* 1. breaker tripped → `halt`. A limit the harness set on itself is not the app's
|
|
78
|
+
* failure, and continuing would report a stall as a verdict.
|
|
79
|
+
* 2. round budget spent → `halt`. Checked before the work so a run cannot buy
|
|
80
|
+
* another round by reporting findings it already had.
|
|
81
|
+
* 3. the invariant check errored → `halt`. Nothing can be derived from a check that
|
|
82
|
+
* did not run; retrying is the runner's job, not the loop's.
|
|
83
|
+
* 4. open findings, or invariants that failed → `fix`.
|
|
84
|
+
* 5. evidence incomplete, or invariants unmeasured → `verify`. Not `converged`:
|
|
85
|
+
* "we could not look" and "we looked and it holds" are different states, and
|
|
86
|
+
* collapsing them is the failure this whole contract exists to prevent.
|
|
87
|
+
* 6. otherwise → `converged`.
|
|
88
|
+
*/
|
|
89
|
+
export declare function convergenceDecision(state: RoundState): ConvergenceDecision;
|
|
90
|
+
//# sourceMappingURL=convergence.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"convergence.d.ts","sourceRoot":"","sources":["../src/convergence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,EAAG,yBAAkC,CAAC;AAE7E,eAAO,MAAM,oBAAoB,oDAAkD,CAAC;AACpF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB;;;;;;IAM3B,4FAA4F;;IAE5F,yEAAyE;;;;;;;;;;;;;;;;;;EAEzE,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,uBAAuB,mDAAiD,CAAC;AACtF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,mBAAmB;;;;;;;;;CAStB,CAAC;AACX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAE/F,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;EAcpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,mBAAmB,CAuB1E"}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { schemaErrorFrom } from "./errors.js";
|
|
3
|
+
/**
|
|
4
|
+
* Convergence rules: what happens after a round, decided from stated inputs
|
|
5
|
+
* (5.7 R40 scenario 4 — a GlassPane fix finishing hands the next step to the
|
|
6
|
+
* invariant review, and only then does the loop consider re-verifying).
|
|
7
|
+
*
|
|
8
|
+
* This is the piece §8.5 puts **inside** the kernel ("收敛规则"), and it is policy
|
|
9
|
+
* arithmetic, not verification: every input is a verdict somebody else produced. The
|
|
10
|
+
* rules exist so the two harnesses do not each grow a private idea of "done" — the
|
|
11
|
+
* asymmetry that makes a loop stop in one product and keep running in the other.
|
|
12
|
+
*/
|
|
13
|
+
export const CONVERGENCE_SCHEMA_VERSION = "iterate.convergence/0.1";
|
|
14
|
+
export const InvariantStateSchema = z.enum(["pass", "fail", "error", "unmeasured"]);
|
|
15
|
+
/** What a caller states about the round that just finished. */
|
|
16
|
+
export const RoundStateSchema = z.strictObject({
|
|
17
|
+
schemaVersion: z.literal(CONVERGENCE_SCHEMA_VERSION).optional(),
|
|
18
|
+
round: z.number().int().min(1),
|
|
19
|
+
maxRounds: z.number().int().min(1),
|
|
20
|
+
invariantState: InvariantStateSchema,
|
|
21
|
+
openFindings: z.number().int().min(0),
|
|
22
|
+
/** False when the engine never got to evidence something (refused, crashed, unattached). */
|
|
23
|
+
evidenceComplete: z.boolean(),
|
|
24
|
+
/** The engine's own circuit-breaker level for this run; 3 is tripped. */
|
|
25
|
+
breakerLevel: z.number().int().min(0).max(3)
|
|
26
|
+
});
|
|
27
|
+
export const ConvergenceActionSchema = z.enum(["fix", "verify", "converged", "halt"]);
|
|
28
|
+
export const CONVERGENCE_REASONS = {
|
|
29
|
+
breakerTripped: "circuit-breaker-tripped",
|
|
30
|
+
budgetExhausted: "round-budget-exhausted",
|
|
31
|
+
invariantErrored: "invariant-check-errored",
|
|
32
|
+
openFindings: "open-findings",
|
|
33
|
+
invariantsFailed: "invariants-failed",
|
|
34
|
+
evidenceIncomplete: "evidence-incomplete",
|
|
35
|
+
invariantsUnmeasured: "invariants-unmeasured",
|
|
36
|
+
allGatesGreen: "all-gates-green"
|
|
37
|
+
};
|
|
38
|
+
export const ConvergenceDecisionSchema = z.strictObject({
|
|
39
|
+
action: ConvergenceActionSchema,
|
|
40
|
+
reason: z.enum([
|
|
41
|
+
CONVERGENCE_REASONS.breakerTripped,
|
|
42
|
+
CONVERGENCE_REASONS.budgetExhausted,
|
|
43
|
+
CONVERGENCE_REASONS.invariantErrored,
|
|
44
|
+
CONVERGENCE_REASONS.openFindings,
|
|
45
|
+
CONVERGENCE_REASONS.invariantsFailed,
|
|
46
|
+
CONVERGENCE_REASONS.evidenceIncomplete,
|
|
47
|
+
CONVERGENCE_REASONS.invariantsUnmeasured,
|
|
48
|
+
CONVERGENCE_REASONS.allGatesGreen
|
|
49
|
+
]),
|
|
50
|
+
round: z.number().int().min(1),
|
|
51
|
+
maxRounds: z.number().int().min(1)
|
|
52
|
+
});
|
|
53
|
+
/**
|
|
54
|
+
* Precedence, and why it is this order:
|
|
55
|
+
*
|
|
56
|
+
* 1. breaker tripped → `halt`. A limit the harness set on itself is not the app's
|
|
57
|
+
* failure, and continuing would report a stall as a verdict.
|
|
58
|
+
* 2. round budget spent → `halt`. Checked before the work so a run cannot buy
|
|
59
|
+
* another round by reporting findings it already had.
|
|
60
|
+
* 3. the invariant check errored → `halt`. Nothing can be derived from a check that
|
|
61
|
+
* did not run; retrying is the runner's job, not the loop's.
|
|
62
|
+
* 4. open findings, or invariants that failed → `fix`.
|
|
63
|
+
* 5. evidence incomplete, or invariants unmeasured → `verify`. Not `converged`:
|
|
64
|
+
* "we could not look" and "we looked and it holds" are different states, and
|
|
65
|
+
* collapsing them is the failure this whole contract exists to prevent.
|
|
66
|
+
* 6. otherwise → `converged`.
|
|
67
|
+
*/
|
|
68
|
+
export function convergenceDecision(state) {
|
|
69
|
+
const checked = RoundStateSchema.safeParse(state);
|
|
70
|
+
if (!checked.success) {
|
|
71
|
+
throw schemaErrorFrom("round state", checked.error);
|
|
72
|
+
}
|
|
73
|
+
const input = checked.data;
|
|
74
|
+
const decided = (action, reason) => ({
|
|
75
|
+
action,
|
|
76
|
+
reason,
|
|
77
|
+
round: input.round,
|
|
78
|
+
maxRounds: input.maxRounds
|
|
79
|
+
});
|
|
80
|
+
if (input.breakerLevel >= 3)
|
|
81
|
+
return decided("halt", CONVERGENCE_REASONS.breakerTripped);
|
|
82
|
+
if (input.round >= input.maxRounds)
|
|
83
|
+
return decided("halt", CONVERGENCE_REASONS.budgetExhausted);
|
|
84
|
+
if (input.invariantState === "error")
|
|
85
|
+
return decided("halt", CONVERGENCE_REASONS.invariantErrored);
|
|
86
|
+
if (input.openFindings > 0)
|
|
87
|
+
return decided("fix", CONVERGENCE_REASONS.openFindings);
|
|
88
|
+
if (input.invariantState === "fail")
|
|
89
|
+
return decided("fix", CONVERGENCE_REASONS.invariantsFailed);
|
|
90
|
+
if (!input.evidenceComplete)
|
|
91
|
+
return decided("verify", CONVERGENCE_REASONS.evidenceIncomplete);
|
|
92
|
+
if (input.invariantState === "unmeasured") {
|
|
93
|
+
return decided("verify", CONVERGENCE_REASONS.invariantsUnmeasured);
|
|
94
|
+
}
|
|
95
|
+
return decided("converged", CONVERGENCE_REASONS.allGatesGreen);
|
|
96
|
+
}
|
|
97
|
+
//# sourceMappingURL=convergence.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"convergence.js","sourceRoot":"","sources":["../src/convergence.ts"],"names":[],"mappings":"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"}
|
|
@@ -3,8 +3,42 @@ export declare const DECISION_ENTRY_ID_PATTERN: RegExp;
|
|
|
3
3
|
/** SHA-256 full hex (64 lowercase chars), or the empty string for the genesis entry. */
|
|
4
4
|
export declare const PREV_ENTRY_HASH_PATTERN: RegExp;
|
|
5
5
|
export declare const SUMMARY_MAX_LENGTH = 2048;
|
|
6
|
+
/**
|
|
7
|
+
* What kind of decision an entry records — snake_case producer vocabulary, deliberately
|
|
8
|
+
* NOT an enum here.
|
|
9
|
+
*
|
|
10
|
+
* WHY IT IS NOT ENUMERATED. Each ecosystem has its own set of event kinds and each is
|
|
11
|
+
* the authority on its own list: the iterate loop records `round_start`, `review_result`,
|
|
12
|
+
* `atomic_fix`, `architectural_fix`, `revert`, `validation`, `decision`, `report` (and the
|
|
13
|
+
* plugin's history adds `round_failed`, `resume`), while the GlassPane fork records tool
|
|
14
|
+
* executions. Enumerating them in this package would make the kernel the owner of two
|
|
15
|
+
* vocabularies it does not maintain, and every new kind would need a kernel release —
|
|
16
|
+
* the same reason there is no dimension list in `dimension-context.ts`. The kernel's job
|
|
17
|
+
* is to make the field *comparable* (shape, bound, no silent free-text drift), not to
|
|
18
|
+
* decide what counts as a decision.
|
|
19
|
+
*/
|
|
20
|
+
export declare const DECISION_KIND_PATTERN: RegExp;
|
|
21
|
+
/**
|
|
22
|
+
* Upper bound on the canonical-JSON length of `payload`. The legacy logs this shape
|
|
23
|
+
* replaces put an unbounded `data` object on every line; an unbounded field in a
|
|
24
|
+
* hash-chained ledger is a line whose bytes — and therefore whose digest — can grow
|
|
25
|
+
* without limit, so the bound is part of the contract even though JSON Schema cannot
|
|
26
|
+
* state it (see the documented divergence in `schemas/decision-log-entry.schema.json`).
|
|
27
|
+
*/
|
|
28
|
+
export declare const PAYLOAD_MAX_CANONICAL_LENGTH = 8192;
|
|
6
29
|
export declare const DecisionOutcomeSchema: z.ZodEnum<["pass", "fail", "blocked", "inconclusive"]>;
|
|
7
30
|
export type DecisionOutcome = z.infer<typeof DecisionOutcomeSchema>;
|
|
31
|
+
/**
|
|
32
|
+
* One line of the audit chain.
|
|
33
|
+
*
|
|
34
|
+
* `kind`, `round`, `dimension` and `payload` are all optional so the entries the GlassPane
|
|
35
|
+
* fork already wrote keep parsing and keep their recorded digests: an omitted field is
|
|
36
|
+
* absent from the canonical bytes, not `null`, so widening this shape does not retroactively
|
|
37
|
+
* break a chain. They exist because the ledgers this shape is meant to replace carry that
|
|
38
|
+
* information, and a canonical form that cannot state "which round, what kind, which
|
|
39
|
+
* dimension, against what finding" would force each ecosystem to keep its own log beside
|
|
40
|
+
* the shared one — which is the divergence this entry exists to end.
|
|
41
|
+
*/
|
|
8
42
|
export declare const DecisionLogEntrySchema: z.ZodObject<{
|
|
9
43
|
entryId: z.ZodString;
|
|
10
44
|
sequence: z.ZodNumber;
|
|
@@ -13,6 +47,10 @@ export declare const DecisionLogEntrySchema: z.ZodObject<{
|
|
|
13
47
|
summary: z.ZodString;
|
|
14
48
|
outcome: z.ZodEnum<["pass", "fail", "blocked", "inconclusive"]>;
|
|
15
49
|
createdAt: z.ZodString;
|
|
50
|
+
kind: z.ZodOptional<z.ZodString>;
|
|
51
|
+
round: z.ZodOptional<z.ZodNumber>;
|
|
52
|
+
dimension: z.ZodOptional<z.ZodString>;
|
|
53
|
+
payload: z.ZodEffects<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>, Record<string, unknown> | undefined, Record<string, unknown> | undefined>;
|
|
16
54
|
}, "strict", z.ZodTypeAny, {
|
|
17
55
|
createdAt: string;
|
|
18
56
|
entryId: string;
|
|
@@ -20,7 +58,11 @@ export declare const DecisionLogEntrySchema: z.ZodObject<{
|
|
|
20
58
|
prevEntryHash: string;
|
|
21
59
|
summary: string;
|
|
22
60
|
outcome: "pass" | "fail" | "blocked" | "inconclusive";
|
|
61
|
+
round?: number | undefined;
|
|
62
|
+
kind?: string | undefined;
|
|
23
63
|
operationId?: string | undefined;
|
|
64
|
+
dimension?: string | undefined;
|
|
65
|
+
payload?: Record<string, unknown> | undefined;
|
|
24
66
|
}, {
|
|
25
67
|
createdAt: string;
|
|
26
68
|
entryId: string;
|
|
@@ -28,7 +70,11 @@ export declare const DecisionLogEntrySchema: z.ZodObject<{
|
|
|
28
70
|
prevEntryHash: string;
|
|
29
71
|
summary: string;
|
|
30
72
|
outcome: "pass" | "fail" | "blocked" | "inconclusive";
|
|
73
|
+
round?: number | undefined;
|
|
74
|
+
kind?: string | undefined;
|
|
31
75
|
operationId?: string | undefined;
|
|
76
|
+
dimension?: string | undefined;
|
|
77
|
+
payload?: Record<string, unknown> | undefined;
|
|
32
78
|
}>;
|
|
33
79
|
export type DecisionLogEntry = z.infer<typeof DecisionLogEntrySchema>;
|
|
34
80
|
//# sourceMappingURL=decision-log-entry.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"decision-log-entry.d.ts","sourceRoot":"","sources":["../src/decision-log-entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;
|
|
1
|
+
{"version":3,"file":"decision-log-entry.d.ts","sourceRoot":"","sources":["../src/decision-log-entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,yBAAyB,QAAgC,CAAC;AAEvE,wFAAwF;AACxF,eAAO,MAAM,uBAAuB,QAAsB,CAAC;AAE3D,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,QAA2B,CAAC;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,eAAO,MAAM,qBAAqB,wDAAsD,CAAC;AACzF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkBjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}
|
|
@@ -1,10 +1,46 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
+
import { canonicalJson } from "./canonical-json.js";
|
|
3
|
+
import { DIMENSION_ID_MAX_LENGTH, DIMENSION_ID_PATTERN } from "./dimension-context.js";
|
|
2
4
|
import { ISO_MILLIS_PATTERN, OPERATION_ID_PATTERN } from "./evidence-pack.js";
|
|
3
5
|
export const DECISION_ENTRY_ID_PATTERN = /^dl_[0-9A-HJKMNP-TV-Z]{26}$/;
|
|
4
6
|
/** SHA-256 full hex (64 lowercase chars), or the empty string for the genesis entry. */
|
|
5
7
|
export const PREV_ENTRY_HASH_PATTERN = /^([0-9a-f]{64})?$/;
|
|
6
8
|
export const SUMMARY_MAX_LENGTH = 2048;
|
|
9
|
+
/**
|
|
10
|
+
* What kind of decision an entry records — snake_case producer vocabulary, deliberately
|
|
11
|
+
* NOT an enum here.
|
|
12
|
+
*
|
|
13
|
+
* WHY IT IS NOT ENUMERATED. Each ecosystem has its own set of event kinds and each is
|
|
14
|
+
* the authority on its own list: the iterate loop records `round_start`, `review_result`,
|
|
15
|
+
* `atomic_fix`, `architectural_fix`, `revert`, `validation`, `decision`, `report` (and the
|
|
16
|
+
* plugin's history adds `round_failed`, `resume`), while the GlassPane fork records tool
|
|
17
|
+
* executions. Enumerating them in this package would make the kernel the owner of two
|
|
18
|
+
* vocabularies it does not maintain, and every new kind would need a kernel release —
|
|
19
|
+
* the same reason there is no dimension list in `dimension-context.ts`. The kernel's job
|
|
20
|
+
* is to make the field *comparable* (shape, bound, no silent free-text drift), not to
|
|
21
|
+
* decide what counts as a decision.
|
|
22
|
+
*/
|
|
23
|
+
export const DECISION_KIND_PATTERN = /^[a-z][a-z0-9_]{0,31}$/;
|
|
24
|
+
/**
|
|
25
|
+
* Upper bound on the canonical-JSON length of `payload`. The legacy logs this shape
|
|
26
|
+
* replaces put an unbounded `data` object on every line; an unbounded field in a
|
|
27
|
+
* hash-chained ledger is a line whose bytes — and therefore whose digest — can grow
|
|
28
|
+
* without limit, so the bound is part of the contract even though JSON Schema cannot
|
|
29
|
+
* state it (see the documented divergence in `schemas/decision-log-entry.schema.json`).
|
|
30
|
+
*/
|
|
31
|
+
export const PAYLOAD_MAX_CANONICAL_LENGTH = 8192;
|
|
7
32
|
export const DecisionOutcomeSchema = z.enum(["pass", "fail", "blocked", "inconclusive"]);
|
|
33
|
+
/**
|
|
34
|
+
* One line of the audit chain.
|
|
35
|
+
*
|
|
36
|
+
* `kind`, `round`, `dimension` and `payload` are all optional so the entries the GlassPane
|
|
37
|
+
* fork already wrote keep parsing and keep their recorded digests: an omitted field is
|
|
38
|
+
* absent from the canonical bytes, not `null`, so widening this shape does not retroactively
|
|
39
|
+
* break a chain. They exist because the ledgers this shape is meant to replace carry that
|
|
40
|
+
* information, and a canonical form that cannot state "which round, what kind, which
|
|
41
|
+
* dimension, against what finding" would force each ecosystem to keep its own log beside
|
|
42
|
+
* the shared one — which is the divergence this entry exists to end.
|
|
43
|
+
*/
|
|
8
44
|
export const DecisionLogEntrySchema = z.strictObject({
|
|
9
45
|
entryId: z.string().regex(DECISION_ENTRY_ID_PATTERN),
|
|
10
46
|
sequence: z.number().int().min(0),
|
|
@@ -12,6 +48,13 @@ export const DecisionLogEntrySchema = z.strictObject({
|
|
|
12
48
|
operationId: z.string().regex(OPERATION_ID_PATTERN).optional(),
|
|
13
49
|
summary: z.string().max(SUMMARY_MAX_LENGTH),
|
|
14
50
|
outcome: DecisionOutcomeSchema,
|
|
15
|
-
createdAt: z.string().regex(ISO_MILLIS_PATTERN)
|
|
51
|
+
createdAt: z.string().regex(ISO_MILLIS_PATTERN),
|
|
52
|
+
kind: z.string().regex(DECISION_KIND_PATTERN).optional(),
|
|
53
|
+
round: z.number().int().min(0).optional(),
|
|
54
|
+
dimension: z.string().regex(DIMENSION_ID_PATTERN).max(DIMENSION_ID_MAX_LENGTH).optional(),
|
|
55
|
+
payload: z
|
|
56
|
+
.record(z.string(), z.unknown())
|
|
57
|
+
.optional()
|
|
58
|
+
.refine((value) => value === undefined || canonicalJson(value).length <= PAYLOAD_MAX_CANONICAL_LENGTH, { message: `payload must stay within ${PAYLOAD_MAX_CANONICAL_LENGTH} characters of canonical JSON` })
|
|
16
59
|
});
|
|
17
60
|
//# sourceMappingURL=decision-log-entry.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"decision-log-entry.js","sourceRoot":"","sources":["../src/decision-log-entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE9E,MAAM,CAAC,MAAM,yBAAyB,GAAG,6BAA6B,CAAC;AAEvE,wFAAwF;AACxF,MAAM,CAAC,MAAM,uBAAuB,GAAG,mBAAmB,CAAC;AAE3D,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC;AAGzF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,YAAY,CAAC;IACnD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,yBAAyB,CAAC;IACpD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,uBAAuB,CAAC;IACxD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,QAAQ,EAAE;IAC9D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAC3C,OAAO,EAAE,qBAAqB;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"decision-log-entry.js","sourceRoot":"","sources":["../src/decision-log-entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACvF,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE9E,MAAM,CAAC,MAAM,yBAAyB,GAAG,6BAA6B,CAAC;AAEvE,wFAAwF;AACxF,MAAM,CAAC,MAAM,uBAAuB,GAAG,mBAAmB,CAAC;AAE3D,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,wBAAwB,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAAC;AAEjD,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC;AAGzF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,YAAY,CAAC;IACnD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,yBAAyB,CAAC;IACpD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,uBAAuB,CAAC;IACxD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,QAAQ,EAAE;IAC9D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAC3C,OAAO,EAAE,qBAAqB;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC;IAC/C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,QAAQ,EAAE;IACxD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,QAAQ,EAAE;IACzF,OAAO,EAAE,CAAC;SACP,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/B,QAAQ,EAAE;SACV,MAAM,CACL,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC,MAAM,IAAI,4BAA4B,EAC7F,EAAE,OAAO,EAAE,4BAA4B,4BAA4B,+BAA+B,EAAE,CACrG;CACJ,CAAC,CAAC"}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import { type DecisionLogEntry } from "./decision-log-entry.js";
|
|
2
|
+
import { type DecisionLogDraft } from "./decision-log.js";
|
|
3
|
+
/**
|
|
4
|
+
* Transcription: one ecosystem's *in use* decision record → the canonical draft this ledger
|
|
5
|
+
* stores.
|
|
6
|
+
*
|
|
7
|
+
* WHY THIS EXISTS IN THE KERNEL AND NOT IN EITHER SHELL. Both ecosystems already keep
|
|
8
|
+
* ledgers, and they are not the same shape: the iterate loop appends
|
|
9
|
+
* `{timestamp, round, type, data}` JSONL from two independent implementations (the Python
|
|
10
|
+
* harness and the TypeScript plugin), and the plugin's history carries kinds the Python
|
|
11
|
+
* validator does not accept. If each shell writes its own log and the kernel only defines
|
|
12
|
+
* the *target* shape, nothing converges — the shared contract becomes a document rather
|
|
13
|
+
* than the file on disk. Mapping rules therefore have to have exactly one owner, and the
|
|
14
|
+
* owner has to be the side both shells already depend on. The direction stays
|
|
15
|
+
* shell → kernel: this module imports nothing from either shell and receives the legacy
|
|
16
|
+
* vocabulary as data.
|
|
17
|
+
*
|
|
18
|
+
* THE RULES, stated so a second implementation can reproduce them without reading
|
|
19
|
+
* TypeScript (and pinned by `fixtures/decision-record-transcription.ok-01.json`):
|
|
20
|
+
*
|
|
21
|
+
* 1. input is an object with exactly the keys `timestamp`, `round`, `type`, `data`;
|
|
22
|
+
* anything else (including extra keys) is refused, not dropped.
|
|
23
|
+
* 2. `type` becomes `kind` verbatim, and must match `DECISION_KIND_PATTERN`. No
|
|
24
|
+
* renaming, no case folding: a kind this module would have to rewrite is a kind it
|
|
25
|
+
* cannot compare across ecosystems.
|
|
26
|
+
* 3. `round` must be an integer >= 0 and is copied; `data` becomes `payload` in full so
|
|
27
|
+
* no recorded detail is lost, and it must stay inside `PAYLOAD_MAX_CANONICAL_LENGTH`.
|
|
28
|
+
* 4. `createdAt` is `timestamp` normalized to ISO-8601 UTC milliseconds. An unparseable
|
|
29
|
+
* timestamp is refused: a ledger entry dated "whenever" cannot be audited.
|
|
30
|
+
* 5. `outcome` is read, never inferred from tone: `data.outcome` / `data.status` when
|
|
31
|
+
* one of the four canonical values; else `data.passed === true` -> `pass`,
|
|
32
|
+
* `=== false` -> `fail`; else `inconclusive`. `inconclusive` is the honest value for
|
|
33
|
+
* "the record does not say", and it is distinguishable from a recorded verdict.
|
|
34
|
+
* 6. `summary` is the record's own sentence (`data.summary`, `data.message`,
|
|
35
|
+
* `data.reason`, in that order). When it carries none, the label
|
|
36
|
+
* `<kind> (round <round>)` is used — a label, not a claim — and if the chosen text
|
|
37
|
+
* exceeds `SUMMARY_MAX_LENGTH` the record is refused rather than truncated.
|
|
38
|
+
* 7. `dimension` is `data.dimension` when it is a kernel dimension id, otherwise absent.
|
|
39
|
+
* Falling back to the kind or the method name is the guessing this ledger exists to
|
|
40
|
+
* prevent (the same rule the fork's compaction collector applies).
|
|
41
|
+
* 8. `operationId` is `data.operationId` when it matches the `op_` id shape, else absent.
|
|
42
|
+
*/
|
|
43
|
+
export declare const DECISION_TRANSCRIBE_CODES: {
|
|
44
|
+
readonly record: "KERNEL_E_DECISION_RECORD";
|
|
45
|
+
readonly kind: "KERNEL_E_DECISION_KIND";
|
|
46
|
+
readonly round: "KERNEL_E_DECISION_ROUND";
|
|
47
|
+
readonly timestamp: "KERNEL_E_DECISION_TIMESTAMP";
|
|
48
|
+
readonly summary: "KERNEL_E_DECISION_SUMMARY";
|
|
49
|
+
readonly payload: "KERNEL_E_DECISION_PAYLOAD";
|
|
50
|
+
};
|
|
51
|
+
export type DecisionTranscribeCode = (typeof DECISION_TRANSCRIBE_CODES)[keyof typeof DECISION_TRANSCRIBE_CODES];
|
|
52
|
+
/** Every failure carries code + message + remedy, like the rest of this package. */
|
|
53
|
+
export declare class KernelDecisionTranscribeError extends Error {
|
|
54
|
+
readonly code: DecisionTranscribeCode;
|
|
55
|
+
readonly remedy: string;
|
|
56
|
+
constructor(code: DecisionTranscribeCode, message: string, remedy: string);
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Transcribe one legacy record into a ledger draft.
|
|
60
|
+
*
|
|
61
|
+
* `entryId` is supplied by the caller because it is ledger-owned: the ULID's random tail
|
|
62
|
+
* cannot be derived from the record, and a transcription function that minted ids would not
|
|
63
|
+
* be reproducible — which is the whole requirement for the Python and TypeScript sides to be
|
|
64
|
+
* compared against the same fixture.
|
|
65
|
+
*/
|
|
66
|
+
export declare function decisionLogDraftFromRecord(record: unknown, entryId: string): DecisionLogDraft;
|
|
67
|
+
/**
|
|
68
|
+
* Whether an on-disk JSONL line is a canonical entry or a legacy record — the check that lets
|
|
69
|
+
* a reader migrate a log that has both in it instead of reporting history as corrupt.
|
|
70
|
+
*
|
|
71
|
+
* A canonical entry is refused by the strict entry schema only when it is genuinely broken,
|
|
72
|
+
* so the classification is by parse success, never by guessing at field names.
|
|
73
|
+
*/
|
|
74
|
+
export declare function isLegacyDecisionRecord(line: unknown): boolean;
|
|
75
|
+
/** Re-exported so a consumer can verify a migrated chain without importing two modules. */
|
|
76
|
+
export type TranscribedDecisionLogEntry = DecisionLogEntry;
|
|
77
|
+
//# sourceMappingURL=decision-log-transcribe.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"decision-log-transcribe.d.ts","sourceRoot":"","sources":["../src/decision-log-transcribe.ts"],"names":[],"mappings":"AACA,OAAO,EAAuD,KAAK,gBAAgB,EAAwB,MAAM,yBAAyB,CAAC;AAC3I,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,eAAO,MAAM,yBAAyB;;;;;;;CAO5B,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,OAAO,yBAAyB,CAAC,CAAC;AAEhH,oFAAoF;AACpF,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM1E;AA4ED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,CA8E7F;AAGD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAM7D;AAGD,2FAA2F;AAC3F,MAAM,MAAM,2BAA2B,GAAG,gBAAgB,CAAC"}
|