@cat-factory/contracts 0.166.0 → 0.168.0

package/dist/mergeTrackRecord.d.ts

@@ -0,0 +1,183 @@
+import * as v from 'valibot';
+/**
+ * What kind of change a run's pull request made, derived DETERMINISTICALLY on the backend
+ * from the PR's changed-file list (never from an agent's opinion). A small closed set so it
+ * can key a per-class merge rule, a rollup `GROUP BY`, and an i18n label.
+ *
+ *  - `docs`       — documentation + user-facing copy (Markdown, `docs/`, i18n catalogs).
+ *  - `test`       — test/spec/fixture files only.
+ *  - `dependency` — dependency manifests + lockfiles (a bump).
+ *  - `config`     — CI workflows, tooling config, container/IaC manifests.
+ *  - `source`     — application/library source code (the catch-all for real code).
+ *  - `schema`     — database migrations + schema definitions (the riskiest: irreversible).
+ *  - `unknown`    — no changed-file list was available (no VCS client wired, or an empty diff).
+ *
+ * A MIXED diff resolves to the HIGHEST-RANKED class present (see `CHANGE_CLASS_RANK` /
+ * `classifyChangedFiles` in `@cat-factory/kernel`), so a per-class rule can only ever fire on a
+ * diff containing nothing riskier than that class.
+ */
+export declare const changeClassSchema: v.PicklistSchema<["docs", "test", "dependency", "config", "source", "schema", "unknown"], undefined>;
+export type ChangeClass = v.InferOutput<typeof changeClassSchema>;
+/**
+ * Every {@link ChangeClass} in rank order (lowest → highest risk), `unknown` last. The
+ * ordering the preset editor renders and the rollup table iterates, so a new class is added
+ * in ONE place. `unknown` is deliberately last: it is a fallback outcome, not a policy target.
+ */
+export declare const CHANGE_CLASSES: readonly ["docs", "test", "dependency", "config", "source", "schema", "unknown"];
+/**
+ * The classes a per-class merge RULE may be authored for — every class except `unknown`.
+ * `unknown` must stay inert: an unclassifiable diff (a transient VCS outage) has to fall
+ * back to the score thresholds rather than silently adopt a widened policy.
+ */
+export declare const RULEABLE_CHANGE_CLASSES: readonly ["docs", "test", "dependency", "config", "source", "schema"];
+export type RuleableChangeClass = (typeof RULEABLE_CHANGE_CLASSES)[number];
+/**
+ * How much review effort a human actually spent on a pull request before merging it — the
+ * ground truth the auto-merge score thresholds are trying to approximate.
+ *
+ *  - `none`  — merged with zero blocking comments.
+ *  - `minor` — small comments / a nit pass, no substantive rework.
+ *  - `major` — real rework was required.
+ *
+ * ALWAYS optional: an untagged merge records a null tag and every consumer treats null as
+ * "not tagged", never as `none`.
+ */
+export declare const reviewEffortSchema: v.PicklistSchema<["none", "minor", "major"], undefined>;
+export type ReviewEffort = v.InferOutput<typeof reviewEffortSchema>;
+/** Every {@link ReviewEffort} in ascending order — the chip order the SPA renders. */
+export declare const REVIEW_EFFORTS: readonly ["none", "minor", "major"];
+/**
+ * What ultimately happened to the pull request a track record covers.
+ *
+ *  - `pending_review`   — the merger step routed it to a human; not yet resolved. Recorded at
+ *    the decision so the class + scores are captured even if the human never comes back.
+ *  - `auto_merged`      — the engine merged it on the policy (thresholds or a class rule).
+ *  - `human_merged`     — a human confirmed the merge THROUGH cat-factory (a notification act
+ *    or the inspector's merge control).
+ *  - `external_merged`  — a human merged it directly on the VCS provider, bypassing
+ *    cat-factory; detected from the webhook ingest.
+ *  - `rejected`         — a human dismissed the review card instead of merging.
+ */
+export declare const mergeTrackDecisionSchema: v.PicklistSchema<["pending_review", "auto_merged", "human_merged", "external_merged", "rejected"], undefined>;
+export type MergeTrackDecision = v.InferOutput<typeof mergeTrackDecisionSchema>;
+/**
+ * The decisions that represent a pull request that actually LANDED. The auto-merge share a
+ * rollup reports is `autoMerged / (every landed decision)` — a `pending_review` row is not in
+ * the denominator (nothing was decided yet) and neither is a `rejected` one.
+ */
+export declare const MERGED_TRACK_DECISIONS: readonly ["auto_merged", "human_merged", "external_merged"];
+/**
+ * One persisted merge decision: what kind of change it was, what the merger scored it, what
+ * the engine/human did, and how much review effort it needed. Written best-effort off the
+ * merge path — a failure to write one NEVER blocks or fails a merge.
+ *
+ * Provider-neutral by construction: the repo identity is `repoId` + `provider` (the kernel
+ * `VcsRepoRef`/`VcsProvider` vocabulary), never a GitHub-shaped `githubId`/`installationId`.
+ */
+export declare const mergeTrackRecordSchema: v.ObjectSchema<{
+    /**
+     * Deterministic id, derived from the run: `mtr_<executionId>`. Deterministic so a durable-driver
+     * replay of a settled merger step collides with the row it already wrote (first write wins)
+     * instead of duplicating it.
+     */
+    readonly id: v.StringSchema<undefined>;
+    /** The task/block whose pull request this covers. */
+    readonly blockId: v.StringSchema<undefined>;
+    /**
+     * The run that produced the PR. Nullable at the wire/storage level because the column is, but
+     * every record written today is born at a merge DECISION POINT inside a run, so it is set. An
+     * external merge does not MINT a record — it settles the one the run already wrote (which is
+     * also why attribution keys on `(repoId, prNumber)`); a PR cat-factory never opened has no
+     * record and is correctly invisible to the track record.
+     */
+    readonly executionId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** The deterministic, path-derived change class (see {@link changeClassSchema}). */
+    readonly changeClass: v.PicklistSchema<["docs", "test", "dependency", "config", "source", "schema", "unknown"], undefined>;
+    /** How many files the PR changed, when the changed-file list was readable. */
+    readonly changedFileCount: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    /** The merger's complexity score at the decision, when it produced a parseable assessment. */
+    readonly complexity: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>, undefined>;
+    /** The merger's risk score at the decision, when one was produced. */
+    readonly risk: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>, undefined>;
+    /** The merger's impact score at the decision, when one was produced. */
+    readonly impact: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>, undefined>;
+    /** The merge preset the decision was made against, for reading a record back in context. */
+    readonly riskPolicyId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly riskPolicyName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** What happened (see {@link mergeTrackDecisionSchema}). */
+    readonly decision: v.PicklistSchema<["pending_review", "auto_merged", "human_merged", "external_merged", "rejected"], undefined>;
+    /** The human's effort tag — null until somebody tags it. Tagging is never mandatory. */
+    readonly reviewEffort: v.NullableSchema<v.PicklistSchema<["none", "minor", "major"], undefined>, undefined>;
+    /** The PR number within its repo, when known. */
+    readonly prNumber: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    /** The PR's web URL, for the card's deep link. */
+    readonly prUrl: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Provider-neutral repo id the PR belongs to (`VcsRepoRef.repoId`). */
+    readonly repoId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Which VCS provider hosts it — so a mixed-provider workspace reads back correctly. */
+    readonly provider: v.NullableSchema<v.PicklistSchema<["github", "gitlab"], undefined>, undefined>;
+    /** Epoch ms the decision was recorded (the merger step's resolution). */
+    readonly createdAt: v.NumberSchema<undefined>;
+    /** Epoch ms the decision reached a terminal value; null while `pending_review`. */
+    readonly resolvedAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    /** Epoch ms the effort tag was recorded; null while untagged. */
+    readonly taggedAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+}, undefined>;
+export type MergeTrackRecord = v.InferOutput<typeof mergeTrackRecordSchema>;
+/** The per-effort-level counts within a class's rollup. `untagged` counts null tags. */
+export declare const reviewEffortDistributionSchema: v.ObjectSchema<{
+    readonly none: v.NumberSchema<undefined>;
+    readonly minor: v.NumberSchema<undefined>;
+    readonly major: v.NumberSchema<undefined>;
+    readonly untagged: v.NumberSchema<undefined>;
+}, undefined>;
+export type ReviewEffortDistribution = v.InferOutput<typeof reviewEffortDistributionSchema>;
+/** One change class's accumulated track record — the number that justifies widening a rule. */
+export declare const mergeClassRollupSchema: v.ObjectSchema<{
+    readonly changeClass: v.PicklistSchema<["docs", "test", "dependency", "config", "source", "schema", "unknown"], undefined>;
+    /** Every record in the class, including still-`pending_review` ones. */
+    readonly total: v.NumberSchema<undefined>;
+    /** Records whose PR landed (auto + human + external) — the auto-merge-share denominator. */
+    readonly merged: v.NumberSchema<undefined>;
+    readonly autoMerged: v.NumberSchema<undefined>;
+    readonly humanMerged: v.NumberSchema<undefined>;
+    readonly externalMerged: v.NumberSchema<undefined>;
+    readonly rejected: v.NumberSchema<undefined>;
+    readonly pendingReview: v.NumberSchema<undefined>;
+    readonly effort: v.ObjectSchema<{
+        readonly none: v.NumberSchema<undefined>;
+        readonly minor: v.NumberSchema<undefined>;
+        readonly major: v.NumberSchema<undefined>;
+        readonly untagged: v.NumberSchema<undefined>;
+    }, undefined>;
+}, undefined>;
+export type MergeClassRollup = v.InferOutput<typeof mergeClassRollupSchema>;
+/**
+ * The auto-merge share of a class's LANDED records, 0..1, or null when nothing has landed
+ * yet (so the UI shows "no data" rather than a misleading 0%). Shared by the preset editor
+ * and any backend consumer so the two can never disagree.
+ */
+export declare function autoMergeShare(rollup: MergeClassRollup): number | null;
+/**
+ * The share of a class's TAGGED records that needed no blocking comments, 0..1, or null when
+ * nothing in the class has been tagged. This — not the auto-merge share — is the evidence that
+ * justifies flipping a class to `always`: it says humans found nothing to say.
+ */
+export declare function frictionlessShare(rollup: MergeClassRollup): number | null;
+/** An empty rollup for a class with no records yet (the UI renders every class, always). */
+export declare function emptyMergeClassRollup(changeClass: ChangeClass): MergeClassRollup;
+/**
+ * Body of `POST /blocks/:blockId/merge` — the inspector's merge control. Every field is optional,
+ * so `{}` is the historical no-body merge; `reviewEffort` records the effort tag onto the block's
+ * merge track record in the same request (the counterpart of the notification card's `act` body).
+ */
+export declare const mergeBlockSchema: v.ObjectSchema<{
+    readonly reviewEffort: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["none", "minor", "major"], undefined>, undefined>, undefined>;
+}, undefined>;
+export type MergeBlockInput = v.InferOutput<typeof mergeBlockSchema>;
+/** Tag a record with the review effort a human actually spent (`null` clears the tag). */
+export declare const tagReviewEffortSchema: v.ObjectSchema<{
+    readonly reviewEffort: v.NullableSchema<v.PicklistSchema<["none", "minor", "major"], undefined>, undefined>;
+}, undefined>;
+export type TagReviewEffortInput = v.InferOutput<typeof tagReviewEffortSchema>;
+//# sourceMappingURL=mergeTrackRecord.d.ts.map

