@company-semantics/contracts 100.0.0 → 101.1.0

package/src/source-sync/__tests__/README.md

@@ -37,8 +37,10 @@ Locks the closed Source Sync vocabularies.
 - `upkeep.test.ts` — locks staleness findings and standing orders: the six
   finding kinds, the open/resolved/dismissed lifecycle, a required-but-nullable
   dismissal, a ceiling of `none` or `low` and nothing higher, a suspended order
-  that says why, and a strict standing-order request that may not name its own
-  grantor.
+  that says why (including `grantor_lost_doc_access`), a strict standing-order
+  request that may not name its own grantor, grantability whose blocked reason
+  is non-null exactly when a scope is not grantable, and a list that always
+  carries the caller's grantability.
 - `reach.test.ts` — locks the Drive-reach wire: reach is user or domain, the
   probe may be unknown, `lastChange: null` parses while an absent key does
   not, an upgrade is exactly `{ confirm: true }`, the upgrade response is the

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

@@ -70,6 +70,8 @@ import type {
   SourceSyncReachUpgradeRequest,
   SourceSyncReachUpgradeResponse,
   SourceSyncStandingOrder,
+  SourceSyncStandingOrderGrantability,
+  SourceSyncStandingOrderSuspendedReason,
   SourceSyncStandingOrdersResponse,
 } from "../../index";
 import * as attentionEvidence from "../attention-evidence";
@@ -162,7 +164,9 @@ const RELEASE_D_RUNTIME_NAMES: ReadonlyArray<
   ["SourceSyncFindingsResponseSchema", upkeep],
   ["SourceSyncDismissFindingRequestSchema", upkeep],
   ["SOURCE_SYNC_AUTO_APPLY_CEILINGS", upkeep],
+  ["SOURCE_SYNC_STANDING_ORDER_SUSPENDED_REASONS", upkeep],
   ["SourceSyncStandingOrderSchema", upkeep],
+  ["SourceSyncStandingOrderGrantabilitySchema", upkeep],
   ["SourceSyncStandingOrdersResponseSchema", upkeep],
   ["SourceSyncPutStandingOrderRequestSchema", upkeep],
   ["SOURCE_SYNC_REACHES", reach],
