@company-semantics/contracts 62.3.0 → 62.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "62.3.0",
+  "version": "62.4.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 = '6936b8c0f7c6' as const;
-export const SPEC_HASH_FULL = '6936b8c0f7c66b91f7498524d0d08f87039e0626f300e94c160e7f005fa85e95' as const;
+export const SPEC_HASH = 'bd8b060aedb2' as const;
+export const SPEC_HASH_FULL = 'bd8b060aedb2cd35af45ee8c8b0e1dc97da92305f985757cd19a57fbd44866e3' as const;

package/src/api/generated.ts

@@ -4068,6 +4068,7 @@ export interface components {
                 /** @enum {string} */
                 origin?: "user" | "proactive";
                 unread?: boolean;
+                compactedThroughSequence?: number | null;
             };
             messages: {
                 id: string;

package/src/chat/README.md

@@ -22,6 +22,8 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - Page context carries IDENTIFIERS ONLY. Content reaches the model through tools, which apply resource-native read authority per the backend ADR slug `retrieval-source-authority-contract`; a body injected here would bypass the source's own check for a reader who may not be allowed to see it. There is deliberately no display-name field either — where a human-readable name is wanted, the server resolves it from the id through the owning source (ADR-CONTRACTS-153)
 - Page context carries NO FREE-FORM TEXT. Its values are caller-controlled — they arrive in an HTTP request body — and the server renders them into a `{role:"system"}` message it authored. `.strict()` rejects unknown KEYS and says nothing about adversarial VALUES, so every field is an enum, a bounded pattern, or an opaque id. The channel carries operator authority; the values in it do not inherit it
 - Page context carries NO ORG IDENTITY, though the app's org routes have one in the URL. Org scope is derived from the session; a request-supplied org identifier would be an authority claim in a field the server otherwise reads for itself
+- `compactedThroughSequence` on the chat detail is ABSENT or NULL exactly when the conversation has never been compacted. It is never coerced to `0` — sequence numbers are zero-indexed, so `0` is a boundary a chat can really have, and a zero default would make "never compacted" indistinguishable from "compacted through sequence 0". It is optional for the same reason `proactiveKind` is a bare string: a client that does not know the field renders the transcript exactly as before (ADR-CONTRACTS-154)
+- `compactedThroughSequence` is a BOUNDARY MARKER, not a context gauge. It is the one sequence number the summary covers through — never a token count, never a percentage of the context window, and never the summary text itself. The reader's question it answers is "why did it forget the beginning", not "how full is the window" (ADR-CONTRACTS-154)
 - `CHAT_PAGE_VIEWS` and `CHAT_PAGE_SCOPES` are a projection of the app's `Route` union (`company-semantics-app/src/platform/route-parser.ts`), not a parallel vocabulary. A view the parser can emit but the schema rejects fails the send outright rather than degrading
 
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->

package/src/chat/__tests__/compaction-boundary.test.ts

@@ -0,0 +1,121 @@
+/**
+ * `ChatDetail.compactedThroughSequence` — a boundary marker, not a gauge.
+ *
+ * INVARIANTS TESTED:
+ * - ABSENT or NULL means the conversation has never been compacted. Both
+ *   spellings are accepted and both parse to "no boundary": a serializer may
+ *   omit the key or send an explicit null, and neither may become `0`.
+ * - `0` is a REAL boundary, distinguishable from "never compacted". Sequence
+ *   numbers are zero-indexed, so a chat compacted through its first message
+ *   carries `0` — which is exactly why the field is nullable rather than
+ *   defaulted (ADR-CONTRACTS-154).
+ * - The field is OPTIONAL, so a detail produced by an older backend still
+ *   parses and a client that ignores it renders the transcript as before.
+ * - It is an INTEGER sequence number and nothing else. A fractional value is
+ *   refused, and no token-count / percentage sibling exists to be read instead.
+ *
+ * Why this is asserted on the schema rather than left to the serializer:
+ *   the difference between `null` and `0` is invisible at a glance and fails
+ *   silently in the direction that looks correct — every never-compacted chat
+ *   grows a marker. A default of `0` anywhere on this path would be caught by
+ *   nothing else, so the wire shape states the distinction itself.
+ */
+import { describe, expect, it } from "vitest";
+import { ChatDetailSchema, GetChatResponseSchema } from "../schemas.js";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+/** A chat detail with every REQUIRED field and no compaction boundary. */
+const BASE_DETAIL = {
+  id: "chat_1",
+  title: "A long conversation",
+  interactionId: "int_1",
+  createdAt: "2026-08-31T00:00:00.000Z",
+  updatedAt: "2026-08-31T01:00:00.000Z",
+};
+
+describe("ChatDetail compaction boundary", () => {
+  it("an absent compaction boundary means never compacted", () => {
+    const parsed = ChatDetailSchema.parse(BASE_DETAIL);
+
+    // Absent, not zero. A `0` here would be indistinguishable from a chat
+    // compacted through sequence 0, which is a state that really exists.
+    expect(parsed.compactedThroughSequence).toBeUndefined();
+    expect(parsed.compactedThroughSequence ?? null).toBeNull();
+    expect(parsed.compactedThroughSequence).not.toBe(0);
+  });
+
+  it("an explicit null means never compacted too", () => {
+    const parsed = ChatDetailSchema.parse({
+      ...BASE_DETAIL,
+      compactedThroughSequence: null,
+    });
+
+    expect(parsed.compactedThroughSequence).toBeNull();
+    expect(parsed.compactedThroughSequence ?? null).toBeNull();
+  });
+
+  it("sequence zero is a real boundary, not an absence", () => {
+    const parsed = ChatDetailSchema.parse({
+      ...BASE_DETAIL,
+      compactedThroughSequence: 0,
+    });
+
+    expect(parsed.compactedThroughSequence).toBe(0);
+    // The distinction the nullability exists to preserve.
+    expect(parsed.compactedThroughSequence).not.toBeNull();
+    expect(parsed.compactedThroughSequence).not.toBeUndefined();
+  });
+
+  it("carries the boundary sequence number when the chat has been compacted", () => {
+    const parsed = ChatDetailSchema.parse({
+      ...BASE_DETAIL,
+      compactedThroughSequence: 42,
+    });
+
+    expect(parsed.compactedThroughSequence).toBe(42);
+  });
+
+  it("is an integer sequence number, never a fraction", () => {
+    expect(
+      ChatDetailSchema.safeParse({
+        ...BASE_DETAIL,
+        compactedThroughSequence: 1.5,
+      }).success,
+    ).toBe(false);
+  });
+
+  it("is a boundary marker, not a context gauge", () => {
+    const shape = Object.keys(ChatDetailSchema.shape);
+
+    // The published fact is one sequence number. No token count, no percentage
+    // of the context window, and not the summary text (ADR-CONTRACTS-154).
+    expect(shape).toContain("compactedThroughSequence");
+    for (const gauge of [
+      "contextTokens",
+      "contextUsage",
+      "contextPercent",
+      "tokenCount",
+      "contextSummary",
+    ]) {
+      expect(shape).not.toContain(gauge);
+    }
+  });
+
+  it("a detail from an older backend still parses", () => {
+    // The field is optional precisely so this stays true: a client that does
+    // not know it renders the transcript exactly as it did before.
+    expect(ChatDetailSchema.safeParse(BASE_DETAIL).success).toBe(true);
+  });
+
+  it("rides the chat detail in GET /api/chats/:id", () => {
+    const parsed = GetChatResponseSchema.parse({
+      chat: { ...BASE_DETAIL, compactedThroughSequence: 7 },
+      messages: [],
+    });
+
+    expect(parsed.chat.compactedThroughSequence).toBe(7);
+  });
+});

package/src/chat/schemas.ts

@@ -335,6 +335,26 @@ export const ChatDetailSchema = z.object({
   // a list concern (the sidebar row) and does not ride the detail.
   origin: proactiveChatFields.origin,
   unread: proactiveChatFields.unread,
+  /**
+   * The message sequence number the conversation's compacted summary covers
+   * THROUGH — a boundary marker, not a context gauge.
+   *
+   * ABSENT or NULL means the conversation has never been compacted. The
+   * nullability is load-bearing and must survive to the wire: a zero default
+   * would make "never compacted" indistinguishable from "compacted through
+   * sequence 0", and sequence numbers are zero-indexed, so 0 is a real
+   * boundary a chat can actually have.
+   *
+   * OPTIONAL for the same forward-compatibility reason `proactiveKind` is a
+   * bare string: a client that does not know this field renders the transcript
+   * exactly as it did before, rather than rejecting the whole detail.
+   *
+   * Deliberately the boundary and NOTHING else — no token count, no
+   * percentage-of-window, and not the summary text. The reader's question is
+   * why the model forgot the beginning, not how full the window is
+   * (ADR-CONTRACTS-154).
+   */
+  compactedThroughSequence: z.number().int().nullable().optional(),
 });
 
 /** Response for GET /api/chats/:id */

package/src/index.ts

@@ -1024,6 +1024,9 @@ export type {
   InteractiveTaskData,
   InteractiveTaskPart,
   InteractiveTaskDataPart,
+  StructureReviewData,
+  StructureReviewPart,
+  StructureReviewDataPart,
   // Suggested replies surface types (non-governed chips, PRD-00958)
   SuggestedReply,
   SuggestedRepliesData,

package/src/message-parts/README.md

@@ -66,6 +66,9 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 - `StatusPanelEntry` _(type)_ — Single entry in a status panel.
 - `StatusPanelPart` _(type)_ — Status panel surface part.
 - `StreamPhase` _(type)_ — Derived stream phase for UI state management.
+- `StructureReviewData` _(type)_ — Structure review surface data payload — the anchor's handle and its intro-coherence counts.
+- `StructureReviewDataPart` _(type)_ — Structure review data part (wire format).
+- `StructureReviewPart` _(type)_ — Structure review message part (semantic type).
 - `SuggestedRepliesData` _(type)_ — Suggested replies surface data payload.
 - `SuggestedRepliesDataPart` _(type)_ — Wire form, as persisted in `chat_messages.parts`.
 - `SuggestedRepliesPart` _(type)_ — Normalized form, as rendered.

package/src/message-parts/__tests__/structure-review.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import { WireSurfaceBuilder } from "../wire";
+import type { StructureReviewData } from "../structure-review";
+
+describe("WireSurfaceBuilder.structureReview", () => {
+  const data: StructureReviewData = {
+    proposalId: "42202e9f-0000-0000-0000-000000000000",
+    stepCount: 4,
+    withheldCount: 5,
+  };
+
+  it("returns data part with type data-structure-review", () => {
+    const result = WireSurfaceBuilder.structureReview(data);
+    expect(result.type).toBe("data-structure-review");
+  });
+
+  it("data matches input StructureReviewData exactly", () => {
+    const result = WireSurfaceBuilder.structureReview(data);
+    expect(result.data).toEqual(data);
+  });
+
+  // The part is an ANCHOR: a handle plus intro-coherence counts and nothing
+  // else. Pinning the key set catches the two documented regressions — a
+  // mutation precondition (expectedInputHash/expectedStructureRevision) or an
+  // endpoint creeping onto a durably persisted, share-visible payload.
+  it("carries only the anchor fields (no hashes, no endpoints, no cards)", () => {
+    const result = WireSurfaceBuilder.structureReview(data);
+    expect(Object.keys(result.data).sort()).toEqual([
+      "proposalId",
+      "stepCount",
+      "withheldCount",
+    ]);
+  });
+});

package/src/message-parts/index.ts

@@ -56,6 +56,13 @@ export type {
   InteractiveTaskDataPart,
 } from "./interactive";
 
+// Structure review surface types (governed anchor; sibling of interactive)
+export type {
+  StructureReviewData,
+  StructureReviewPart,
+  StructureReviewDataPart,
+} from "./structure-review";
+
 // Suggested replies surface types (non-governed chips)
 export type {
   SuggestedReply,

package/src/message-parts/structure-review.ts

@@ -0,0 +1,64 @@
+/**
+ * Structure Review Surface Types
+ *
+ * The chat anchor for the org-structure review stepper: analysis completes,
+ * the assistant introduces what it found, and this part is where the
+ * interactive review lives. It is a SIBLING of `preview` / `confirmation` /
+ * `interactive` — governed (it counts against the at-most-one-governed-surface
+ * -per-turn rule) but deliberately NOT an InteractiveTaskKind, because its
+ * submit is a domain apply with its own receipt and concurrency fences, not a
+ * governance-engine execution.
+ *
+ * STRUCTURE REVIEW INVARIANTS:
+ * - The part is an ANCHOR, not the stepper. It carries a handle; the surface
+ *   is assembled client-side from a live, authorized proposal read. Never
+ *   inline the presented cards here: chat parts are durably persisted and
+ *   reach share viewers verbatim, while presentations are recomputed at read
+ *   time and scope-gated.
+ * - The durable part contains NO mutation preconditions. `expectedInputHash`
+ *   and `expectedStructureRevision` always come from the same live read that
+ *   produced the cards being acted on — never from this part.
+ * - No endpoints. The consuming app's domain API module owns them; an
+ *   `applyEndpoint` here would imply generic-surface semantics this part does
+ *   not have (its submit is a domain route, not a governance submit).
+ * - `stepCount` / `withheldCount` are intro-coherence hints fixed at emission
+ *   time: a differing live count means "the decision count changed since the
+ *   introduction" (a display notice), while a differing proposalId means the
+ *   review was superseded. They are counts, and cannot detect N questions
+ *   becoming N different questions — the surface's questionId-keyed
+ *   reconciliation handles that.
+ * - Emission is orchestration-driven (a typed launch), never a model choice.
+ *
+ * @see the contracts ADR for this surface for design rationale
+ */
+
+/**
+ * Structure review surface data payload — the anchor's handle and its
+ * intro-coherence counts. All fields required: the counts are non-sensitive
+ * and fixed at emission time, and the coherence check depends on them.
+ */
+export interface StructureReviewData {
+  /** The org-structure proposal this review addresses. */
+  proposalId: string;
+  /** Answerable questions at emit time (defective and withheld items excluded). */
+  stepCount: number;
+  /** Questions withheld or defective at emit time — disclosed, never hidden. */
+  withheldCount: number;
+}
+
+/**
+ * Structure review message part (semantic type).
+ */
+export interface StructureReviewPart {
+  type: "structure-review";
+  data: StructureReviewData;
+}
+
+/**
+ * Structure review data part (wire format).
+ * Uses AI SDK's data-{name} convention.
+ */
+export interface StructureReviewDataPart {
+  type: "data-structure-review";
+  data: StructureReviewData;
+}

package/src/message-parts/types.ts

@@ -17,6 +17,7 @@ import type { ToolListMessagePart } from "../mcp/index";
 import type { PreviewPart } from "./preview";
 import type { ConfirmationPart } from "./confirmation";
 import type { InteractiveTaskPart } from "./interactive";
+import type { StructureReviewPart } from "./structure-review";
 import type { SuggestedRepliesPart } from "./suggested-replies";
 
 // =============================================================================
@@ -126,6 +127,7 @@ export type SurfacePart =
   | ConfirmationPart
   | PreviewPart
   | InteractiveTaskPart
+  | StructureReviewPart
   | SuggestedRepliesPart;
 
 /**

package/src/message-parts/wire.ts

@@ -17,6 +17,10 @@ import type {
   InteractiveTaskData,
   InteractiveTaskDataPart,
 } from "./interactive";
+import type {
+  StructureReviewData,
+  StructureReviewDataPart,
+} from "./structure-review";
 import type {
   SuggestedRepliesData,
   SuggestedRepliesDataPart,
@@ -116,6 +120,28 @@ export const WireSurfaceBuilder = {
     };
   },
 
+  /**
+   * Build a structure-review data part for streaming.
+   * The anchor for the org-structure review stepper: a handle plus
+   * intro-coherence counts, assembled into a surface client-side from a live
+   * authorized proposal read.
+   *
+   * INVARIANTS:
+   * - Governed: counts against the at-most-one-governed-surface-per-turn rule
+   * - Anchor only: never inline presented cards, endpoints, or staleness
+   *   hashes (mutation preconditions come from the live read)
+   * - Emission is orchestration-driven (a typed launch), never a model choice
+   *
+   * @param data - Structure review data (proposalId + counts)
+   * @returns Wire-format structure review part ready for stream
+   */
+  structureReview(data: StructureReviewData): StructureReviewDataPart {
+    return {
+      type: "data-structure-review",
+      data,
+    };
+  },
+
   /**
    * Build a suggested-replies data part for streaming.
    * Chips beneath an assistant turn that each fire an ORDINARY user turn.