package/dist/mergeTrackRecord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mergeTrackRecord.d.ts","sourceRoot":"","sources":["../src/mergeTrackRecord.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAwB5B;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,sGAQ5B,CAAA;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEjE;;;;GAIG;AACH,eAAO,MAAM,cAAc,kFAQgB,CAAA;AAE3C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,uEAOO,CAAA;AAE3C,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE1E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,yDAAyC,CAAA;AACxE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEnE,sFAAsF;AACtF,eAAO,MAAM,cAAc,qCAAwE,CAAA;AAEnG;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,+GAMnC,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,6DAIe,CAAA;AAIlD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB;IACjC;;;;OAIG;;IAEH,qDAAqD;;IAErD;;;;;;OAMG;;IAEH,oFAAoF;;IAEpF,8EAA8E;;IAE9E,8FAA8F;;IAE9F,sEAAsE;;IAEtE,wEAAwE;;IAExE,4FAA4F;;;IAG5F,4DAA4D;;IAE5D,wFAAwF;;IAExF,iDAAiD;;IAEjD,kDAAkD;;IAElD,wEAAwE;;IAExE,wFAAwF;;IAExF,yEAAyE;;IAEzE,mFAAmF;;IAEnF,iEAAiE;;aAEjE,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAQ3E,wFAAwF;AACxF,eAAO,MAAM,8BAA8B;;;;;aAKzC,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,8BAA8B,CAAC,CAAA;AAE3F,+FAA+F;AAC/F,eAAO,MAAM,sBAAsB;;IAEjC,wEAAwE;;IAExE,4FAA4F;;;;;;;;;;;;;aAQ5F,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAGtE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAIzE;AAED,4FAA4F;AAC5F,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,WAAW,GAAG,gBAAgB,CAYhF;AAID;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;aAE3B,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEpE,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB;;aAEhC,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA"}

