@company-semantics/contracts 99.3.0 → 101.0.0

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";
@@ -190,7 +192,9 @@ export type {
   SourceSyncFindingsResponse,
   SourceSyncDismissFindingRequest,
   SourceSyncAutoApplyCeiling,
+  SourceSyncStandingOrderSuspendedReason,
   SourceSyncStandingOrder,
+  SourceSyncStandingOrderGrantability,
   SourceSyncStandingOrdersResponse,
   SourceSyncPutStandingOrderRequest,
 } from "./upkeep";
@@ -201,7 +205,9 @@ export {
   SourceSyncFindingsResponseSchema,
   SourceSyncDismissFindingRequestSchema,
   SOURCE_SYNC_AUTO_APPLY_CEILINGS,
+  SOURCE_SYNC_STANDING_ORDER_SUSPENDED_REASONS,
   SourceSyncStandingOrderSchema,
+  SourceSyncStandingOrderGrantabilitySchema,
   SourceSyncStandingOrdersResponseSchema,
   SourceSyncPutStandingOrderRequestSchema,
 } from "./upkeep";

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,16 @@ 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 approval authority on the
+ *   scope AND 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 BY THE CALLER:
+ *   `needs_approval_authority` (no approval authority: e.g. an org admin, who
+ *   coordinates and never approves) or `needs_doc_access`. 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 +73,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/upkeep.ts

@@ -18,6 +18,7 @@
 
 import { z } from "zod";
 import { IsoDateTime } from "../api/primitives";