@@ -180,7 +184,9 @@ type ReleaseDTypes = [
   SourceSyncFindingsResponse,
   SourceSyncDismissFindingRequest,
   SourceSyncAutoApplyCeiling,
+  SourceSyncStandingOrderSuspendedReason,
   SourceSyncStandingOrder,
+  SourceSyncStandingOrderGrantability,
   SourceSyncStandingOrdersResponse,
   SourceSyncPutStandingOrderRequest,
   SourceSyncReach,
@@ -197,7 +203,9 @@ const RELEASE_D_TYPE_NAMES = [
   "SourceSyncFindingsResponse",
   "SourceSyncDismissFindingRequest",
   "SourceSyncAutoApplyCeiling",
+  "SourceSyncStandingOrderSuspendedReason",
   "SourceSyncStandingOrder",
+  "SourceSyncStandingOrderGrantability",
   "SourceSyncStandingOrdersResponse",
   "SourceSyncPutStandingOrderRequest",
   "SourceSyncReach",

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

@@ -110,6 +110,14 @@ describe("approvable and blockedReason", () => {
     expect(parsed.success).toBe(true);
   });
 
+  it("a projection may say the caller lacks approval authority", () => {
+    expect(
+      SourceSyncScopeApprovalProjectionSchema.safeParse(
+        scope({ approvable: false, blockedReason: "needs_approval_authority" }),
+      ).success,
+    ).toBe(true);
+  });
+
   it("refuses a reason outside the vocabulary and a missing approvable", () => {
     expect(
       SourceSyncScopeApprovalProjectionSchema.safeParse(

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

@@ -8,14 +8,20 @@
  * - A standing order's auto-apply ceiling is none or low; nothing higher parses.
  * - A standing-order request is strict: it may not name a grantor, a user or
  *   an actor, because the grantor is the authenticated caller.
- * - A suspended order says why, from a closed set.
+ * - A suspended order says why, from a closed set that includes the grantor
+ *   losing access to the scope's document.
  * - Money is an integer micro-USD string.
+ * - Grantability names a blocked reason exactly when a scope is not grantable,
+ *   from the scope blocked-reason vocabulary.
+ * - The standing-orders list always carries the caller's grantability.
  */
 
 import { describe, expect, it } from "vitest";
 import {
   SOURCE_SYNC_AUTO_APPLY_CEILINGS,
   SOURCE_SYNC_FINDING_KINDS,
+  SOURCE_SYNC_STANDING_ORDER_SUSPENDED_REASONS,
+  SourceSyncStandingOrderGrantabilitySchema,
   SourceSyncDismissFindingRequestSchema,
   SourceSyncFindingSchema,
   SourceSyncFindingsResponseSchema,
@@ -198,9 +204,94 @@ describe("standing orders", () => {
         ).success,
       ).toBe(false);
     }
+    expect(
+      SourceSyncStandingOrdersResponseSchema.safeParse({
+        orders: [order()],
+        grantability: [],
+      }).success,
+    ).toBe(true);
+  });
+
+  it("a suspended order may say its grantor lost access to the document", () => {
+    expect([...SOURCE_SYNC_STANDING_ORDER_SUSPENDED_REASONS]).toEqual([
+      "grantor_lost_authority",
+      "grantor_lost_doc_access",
+      "spend_cap_reached",
+      "connection_lost",
+    ]);
+    expect(
+      SourceSyncStandingOrderSchema.safeParse(
+        order({
+          state: "suspended",
+          suspendedReason: "grantor_lost_doc_access",
+        }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("grantability names why a scope cannot be granted", () => {
+    for (const blockedReason of [
+      "needs_approval_authority",
+      "needs_doc_access",
+    ]) {
+      expect(
+        SourceSyncStandingOrderGrantabilitySchema.safeParse({
+          scopeKey: "company",
+          grantable: false,
+          blockedReason,
+        }).success,
+        blockedReason,
+      ).toBe(true);
+    }
+    expect(
+      SourceSyncStandingOrderGrantabilitySchema.safeParse({
+        scopeKey: "company",
+        grantable: false,
+        blockedReason: null,
+      }).success,
+    ).toBe(false);
+    expect(
+      SourceSyncStandingOrderGrantabilitySchema.safeParse({
+        scopeKey: "company",
+        grantable: false,
+        blockedReason: "felt_like_it",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("a grantable scope carries no blocked reason", () => {
+    expect(
+      SourceSyncStandingOrderGrantabilitySchema.safeParse({
+        scopeKey: "company",
+        grantable: true,
+        blockedReason: null,
+      }).success,
+    ).toBe(true);
+    expect(
+      SourceSyncStandingOrderGrantabilitySchema.safeParse({
+        scopeKey: "company",
+        grantable: true,
+        blockedReason: "needs_doc_access",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("the standing-orders list carries the caller's grantability", () => {
     expect(
       SourceSyncStandingOrdersResponseSchema.safeParse({ orders: [order()] })
         .success,
+    ).toBe(false);
+    expect(
+      SourceSyncStandingOrdersResponseSchema.safeParse({
+        orders: [order()],
+        grantability: [
+          {
+            scopeKey: "company",
+            grantable: false,
+            blockedReason: "needs_approval_authority",
+          },
+        ],
+      }).success,
     ).toBe(true);
   });
 });

package/src/source-sync/index.ts

@@ -192,7 +192,9 @@ export type {
   SourceSyncFindingsResponse,
   SourceSyncDismissFindingRequest,
   SourceSyncAutoApplyCeiling,
+  SourceSyncStandingOrderSuspendedReason,
   SourceSyncStandingOrder,
+  SourceSyncStandingOrderGrantability,
   SourceSyncStandingOrdersResponse,
   SourceSyncPutStandingOrderRequest,
 } from "./upkeep";
@@ -203,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

@@ -47,10 +47,13 @@ const PersonLabel = z.string().min(1).max(255);
  * - 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
+ *   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.
  */

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

@@ -112,12 +112,26 @@ 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).
+ * 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_doc_access"] as const;
+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];
 

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

@@ -150,6 +150,10 @@ export const SYNTHESIZE_DEFERRED_ROUTE_OF_REASON = {
   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

@@ -122,7 +122,19 @@ 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",
@@ -146,6 +158,8 @@ 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: [],
@@ -173,6 +187,18 @@ export const SynthesizeOutcomeFactsSchema = z
     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();