package/dist/mergeTrackRecord.js

@@ -0,0 +1,251 @@
+import * as v from 'valibot';
+import { vcsProviderSchema } from './routes/auth.js';
+// ---------------------------------------------------------------------------
+// Merge TRACK RECORD wire contracts — the accumulated human evidence behind the
+// auto-merge policy.
+//
+// The merge decision itself runs on the `merger` agent's self-assessment (see
+// `merge.ts`): scores vs the task's preset ceilings. This module models what the
+// decision LEAVES BEHIND so the policy can eventually stand on evidence instead:
+//
+//   - WHAT KIND of change it was (a deterministic, path-derived {@link ChangeClass}),
+//   - the merger's scores at the moment of the decision,
+//   - how much review effort a human actually spent ({@link ReviewEffort}, nullable
+//     until somebody tags it — tagging is never mandatory),
+//   - and what happened ({@link MergeTrackDecision}).
+//
+// Per-class rollups of those records are what justify WIDENING a policy, which is
+// why merge presets carry per-class rules ({@link MergeClassRules} in `merge.ts`).
+//
+// Full design — the class precedence rules, the external-merge detection, and the
+// preset reshape — is in `docs/initiatives/merge-track-record.md`.
+// ---------------------------------------------------------------------------
+/**
+ * What kind of change a run's pull request made, derived DETERMINISTICALLY on the backend
+ * from the PR's changed-file list (never from an agent's opinion). A small closed set so it
+ * can key a per-class merge rule, a rollup `GROUP BY`, and an i18n label.
+ *
+ *  - `docs`       — documentation + user-facing copy (Markdown, `docs/`, i18n catalogs).
+ *  - `test`       — test/spec/fixture files only.
+ *  - `dependency` — dependency manifests + lockfiles (a bump).
+ *  - `config`     — CI workflows, tooling config, container/IaC manifests.
+ *  - `source`     — application/library source code (the catch-all for real code).
+ *  - `schema`     — database migrations + schema definitions (the riskiest: irreversible).
+ *  - `unknown`    — no changed-file list was available (no VCS client wired, or an empty diff).
+ *
+ * A MIXED diff resolves to the HIGHEST-RANKED class present (see `CHANGE_CLASS_RANK` /
+ * `classifyChangedFiles` in `@cat-factory/kernel`), so a per-class rule can only ever fire on a
+ * diff containing nothing riskier than that class.
+ */
+export const changeClassSchema = v.picklist([
+    'docs',
+    'test',
+    'dependency',
+    'config',
+    'source',
+    'schema',
+    'unknown',
+]);
+/**
+ * Every {@link ChangeClass} in rank order (lowest → highest risk), `unknown` last. The
+ * ordering the preset editor renders and the rollup table iterates, so a new class is added
+ * in ONE place. `unknown` is deliberately last: it is a fallback outcome, not a policy target.
+ */
+export const CHANGE_CLASSES = [
+    'docs',
+    'test',
+    'dependency',
+    'config',
+    'source',
+    'schema',
+    'unknown',
+];
+/**
+ * The classes a per-class merge RULE may be authored for — every class except `unknown`.
+ * `unknown` must stay inert: an unclassifiable diff (a transient VCS outage) has to fall
+ * back to the score thresholds rather than silently adopt a widened policy.
+ */
+export const RULEABLE_CHANGE_CLASSES = [
+    'docs',
+    'test',
+    'dependency',
+    'config',
+    'source',
+    'schema',
+];
+/**
+ * How much review effort a human actually spent on a pull request before merging it — the
+ * ground truth the auto-merge score thresholds are trying to approximate.
+ *
+ *  - `none`  — merged with zero blocking comments.
+ *  - `minor` — small comments / a nit pass, no substantive rework.
+ *  - `major` — real rework was required.
+ *
+ * ALWAYS optional: an untagged merge records a null tag and every consumer treats null as
+ * "not tagged", never as `none`.
+ */
+export const reviewEffortSchema = v.picklist(['none', 'minor', 'major']);
+/** Every {@link ReviewEffort} in ascending order — the chip order the SPA renders. */
+export const REVIEW_EFFORTS = ['none', 'minor', 'major'];
+/**
+ * What ultimately happened to the pull request a track record covers.
+ *
+ *  - `pending_review`   — the merger step routed it to a human; not yet resolved. Recorded at
+ *    the decision so the class + scores are captured even if the human never comes back.
+ *  - `auto_merged`      — the engine merged it on the policy (thresholds or a class rule).
+ *  - `human_merged`     — a human confirmed the merge THROUGH cat-factory (a notification act
+ *    or the inspector's merge control).
+ *  - `external_merged`  — a human merged it directly on the VCS provider, bypassing
+ *    cat-factory; detected from the webhook ingest.
+ *  - `rejected`         — a human dismissed the review card instead of merging.
+ */
+export const mergeTrackDecisionSchema = v.picklist([
+    'pending_review',
+    'auto_merged',
+    'human_merged',
+    'external_merged',
+    'rejected',
+]);
+/**
+ * The decisions that represent a pull request that actually LANDED. The auto-merge share a
+ * rollup reports is `autoMerged / (every landed decision)` — a `pending_review` row is not in
+ * the denominator (nothing was decided yet) and neither is a `rejected` one.
+ */
+export const MERGED_TRACK_DECISIONS = [
+    'auto_merged',
+    'human_merged',
+    'external_merged',
+];
+const scoreSchema = v.pipe(v.number(), v.minValue(0), v.maxValue(1));
+/**
+ * One persisted merge decision: what kind of change it was, what the merger scored it, what
+ * the engine/human did, and how much review effort it needed. Written best-effort off the
+ * merge path — a failure to write one NEVER blocks or fails a merge.
+ *
+ * Provider-neutral by construction: the repo identity is `repoId` + `provider` (the kernel
+ * `VcsRepoRef`/`VcsProvider` vocabulary), never a GitHub-shaped `githubId`/`installationId`.
+ */
+export const mergeTrackRecordSchema = v.object({
+    /**
+     * Deterministic id, derived from the run: `mtr_<executionId>`. Deterministic so a durable-driver
+     * replay of a settled merger step collides with the row it already wrote (first write wins)
+     * instead of duplicating it.
+     */
+    id: v.string(),
+    /** The task/block whose pull request this covers. */
+    blockId: v.string(),
+    /**
+     * The run that produced the PR. Nullable at the wire/storage level because the column is, but
+     * every record written today is born at a merge DECISION POINT inside a run, so it is set. An
+     * external merge does not MINT a record — it settles the one the run already wrote (which is
+     * also why attribution keys on `(repoId, prNumber)`); a PR cat-factory never opened has no
+     * record and is correctly invisible to the track record.
+     */
+    executionId: v.nullable(v.string()),
+    /** The deterministic, path-derived change class (see {@link changeClassSchema}). */
+    changeClass: changeClassSchema,
+    /** How many files the PR changed, when the changed-file list was readable. */
+    changedFileCount: v.nullable(v.number()),
+    /** The merger's complexity score at the decision, when it produced a parseable assessment. */
+    complexity: v.nullable(scoreSchema),
+    /** The merger's risk score at the decision, when one was produced. */
+    risk: v.nullable(scoreSchema),
+    /** The merger's impact score at the decision, when one was produced. */
+    impact: v.nullable(scoreSchema),
+    /** The merge preset the decision was made against, for reading a record back in context. */
+    riskPolicyId: v.nullable(v.string()),
+    riskPolicyName: v.nullable(v.string()),
+    /** What happened (see {@link mergeTrackDecisionSchema}). */
+    decision: mergeTrackDecisionSchema,
+    /** The human's effort tag — null until somebody tags it. Tagging is never mandatory. */
+    reviewEffort: v.nullable(reviewEffortSchema),
+    /** The PR number within its repo, when known. */
+    prNumber: v.nullable(v.number()),
+    /** The PR's web URL, for the card's deep link. */
+    prUrl: v.nullable(v.string()),
+    /** Provider-neutral repo id the PR belongs to (`VcsRepoRef.repoId`). */
+    repoId: v.nullable(v.string()),
+    /** Which VCS provider hosts it — so a mixed-provider workspace reads back correctly. */
+    provider: v.nullable(vcsProviderSchema),
+    /** Epoch ms the decision was recorded (the merger step's resolution). */
+    createdAt: v.number(),
+    /** Epoch ms the decision reached a terminal value; null while `pending_review`. */
+    resolvedAt: v.nullable(v.number()),
+    /** Epoch ms the effort tag was recorded; null while untagged. */
+    taggedAt: v.nullable(v.number()),
+});
+// ---------------------------------------------------------------------------
+// Per-class rollups — SQL aggregates (COUNT / GROUP BY / conditional SUM), never
+// rows loaded and reduced in JS. ONE query per workspace returns every class, so
+// the preset editor's stats load in a single round-trip.
+// ---------------------------------------------------------------------------
+/** The per-effort-level counts within a class's rollup. `untagged` counts null tags. */
+export const reviewEffortDistributionSchema = v.object({
+    none: v.number(),
+    minor: v.number(),
+    major: v.number(),
+    untagged: v.number(),
+});
+/** One change class's accumulated track record — the number that justifies widening a rule. */
+export const mergeClassRollupSchema = v.object({
+    changeClass: changeClassSchema,
+    /** Every record in the class, including still-`pending_review` ones. */
+    total: v.number(),
+    /** Records whose PR landed (auto + human + external) — the auto-merge-share denominator. */
+    merged: v.number(),
+    autoMerged: v.number(),
+    humanMerged: v.number(),
+    externalMerged: v.number(),
+    rejected: v.number(),
+    pendingReview: v.number(),
+    effort: reviewEffortDistributionSchema,
+});
+/**
+ * The auto-merge share of a class's LANDED records, 0..1, or null when nothing has landed
+ * yet (so the UI shows "no data" rather than a misleading 0%). Shared by the preset editor
+ * and any backend consumer so the two can never disagree.
+ */
+export function autoMergeShare(rollup) {
+    if (rollup.merged === 0)
+        return null;
+    return rollup.autoMerged / rollup.merged;
+}
+/**
+ * The share of a class's TAGGED records that needed no blocking comments, 0..1, or null when
+ * nothing in the class has been tagged. This — not the auto-merge share — is the evidence that
+ * justifies flipping a class to `always`: it says humans found nothing to say.
+ */
+export function frictionlessShare(rollup) {
+    const tagged = rollup.effort.none + rollup.effort.minor + rollup.effort.major;
+    if (tagged === 0)
+        return null;
+    return rollup.effort.none / tagged;
+}
+/** An empty rollup for a class with no records yet (the UI renders every class, always). */
+export function emptyMergeClassRollup(changeClass) {
+    return {
+        changeClass,
+        total: 0,
+        merged: 0,
+        autoMerged: 0,
+        humanMerged: 0,
+        externalMerged: 0,
+        rejected: 0,
+        pendingReview: 0,
+        effort: { none: 0, minor: 0, major: 0, untagged: 0 },
+    };
+}
+// ---- Request bodies -------------------------------------------------------
+/**
+ * Body of `POST /blocks/:blockId/merge` — the inspector's merge control. Every field is optional,
+ * so `{}` is the historical no-body merge; `reviewEffort` records the effort tag onto the block's
+ * merge track record in the same request (the counterpart of the notification card's `act` body).
+ */
+export const mergeBlockSchema = v.object({
+    reviewEffort: v.optional(v.nullable(reviewEffortSchema)),
+});
+/** Tag a record with the review effort a human actually spent (`null` clears the tag). */
+export const tagReviewEffortSchema = v.object({
+    reviewEffort: v.nullable(reviewEffortSchema),
+});
+//# sourceMappingURL=mergeTrackRecord.js.map

