@company-semantics/contracts 93.0.0 → 93.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "93.0.0",
+  "version": "93.1.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -168,7 +168,7 @@
   "pnpm": {
     "overrides": {
       "brace-expansion@<5.0.11": ">=5.0.11",
-      "smol-toml@<1.7.1": ">=1.7.1",
+      "smol-toml@<1.9.0": ">=1.9.0",
       "minimatch@<10.2.3": ">=10.2.3",
       "nanoid@<3.3.18": ">=3.3.18",
       "js-yaml@>=4.0.0 <4.3.2": ">=4.3.2 <5.0.0",
@@ -181,7 +181,8 @@
       "postcss@<8.5.23": ">=8.5.23",
       "source-map-js@<1.2.2": ">=1.2.2",
       "markdown-it@<14.2.0": ">=14.2.0",
-      "@humanfs/node@<0.16.8": ">=0.16.8 <0.17.0"
+      "@humanfs/node@<0.16.8": ">=0.16.8 <0.17.0",
+      "katex@<0.18.2": ">=0.18.2 <0.19.0"
     }
   },
   "lint-staged": {
@@ -189,5 +190,5 @@
     "*.md": "markdownlint-cli2",
     "package.json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\""
   },
-  "securityRequirementsVersion": "4b88755e9a43a82b2f5eb55b953581526f1982de362da77bc579888d1f6a1bb0"
+  "securityRequirementsVersion": "71a26f10642b9fc598f6da99c75200fd174ebd0e6a9e32437a3f1b245e906792"
 }

package/src/__tests__/resource-keys.test.ts

@@ -157,6 +157,7 @@ describe("resource-keys: system-scoped internalAdmin* types", () => {
     "factoryFloor",
     "factorySnapshot",
     "factoryKpis",
+    "factoryLineage",
   ] as const;
 
   for (const type of systemTypes) {

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 = '4eb1b17b3340' as const;
-export const SPEC_HASH_FULL = '4eb1b17b3340b7613c5f8189f7fef55164ea1d859c67b31790297ce5709b2db4' as const;
+export const SPEC_HASH = 'aebd06a13983' as const;
+export const SPEC_HASH_FULL = 'aebd06a139833549518e70adbcd3af333598cf06fa6669a838f605231395c8cf' as const;

package/src/api/generated.ts

@@ -3911,6 +3911,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/factory/lineage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read change lineage: each release with its commits, PRDs, workers, run and health */
+        get: operations["factoryLineage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/factory/quality/changes": {
         parameters: {
             query?: never;
@@ -6893,6 +6910,13 @@ export interface components {
                         requiredScope?: string;
                     };
                 };
+                workspace?: {
+                    manageSettings: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
+                };
             };
             chatMentions: boolean;
             chatMultiParty: boolean;
@@ -9253,6 +9277,11 @@ export interface components {
                     };
                     eventTimestamp: string;
                 }[];
+                pausedAuth?: {
+                    since: string;
+                    lane: number;
+                    reason: string | null;
+                } | null;
             }[];
         };
         FactorySnapshotResponse: {
@@ -9389,6 +9418,49 @@ export interface components {
                 [key: string]: unknown;
             } | null;
         };
+        FactoryLineageResponse: {
+            releases: {
+                key: string;
+                manifestId: string | null;
+                stationId: string;
+                /** @enum {string} */
+                status: "in_progress" | "applied" | "rolled_back";
+                intendedAt: string | null;
+                appliedAt: string | null;
+                durationMs: number | null;
+                surfaces: string[];
+                shas: {
+                    [key: string]: string;
+                } | null;
+                run: {
+                    id: string;
+                    attempt: number;
+                    repository: string;
+                    url: string;
+                } | null;
+                health: {
+                    /** @enum {string} */
+                    releaseInvariant: "ok" | "failed" | "unproven" | "unknown";
+                    /** @enum {string} */
+                    windowMetric: "ok" | "failed" | "unproven" | "unknown";
+                    /** @enum {string} */
+                    pointProbe: "ok" | "failed" | "unproven" | "unknown";
+                    rolledBack: boolean;
+                } | null;
+                commitsRecorded: boolean;
+                changesTruncated: boolean;
+                changes: {
+                    repo: string;
+                    sha: string;
+                    prdId: string | null;
+                    pr: number | null;
+                    worker: {
+                        stationId: string;
+                        executorId: string;
+                    } | null;
+                }[];
+            }[];
+        };
         CreateQualityChangeResponse: {
             /** Format: uuid */
             planId: string;
@@ -17897,6 +17969,43 @@ export interface operations {
             };
         };
     };
