@company-semantics/contracts 99.3.0 → 100.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "99.3.0",
+  "version": "100.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 = 'c7651db1db74' as const;
-export const SPEC_HASH_FULL = 'c7651db1db74df7ba1f8d6ef92caef3024498071b187aa818640d98f2d90c037' as const;
+export const SPEC_HASH = '7e0143b235a3' as const;
+export const SPEC_HASH_FULL = '7e0143b235a3cc79cc020305bc8e4cf82c7784774cff280504fe70c0e9ee9a81' as const;

package/src/api/generated.ts

@@ -7469,10 +7469,11 @@ export interface components {
                 /** @enum {string} */
                 kind: "produced" | "empty" | "partial" | "stopped" | "failed" | "abandoned" | "unknown";
                 /** @enum {string} */
-                reason: "updates_ready" | "updates_applied" | "stopped_by_user" | "paused_billing" | "run_ceiling_reached" | "pricing_unconfigured" | "synthesis_incomplete" | "approval_mismatch" | "landing_refused" | "standing_order_refused" | "no_connection" | "source_sync_off" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
+                reason: "updates_ready" | "updates_ready_partial" | "updates_applied" | "stopped_by_user" | "paused_billing" | "run_ceiling_reached" | "pricing_unconfigured" | "synthesis_incomplete" | "approval_mismatch" | "landing_refused" | "standing_order_refused" | "no_connection" | "source_sync_off" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
                 facts: {
                     scopeCount: number;
                     violationCount: number;
+                    notLandedCount: number;
                 } | null;
                 disposition: {
                     /** @constant */
@@ -10848,6 +10849,8 @@ export interface components {
                     label: string;
                 } | null;
                 approvedAt: string | null;
+                approvable: boolean;
+                blockedReason: "needs_doc_access" | null;
             }[];
             discovery: {
                 foundThisRun: number;
@@ -10912,6 +10915,8 @@ export interface components {
                     label: string;
                 } | null;
                 approvedAt: string | null;
+                approvable: boolean;
+                blockedReason: "needs_doc_access" | null;
             }[];
             /** Format: uuid */
             workflowId: string;
@@ -11039,6 +11044,8 @@ export interface components {
                     label: string;
                 } | null;
                 approvedAt: string | null;
+                approvable: boolean;
+                blockedReason: "needs_doc_access" | null;
             }[];
         };
         SourceSyncApplyResponse: {
@@ -11098,6 +11105,8 @@ export interface components {
                     label: string;
                 } | null;
                 approvedAt: string | null;
+                approvable: boolean;
+                blockedReason: "needs_doc_access" | null;
             }[];
         };
         SourceSyncRulesResponse: {

package/src/source-sync/__tests__/scope-projection.test.ts

@@ -34,6 +34,8 @@ function scope(overrides: Record<string, unknown> = {}) {
     vacantHead: false,
     approvedBy: null,
     approvedAt: null,
+    approvable: true,
+    blockedReason: null,
     ...overrides,
   };
 }
@@ -100,6 +102,28 @@ describe("SourceSyncScopeApprovalProjectionSchema", () => {
   });
 });
 