+import { SOURCE_SYNC_SCOPE_BLOCKED_REASONS } from "./vocabulary";
 
 export const SOURCE_SYNC_FINDING_KINDS = [
   "source_changed",
@@ -92,6 +93,29 @@ export type SourceSyncAutoApplyCeiling =
 
 const MicroUsd = z.string().regex(/^[0-9]+$/);
 
+/**
+ * Why a standing order stopped acting. Closed; mirrors the backend
+ * `source_sync_standing_orders_suspended_reason_valid` CHECK exactly.
+ *
+ * - `grantor_lost_authority`: the grantor no longer holds approval authority on
+ *   the scope (they left the org, lost the unit, or were an org admin, who no
+ *   longer approves).
+ * - `grantor_lost_doc_access`: the grantor still holds the authority but can no
+ *   longer upload to and edit the scope's document, so an unattended landing or
+ *   apply would be refused as them. Nothing is retried as anyone else.
+ * - `spend_cap_reached`: the month's spend met the cap the grantor stated.
+ * - `connection_lost`: Google Drive was disconnected; a reconnect re-activates
+ *   nothing.
+ */
+export const SOURCE_SYNC_STANDING_ORDER_SUSPENDED_REASONS = [
+  "grantor_lost_authority",
+  "grantor_lost_doc_access",
+  "spend_cap_reached",
+  "connection_lost",
+] as const;
+export type SourceSyncStandingOrderSuspendedReason =
+  (typeof SOURCE_SYNC_STANDING_ORDER_SUSPENDED_REASONS)[number];
+
 export const SourceSyncStandingOrderSchema = z.object({
   /** 'company' or 'unit:<uuid>'. */
   scopeKey: z.string().min(1).max(64),
@@ -101,14 +125,46 @@ export const SourceSyncStandingOrderSchema = z.object({
   /** Display-only, resolved at read time. */
   grantedByLabel: z.string().max(255).nullable(),
   grantedAt: IsoDateTime,
-  /** Why it stopped acting, e.g. the grantor lost the authority it was granted under. */
+  /** Why it stopped acting; null unless suspended. */
   suspendedReason: z
-    .enum(["grantor_lost_authority", "spend_cap_reached", "connection_lost"])
+    .enum(SOURCE_SYNC_STANDING_ORDER_SUSPENDED_REASONS)
     .nullable(),
 });
 
+/**
+ * Whether the CALLER may grant (turn on, change or turn on again) the standing
+ * order of one scope, decided by the server with exactly the rule a grant
+ * enforces: approval authority on the scope (an account owner, or authority on
+ * that unit) AND the caller's own upload and edit access on the scope's
+ * document. Authority is checked first: `needs_approval_authority` when the
+ * caller holds none (an org admin coordinates, never approves);
+ * `needs_doc_access` when they hold it but cannot act on the document.
+ * `blockedReason` is non-null exactly when `grantable` is false. Advisory: the
+ * grant re-decides and refuses (403) whatever this said.
+ */
+export const SourceSyncStandingOrderGrantabilitySchema = z
+  .object({
+    /** 'company' or 'unit:<uuid>'. */
+    scopeKey: z.string().min(1).max(64),
+    grantable: z.boolean(),
+    blockedReason: z.enum(SOURCE_SYNC_SCOPE_BLOCKED_REASONS).nullable(),
+  })
+  .strict()
+  .refine((g) => g.grantable === (g.blockedReason === null), {
+    message:
+      "blockedReason is non-null exactly when the scope is not grantable",
+    path: ["blockedReason"],
+  });
+
 export const SourceSyncStandingOrdersResponseSchema = z.object({
   orders: z.array(SourceSyncStandingOrderSchema).max(500),
+  /**
+   * The caller's grantability: the company scope first, then each distinct
+   * scope of an active or suspended order in `orders`, at most once each. A
+   * scope absent here is undecided (the server evaluated a bounded number); the
+   * grant still decides.
+   */
+  grantability: z.array(SourceSyncStandingOrderGrantabilitySchema).max(500),
 });
 
 /**
@@ -132,6 +188,9 @@ export type SourceSyncDismissFindingRequest = z.infer<
 export type SourceSyncStandingOrder = z.infer<
   typeof SourceSyncStandingOrderSchema
 >;
+export type SourceSyncStandingOrderGrantability = z.infer<
+  typeof SourceSyncStandingOrderGrantabilitySchema
+>;
 export type SourceSyncStandingOrdersResponse = z.infer<
   typeof SourceSyncStandingOrdersResponseSchema
 >;

package/src/source-sync/vocabulary.ts

@@ -111,6 +111,30 @@ 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, or grant its standing
+ * order. One vocabulary for both decisions (they are the same rule).
+ *
+ * - `needs_approval_authority`: the caller may see the scope but holds no
+ *   approval authority on it. Approval authority is an account owner, or
+ *   authority on that unit (local, inherited or delegated). An org admin
+ *   coordinates and never approves: being responsible for work getting done is
+ *   not authority to do it.
+ * - `needs_doc_access`: the caller holds the authority but lacks their own
+ *   upload and edit access on the scope's document; landing and apply act as
+ *   the approver (or a standing order's grantor), so approving would land
+ *   nothing.
+ *
+ * Authority is checked first, so a caller lacking both reads
+ * `needs_approval_authority`.
+ */
+export const SOURCE_SYNC_SCOPE_BLOCKED_REASONS = [
+  "needs_approval_authority",
+  "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/__tests__/outcome.test.ts

@@ -13,6 +13,7 @@ import {
   ORG_STRUCTURE_OUTCOME_KIND_OF_REASON,
   SYNTHESIZE_AFFORDANCES_OF_REASON,
   SYNTHESIZE_OUTCOME_KIND_OF_REASON,
+  SynthesizeOutcomeFactsSchema,
   WORKFLOW_OUTCOME_KINDS,
 } from "../outcome-reasons";
 
@@ -193,3 +194,83 @@ describe("WorkflowOutcome", () => {
     ).toBe(false);
   });
 });
+
+describe("source-sync/synthesize unattended endings", () => {
+  // The strict member (src/workflows/outcome.ts memberSchema): workflowType,
+  // executionEpoch, kind, reason, facts, disposition, affordances. Each test
+  // below supplies kind, reason, facts and its `review` disposition.
+  const base = {
+    workflowType: "source-sync/synthesize",
+    executionEpoch: 0,
+    affordances: [],
+  };
+  const unattended = {
+    scopeCount: 1,
+    violationCount: 0,
+    notLandedCount: 0,
+    appliedDocCount: 1,
+    notAppliedDocCount: 1,
+  };
+
+  it("a partly applied unattended batch is partial and may hand off to review", () => {
+    expect(SYNTHESIZE_OUTCOME_KIND_OF_REASON.updates_applied_partial).toBe(
+      "partial",
+    );
+    expect(SYNTHESIZE_OUTCOME_KIND_OF_REASON.apply_refused).toBe("partial");
+    expect(
+      WorkflowOutcomeSchema.safeParse({
+        ...base,
+        kind: "partial",
+        reason: "updates_applied_partial",
+        facts: unattended,
+        disposition: {
+          kind: "review",
+          requestType: "source-sync/synthesis",
+          requestId: "batch-1",
+        },
+      }).success,
+    ).toBe(true);
+  });
+
+  it("an unattended ending names how many documents it applied", () => {
+    const { appliedDocCount: _a, ...withoutApplied } = unattended;
+    expect(
+      WorkflowOutcomeSchema.safeParse({
+        ...base,
+        kind: "partial",
+        reason: "apply_refused",
+        facts: withoutApplied,
+        disposition: {
+          kind: "review",
+          requestType: "source-sync/synthesis",
+          requestId: "batch-1",
+        },
+      }).success,
+    ).toBe(false);
+    expect(
+      WorkflowOutcomeSchema.safeParse({
+        ...base,
+        kind: "partial",
+        reason: "apply_refused",
+        facts: { ...unattended, appliedDocCount: 0, notAppliedDocCount: 2 },
+        disposition: {
+          kind: "review",
+          requestType: "source-sync/synthesis",
+          requestId: "batch-1",
+        },
+      }).success,
+    ).toBe(true);
+  });
+
+  it("an attended ending says no automatic apply happened with null counts", () => {
+    expect(
+      SynthesizeOutcomeFactsSchema.safeParse({
+        scopeCount: 1,
+        violationCount: 0,
+        notLandedCount: 0,
+        appliedDocCount: null,
+        notAppliedDocCount: null,
+      }).success,
+    ).toBe(true);
+  });
+});

package/src/workflows/deferred-route.ts

@@ -147,7 +147,13 @@ 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" },
+  // prettier-ignore
+  updates_applied_partial: { route: "covered", by: "sourceSync.review_ready", fallback: "notice", audience: "creator" },
+  // prettier-ignore
+  apply_refused: { route: "covered", by: "sourceSync.review_ready", fallback: "notice", audience: "creator" },
   stopped_by_user: STOPPED,
   paused_billing: EXPLAINED,
   run_ceiling_reached: NOTICE_ADMINS,

package/src/workflows/outcome-reasons.ts

@@ -120,7 +120,21 @@ 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",
+  /** An unattended batch: the standing order applied EVERY drafted document. */
   updates_applied: "produced",
+  /**
+   * An unattended batch: the standing order applied some documents; the rest
+   * (proposed by the auto-apply gate, or refused when applied) wait for a person.
+   */
+  updates_applied_partial: "partial",
+  /**
+   * An unattended batch: the automatic apply was attempted and refused for every
+   * document it tried, so nothing was applied; the drafts wait for review. Never
+   * narrated as applied.
+   */
+  apply_refused: "partial",
   stopped_by_user: "stopped",
   paused_billing: "failed",
   run_ceiling_reached: "failed",
@@ -142,7 +156,10 @@ 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: [],
+  updates_applied_partial: [],
+  apply_refused: [],
   stopped_by_user: [],
   paused_billing: [OPEN_BILLING],
   run_ceiling_reached: [],
@@ -168,6 +185,20 @@ 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,
+    /**
+     * Documents an UNATTENDED batch applied on its own (the standing order's
+     * auto-apply). Null when no automatic apply happened at all: an attended
+     * run, or an unattended run that ended before its batch validated. Missing
+     * evidence is null, never 0.
+     */
+    appliedDocCount: Count.nullable(),
+    /**
+     * Documents of an UNATTENDED batch left for a person (proposed by the gate,
+     * or refused when applied). Null exactly when `appliedDocCount` is null.
+     */
+    notAppliedDocCount: Count.nullable(),
   })
   .strict();