+    factoryLineage: {
+        parameters: {
+            query?: {
+                limit?: number;
+                prdId?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Lineage records, newest release first */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FactoryLineageResponse"];
+                };
+            };
+            /** @description Not authenticated */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Not an internal admin */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     createQualityChange: {
         parameters: {
             query?: never;

package/src/chat/__tests__/page-context.test.ts

@@ -23,13 +23,21 @@
  *   no-sibling-imports invariant intact (the same pattern as
  *   runtime-profile.test.ts).
  *
- * It is skipped when the app is not checked out beside this repo — contracts
- * consumed standalone from npm, or contracts CI, which by design has no app
- * checkout because contracts is the root of the dependency tree. The inverted
- * marker test makes the reporter say so rather than showing a silent pass.
+ * Where the app is read from: `resolveSibling` (tests/workspace-sibling.ts), the
+ * workspace's sibling rule (ci ADR-CI-276): this session's app worktree when
+ * the session holds one, else app's committed origin/main; never a primary's
+ * working tree. It used to probe `<workspace>/company-semantics-app` (the
+ * PRIMARY) and `../company-semantics-app` from cwd for
+ * `src/platform/route-parser.ts`, a path app has since moved to
+ * `src/lib/nav/route-parser.ts`, so it skipped everywhere (ci ADR-CI-294
+ * follow-up). A moved file now fails the read.
+ *
+ * Inside the workspace a missing or unreadable app FAILS this file. The parity
+ * tests skip, and the inverted marker test says why, only in a standalone
+ * clone (no other company-semantics-* checkout beside it): contracts consumed
+ * from npm, or contracts CI, which by design has no app checkout because
+ * contracts is the root of the dependency tree.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { resolve, sep } from "node:path";
 import { describe, it, expect } from "vitest";
 import {
   ChatPageContextSchema,
@@ -37,6 +45,7 @@ import {
   CHAT_PAGE_SCOPES,
   CHAT_PAGE_ENTITY_TYPES,
 } from "../schemas.js";
+import { resolveSibling } from "../../../tests/workspace-sibling.js";
 
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -56,52 +65,22 @@ const A_DOCUMENT_BODY = `# Q3 plan\n${"Revenue grew. ".repeat(200)}`;
 // Locating the app checkout that governs this run
 // ---------------------------------------------------------------------------
 
-/**
- * Probed in order:
- *   1. The app worktree mirroring this one. Ralph checks the same branch of
- *      every repo out at the same relative path, so a contracts worktree has an
- *      app worktree beside it carrying the branch's route grammar. The app MAIN
- *      checkout sits on another branch entirely, and comparing against it would
- *      report drift for a value this branch already corrected.
- *   2. The app main checkout in the same workspace.
- *   3. The plain sibling guess, for a non-worktree local dev layout.
- */
-function resolveAppRoot(): string | undefined {
-  const candidates: string[] = [];
-
-  const segments = process.cwd().split(sep);
-  const contractsIdx = segments.lastIndexOf("company-semantics-contracts");
-  if (contractsIdx !== -1) {
-    const workspaceRoot = segments.slice(0, contractsIdx).join(sep);
-    const worktreeSuffix = segments.slice(contractsIdx + 1);
-    const appRoot = resolve(workspaceRoot, "company-semantics-app");
-    if (worktreeSuffix.length > 0) {
-      candidates.push(resolve(appRoot, ...worktreeSuffix));
-    }
-    candidates.push(appRoot);
-  }
-  candidates.push(resolve(process.cwd(), "..", "company-semantics-app"));
-
-  return candidates.find((root) =>
-    existsSync(resolve(root, "src", "platform", "route-parser.ts")),
-  );
-}
+const APP_ROUTE_PARSER = "src/lib/nav/route-parser.ts";
 
-const APP_ROOT = resolveAppRoot();
-const appAvailable = APP_ROOT !== undefined;
+// Throws (failing this file loudly) inside the workspace when the app cannot
+// be resolved; null only in a standalone clone.
+const app = await resolveSibling("company-semantics-app");
+const appAvailable = app !== null;
 
 /** The body of the app's `export type Route = ...;` union, as a string. */
 function appRouteUnionSource(): string {
-  const source = readFileSync(
-    resolve(APP_ROOT!, "src", "platform", "route-parser.ts"),
-    "utf8",
-  );
+  const source = app!.read(APP_ROUTE_PARSER);
   // Terminated by the blank line after the union, because `;` also ends every
   // member field inside it.
   const match = source.match(/export type Route =([\s\S]*?);\r?\n\r?\n/);
   if (!match?.[1]) {
     throw new Error(
-      "Could not locate the `Route` union in app src/platform/route-parser.ts. " +
+      `Could not locate the \`Route\` union in app ${APP_ROUTE_PARSER}. ` +
         "If the declaration was renamed or restructured, update this test — do " +
         "NOT delete it, or the view vocabulary can drift out of step unseen.",
     );

package/src/chat/__tests__/runtime-profile.test.ts

@@ -18,59 +18,35 @@
  *   imports, keeping the contracts no-sibling-imports invariant intact (the
  *   same pattern as tests/org/reserved-slug-roundtrip.test.ts).
  *
- * They are skipped when the backend is not checked out beside this repo — e.g.
- * contracts consumed standalone from npm, or contracts CI, which by design has
- * no backend checkout because contracts is the root of the dependency tree.
- * Drift introduced on the backend side is therefore NOT gated by contracts CI;
- * it is caught here in a workspace checkout, and the inverted marker test below
- * makes the reporter say so rather than showing a silent pass.
+ * Where the backend is read from: `resolveSibling` (tests/workspace-sibling.ts),
+ * the workspace's sibling rule (ci ADR-CI-276): this session's backend worktree
+ * when the session holds one, else backend's committed origin/main; never a
+ * primary's working tree, which may hold another session's uncommitted work.
+ * It used to probe `<workspace>/company-semantics-backend` (the PRIMARY) and
+ * `../company-semantics-backend` from cwd (ci ADR-CI-294 follow-up).
+ *
+ * Inside the workspace a missing or unreadable backend FAILS this file. The
+ * parity tests skip, and the inverted marker test says why, only in a
+ * standalone clone (no other company-semantics-* checkout beside it): contracts
+ * consumed from npm, or contracts CI, which by design has no backend checkout
+ * because contracts is the root of the dependency tree. Drift introduced on the
+ * backend side is therefore NOT gated by contracts CI; it is caught here in a
+ * workspace checkout.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { resolve, sep } from "node:path";
 import { describe, it, expect } from "vitest";
 import {
   CHAT_RUNTIME_PROFILES,
   DEFAULT_CHAT_RUNTIME_PROFILE,
 } from "../runtime-profile.js";
+import { resolveSibling } from "../../../tests/workspace-sibling.js";
 
-/**
- * Locate the backend checkout that governs this run.
- *
- * Probed in order:
- *   1. The backend worktree mirroring this one. Ralph checks the same branch of
- *      every repo out at the same relative path, so a contracts worktree has a
- *      backend worktree beside it carrying the branch's constants. The backend
- *      MAIN checkout sits on another branch entirely, and comparing against it
- *      would report drift for a value this branch already corrected.
- *   2. The backend main checkout in the same workspace.
- *   3. The plain sibling guess, for a non-worktree local dev layout.
- */
-function resolveBackendRoot(): string | undefined {
-  const candidates: string[] = [];
-
-  const segments = process.cwd().split(sep);
-  const contractsIdx = segments.lastIndexOf("company-semantics-contracts");
-  if (contractsIdx !== -1) {
-    const workspaceRoot = segments.slice(0, contractsIdx).join(sep);
-    const worktreeSuffix = segments.slice(contractsIdx + 1);
-    const backendRoot = resolve(workspaceRoot, "company-semantics-backend");
-    if (worktreeSuffix.length > 0) {
-      candidates.push(resolve(backendRoot, ...worktreeSuffix));
-    }
-    candidates.push(backendRoot);
-  }
-  candidates.push(resolve(process.cwd(), "..", "company-semantics-backend"));
-
-  return candidates.find((root) =>
-    existsSync(resolve(root, "src", "chat", "orchestrator", "factory.ts")),
-  );
-}
-
-const BACKEND_ROOT = resolveBackendRoot();
-const backendAvailable = BACKEND_ROOT !== undefined;
+// Throws (failing this file loudly) inside the workspace when the backend
+// cannot be resolved; null only in a standalone clone.
+const backend = await resolveSibling("company-semantics-backend");
+const backendAvailable = backend !== null;
 
 function readBackendSource(...relative: string[]): string {
-  return readFileSync(resolve(BACKEND_ROOT!, ...relative), "utf8");
+  return backend!.read(relative.join("/"));
 }
 
 /** Extract the single capture of `pattern`, or explain what moved. */

package/src/generated/openapi-routes.ts

@@ -95,6 +95,7 @@ export const openApiRoutes = {
   '/api/executions/{executionId}/undo': ['POST'],
   '/api/factory/floor': ['GET'],
   '/api/factory/kpis': ['GET'],
+  '/api/factory/lineage': ['GET'],
   '/api/factory/quality/changes': ['POST'],
   '/api/factory/quality/corpus': ['GET'],
   '/api/factory/quality/deployments': ['POST'],

package/src/resource-key-tables.ts

@@ -161,6 +161,7 @@ export const SYSTEM_SCOPED_TYPES = [
   "factoryFloor",
   "factorySnapshot",
   "factoryKpis",
+  "factoryLineage",
 ] as const satisfies readonly SystemScopedType[];
 
 /** Every literal `fromQueryKey` can route, across all five tables. */

package/src/resource-key-types.ts

@@ -157,6 +157,9 @@ export type ResourceKey =
   // `useResource` disables a query whose `toQueryKey` throws, the panel it backs
   // never fetched at all. An unregistered key is not a stale read, it is no read.
   | { type: "factoryKpis"; scope: "system" }
+  // Change lineage over the release ledger (ADR-CONTRACTS-222, backend
+  // ADR-BE-926): each release with its commits, PRDs, workers, run and health.
+  | { type: "factoryLineage"; scope: "system" }
   // Everything awaiting the viewer's decision, across every domain
   // (ADR-CONT-104). ORG-scoped, not user-scoped, even though the content is
   // per-viewer: the bucket differs per org, so a user-keyed entry would serve

package/src/resource-keys.ts

@@ -137,6 +137,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "factoryFloor":
     case "factorySnapshot":
     case "factoryKpis":
+    case "factoryLineage":
       return [key.type, key.scope] as const;
 
     default: {