+describe("approvable and blockedReason", () => {
+  it("accepts a visible scope the caller may not approve, with its reason", () => {
+    const parsed = SourceSyncScopeApprovalProjectionSchema.safeParse(
+      scope({ approvable: false, blockedReason: "needs_doc_access" }),
+    );
+    expect(parsed.success).toBe(true);
+  });
+
+  it("refuses a reason outside the vocabulary and a missing approvable", () => {
+    expect(
+      SourceSyncScopeApprovalProjectionSchema.safeParse(
+        scope({ approvable: false, blockedReason: "not_admin" }),
+      ).success,
+    ).toBe(false);
+    const { approvable: _omit, ...withoutApprovable } = scope();
+    expect(
+      SourceSyncScopeApprovalProjectionSchema.safeParse(withoutApprovable)
+        .success,
+    ).toBe(false);
+  });
+});
+
 describe("scopes is required on every checkpoint response", () => {
   const schemas = [
     ["candidate set", SourceSyncCandidateSetResponseSchema],

package/src/source-sync/index.ts

@@ -31,6 +31,7 @@ export type {
   SourceSyncDocDisposition,
   SourceSyncScopeApprovalState,
   SourceSyncScopeApproverKind,
+  SourceSyncScopeBlockedReason,
   DocumentType,
   KnownDocumentType,
   OperatingKnowledgeFamily,
@@ -47,6 +48,7 @@ export {
   SOURCE_SYNC_DOC_DISPOSITIONS,
   SOURCE_SYNC_SCOPE_APPROVAL_STATES,
   SOURCE_SYNC_SCOPE_APPROVER_KINDS,
+  SOURCE_SYNC_SCOPE_BLOCKED_REASONS,
   DOCUMENT_TYPES,
   OPERATING_KNOWLEDGE_FAMILIES,
 } from "./vocabulary";

package/src/source-sync/schemas.ts

@@ -26,6 +26,7 @@ import {
   SOURCE_SYNC_DOC_RISKS,
   SOURCE_SYNC_SCOPE_APPROVAL_STATES,
   SOURCE_SYNC_SCOPE_APPROVER_KINDS,
+  SOURCE_SYNC_SCOPE_BLOCKED_REASONS,
 } from "./vocabulary";
 import { CandidateDiscoverySummarySchema } from "./relevance";
 import { SourceSyncCandidateItemSchema } from "./candidate-item";
@@ -45,6 +46,13 @@ const PersonLabel = z.string().min(1).max(255);
  *   still a `unit_head` scope, `assignedTo` is null, and the org's admins approve it.
  * - An approved scope reports the routing its approval RECORDED; a later head
  *   change does not rewrite it. A pending scope reports its routing as of now.
+ * - `approvable` is whether THE CALLER may approve this pending scope now. A scope
+ *   can be visible but not approvable: approving needs the caller's own upload and
+ *   edit access on the scope's document, because landing and apply act as the
+ *   approver. `blockedReason` is non-null exactly when a pending scope is not
+ *   approvable; an approved scope is never approvable and carries null. At the
+ *   synthesis checkpoint a pending scope is approvable: apply is decided per
+ *   document by the edit policy, which approving the candidate set required.
  */
 export const SourceSyncScopeApprovalProjectionSchema = z.object({
   /** 'company' or 'unit:<uuid>'. */
@@ -62,6 +70,8 @@ export const SourceSyncScopeApprovalProjectionSchema = z.object({
   /** Non-null exactly when a person's approval is recorded. */
   approvedBy: z.object({ label: PersonLabel }).nullable(),
   approvedAt: IsoDateTime.nullable(),
+  approvable: z.boolean(),
+  blockedReason: z.enum(SOURCE_SYNC_SCOPE_BLOCKED_REASONS).nullable(),
 });
 
 /** The discovery run a person started, or that upkeep started on a schedule. */

package/src/source-sync/vocabulary.ts

@@ -111,6 +111,16 @@ export const SOURCE_SYNC_SCOPE_APPROVER_KINDS = [
 export type SourceSyncScopeApproverKind =
   (typeof SOURCE_SYNC_SCOPE_APPROVER_KINDS)[number];
 
+/**
+ * Why the CALLER may not approve a scope they can see. `needs_doc_access`: the
+ * landing and the apply act as the approver, so approving needs the caller's own
+ * upload and edit access on the scope's document (an admin holds only metadata
+ * access to company.md content).
+ */
+export const SOURCE_SYNC_SCOPE_BLOCKED_REASONS = ["needs_doc_access"] as const;
+export type SourceSyncScopeBlockedReason =
+  (typeof SOURCE_SYNC_SCOPE_BLOCKED_REASONS)[number];
+
 /**
  * What a source IS — a STRUCTURAL name the model observes, never a relevance verdict
  * (control ADR source-discovery-observation-vs-policy). The set names operating

package/src/workflows/deferred-route.ts

@@ -147,6 +147,8 @@ export const SYNTHESIZE_DEFERRED_ROUTE_OF_REASON = {
   // prettier-ignore
   updates_ready: { route: "covered", by: "sourceSync.review_ready", fallback: "notice", audience: "creator" },
   // prettier-ignore
+  updates_ready_partial: { route: "covered", by: "sourceSync.review_ready", fallback: "notice", audience: "creator" },
+  // prettier-ignore
   updates_applied: { route: "covered", by: "sourceSync.docs_updated", fallback: "notice", audience: "creator" },
   stopped_by_user: STOPPED,
   paused_billing: EXPLAINED,

package/src/workflows/outcome-reasons.ts

@@ -120,6 +120,8 @@ export type DiscoverOutcomeFacts = z.infer<typeof DiscoverOutcomeFactsSchema>;
 /** Why a synthesis (landing then drafting) run ended the way it did. */
 export const SYNTHESIZE_OUTCOME_KIND_OF_REASON = {
   updates_ready: "produced",
+  /** Drafted from what landed; some approved files could not be brought in. */
+  updates_ready_partial: "partial",
   updates_applied: "produced",
   stopped_by_user: "stopped",
   paused_billing: "failed",
@@ -142,6 +144,7 @@ export type SynthesizeOutcomeReason =
 /** What each synthesis ending offers. TOTAL; an empty list is explicit. */
 export const SYNTHESIZE_AFFORDANCES_OF_REASON = {
   updates_ready: [],
+  updates_ready_partial: [],
   updates_applied: [],
   stopped_by_user: [],
   paused_billing: [OPEN_BILLING],
@@ -168,6 +171,8 @@ export const SynthesizeOutcomeFactsSchema = z
     scopeCount: Count,
     /** Authority or size violations that left the batch incomplete. */
     violationCount: Count,
+    /** Approved files to attach that did not land (refused, unreadable, gone). */
+    notLandedCount: Count,
   })
   .strict();