@dzhechkov/harness-core 0.3.144 → 0.3.145

package/.dz-manifest.json

@@ -419,21 +419,37 @@
         "path": "dist/feature-adr-setup.js.map",
         "sha256": "dc50ce0dd4b4680afdda3e2c650d0d8665c7defce22e4afaeb24d2113c0dec9d"
       },
+      {
+        "path": "dist/guard-promotion.d.ts",
+        "sha256": "eba21256fa7ed8082acf9571c0606aa2926c0a13635fd994aa74f44d7f3db1d4"
+      },
+      {
+        "path": "dist/guard-promotion.d.ts.map",
+        "sha256": "6da389f6fbdae2b886d526db90b09ca7fabac88f26ff96e73cdfd98d1a6a90d4"
+      },
+      {
+        "path": "dist/guard-promotion.js",
+        "sha256": "a03bf0166ac3056d93c67a2571c6300cc92941424cc5a8aecce529a6879e4a47"
+      },
+      {
+        "path": "dist/guard-promotion.js.map",
+        "sha256": "858b3ad88b0c2fdf3a66a89075df493e3592cbf8c12f3df880be93a0e446ad8e"
+      },
       {
         "path": "dist/guard.d.ts",
-        "sha256": "7a1df1aa511a5d96669e660b99d29ba633393e1a20dc346e1dedfa9aec221260"
+        "sha256": "5ac5bd9b2d927117d124861c5532a0618c5f3f4859b8a91a6b62203475db047e"
       },
       {
         "path": "dist/guard.d.ts.map",
-        "sha256": "be03334a1746d3261afe69252f119c82f3718e0608957eebf5de311acf9d8a04"
+        "sha256": "f56619488145d4ccdac45298cb76647ea670d5b37d210f30972b602d3fad5f24"
       },
       {
         "path": "dist/guard.js",
-        "sha256": "dc20d0ea9ff7e1299b52ed3ce03dbd2f8bb13b1b86ee2799a49837f33ec33883"
+        "sha256": "7dc53438c377aa007264384fc30f34764fcb969fd6d0bfae15a0b976bafd0e17"
       },
       {
         "path": "dist/guard.js.map",
-        "sha256": "1696212693b8cd400ff6d2af843e2901ad0e79679ddd09ea9831306aa75e342a"
+        "sha256": "389544fa42d0010f48ae1bccdd81170053fbd56d5131c1479db87535c9a34662"
       },
       {
         "path": "dist/import-ecc.d.ts",
@@ -453,19 +469,19 @@
       },
       {
         "path": "dist/index.d.ts",
-        "sha256": "88213a2320b2b99781919788883ab99da93c4043e7c235f14d7f97db034703e0"
+        "sha256": "88d54740d8b19ff5dd759810459d8484c2fa5b428f5d2bf56fcbc431b439eb47"
       },
       {
         "path": "dist/index.d.ts.map",
-        "sha256": "e568286b5e7123dbd73a623268134af1b55555e61e90ea0271a9d4938184b6a0"
+        "sha256": "8538e8daa8b84ad85e961062b78a25ded82cbb575fd8a60d5ad1a01d3d924396"
       },
       {
         "path": "dist/index.js",
-        "sha256": "a779d72721eb025257beee64dd6e29a8e54e1dde1f152a0887d94aa2f9c3f1be"
+        "sha256": "6d90d71faff6629442c9f553be6da1e8b3b1bf29c36c04ebd28b63b24cb63e67"
       },
       {
         "path": "dist/index.js.map",
-        "sha256": "7f3cd564e49f49d2fb6a736e98ce837f987994776730ff07f04cb71c7113c22e"
+        "sha256": "a31f03dd37db8ddc701ddb181aaf46ec11259ea099924a03e91fdc2bb59ee125"
       },
       {
         "path": "dist/learning-backend.d.ts",
@@ -1045,7 +1061,7 @@
       },
       {
         "path": "package.json",
-        "sha256": "2b12d89fc52919b1963d3bd655cf21312df2306e3b7b3ff09c6812675197c58c"
+        "sha256": "97904a633c24b3de454752e7d3d5f3b0bb8904d18b64ed90787d6963a3103087"
       },
       {
         "path": "src/__tests__/golden-baseline.test.ts",
@@ -1147,9 +1163,13 @@
         "path": "src/feature-adr-setup.ts",
         "sha256": "311f4344eed1a43a0a3bd2723cafce141e035078cdcc404509cdf26ee7df4904"
       },
