@company-semantics/contracts 88.2.0 → 89.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "88.2.0",
+  "version": "89.0.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = 'fa844a445bc5' as const;
-export const SPEC_HASH_FULL = 'fa844a445bc5f62afa70d732ba33c9ce0b90b89f0634fabb2d6342743c0efeee' as const;
+export const SPEC_HASH = '280a694d540b' as const;
+export const SPEC_HASH_FULL = '280a694d540b48ca0e4f5985e8529cc5a88f96efca70980012b011cc914cc08c' as const;

package/src/api/generated.ts

@@ -3834,6 +3834,80 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/factory/quality/changes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Report a pull request head and get the evaluation plan to run for it
+         * @description Resolves the changed files to an impact set, records the change and plans its evaluation. Idempotent: the same head reported again answers the same plan. A change no impact rule matches answers { noImpact: true } and records nothing.
+         */
+        post: operations["createQualityChange"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/factory/quality/plans/{planId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read an evaluation plan: suites, pinned manifests, samples, model profile, budget */
+        get: operations["getQualityPlan"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/factory/quality/plans/{planId}/decision": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read where a plan's evaluation stands and, once recorded, its decision */
+        get: operations["getQualityPlanDecision"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/factory/quality/deployments": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Report one phase of a deploy run so an applied backend deployment is verified
+         * @description An applied phase that names a backend commit pins the release references, records the deployment as a change to verify, plans the verification and asks for its runs. Idempotent: the same deployment reported again answers the same change and plan. Any other report answers 202 { ignored: true } and records nothing. The deployment is never held for its verification.
+         */
+        post: operations["recordQualityDeployment"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/internal-admin/impersonate/start": {
         parameters: {
             query?: never;
@@ -8255,6 +8329,87 @@ export interface components {
                 [key: string]: unknown;
             } | null;
         };
+        CreateQualityChangeResponse: {
+            /** Format: uuid */
+            planId: string;
+            suites: string[];
+            samples: number;
+            budgetUsd: number;
+            modelProfile: {
+                [key: string]: unknown;
+            };
+        } | {
+            /** @constant */
+            noImpact: true;
+        };
+        CreateQualityChangeRequest: {
+            /** @constant */
+            sourceKind: "pull_request";
+            sourceRef: string;
+            gitSha: string;
+            changedFiles: string[];
+        };
+        QualityPlanResponse: {
+            /** Format: uuid */
+            planId: string;
+            suites: string[];
+            samples: number;
+            budgetUsd: number;
+            modelProfile: {
+                [key: string]: unknown;
+            };
+            /** Format: uuid */
+            changeId: string;
+            /** @enum {string} */
+            state: "active" | "superseded";
+            supersededBy: string | null;
+            manifests: {
+                suite: string;
+                manifestId: string;
+                entries: {
+                    caseId: string;
+                    caseRevision: string;
+                }[] | null;
+            }[];
+        };
+        QualityPlanDecisionResponse: {
+            /** @enum {string} */
+            state: "queued" | "running" | "blocked" | "complete";
+            /** @enum {string} */
+            blockReason?: "budget_exhausted" | "grader_calibration_pending" | "required_run_pending" | "provider_unavailable" | "manifest_unavailable";
+            decision?: {
+                /** @enum {string} */
+                outcome: "promote" | "reject" | "escalate";
+                reasons: {
+                    /** @enum {string} */
+                    code: "critical_regression" | "invariant_regression" | "protected_case_failed" | "below_floor" | "bucket_budget_exceeded" | "insufficient_improvement" | "cost_regression" | "latency_regression" | "grader_ineligible" | "insufficient_samples" | "flaky_case" | "policy_ambiguous" | "all_gates_passed" | "human_override";
+                    detail?: string;
+                }[];
+            };
+            /** Format: uuid */
+            supersededBy?: string;
+        };
+        RecordQualityDeploymentResponse: {
+            /** Format: uuid */
+            changeId: string;
+            /** Format: uuid */
+            planId: string;
+            releaseReferences: number;
+        };
+        QualityDeploymentIgnored: {
+            /** @constant */
+            ignored: true;
+        };
+        RecordQualityDeploymentRequest: {
+            manifestId: string | null;
+            phase: string;
+            shas: {
+                backend?: string;
+                app?: string;
+                edge?: string;
+            } | null;
+            surfaces: string[];
+        };
         ImpersonationSessionResponse: {
             session: {
                 impersonationSessionId: string;
@@ -8816,6 +8971,8 @@ export interface components {
                 /** @enum {string} */
                 classificationState: "unclassified" | "classified";
                 sourceClass: ("board_deck" | "board_minutes" | "investor_update" | "financial_brief" | "budget_forecast" | "okr_plan" | "annual_plan" | "all_hands" | "unit_strategy" | "roadmap" | "qbr" | "other" | "decoy") | null;
+                documentType: ("board_deck" | "board_minutes" | "strategy_memo" | "planning_doc" | "okr_doc" | "roadmap" | "operating_review" | "all_hands_deck" | "offsite_notes" | "investor_update" | "pitch_deck" | "product_spec" | "research_analysis" | "general_meeting_notes" | "financial_plan" | "financial_actuals" | "equity_admin_record" | "corporate_formation_record" | "corporate_governance_record" | "government_filing" | "equity_agreement" | "commercial_agreement" | "employment_agreement" | "transaction_record" | "personal_document" | "social_event_material" | "coursework" | "empty_template" | "image_or_screenshot" | "unknown") | null;
+                documentTypeConfidence: number | null;
                 periodLabel: string | null;
                 seriesRole: ("current" | "history") | null;
                 relevance: number;
@@ -8848,12 +9005,12 @@ export interface components {
                     /** @constant */
                     kind: "evaluation";
                     /** @enum {string} */
-                    code: "not_evaluated_t1" | "not_evaluated_t2" | "folder_unresolved" | "folder_truncated" | "explored_t1" | "explored_t2";
+                    code: "not_evaluated_t1" | "not_evaluated_t2" | "folder_unresolved" | "folder_truncated" | "explored_t1" | "explored_t2" | "peek_insufficient_evidence" | "type_disagreement" | "type_below_confidence" | "execution_failed_t1" | "execution_failed_t2";
                 } | {
                     /** @constant */
                     kind: "model";
                     /** @enum {string} */
-                    code: "title_path_score" | "peek_confirms" | "peek_contradicts";
+                    code: "title_path_score" | "peek_confirms" | "peek_contradicts" | "type_policy" | "peek_strategy_evidence_present" | "peek_strategy_evidence_absent";
                     score: number | null;
                 })[];
                 targetAudience: ("restricted" | "unit" | "org_wide") | null;
@@ -16451,6 +16608,184 @@ export interface operations {
             };
         };
     };
+    createQualityChange: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateQualityChangeRequest"];
+            };
+        };
+        responses: {
+            /** @description The plan to run (planId, suites, samples, budgetUsd, modelProfile), or noImpact */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CreateQualityChangeResponse"];
+                };
+            };
+            /** @description Payload invalid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing or invalid Floor bearer token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The change was replaced; its replacement is what is planned */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    getQualityPlan: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                planId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The plan as a runner needs it */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["QualityPlanResponse"];
+                };
+            };
+            /** @description Payload invalid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing or invalid Floor bearer token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such plan */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    getQualityPlanDecision: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                planId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Evaluation state, block reason while blocked, and the decision once decided */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["QualityPlanDecisionResponse"];
+                };
+            };
+            /** @description Payload invalid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing or invalid Floor bearer token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such plan */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    recordQualityDeployment: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RecordQualityDeploymentRequest"];
+            };
+        };
+        responses: {
+            /** @description The change that verifies the deployment, its plan, and the release references pinned */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RecordQualityDeploymentResponse"];
+                };
+            };
+            /** @description Not an applied backend deployment: nothing was recorded */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["QualityDeploymentIgnored"];
+                };
+            };
+            /** @description Payload invalid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing or invalid Floor bearer token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     startImpersonation: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -93,6 +93,10 @@ export const openApiRoutes = {
   '/api/executions/{executionId}/undo': ['POST'],
   '/api/factory/floor': ['GET'],
   '/api/factory/kpis': ['GET'],
+  '/api/factory/quality/changes': ['POST'],
+  '/api/factory/quality/deployments': ['POST'],
+  '/api/factory/quality/plans/{planId}': ['GET'],
+  '/api/factory/quality/plans/{planId}/decision': ['GET'],
   '/api/factory/snapshot': ['GET'],
   '/api/ingestion/operations/{id}': ['GET'],
   '/api/internal-admin/impersonate/end': ['POST'],

package/src/source-sync/README.md

@@ -134,7 +134,7 @@ Doctrine: control ADR `source-discovery-relevance-funnel`. Vocabulary: ADR
   `unclassified` (so `sourceClass` and `recommendedUse` are both null) or
   `classified` (both non-null). A shown line can still be
   `pending_classification` in its `machineState`.
-- **Reasons are a discriminated union.** `relevanceReasons` (≤ 8) is
+- **Reasons are a discriminated union.** `relevanceReasons` (≤ 16) is
   `RelevanceReason`: `lexicon` (a product-owned `term` and a `count`),
   `signal` (a `value` or null), `evaluation` (a code only) or `model` (a
   `score` or null). Each kind has its own disjoint code set, and the app
@@ -155,6 +155,42 @@ Doctrine: control ADR `source-discovery-relevance-funnel`. Vocabulary: ADR
   `filesNotRediscovered` and `filesPendingClassification`, counted by
   `candidateTotalsOf` over distinct files.
 
+## Document type
+
+Doctrine: control ADR `source-discovery-observation-vs-policy`. Vocabulary: ADR
+`source-discovery-document-type-vocabulary`. The model NAMES what a source is;
+product policy in the backend decides what that means.
+
+- **Structural, never a verdict.** `DOCUMENT_TYPES` (in `vocabulary.ts`) says
+  what a file IS — `corporate_formation_record`, never `irrelevant_doc` —
+  never how relevant it is. A medium is not a meaning: `image_or_screenshot`
+  is graded on its content. `unknown` is a real answer (the model could not
+  tell, or two reads disagreed) and is always last.
+- **The resolved type travels, nothing else.** The candidate item's
+  `documentType` and `documentTypeConfidence` (0..1) carry the RESOLVED type,
+  after the backend reconciles the T1 and T2 observations. Both are null on an
+  unclassified line and on every line of a run pinned before the typed path
+  (v1), where `sourceClass` alone is set. A known type always carries a
+  confidence; `unknown` and null never do. Per-tier types and per-layer scores
+  are backend evidence and stay off the wire.
+- **Policy lives in the backend.** Families, relevance policy modes, ceilings,
+  confidence floors, strategy signals and peek verdicts are backend product
+  policy, never contracts vocabulary
+  (INV-SOURCESYNC-OBSERVATION-IS-SEPARATE-FROM-POLICY). Changing what a type
+  means is a backend change, not a release.
+- **Same word, separate axis.** Five members are also words in other sets:
+  `board_deck`, `board_minutes`, `investor_update`, `roadmap`
+  (`SOURCE_CLASSES`) and `unknown` (`SHARING_BREADTHS`). `DOCUMENT_TYPES`
+  therefore sits outside the cross-set disjointness check, and its overlap is
+  pinned to exactly those five.
+- **Typed-relevance reasons.** Model codes `type_policy` (the policy-applied
+  score of the resolved type) and `peek_strategy_evidence_present` /
+  `peek_strategy_evidence_absent`. Evaluation codes
+  `peek_insufficient_evidence`, `type_disagreement`, `type_below_confidence`
+  and `execution_failed_t1` / `execution_failed_t2`: a tier that did not run
+  is uncertainty, never irrelevance. `peek_confirms` / `peek_contradicts`
+  stay for v1-pinned rows.
+
 ## Public API
 
 - `SOURCE_CLASSES` / `SourceClass` — what kind of document a source is.
@@ -172,10 +208,14 @@ Doctrine: control ADR `source-discovery-relevance-funnel`. Vocabulary: ADR
   `pending`, `approved` or `rejected` (no verb writes `rejected` yet).
 - `SOURCE_SYNC_SCOPE_APPROVER_KINDS` / `SourceSyncScopeApproverKind` —
   `org_admin` or `unit_head`.
+- `DOCUMENT_TYPES` / `DocumentType` / `KnownDocumentType` — what a source is,
+  structurally; `KnownDocumentType` excludes `unknown` (see Document type).
 - `SourceSyncDiscoveryRunResponseSchema` / `SourceSyncDiscoveryRunResponse` —
   the discovery run started, and the workflow narrating it.
 - `SourceSyncCandidateItemSchema` / `SourceSyncCandidateItem` — one source
-  proposed for one target document, with the server's `included`.
+  proposed for one target document, with the server's `included` and the
+  resolved `documentType` / `documentTypeConfidence` (null when unclassified
+  or v1-pinned).
 - `SourceSyncCandidateSetResponseSchema` / `SourceSyncCandidateSetResponse` —
   the draft set under review: its revision, items, presented questions,
   distinct-file `totals` and cost estimate.
@@ -267,5 +307,7 @@ Doctrine: control ADR `source-discovery-relevance-funnel`. Vocabulary: ADR
 
 `rules.ts` imports only `zod`, `../api/primitives` and `./vocabulary`.
 `upkeep.ts` and `reach.ts` import only `zod` and `../api/primitives`.
+`candidate-item.ts` imports only `zod`, `../api/primitives`, `./vocabulary`
+and `./relevance`.
 `relevance.ts` imports only `zod`.
 `vocabulary.ts` itself has no imports.

package/src/source-sync/__tests__/barrel.test.ts

@@ -18,6 +18,8 @@
  *   standing orders and the Drive-reach shapes.
  * - Every runtime name `relevance.ts` declares is reachable from the root as
  *   the same binding.
+ * - `DOCUMENT_TYPES` is reachable from the root as the same binding, and its
+ *   two types are named by the barrel.
  * - `ACTION_ITEM_KINDS` at the root carries `sourceSync.approval_pending`.
  * - The root re-exports the domain barrel explicitly.
  *
@@ -67,18 +69,20 @@ import type {
   SourceSyncStandingOrder,
   SourceSyncStandingOrdersResponse,
 } from "../../index";
+import * as candidateItem from "../candidate-item";
 import * as reach from "../reach";
 import * as relevance from "../relevance";
 import * as rules from "../rules";
 import * as schemas from "../schemas";
 import * as upkeep from "../upkeep";
+import * as vocabulary from "../vocabulary";
 
 /** Runtime names Release C adds, keyed to the module that declares them. */
 const RELEASE_C_RUNTIME_NAMES: ReadonlyArray<
   readonly [name: string, module: Record<string, unknown>]
 > = [
   ["SOURCE_SYNC_RISK_REASONS", schemas],
-  ["SourceSyncCandidateItemPatchSchema", schemas],
+  ["SourceSyncCandidateItemPatchSchema", candidateItem],
   ["SourceSyncAddCandidateRequestSchema", schemas],
   ["SourceSyncApproveRequestSchema", schemas],
   ["SourceSyncScopeApprovalSchema", schemas],
@@ -250,6 +254,12 @@ describe("source-sync Release C package surface", () => {
     }
   });
 
+  it("every document-type name is reachable from the root as the same binding", () => {
+    expect(rootBarrel.DOCUMENT_TYPES).toBe(vocabulary.DOCUMENT_TYPES);
+    expect([...barrelTypeExports]).toContain("DocumentType");
+    expect([...barrelTypeExports]).toContain("KnownDocumentType");
+  });
+
   it("exposes sourceSync.approval_pending in ACTION_ITEM_KINDS at the root", () => {
     expect(rootBarrel.ACTION_ITEM_KINDS).toContain(
       "sourceSync.approval_pending",