iterate-kernel 0.1.0-draft.1

package/dist/dimension-context.d.ts

@@ -0,0 +1,402 @@
+import { z } from "zod";
+/**
+ * Dimension context: what a run *said* it would review, set against what it
+ * actually recorded.
+ *
+ * WHY THIS LIVES IN THE KERNEL. The two shells keep losing the same
+ * information in the same two places — a compaction summary that keeps the
+ * story and drops which dimensions were covered, and a run report that lists
+ * findings without saying which planned dimension had *none*. Both are
+ * arithmetic over two lists the caller already holds. Doing it here means both
+ * shells report the same numbers for the same run, and it is checkable against
+ * a fixture instead of argued about in review.
+ *
+ * WHY THERE IS NO LIST OF DIMENSIONS IN HERE. The dimension ids are a
+ * *vocabulary*, and the vocabulary is owned by the iterate config
+ * (`config/config.schema.json` `$defs.dimension.enum`, kept in lockstep with
+ * `config/dimensions.yaml` and the wizard constants by
+ * `tests/test_dimension_lock.py` across six sources). A hard-coded copy in this
+ * package would be a seventh source that CI does not compare against the other
+ * six — the exact failure that lock exists to prevent. So the caller passes the
+ * ids it was configured with, and this module only does the accounting. A
+ * dimension the engine adds tomorrow works here without a kernel release; a
+ * dimension that is *not* in the caller's list is reported as unplanned, not
+ * silently accepted.
+ *
+ * WHAT THIS REFUSES TO DO. It never infers coverage. Coverage is a count of
+ * recorded decisions against a planned dimension, and a dimension with no
+ * decisions is `unverified` — never "probably fine", never dropped. Ordering is
+ * the caller's planned order, and unplanned ids follow sorted, so the same
+ * inputs produce the same bytes in any language.
+ */
+/** Ids are kebab-case, non-empty, and bounded — validated, never enumerated. */
+export declare const DIMENSION_ID_PATTERN: RegExp;
+export declare const DIMENSION_ID_MAX_LENGTH = 64;
+export declare const DIMENSION_LABEL_MAX_LENGTH = 256;
+/** A `focus` blob is prose copied from config; bounded so it cannot become a payload. */
+export declare const DIMENSION_FOCUS_MAX_LENGTH = 4096;
+export declare const DIMENSION_MIN_PLANNED = 1;
+export declare const DIMENSION_MAX_PLANNED = 64;
+/**
+ * One dimension the run declared it would review, as configured. `id` is the
+ * vocabulary key; `label` and `focus` are the human-facing text from the same
+ * config entry, carried through so a report can name the dimension without
+ * re-reading the config.
+ */
+export declare const PlannedDimensionSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    label?: string | undefined;
+    focus?: string | undefined;
+}, {
+    id: string;
+    label?: string | undefined;
+    focus?: string | undefined;
+}>;
+export type PlannedDimension = z.infer<typeof PlannedDimensionSchema>;
+/**
+ * What the engine recorded for one dimension. `decisions` is a count of ledger
+ * entries, not a list: the point of this structure is to survive compaction,
+ * and a list of hashes would be the thing compaction drops. `operationIds` is
+ * the optional back-pointer to the evidence, capped small for the same reason.
+ */
+export declare const DIMENSION_MAX_OPERATION_IDS = 32;
+export declare const DimensionEvidenceSchema: z.ZodObject<{
+    decisions: z.ZodNumber;
+    operationIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    decisions: number;
+    operationIds?: string[] | undefined;
+}, {
+    decisions: number;
+    operationIds?: string[] | undefined;
+}>;
+export type DimensionEvidence = z.infer<typeof DimensionEvidenceSchema>;
+/**
+ * A dimension's state, and the only three words this module will use:
+ *
+ *   - `verified`   — planned, and the engine recorded at least one decision
+ *   - `unverified` — planned, and the engine recorded none
+ *   - `unplanned`  — recorded, but the run never declared it
+ *
+ * There is no `skipped` and no `passed`. Those are judgements about *why* a
+ * dimension is empty, and the engine is the only thing entitled to make one;
+ * a reporter that guesses is how "we reviewed correctness" ends up in a summary
+ * when nothing was checked.
+ */
+export declare const DimensionStatusSchema: z.ZodEnum<["verified", "unverified", "unplanned"]>;
+export type DimensionStatus = z.infer<typeof DimensionStatusSchema>;
+export declare const DimensionContextEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<["verified", "unverified", "unplanned"]>;
+    label: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodString>;
+    evidence: z.ZodObject<{
+        decisions: z.ZodNumber;
+        operationIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        decisions: number;
+        operationIds?: string[] | undefined;
+    }, {
+        decisions: number;
+        operationIds?: string[] | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    status: "verified" | "unverified" | "unplanned";
+    evidence: {
+        decisions: number;
+        operationIds?: string[] | undefined;
+    };
+    id: string;
+    label?: string | undefined;
+    focus?: string | undefined;
+}, {
+    status: "verified" | "unverified" | "unplanned";
+    evidence: {
+        decisions: number;
+        operationIds?: string[] | undefined;
+    };
+    id: string;
+    label?: string | undefined;
+    focus?: string | undefined;
+}>;
+export type DimensionContextEntry = z.infer<typeof DimensionContextEntrySchema>;
+/**
+ * The per-dimension summary plus the counts a caller asserts out loud. The
+ * totals are stored rather than recomputed by every consumer so that a
+ * consumer that reports `verified: 3` and one that iterates the entries cannot
+ * disagree — a disagreement there is a bug in one of them, and this is where it
+ * becomes visible.
+ */
+export declare const DimensionContextTotalsSchema: z.ZodObject<{
+    planned: z.ZodNumber;
+    verified: z.ZodNumber;
+    unverified: z.ZodNumber;
+    unplanned: z.ZodNumber;
+    decisions: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    decisions: number;
+    verified: number;
+    unverified: number;
+    unplanned: number;
+    planned: number;
+}, {
+    decisions: number;
+    verified: number;
+    unverified: number;
+    unplanned: number;
+    planned: number;
+}>;
+export type DimensionContextTotals = z.infer<typeof DimensionContextTotalsSchema>;
+export declare const DimensionContextSchema: z.ZodObject<{
+    planned: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<["verified", "unverified", "unplanned"]>;
+        label: z.ZodOptional<z.ZodString>;
+        focus: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodObject<{
+            decisions: z.ZodNumber;
+            operationIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            decisions: number;
+            operationIds?: string[] | undefined;
+        }, {
+            decisions: number;
+            operationIds?: string[] | undefined;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        status: "verified" | "unverified" | "unplanned";
+        evidence: {
+            decisions: number;
+            operationIds?: string[] | undefined;
+        };
+        id: string;
+        label?: string | undefined;
+        focus?: string | undefined;
+    }, {
+        status: "verified" | "unverified" | "unplanned";
+        evidence: {
+            decisions: number;
+            operationIds?: string[] | undefined;
+        };
+        id: string;
+        label?: string | undefined;
+        focus?: string | undefined;
+    }>, "many">;
+    unplanned: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<["verified", "unverified", "unplanned"]>;
+        label: z.ZodOptional<z.ZodString>;
+        focus: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodObject<{
+            decisions: z.ZodNumber;
+            operationIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            decisions: number;
+            operationIds?: string[] | undefined;
+        }, {
+            decisions: number;
+            operationIds?: string[] | undefined;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        status: "verified" | "unverified" | "unplanned";
+        evidence: {
+            decisions: number;
+            operationIds?: string[] | undefined;
+        };
+        id: string;
+        label?: string | undefined;
+        focus?: string | undefined;
+    }, {
+        status: "verified" | "unverified" | "unplanned";
+        evidence: {
+            decisions: number;
+            operationIds?: string[] | undefined;
+        };
+        id: string;
+        label?: string | undefined;
+        focus?: string | undefined;
+    }>, "many">;
+    totals: z.ZodObject<{
+        planned: z.ZodNumber;
+        verified: z.ZodNumber;
+        unverified: z.ZodNumber;
+        unplanned: z.ZodNumber;
+        decisions: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        decisions: number;
+        verified: number;
+        unverified: number;
+        unplanned: number;
+        planned: number;
+    }, {
+        decisions: number;
+        verified: number;
+        unverified: number;
+        unplanned: number;
+        planned: number;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    unplanned: {
+        status: "verified" | "unverified" | "unplanned";
+        evidence: {
+            decisions: number;
+            operationIds?: string[] | undefined;
+        };
+        id: string;
+        label?: string | undefined;
+        focus?: string | undefined;
+    }[];
+    planned: {
+        status: "verified" | "unverified" | "unplanned";
+        evidence: {
+            decisions: number;
+            operationIds?: string[] | undefined;
+        };
+        id: string;
+        label?: string | undefined;
+        focus?: string | undefined;
+    }[];
+    totals: {
+        decisions: number;
+        verified: number;
+        unverified: number;
+        unplanned: number;
+        planned: number;
+    };
+}, {
+    unplanned: {
+        status: "verified" | "unverified" | "unplanned";
+        evidence: {
+            decisions: number;
+            operationIds?: string[] | undefined;
+        };
+        id: string;
+        label?: string | undefined;
+        focus?: string | undefined;
+    }[];
+    planned: {
+        status: "verified" | "unverified" | "unplanned";
+        evidence: {
+            decisions: number;
+            operationIds?: string[] | undefined;
+        };
+        id: string;
+        label?: string | undefined;
+        focus?: string | undefined;
+    }[];
+    totals: {
+        decisions: number;
+        verified: number;
+        unverified: number;
+        unplanned: number;
+        planned: number;
+    };
+}>;
+export type DimensionContext = z.infer<typeof DimensionContextSchema>;
+/** What a caller supplies: the plan, plus what the engine recorded per id. */
+export declare const DimensionContextInputSchema: z.ZodObject<{
+    planned: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        focus: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        label?: string | undefined;
+        focus?: string | undefined;
+    }, {
+        id: string;
+        label?: string | undefined;
+        focus?: string | undefined;
+    }>, "many">;
+    recorded: z.ZodRecord<z.ZodString, z.ZodObject<{
+        decisions: z.ZodNumber;
+        operationIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        decisions: number;
+        operationIds?: string[] | undefined;
+    }, {
+        decisions: number;
+        operationIds?: string[] | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    planned: {
+        id: string;
+        label?: string | undefined;
+        focus?: string | undefined;
+    }[];
+    recorded: Record<string, {
+        decisions: number;
+        operationIds?: string[] | undefined;
+    }>;
+}, {
+    planned: {
+        id: string;
+        label?: string | undefined;
+        focus?: string | undefined;
+    }[];
+    recorded: Record<string, {
+        decisions: number;
+        operationIds?: string[] | undefined;
+    }>;
+}>;
+export type DimensionContextInput = z.infer<typeof DimensionContextInputSchema>;
+export declare const DIMENSION_CONTEXT_CODES: {
+    readonly duplicate: "KERNEL_E_DIMENSION_DUPLICATE";
+    readonly empty: "KERNEL_E_DIMENSION_EMPTY";
+};
+export type KernelDimensionCode = (typeof DIMENSION_CONTEXT_CODES)[keyof typeof DIMENSION_CONTEXT_CODES];
+/**
+ * Every failure carries `code` + `message` + `remedy`, matching
+ * `KernelDecisionLogError`: whoever catches this must be able to act on it
+ * without reading this file.
+ */
+export declare class KernelDimensionError extends Error {
+    readonly code: KernelDimensionCode;
+    readonly dimension?: string;
+    readonly remedy: string;
+    constructor(code: KernelDimensionCode, message: string, remedy: string, dimension?: string);
+}
+/**
+ * Build the dimension context.
+ *
+ * The rules, stated so a second implementation can be written against this
+ * paragraph rather than against the TypeScript:
+ *
+ *   1. `planned` entries appear in `context.planned` in the caller's order.
+ *      Their status is `verified` when `recorded[id].decisions >= 1`, else
+ *      `unverified`. `evidence` is the recorded value verbatim, defaulting to
+ *      `{ decisions: 0 }` when the id is absent — an absent id and a recorded
+ *      zero are the same fact, and both mean `unverified`.
+ *   2. An id present in `recorded` but not in `planned` becomes one `unplanned`
+ *      entry, status `unplanned`, sorted by id ascending (UTF-16 code unit
+ *      order, the same rule `canonicalJson` uses). This is the case that must
+ *      not be dropped: the engine checked something the run never declared.
+ *   3. `totals.decisions` is the sum over planned entries **plus** unplanned
+ *      ones — every recorded decision, counted once. `totals.planned` is the
+ *      length of the planned list, so `verified + unverified === planned`
+ *      always holds and a caller can assert it.
+ *   4. A duplicate id in `planned` throws. Silently keeping the last one would
+ *      make the planned count disagree with the list a caller printed, which is
+ *      the class of quiet drift this whole structure exists to catch.
+ */
+export declare function dimensionContext(input: DimensionContextInput): DimensionContext;
+/**
+ * The one-line form a compaction summary or a report header can carry: it
+ * states coverage as counts, so the reader learns what was *not* checked
+ * without the reporter having to characterise it.
+ *
+ * `3/5 dimensions verified, 2 unverified (security, ui-ux), 1 unplanned (tech-debt), 12 decisions`
+ *
+ * The unverified ids are named because a bare "2 unverified" is a number
+ * nobody can act on; the unplanned ones are named because an undeclared
+ * dimension is a finding about the plan, not about the code. A run with nothing
+ * verified still produces a sentence — `0/5 dimensions verified, 5 unverified
+ * (…), 0 decisions` is a legitimate and useful line, which is why this never
+ * collapses to an empty string.
+ */
+export declare function formatDimensionContext(context: DimensionContext): string;
+//# sourceMappingURL=dimension-context.d.ts.map

package/dist/dimension-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dimension-context.d.ts","sourceRoot":"","sources":["../src/dimension-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,QAA+B,CAAC;AACjE,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAC9C,yFAAyF;AACzF,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,eAAO,MAAM,qBAAqB,IAAI,CAAC;AACvC,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;EAIjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,eAAO,MAAM,uBAAuB;;;;;;;;;EAGlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAGxE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,oDAAkD,CAAC;AACrF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;EAMvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAIjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,8EAA8E;AAC9E,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,uBAAuB;;;CAG1B,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,OAAO,uBAAuB,CAAC,CAAC;AAEzG;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAO3F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,gBAAgB,CA4D/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAexE"}

package/dist/dimension-context.js

@@ -0,0 +1,226 @@
+import { z } from "zod";
+/**
+ * Dimension context: what a run *said* it would review, set against what it
+ * actually recorded.
+ *
+ * WHY THIS LIVES IN THE KERNEL. The two shells keep losing the same
+ * information in the same two places — a compaction summary that keeps the
+ * story and drops which dimensions were covered, and a run report that lists
+ * findings without saying which planned dimension had *none*. Both are
+ * arithmetic over two lists the caller already holds. Doing it here means both
+ * shells report the same numbers for the same run, and it is checkable against
+ * a fixture instead of argued about in review.
+ *
+ * WHY THERE IS NO LIST OF DIMENSIONS IN HERE. The dimension ids are a
+ * *vocabulary*, and the vocabulary is owned by the iterate config
+ * (`config/config.schema.json` `$defs.dimension.enum`, kept in lockstep with
+ * `config/dimensions.yaml` and the wizard constants by
+ * `tests/test_dimension_lock.py` across six sources). A hard-coded copy in this
+ * package would be a seventh source that CI does not compare against the other
+ * six — the exact failure that lock exists to prevent. So the caller passes the
+ * ids it was configured with, and this module only does the accounting. A
+ * dimension the engine adds tomorrow works here without a kernel release; a
+ * dimension that is *not* in the caller's list is reported as unplanned, not
+ * silently accepted.
+ *
+ * WHAT THIS REFUSES TO DO. It never infers coverage. Coverage is a count of
+ * recorded decisions against a planned dimension, and a dimension with no
+ * decisions is `unverified` — never "probably fine", never dropped. Ordering is
+ * the caller's planned order, and unplanned ids follow sorted, so the same
+ * inputs produce the same bytes in any language.
+ */
+/** Ids are kebab-case, non-empty, and bounded — validated, never enumerated. */
+export const DIMENSION_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const DIMENSION_ID_MAX_LENGTH = 64;
+export const DIMENSION_LABEL_MAX_LENGTH = 256;
+/** A `focus` blob is prose copied from config; bounded so it cannot become a payload. */
+export const DIMENSION_FOCUS_MAX_LENGTH = 4096;
+export const DIMENSION_MIN_PLANNED = 1;
+export const DIMENSION_MAX_PLANNED = 64;
+/**
+ * One dimension the run declared it would review, as configured. `id` is the
+ * vocabulary key; `label` and `focus` are the human-facing text from the same
+ * config entry, carried through so a report can name the dimension without
+ * re-reading the config.
+ */
+export const PlannedDimensionSchema = z.strictObject({
+    id: z.string().regex(DIMENSION_ID_PATTERN).max(DIMENSION_ID_MAX_LENGTH),
+    label: z.string().min(1).max(DIMENSION_LABEL_MAX_LENGTH).optional(),
+    focus: z.string().max(DIMENSION_FOCUS_MAX_LENGTH).optional()
+});
+/**
+ * What the engine recorded for one dimension. `decisions` is a count of ledger
+ * entries, not a list: the point of this structure is to survive compaction,
+ * and a list of hashes would be the thing compaction drops. `operationIds` is
+ * the optional back-pointer to the evidence, capped small for the same reason.
+ */
+export const DIMENSION_MAX_OPERATION_IDS = 32;
+export const DimensionEvidenceSchema = z.strictObject({
+    decisions: z.number().int().min(0),
+    operationIds: z.array(z.string().min(1)).max(DIMENSION_MAX_OPERATION_IDS).optional()
+});
+/**
+ * A dimension's state, and the only three words this module will use:
+ *
+ *   - `verified`   — planned, and the engine recorded at least one decision
+ *   - `unverified` — planned, and the engine recorded none
+ *   - `unplanned`  — recorded, but the run never declared it
+ *
+ * There is no `skipped` and no `passed`. Those are judgements about *why* a
+ * dimension is empty, and the engine is the only thing entitled to make one;
+ * a reporter that guesses is how "we reviewed correctness" ends up in a summary
+ * when nothing was checked.
+ */
+export const DimensionStatusSchema = z.enum(["verified", "unverified", "unplanned"]);
+export const DimensionContextEntrySchema = z.strictObject({
+    id: z.string().regex(DIMENSION_ID_PATTERN).max(DIMENSION_ID_MAX_LENGTH),
+    status: DimensionStatusSchema,
+    label: z.string().min(1).max(DIMENSION_LABEL_MAX_LENGTH).optional(),
+    focus: z.string().max(DIMENSION_FOCUS_MAX_LENGTH).optional(),
+    evidence: DimensionEvidenceSchema
+});
+/**
+ * The per-dimension summary plus the counts a caller asserts out loud. The
+ * totals are stored rather than recomputed by every consumer so that a
+ * consumer that reports `verified: 3` and one that iterates the entries cannot
+ * disagree — a disagreement there is a bug in one of them, and this is where it
+ * becomes visible.
+ */
+export const DimensionContextTotalsSchema = z.strictObject({
+    planned: z.number().int().min(0),
+    verified: z.number().int().min(0),
+    unverified: z.number().int().min(0),
+    unplanned: z.number().int().min(0),
+    decisions: z.number().int().min(0)
+});
+export const DimensionContextSchema = z.strictObject({
+    planned: z.array(DimensionContextEntrySchema),
+    unplanned: z.array(DimensionContextEntrySchema),
+    totals: DimensionContextTotalsSchema
+});
+/** What a caller supplies: the plan, plus what the engine recorded per id. */
+export const DimensionContextInputSchema = z.strictObject({
+    planned: z.array(PlannedDimensionSchema).min(DIMENSION_MIN_PLANNED).max(DIMENSION_MAX_PLANNED),
+    recorded: z.record(z.string().regex(DIMENSION_ID_PATTERN).max(DIMENSION_ID_MAX_LENGTH), DimensionEvidenceSchema)
+});
+export const DIMENSION_CONTEXT_CODES = {
+    duplicate: "KERNEL_E_DIMENSION_DUPLICATE",
+    empty: "KERNEL_E_DIMENSION_EMPTY"
+};
+/**
+ * Every failure carries `code` + `message` + `remedy`, matching
+ * `KernelDecisionLogError`: whoever catches this must be able to act on it
+ * without reading this file.
+ */
+export class KernelDimensionError extends Error {
+    code;
+    dimension;
+    remedy;
+    constructor(code, message, remedy, dimension) {
+        super(`${code}: ${message}`);
+        this.name = "KernelDimensionError";
+        this.code = code;
+        this.remedy = remedy;
+        if (dimension !== undefined)
+            this.dimension = dimension;
+    }
+}
+/**
+ * Build the dimension context.
+ *
+ * The rules, stated so a second implementation can be written against this
+ * paragraph rather than against the TypeScript:
+ *
+ *   1. `planned` entries appear in `context.planned` in the caller's order.
+ *      Their status is `verified` when `recorded[id].decisions >= 1`, else
+ *      `unverified`. `evidence` is the recorded value verbatim, defaulting to
+ *      `{ decisions: 0 }` when the id is absent — an absent id and a recorded
+ *      zero are the same fact, and both mean `unverified`.
+ *   2. An id present in `recorded` but not in `planned` becomes one `unplanned`
+ *      entry, status `unplanned`, sorted by id ascending (UTF-16 code unit
+ *      order, the same rule `canonicalJson` uses). This is the case that must
+ *      not be dropped: the engine checked something the run never declared.
+ *   3. `totals.decisions` is the sum over planned entries **plus** unplanned
+ *      ones — every recorded decision, counted once. `totals.planned` is the
+ *      length of the planned list, so `verified + unverified === planned`
+ *      always holds and a caller can assert it.
+ *   4. A duplicate id in `planned` throws. Silently keeping the last one would
+ *      make the planned count disagree with the list a caller printed, which is
+ *      the class of quiet drift this whole structure exists to catch.
+ */
+export function dimensionContext(input) {
+    const seen = new Set();
+    for (const dimension of input.planned) {
+        if (seen.has(dimension.id)) {
+            throw new KernelDimensionError(DIMENSION_CONTEXT_CODES.duplicate, `dimension ${JSON.stringify(dimension.id)} is planned more than once`, "give each planned dimension exactly one entry; the totals are computed from this list", dimension.id);
+        }
+        seen.add(dimension.id);
+    }
+    const plannedEntries = input.planned.map((dimension) => {
+        const evidence = input.recorded[dimension.id] ?? { decisions: 0 };
+        return {
+            id: dimension.id,
+            status: evidence.decisions >= 1 ? "verified" : "unverified",
+            ...(dimension.label !== undefined ? { label: dimension.label } : {}),
+            ...(dimension.focus !== undefined ? { focus: dimension.focus } : {}),
+            evidence
+        };
+    });
+    const unplannedIds = Object.keys(input.recorded)
+        .filter((id) => !seen.has(id))
+        .sort();
+    const unplannedEntries = unplannedIds.map((id) => {
+        const evidence = input.recorded[id];
+        if (evidence === undefined) {
+            // Unreachable while `recorded`'s values are validated, but the alternative
+            // is a non-null assertion on a value this function then hands to a
+            // consumer as fact.
+            throw new KernelDimensionError(DIMENSION_CONTEXT_CODES.empty, `recorded dimension ${JSON.stringify(id)} has no evidence`, "every key in `recorded` must carry an evidence object");
+        }
+        return { id, status: "unplanned", evidence };
+    });
+    const verified = plannedEntries.filter((entry) => entry.status === "verified").length;
+    const decisions = [...plannedEntries, ...unplannedEntries].reduce((total, entry) => total + entry.evidence.decisions, 0);
+    return {
+        planned: plannedEntries,
+        unplanned: unplannedEntries,
+        totals: {
+            planned: plannedEntries.length,
+            verified,
+            unverified: plannedEntries.length - verified,
+            unplanned: unplannedEntries.length,
+            decisions
+        }
+    };
+}
+/**
+ * The one-line form a compaction summary or a report header can carry: it
+ * states coverage as counts, so the reader learns what was *not* checked
+ * without the reporter having to characterise it.
+ *
+ * `3/5 dimensions verified, 2 unverified (security, ui-ux), 1 unplanned (tech-debt), 12 decisions`
+ *
+ * The unverified ids are named because a bare "2 unverified" is a number
+ * nobody can act on; the unplanned ones are named because an undeclared
+ * dimension is a finding about the plan, not about the code. A run with nothing
+ * verified still produces a sentence — `0/5 dimensions verified, 5 unverified
+ * (…), 0 decisions` is a legitimate and useful line, which is why this never
+ * collapses to an empty string.
+ */
+export function formatDimensionContext(context) {
+    const { totals } = context;
+    const parts = [`${totals.verified}/${totals.planned} dimensions verified`];
+    if (totals.unverified > 0) {
+        const ids = context.planned
+            .filter((entry) => entry.status === "unverified")
+            .map((entry) => entry.id);
+        parts.push(`${totals.unverified} unverified (${ids.join(", ")})`);
+    }
+    if (totals.unplanned > 0) {
+        const ids = context.unplanned.map((entry) => entry.id);
+        parts.push(`${totals.unplanned} unplanned (${ids.join(", ")})`);
+    }
+    parts.push(`${totals.decisions} ${totals.decisions === 1 ? "decision" : "decisions"}`);
+    return parts.join(", ");
+}
+//# sourceMappingURL=dimension-context.js.map

package/dist/dimension-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dimension-context.js","sourceRoot":"","sources":["../src/dimension-context.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+export interface KernelSchemaIssue {
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * Thrown by every parse* function in this package when the input does not
+ * conform to the schema. `code` is stable and machine-readable; `issues`
+ * carries one entry per violation with a JSON-path-like location.
+ */
+export declare class KernelSchemaError extends Error {
+    readonly code = "KERNEL_E_SCHEMA";
+    readonly issues: readonly KernelSchemaIssue[];
+    constructor(label: string, issues: readonly KernelSchemaIssue[]);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,qBAAqB;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;gBAElC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,iBAAiB,EAAE;CAQhE"}