+      {
+        "path": "src/guard-promotion.ts",
+        "sha256": "45e05ef83ac730442760a55f9859f36b2b2a56db53465ca0267f517024646026"
+      },
       {
         "path": "src/guard.ts",
-        "sha256": "f56d5f5e59e9ddecae339b054b9f888b81b3410c56d3a09eedd7be3c11d3438c"
+        "sha256": "e7559a9f42448374ae133a323f8d9e4fa21625b15853d544e1c077ae9331a2ce"
       },
       {
         "path": "src/import-ecc.ts",
@@ -1157,7 +1177,7 @@
       },
       {
         "path": "src/index.ts",
-        "sha256": "98f3820a8d7eafeb6405e2c80b05513ddce58dfccec57612f1136cfa6abdf40e"
+        "sha256": "30f96c27c2f364d5a3aac7311167dba0f154adea3295a182f9b1cfcc28d6f3a6"
       },
       {
         "path": "src/learning-backend.ts",
@@ -1447,6 +1467,10 @@
         "path": "test/fixtures/recall-floor-probes.json",
         "sha256": "9fdfa7db72ebe6d15c604fa0d3eeeec868adb7e41f9ea0f128005fe234e1395f"
       },
+      {
+        "path": "test/guard-promotion.test.ts",
+        "sha256": "c7d38f9ba7d2a1a1d5e40b9422eeef0ffc7784b015adb41a9c8d89893f529c9e"
+      },
       {
         "path": "test/guard.test.ts",
         "sha256": "49829d24440130cfe403a410b9068a76631c68e9baa2cfc978f5029df2d72f3a"
@@ -1633,5 +1657,5 @@
       }
     ]
   },
-  "signature": "9x1Af1YN2KgiryY+uLM532g4McRyNgwN7PcuPboXSZXDIyGDh/bc/FTCx30Z5ZsqHnUBRupAB57gyI+g1VP8CA=="
+  "signature": "+MKRc3DHvGIgL2fuIvPauIW+qwbkQBjZi/EIiJf/3uUMxIlW9v+F8BdCeY3T6EBrBLko/OT9BxPo4JmURHSPDw=="
 }

package/dist/guard-promotion.d.ts