package/dist/mergeTrackRecord.js.map

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

package/dist/notification-webhooks.d.ts

@@ -8,7 +8,7 @@ export declare const notificationWebhookSchema: v.ObjectSchema<{
      * headless overseer cares about — rather than "everything", so registering an endpoint can't
      * accidentally fire-hose every card at an integration that only wanted to hear about parks.
      */
-    readonly types: v.ArraySchema<v.PicklistSchema<["merge_review", "pipeline_complete", "ci_failed", "test_failed", "requirement_review", "clarity_review", "release_regression", "decision_required", "human_test_ready", "visual_confirmation_ready", "human_review", "followup_pending", "fork_decision_pending", "pr_review_ready", "initiative", "platform_health", "budget_paused", "key_drift"], undefined>, undefined>;
+    readonly types: v.ArraySchema<v.PicklistSchema<["merge_review", "pipeline_complete", "ci_failed", "test_failed", "requirement_review", "clarity_review", "release_regression", "decision_required", "human_test_ready", "visual_confirmation_ready", "human_review", "followup_pending", "fork_decision_pending", "pr_review_ready", "initiative", "platform_health", "budget_paused", "key_drift", "merge_tag_request"], undefined>, undefined>;
     /** Whether deliveries are currently attempted. Registering an endpoint enables it. */
     readonly enabled: v.BooleanSchema<undefined>;
     /** Whether a signing secret is set (the secret itself is never returned). */
@@ -24,7 +24,7 @@ export type NotificationWebhook = v.InferOutput<typeof notificationWebhookSchema
 export declare const putNotificationWebhookSchema: v.ObjectSchema<{
     readonly url: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.UrlAction<string, undefined>, v.StartsWithAction<string, "https://", "The webhook endpoint must be an https:// URL">, v.MaxLengthAction<string, 2000, undefined>]>;
     /** Omit ⇒ deliver the default parking types. */
-    readonly types: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["merge_review", "pipeline_complete", "ci_failed", "test_failed", "requirement_review", "clarity_review", "release_regression", "decision_required", "human_test_ready", "visual_confirmation_ready", "human_review", "followup_pending", "fork_decision_pending", "pr_review_ready", "initiative", "platform_health", "budget_paused", "key_drift"], undefined>, undefined>, undefined>;
+    readonly types: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<["merge_review", "pipeline_complete", "ci_failed", "test_failed", "requirement_review", "clarity_review", "release_regression", "decision_required", "human_test_ready", "visual_confirmation_ready", "human_review", "followup_pending", "fork_decision_pending", "pr_review_ready", "initiative", "platform_health", "budget_paused", "key_drift", "merge_tag_request"], undefined>, undefined>, undefined>;
     readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
     /** New signing secret; omit to keep the current one. */
     readonly secret: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 16, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
@@ -52,7 +52,7 @@ export declare const notificationWebhookDeliverySchema: v.ObjectSchema<{
     readonly taskId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     readonly notification: v.ObjectSchema<{
         readonly id: v.StringSchema<undefined>;
-        readonly type: v.PicklistSchema<["merge_review", "pipeline_complete", "ci_failed", "test_failed", "requirement_review", "clarity_review", "release_regression", "decision_required", "human_test_ready", "visual_confirmation_ready", "human_review", "followup_pending", "fork_decision_pending", "pr_review_ready", "initiative", "platform_health", "budget_paused", "key_drift"], undefined>;
+        readonly type: v.PicklistSchema<["merge_review", "pipeline_complete", "ci_failed", "test_failed", "requirement_review", "clarity_review", "release_regression", "decision_required", "human_test_ready", "visual_confirmation_ready", "human_review", "followup_pending", "fork_decision_pending", "pr_review_ready", "initiative", "platform_health", "budget_paused", "key_drift", "merge_tag_request"], undefined>;
         readonly status: v.PicklistSchema<["open", "acted", "dismissed"], undefined>;
         readonly severity: v.OptionalSchema<v.PicklistSchema<["normal", "urgent"], undefined>, undefined>;
         readonly blockId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
@@ -98,6 +98,8 @@ export declare const notificationWebhookDeliverySchema: v.ObjectSchema<{
                 readonly reason: v.PicklistSchema<["key-mismatch", "corrupt"], undefined>;
                 readonly sealedAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
             }, undefined>, undefined>, undefined>;
+            readonly changeClass: v.OptionalSchema<v.PicklistSchema<["docs", "test", "dependency", "config", "source", "schema", "unknown"], undefined>, undefined>;
+            readonly mergeTrackRecordId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         }, undefined>, undefined>, undefined>;
         readonly createdAt: v.NumberSchema<undefined>;
         readonly resolvedAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;

package/dist/notification-webhooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notification-webhooks.d.ts","sourceRoot":"","sources":["../src/notification-webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAmB5B,+FAA+F;AAC/F,eAAO,MAAM,yBAAyB;IACpC,mDAAmD;;IAEnD;;;;OAIG;;IAEH,sFAAsF;;IAEtF,6EAA6E;;;aAG7E,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;IAQvC,gDAAgD;;;IAGhD,wDAAwD;;aAExD,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAE5F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iCAAiC;;IAE5C,kGAAkG;;;IAGlG,4DAA4D;;IAE5D,mEAAmE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAGnE,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iCAAiC,CAAC,CAAA;AAEjG;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC,kKAS6B,CAAA"}
+{"version":3,"file":"notification-webhooks.d.ts","sourceRoot":"","sources":["../src/notification-webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAmB5B,+FAA+F;AAC/F,eAAO,MAAM,yBAAyB;IACpC,mDAAmD;;IAEnD;;;;OAIG;;IAEH,sFAAsF;;IAEtF,6EAA6E;;;aAG7E,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;IAQvC,gDAAgD;;;IAGhD,wDAAwD;;aAExD,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAE5F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iCAAiC;;IAE5C,kGAAkG;;;IAGlG,4DAA4D;;IAE5D,mEAAmE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAGnE,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iCAAiC,CAAC,CAAA;AAEjG;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC,kKAS6B,CAAA"}

package/dist/notifications.d.ts

@@ -4,7 +4,7 @@ import * as v from 'valibot';
  * the frontend can switch on it to render the right action; extending it is a
  * one-line change here plus a handler in the worker's `act` route.
  */
-export declare const notificationTypeSchema: v.PicklistSchema<["merge_review", "pipeline_complete", "ci_failed", "test_failed", "requirement_review", "clarity_review", "release_regression", "decision_required", "human_test_ready", "visual_confirmation_ready", "human_review", "followup_pending", "fork_decision_pending", "pr_review_ready", "initiative", "platform_health", "budget_paused", "key_drift"], undefined>;
+export declare const notificationTypeSchema: v.PicklistSchema<["merge_review", "pipeline_complete", "ci_failed", "test_failed", "requirement_review", "clarity_review", "release_regression", "decision_required", "human_test_ready", "visual_confirmation_ready", "human_review", "followup_pending", "fork_decision_pending", "pr_review_ready", "initiative", "platform_health", "budget_paused", "key_drift", "merge_tag_request"], undefined>;
 export type NotificationType = v.InferOutput<typeof notificationTypeSchema>;
 /**
  * The closed set of notification types that count as "a task is waiting on a human review"
@@ -18,7 +18,9 @@ export type NotificationType = v.InferOutput<typeof notificationTypeSchema>;
  * Deliberately EXCLUDED: failure-remediation cards (`ci_failed`, `test_failed`,
  * `release_regression`) — "the machine needs help", not "a human owes a review" — and
  * block-less/system cards (`platform_health`, `budget_paused`, `key_drift`, `initiative`) that
- * aren't tied to a reviewable task.
+ * aren't tied to a reviewable task. `merge_tag_request` is excluded too: the PR it concerns has
+ * ALREADY merged, so it is a post-hoc nudge for one tap — counting it as review debt would
+ * friction task authoring over work that is finished.
  */
 export declare const REVIEW_WAIT_NOTIFICATION_TYPES: readonly ["merge_review", "pipeline_complete", "requirement_review", "clarity_review", "decision_required", "human_test_ready", "visual_confirmation_ready", "human_review", "followup_pending", "fork_decision_pending", "pr_review_ready"];
 export type ReviewWaitNotificationType = (typeof REVIEW_WAIT_NOTIFICATION_TYPES)[number];
@@ -154,12 +156,24 @@ export declare const notificationPayloadSchema: v.ObjectSchema<{
         /** Epoch ms the secret was sealed, when known — helps an operator correlate a key change. */
         readonly sealedAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
     }, undefined>, undefined>, undefined>;
+    /**
+     * The run's deterministic change class, on a `merge_review` / `pipeline_complete` /
+     * `merge_tag_request` card — so the human sees WHAT KIND of change they are being asked to
+     * review or tag, and the SPA can show that class's accumulated track record alongside.
+     */
+    readonly changeClass: v.OptionalSchema<v.PicklistSchema<["docs", "test", "dependency", "config", "source", "schema", "unknown"], undefined>, undefined>;
+    /**
+     * The merge track record the card's effort tag applies to. Carried on the merge-decision
+     * cards (so acting on one can tag in the same tap) and on a `merge_tag_request` (whose whole
+     * purpose is to tag it). Absent when no record was written (a best-effort side channel).
+     */
+    readonly mergeTrackRecordId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
 }, undefined>;
 export type NotificationPayload = v.InferOutput<typeof notificationPayloadSchema>;
 /** A human-actionable item surfaced on the board. */
 export declare const notificationSchema: v.ObjectSchema<{
     readonly id: v.StringSchema<undefined>;
-    readonly type: v.PicklistSchema<["merge_review", "pipeline_complete", "ci_failed", "test_failed", "requirement_review", "clarity_review", "release_regression", "decision_required", "human_test_ready", "visual_confirmation_ready", "human_review", "followup_pending", "fork_decision_pending", "pr_review_ready", "initiative", "platform_health", "budget_paused", "key_drift"], undefined>;
+    readonly type: v.PicklistSchema<["merge_review", "pipeline_complete", "ci_failed", "test_failed", "requirement_review", "clarity_review", "release_regression", "decision_required", "human_test_ready", "visual_confirmation_ready", "human_review", "followup_pending", "fork_decision_pending", "pr_review_ready", "initiative", "platform_health", "budget_paused", "key_drift", "merge_tag_request"], undefined>;
     readonly status: v.PicklistSchema<["open", "acted", "dismissed"], undefined>;
     /**
      * Render urgency (see {@link notificationSeveritySchema}). Absent ⇒ `normal`. Flipped
@@ -259,6 +273,18 @@ export declare const notificationSchema: v.ObjectSchema<{
             /** Epoch ms the secret was sealed, when known — helps an operator correlate a key change. */
             readonly sealedAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>, undefined>;
+        /**
+         * The run's deterministic change class, on a `merge_review` / `pipeline_complete` /
+         * `merge_tag_request` card — so the human sees WHAT KIND of change they are being asked to
+         * review or tag, and the SPA can show that class's accumulated track record alongside.
+         */
+        readonly changeClass: v.OptionalSchema<v.PicklistSchema<["docs", "test", "dependency", "config", "source", "schema", "unknown"], undefined>, undefined>;
+        /**
+         * The merge track record the card's effort tag applies to. Carried on the merge-decision
+         * cards (so acting on one can tag in the same tap) and on a `merge_tag_request` (whose whole
+         * purpose is to tag it). Absent when no record was written (a best-effort side channel).
+         */
+        readonly mergeTrackRecordId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>, undefined>, undefined>;
     readonly createdAt: v.NumberSchema<undefined>;
     /** When it left `open` (acted/dismissed); null while open. */
@@ -268,4 +294,17 @@ export type Notification = v.InferOutput<typeof notificationSchema>;
 /** How a human resolved a notification from its card. */
 export declare const resolveNotificationActionSchema: v.PicklistSchema<["act", "dismiss"], undefined>;
 export type ResolveNotificationAction = v.InferOutput<typeof resolveNotificationActionSchema>;
+/**
+ * Body of `POST /notifications/:id/act`. Every field is optional, so `{}` is the historical
+ * no-body behaviour.
+ *
+ * On a `merge_review` / `pipeline_complete` card, `reviewEffort` records — in the SAME tap that
+ * confirms the merge — how much review the PR actually needed, onto the run's merge track
+ * record. Omitting it is always fine: the record keeps a null tag and nothing downstream breaks
+ * (tagging is a nudge, never a gate).
+ */
+export declare const actNotificationSchema: v.ObjectSchema<{
+    readonly reviewEffort: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["none", "minor", "major"], undefined>, undefined>, undefined>;
+}, undefined>;
+export type ActNotificationInput = v.InferOutput<typeof actNotificationSchema>;
 //# sourceMappingURL=notifications.d.ts.map

package/dist/notifications.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../src/notifications.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAyE5B;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,mXAmBjC,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,8BAA8B,8OAYK,CAAA;AAEhD,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAA;AAMxF,wFAAwF;AACxF,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAE5E;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;IACjC,qGAAqG;;IAErG,2DAA2D;;IAE3D,+DAA+D;;IAE/D;;;;OAIG;;IAEH,6FAA6F;;aAE7F,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,6DAA6C,CAAA;AAClF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,mDAAmC,CAAA;AAC1E,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAEnF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;IACpC,4DAA4D;;;;;;;IAE5D,sEAAsE;;IAEtE,gFAAgF;;IAEhF,0DAA0D;;IAE1D,kGAAkG;;IAElG,iFAAiF;;IAEjF,mEAAmE;;;;;;;IAEnE,mEAAmE;;;;;;;;IAEnE,4EAA4E;;IAE5E;;;;OAIG;;IAEH,gFAAgF;;IAEhF;;;;OAIG;;IAEH,yGAAyG;;IAEzG,uFAAuF;;IAEvF;;;;;;;OAOG;;IAEH;;;;;OAKG;;QA7FH,qGAAqG;;QAErG,2DAA2D;;QAE3D,+DAA+D;;QAE/D;;;;WAIG;;QAEH,6FAA6F;;;aAmF7F,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF,qDAAqD;AACrD,eAAO,MAAM,kBAAkB;;;;IAI7B;;;OAGG;;IAEH,iFAAiF;;IAEjF,yDAAyD;;IAEzD,wCAAwC;;IAExC,mCAAmC;;IAEnC,wFAAwF;;QAzExF,4DAA4D;;;;;;;QAE5D,sEAAsE;;QAEtE,gFAAgF;;QAEhF,0DAA0D;;QAE1D,kGAAkG;;QAElG,iFAAiF;;QAEjF,mEAAmE;;;;;;;QAEnE,mEAAmE;;;;;;;;QAEnE,4EAA4E;;QAE5E;;;;WAIG;;QAEH,gFAAgF;;QAEhF;;;;WAIG;;QAEH,yGAAyG;;QAEzG,uFAAuF;;QAEvF;;;;;;;WAOG;;QAEH;;;;;WAKG;;YA7FH,qGAAqG;;YAErG,2DAA2D;;YAE3D,+DAA+D;;YAE/D;;;;eAIG;;YAEH,6FAA6F;;;;;IA2G7F,8DAA8D;;aAE9D,CAAA;AACF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAInE,yDAAyD;AACzD,eAAO,MAAM,+BAA+B,iDAAiC,CAAA;AAC7E,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,+BAA+B,CAAC,CAAA"}
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../src/notifications.ts"],"names":[],"mappings":"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"}