@@ -0,0 +1,364 @@
+/**
+ * `dz guard promote` — lesson → guard-rule PROMOTION with a "win twice to promote" gate.
+ *
+ * The cost-of-detection ladder says: put every check on the strongest layer that can express it.
+ * `dz compounding` MEASURED (2026-07-29) that this repo's learned store is ~82% write-only while the
+ * rules that DID reach layer 1 collapsed their own violation rate (no-workspace-star 31→0,
+ * readme-first 49→4). This module is the elevator: it moves a lesson from layer 5 (agent memory) to
+ * layer 1 (a deterministic rule) — but only when real evidence earns it.
+ *
+ * Ported from rUv's `@claude-flow/guidance` ADR-G008 (optimizer-promotion-rule, ACCEPTED) +
+ * `src/optimizer.ts` / `src/ledger.ts` (`score = frequency * cost`, promotionTracker, two
+ * consecutive wins, one loss resets). IMPROVEMENT OVER SOURCE: ADR-G008's own Negative section
+ * admits its A/B uses hard-coded SIMULATED reduction percentages. Here a "win" is a REPLAY of the
+ * candidate's check over REAL commits — the firings are real or there is no win.
+ *
+ * PURE: zero imports, zero I/O, no wall clock. Callers inject lessons, existing rules, and the
+ * change history; this module only computes. Same facts ⇒ byte-identical report.
+ *
+ * WHAT THIS DELIBERATELY IS NOT: a rule SYNTHESISER. Rule code is never generated from lesson text —
+ * that is layer-4 model judgment wearing layer-1 clothing, and its failure mode is silent. The fixed
+ * template vocabulary below is the entire executable surface (ADR-002).
+ */
+/**
+ * The v1 templates. ALL THREE are CHANGE-SHAPED: predicates over the file list of one change, which
+ * is exactly what `git log --name-only` replays and what `git status` supplies at publish time.
+ *
+ * `presence-check` (a repo-STATE predicate, e.g. "every skill dir must carry a SKILL.md") is
+ * deliberately ABSENT. Shadow-replaying a state predicate would need a tree walk at every historical
+ * commit; the cheap substitute — evaluating it against TODAY's tree once per period — returns the
+ * same answer in every window and so MANUFACTURES two consecutive wins out of one observation.
+ * A fabricated win is the one thing this gate must never produce, so presence-shaped lessons are
+ * refused by name (see `classifyLesson`).
+ */
+export type RuleTemplate = 'pairing-check' | 'absence-check' | 'format-match';
+export declare const TEMPLATES: readonly RuleTemplate[];
+export interface TemplateParams {
+    /** pairing-check: the glob whose presence in a change ARMS the rule. */
+    readonly when?: string;
+    /** pairing-check: the glob that must ALSO be in the change. */
+    readonly requires?: string;
+    /** absence-check: a change touching this glob is itself the violation. */
+    readonly forbid?: string;
+    /** format-match: the glob whose changed files must contain `mustMatch`. */
+    readonly file?: string;
+    /** format-match: a LITERAL substring (never a regex — a lesson-derived regex is unbounded risk). */
+    readonly mustMatch?: string;
+}
+/** One change under evaluation: a commit during shadow replay, or the working tree at guard time. */
+export interface ChangeSet {
+    /** commit sha, or a synthetic id for the working tree. */
+    readonly id: string;
+    readonly ts: string;
+    readonly files: readonly string[];
+    /** path → text. Only `format-match` reads it; absent ⇒ that template cannot be evaluated. */
+    readonly contents?: Readonly<Record<string, string>>;
+}
+/** Params are well-formed for their template (a hand-edited config cannot smuggle a half-rule in). */
+export declare function validTemplateParams(template: unknown, params: unknown): params is TemplateParams;
+/**
+ * `**` matches any run of characters (including `/`); `*` matches any run WITHOUT `/`. Every other
+ * character is regex-escaped, so a lesson-derived token can never become an expression. Anchored at
+ * both ends. Never throws.
+ *
+ * The leading `**​/` is OPTIONAL — `**​/package.json` matches BOTH `packages/a/package.json` and a
+ * root-level `package.json`. A naive `.*` + `/` made the segment mandatory, so every promoted rule
+ * silently missed root-level files: the shadow replay of a real 12-commit history scored 0 firings
+ * and the candidate WAITED forever, looking like an honest verdict. A false gate is only ever found
+ * by RUNNING it — the unit tests were green throughout.
+ */
+/**
+ * The most wildcard groups a glob may contain. Our own classifier emits exactly ONE (`**​/<token>`),
+ * so 2 is already generous; the cap exists because a regex built from `**a**a**a…` backtracks
+ * catastrophically (Codex QE MEASURED >10 s on such a pattern). Collapsing adjacent `.*` does NOT
+ * fix that — `.*a.*a.*a` is polynomial in the number of groups, so degree is the thing to bound.
+ * Refusal is the right answer here: these params come from a classifier we control, and a glob
+ * beyond the cap is a hand-edited config, not a promotion.
+ */
+export declare const MAX_GLOB_WILDCARDS = 2;
+/** Longest path a glob is matched against; beyond this the input is not a repo path. */
+export declare const MAX_GLOB_PATH_LENGTH = 4096;
+/** Longest glob accepted. Mirrors the length bound in {@link validTemplateParams}. */
+export declare const MAX_GLOB_LENGTH = 200;
+/** Collapse `***`/`****`/… runs to `**`, so padding cannot inflate the wildcard count. */
+export declare function normalizeGlob(glob: string): string;
+/** How many wildcard groups (`**` or `*`) a NORMALIZED glob contains. */
+export declare function globWildcardCount(glob: unknown): number;
+/** A glob this module is willing to compile: bounded length AND bounded wildcard degree. */
+export declare function isSafeGlob(glob: unknown): glob is string;
+export declare function globMatch(glob: unknown, path: unknown): boolean;
+export type FireOutcome = {
+    readonly fired: boolean;
+    readonly detail?: string;
+} | {
+    readonly undecidable: string;
+};
+/**
+ * Does this (template, params) fire on this change? ONE definition, used by BOTH the historical
+ * replay and `evaluateGuard`'s template checker — a second copy would let the promoter promise a
+ * rule the guard then enforces differently, silently.
+ *
+ * `undecidable` (not `fired:false`) when the evidence the template needs is absent: a
+ * `format-match` over a change whose contents were not fetched is NOT a clean change, and counting
+ * it as a non-firing would convert missing data into a LOSS (the INSUFFICIENT_DATA discipline).
+ */
+export declare function templateFires(template: RuleTemplate, params: TemplateParams, change: ChangeSet): FireOutcome;
+export interface ClassifiedLesson {
+    readonly template: RuleTemplate;
+    readonly params: TemplateParams;
+    readonly tokens: readonly string[];
+}
+export interface ClassifyRefusal {
+    readonly reason: string;
+}
+export declare function isClassified(x: ClassifiedLesson | ClassifyRefusal): x is ClassifiedLesson;
+/** Artifact tokens in TEXT ORDER, deduped. A token with no `/` becomes a basename glob. */
+export declare function artifactTokens(text: string): string[];
+/** `README.md` → `**​/README.md`; `packages/x/README.md` → itself. */
+export declare function tokenToGlob(token: string): string;
+/**
+ * Reduce a lesson to a (template, params) pair, or refuse WITH A REASON.
+ *
+ * Conservative by construction and asymmetric by design: a false negative costs a missed promotion
+ * (the lesson stays exactly where it already was); a false positive is caught downstream by the
+ * win-twice gate and the duplicate refusal, and even a survivor lands SOFT + advisory.
+ */
+export declare function classifyLesson(text: unknown): ClassifiedLesson | ClassifyRefusal;
+/**
+ * FNV-1a, 32-bit — a DISCRIMINATOR, not a security primitive, and labelled as one.
+ *
+ * It exists solely to keep two DIFFERENT rule bodies from claiming the same id after slug
+ * normalisation (`a.b.json` and `a-b.json` both slug to `a-b-json`). Nothing trusts it for
+ * integrity or authenticity; the key space is a few dozen self-generated rule bodies, so a
+ * non-cryptographic 32-bit mix is ample. Kept in-module because this file is deliberately pure with
+ * zero imports (NFR-1) — reaching for `node:crypto` here would buy nothing the threat model needs.
+ */
+export declare function fnv1a32(s: string): string;
+/**
+ * Stable rule id derived from the template + its bound params.
+ *
+ * The trailing hash is load-bearing (Codex QE MED-6): the slug lowercases and collapses every
+ * non-alphanumeric run, so `a.b.json` and `a-b.json` — two genuinely different rules — produced the
+ * SAME id and the second silently read as a duplicate of the first. The hash is taken over the
+ * template and the actual PARAMS (not the pre-normalisation tokens), so two rules collide only if
+ * they would enforce exactly the same thing.
+ */
+export declare function derivedRuleId(c: ClassifiedLesson): string;
+/**
+ * The character set a promoted rule id may use. Enforced wherever an id becomes part of a FILE PATH:
+ * an id is data that has round-tripped through `.dz/promotion-state.json`, and a path segment built
+ * from unvalidated data is an arbitrary-write primitive (Codex QE HIGH-1).
+ */
+export declare function isSafeRuleId(id: unknown): id is string;
+/** The one place mini-ADR paths are defined (POSIX-relative, forward slashes). */
+export declare const PROMOTIONS_REL_DIR = "features/guard-promotion/promotions";
+/**
+ * DERIVE a mini-ADR path from a validated id + an integer sequence — the only way a promotion
+ * document path is ever produced (Codex QE HIGH-1). Returns `null` when either input fails
+ * validation, so a caller that gets `null` writes nothing rather than falling back to a raw string.
+ * The character set (`isSafeRuleId`) admits no `/`, no `.`, and no `..`, so the result cannot escape
+ * {@link PROMOTIONS_REL_DIR}; callers still assert containment after resolving, because a derivation
+ * that is correct today is not a substitute for checking the thing you are about to write.
+ */
+export declare function promotionAdrRelPath(ruleId: unknown, seq: unknown): string | null;
+/**
+ * Template-equivalents of the built-in guard rules that have one. Rule ids are plain literals — this
+ * module must not import `guard.ts` (guard.ts imports THIS one).
+ *
+ * DELIBERATELY PARTIAL. `no-secrets` (content regexes), `readme-consistency` (numeric parity),
+ * `no-skill-drift` (byte comparison) and `store-bloat-cap` (a counter) have no template equivalent
+ * and are simply absent. Partiality errs in the SAFE direction only because over-refusing costs a
+ * missed promotion while under-refusing ships a duplicate rule — so when in doubt, add an entry.
+ */
+export declare const BUILTIN_COVERAGE: Readonly<Record<string, {
+    readonly template: RuleTemplate;
+    readonly params: TemplateParams;
+}>>;
+/** Order-insensitive, whitespace-insensitive params key for equality. */
+export declare function paramsKey(template: RuleTemplate, params: TemplateParams): string;
+/** A rule already present in the engine or the config, in the shape the dedup check consumes. */
+export interface ExistingRuleView {
+    readonly id: string;
+    readonly template?: RuleTemplate;
+    readonly params?: TemplateParams;
+}
+/** The id of the rule that already covers this candidate, or `null`. */
+export declare function coveringRule(c: ClassifiedLesson, existing: readonly ExistingRuleView[]): string | null;
+export declare const DEFAULT_WINDOW_DAYS = 7;
+export declare const DEFAULT_PERIODS = 4;
+/** Below this many changes a window carries no information — it is SKIPPED, never counted a loss. */
+export declare const MIN_CHANGES_PER_PERIOD = 5;
+export declare const WINS_TO_PROMOTE = 2;
+/** Cap on `git show` fetches per run; over it, a format-match candidate is insufficient-data. */
+export declare const MAX_CONTENT_FETCHES = 200;
+export interface Period {
+    readonly start: string;
+    readonly end: string;
+    readonly changes: readonly ChangeSet[];
+}
+/**
+ * Cut history into `periods` consecutive `windowDays` windows anchored at `nowMs`, walking BACKWARDS
+ * and returned oldest→newest. Wall-clock windows, NOT per-invocation and NOT per-commit-count: an
+ * operator's invocation frequency must never be an input to a safety gate (ADR-003 option A).
+ */
+export declare function buildPeriods(changes: readonly ChangeSet[], nowMs: number, windowDays?: number, periods?: number): Period[];
+export type PeriodOutcome = 'win' | 'loss' | 'skipped';
+export interface PeriodResult {
+    readonly start: string;
+    readonly end: string;
+    readonly changes: number;
+    readonly firings: number;
+    readonly outcome: PeriodOutcome;
+    /** first firing's evidence — a real commit id, so a win is always citable. */
+    readonly evidence?: string;
+}
+export interface CandidateEvaluation {
+    readonly periods: readonly PeriodResult[];
+    readonly evaluatedPeriods: number;
+    /** consecutive wins ENDING at the newest evaluated period. A loss resets to 0. */
+    readonly wins: number;
+    readonly totalFirings: number;
+    /** set when a template could not be decided over the available evidence. */
+    readonly undecidable?: string;
+}
+/**
+ * Replay the candidate over each period.
+ *
+ * A period below {@link MIN_CHANGES_PER_PERIOD} is SKIPPED — a one-commit week that happens not to
+ * touch package.json is NOT evidence the pairing rule is worthless, it is NO evidence, and absence
+ * of data must never be converted into a negative observation.
+ */
+export declare function evaluateCandidate(c: ClassifiedLesson, periods: readonly Period[], minChanges?: number): CandidateEvaluation;
+export type CandidateVerdict = 'promote' | 'wait' | 'insufficient-data' | 'duplicate' | 'not-promotable';
+export interface LessonInput {
+    readonly dzId: string;
+    readonly text: string;
+    readonly quarantined: boolean;
+    /** reinforcement/use count — the `cost` PROXY (see `score`). */
+    readonly uses: number;
+}
+export interface PromotionCandidate {
+    readonly lessonId: string;
+    readonly lessonText: string;
+    readonly ruleId: string | null;
+    readonly template: RuleTemplate | null;
+    readonly params: TemplateParams | null;
+    readonly verdict: CandidateVerdict;
+    readonly reason: string;
+    /** `totalFirings × (1 + uses)`. `cost` is an explicitly named PROXY, not a token/dollar figure. */
+    readonly score: number;
+    readonly firings: number;
+    readonly cost: number;
+    readonly wins: number;
+    readonly evaluatedPeriods: number;
+    readonly periods: readonly PeriodResult[];
+    /** the exact `.dz/guard.json` entry `--apply` would write (only for `promote`). */
+    readonly proposedRule: PromotedRule | null;
+    /** LOCAL-clock first observation (see {@link ELAPSED_WINDOWS_REQUIRED}); null until recorded. */
+    readonly firstSeenTs: string | null;
+    /** real elapsed ms since `firstSeenTs`, and the amount required, both for the report. */
+    readonly elapsedMs: number;
+    readonly elapsedRequiredMs: number;
+}
+export interface PromotionFacts {
+    readonly lessons: readonly LessonInput[];
+    readonly existingRules: readonly ExistingRuleView[];
+    readonly changes: readonly ChangeSet[];
+    readonly nowTs: string;
+    readonly windowDays?: number;
+    readonly periods?: number;
+    /**
+     * ruleId → the LOCAL-CLOCK timestamp at which this candidate was first recorded in
+     * `.dz/promotion-state.json`. See {@link ELAPSED_WINDOWS_REQUIRED}. Absent ⇒ first observation
+     * ⇒ the elapsed clock starts now, so nothing promotes on the very first recording run.
+     */
+    readonly firstSeen?: Readonly<Record<string, string>>;
+}
+/**
+ * A promotion also needs this many WINDOW-LENGTHS of REAL elapsed time since the candidate was first
+ * recorded — a defence Codex QE (MED-7) showed the window logic alone does not provide.
+ *
+ * The threat is not an attacker; it is ACCIDENTAL SELF-GAMING. Commit timestamps are author-supplied
+ * (`GIT_COMMITTER_DATE`, a rebase, an import, a clock skew), so a repo whose history is minted in one
+ * afternoon can present two full "windows" instantly, and the gate that is supposed to mean *"this
+ * recurred over two separate stretches of work"* would mean nothing.
+ *
+ * THE HONEST SPLIT, stated so it is not mistaken for more than it is:
+ *   • committer dates are trusted for firing ATTRIBUTION — which commit a violation belongs to;
+ *   • the LOCAL clock, journalled in state, gates ELAPSED time — how long we have been watching.
+ * This is not cryptographic and does not resist a determined forger (state is a local JSON file you
+ * can edit). It resists the realistic failure: history that only LOOKS like it spans two windows.
+ */
+export declare const ELAPSED_WINDOWS_REQUIRED = 2;
+export interface PromotionReport {
+    readonly candidates: readonly PromotionCandidate[];
+    readonly totalLessons: number;
+    readonly quarantinedSkipped: number;
+    readonly windowDays: number;
+    readonly periodCount: number;
+    readonly totalChanges: number;
+    readonly verdict: string;
+}
+/** The rule object written into `.dz/guard.json`. SOFT always — see ADR-004 / `resolveRules`. */
+export interface PromotedRule {
+    readonly id: string;
+    readonly severity: 'soft';
+    readonly ops: readonly string[];
+    readonly enabled: true;
+    readonly template: RuleTemplate;
+    readonly params: TemplateParams;
+    readonly description: string;
+}
+export declare function promotedRuleObject(c: ClassifiedLesson, ruleId: string, lessonId: string): PromotedRule;
+/**
+ * Rank every lesson and decide. Deterministic: the sort is (score desc, ruleId asc, lessonId asc), so
+ * ties never reorder between runs.
+ */
+export declare function assembleCandidates(facts: PromotionFacts): PromotionReport;
+export interface PromotionStateEntry {
+    readonly ruleId: string;
+    readonly lessonId: string;
+    readonly firstSeenTs: string;
+    readonly lastRunTs: string;
+    readonly wins: number;
+    readonly evaluatedPeriods: number;
+    readonly verdict: CandidateVerdict;
+    /**
+     * The mini-ADR's SEQUENCE NUMBER — never its path. The path is DERIVED from this integer and the
+     * validated rule id at write time (Codex QE HIGH-1): a path read back out of state and handed to
+     * `writeFileSync` is an arbitrary-write primitive, and a corrupted entry
+     * (`"adr": "../../victim"` or `".dz/guard.json"`) would overwrite files with no `--apply` at all.
+     */
+    readonly adrSeq?: number;
+    readonly appliedTs?: string;
+}
+export interface PromotionState {
+    readonly version: 1;
+    readonly nextAdrSeq: number;
+    readonly entries: Readonly<Record<string, PromotionStateEntry>>;
+}
+export declare const EMPTY_PROMOTION_STATE: PromotionState;
+/**
+ * Read state defensively. `Object.hasOwn` (never `in`) so a prototype-polluted JSON cannot conjure an
+ * entry; `Number.isInteger` on every counter because `1e400` parses to `Infinity`, passes `> 0`, and
+ * this repo has already been bitten by exactly that twice (storeCap, auto-cost).
+ */
+export declare function normalizePromotionState(raw: unknown): PromotionState;
+/**
+ * Fold a report into the state journal.
+ *
+ * THE ANTI-GAMING PROPERTY (SP-3): `wins` is OVERWRITTEN with the freshly recomputed value — it is
+ * never `prev.wins + …`. The state is a JOURNAL, not the source of truth, so running the promoter
+ * ten times over unchanged history leaves the counter exactly where one run leaves it. (Recalled
+ * lesson: "a learning loop's write path can promote by EXPOSURE without anyone noticing.")
+ */
+export declare function nextPromotionState(prev: PromotionState, report: PromotionReport, nowTs: string, adrSeqs?: Readonly<Record<string, number>>, newlyAllocated?: number): PromotionState;
+export declare function renderPromotionReport(r: PromotionReport, limit?: number): string;
+/**
+ * The mini-ADR for one decision. Written for PROMOTIONS and REJECTIONS alike (ADR-G008 requires
+ * both) — a refusal is a decision about the harness's own capability, and it is what turns the
+ * "not promotable" list into a roadmap instead of a shrug. `wait` / `insufficient-data` get NO
+ * document: they are not decisions yet, and one per run would bury the real ones.
+ */
+export declare function renderPromotionAdr(c: PromotionCandidate, seq: number, nowTs: string): string;
+//# sourceMappingURL=guard-promotion.d.ts.map

package/dist/guard-promotion.d.ts.map

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