@company-semantics/contracts 62.4.0 → 62.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "62.4.0",
+  "version": "62.6.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -139,8 +139,8 @@
     "node": "22.x"
   },
   "dependencies": {
-    "@slack/types": "^3.0.0",
-    "zod": "^4.4.3"
+    "@slack/types": "^3.1.0",
+    "zod": "^4.5.2"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -149,13 +149,13 @@
     "culori": "^4.0.2",
     "eslint": "^10.9.0",
     "husky": "^9.1.7",
-    "lint-staged": "^17.3.0",
+    "lint-staged": "^17.4.1",
     "markdownlint-cli2": "^0.23.2",
     "openapi-typescript": "^7.13.0",
     "prettier": "^3.9.6",
     "tsx": "^4.23.12",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.67.0",
+    "typescript-eslint": "^8.68.0",
     "vite": "^8.2.2",
     "vitest": "^4.1.11",
     "yaml": "^2.9.0"

package/src/__tests__/iso-datetime.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import {
+  ISO_DATETIME_OFFSET_PATTERN,
+  ISO_DATETIME_PATTERN,
+  IsoDateTime,
+  IsoDateTimeWithOffset,
+} from "../api/primitives";
+
+/**
+ * These are drift alarms, not unit tests.
+ *
+ * `IsoDateTime` delegates to zod's built-in RFC 3339 regex, and zod is advanced
+ * automatically by Dependabot inside a grouped `minor`/`patch` bump. That is
+ * exactly how the seconds-optional -> seconds-mandatory tightening reached
+ * production undocumented (backend #520). If zod moves this regex again, the
+ * documented format of every `format: date-time` field on the public API moves
+ * with it — so it fails here first and gets ratified deliberately.
+ *
+ * If one of these fails: do not update the constant to make it green. Work out
+ * what zod changed, decide whether we want it, and record the decision.
+ */
+describe("the RFC 3339 wire contract is pinned, not inherited", () => {
+  it("emits the pinned pattern for the Z-only form", () => {
+    expect(z.toJSONSchema(IsoDateTime, { io: "input" }).pattern).toBe(
+      ISO_DATETIME_PATTERN,
+    );
+  });
+
+  it("emits the pinned pattern for the offset-allowing form", () => {
+    expect(z.toJSONSchema(IsoDateTimeWithOffset, { io: "input" }).pattern).toBe(
+      ISO_DATETIME_OFFSET_PATTERN,
+    );
+  });
+
+  it("still emits format: date-time, which the pattern alone would not carry", () => {
+    expect(z.toJSONSchema(IsoDateTime, { io: "input" }).format).toBe(
+      "date-time",
+    );
+  });
+});
+
+describe("seconds are mandatory (ADR-CONTRACTS-156)", () => {
+  it.each([
+    "2026-09-01T12:00:00Z",
+    "2026-09-01T12:00:00.000Z",
+    "2024-02-29T23:59:59Z",
+  ])("accepts %s", (value) => {
+    expect(IsoDateTime.safeParse(value).success).toBe(true);
+  });
+
+  it.each(["2026-09-01T12:00Z", "2026-09-01T12Z", "2026-09-01"])(
+    "rejects %s",
+    (value) => {
+      expect(IsoDateTime.safeParse(value).success).toBe(false);
+    },
+  );
+
+  it("rejects a numeric offset on the Z-only form", () => {
+    expect(IsoDateTime.safeParse("2026-09-01T12:00:00+02:00").success).toBe(
+      false,
+    );
+  });
+
+  it("accepts a numeric offset on the offset-allowing form", () => {
+    expect(
+      IsoDateTimeWithOffset.safeParse("2026-09-01T12:00:00+02:00").success,
+    ).toBe(true);
+  });
+});

package/src/admin/direct-grants.ts

@@ -7,12 +7,13 @@
  * direct-grant-audit-trail and the `direct-grant-audit` CI guard).
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 export const DirectGrantCreate = z.object({
   subject_id: z.string().uuid(),
   scope_pattern: z.string(),
   resource_filter: z.record(z.string(), z.unknown()).optional(),
-  expires_at: z.string().datetime().optional(),
+  expires_at: IsoDateTime.optional(),
 });
 
 export type DirectGrantCreate = z.infer<typeof DirectGrantCreate>;
@@ -24,8 +25,8 @@ export const DirectGrant = z.object({
   scope_pattern: z.string(),
   source: z.literal("direct"),
   granted_by: z.string().uuid(),
-  granted_at: z.string().datetime(),
-  expires_at: z.string().datetime().nullable(),
+  granted_at: IsoDateTime,
+  expires_at: IsoDateTime.nullable(),
 });
 
 export type DirectGrant = z.infer<typeof DirectGrant>;

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 = 'bd8b060aedb2' as const;
-export const SPEC_HASH_FULL = 'bd8b060aedb2cd35af45ee8c8b0e1dc97da92305f985757cd19a57fbd44866e3' as const;
+export const SPEC_HASH = '52d89a463432' as const;
+export const SPEC_HASH_FULL = '52d89a4634328ae80200c221d6aa25d8c34c9d09208a2c460d82a523ec79144d' as const;

package/src/api/generated.ts

@@ -4293,6 +4293,12 @@ export interface components {
             };
             /** @enum {string} */
             origin?: "user" | "proactive";
+            launch?: {
+                /** @constant */
+                kind: "structure-review";
+                /** Format: uuid */
+                proposalId: string;
+            };
         } | {
             /** @constant */
             trigger: "regenerate-message";
@@ -4315,6 +4321,12 @@ export interface components {
             };
             /** @enum {string} */
             origin?: "user" | "proactive";
+            launch?: {
+                /** @constant */
+                kind: "structure-review";
+                /** Format: uuid */
+                proposalId: string;
+            };
         };
         ProactiveChatResolution: {
             /** @constant */
@@ -6783,9 +6795,8 @@ export interface components {
                     p95ContextTokens: number;
                     medianReadsAfterFirstEdit: number;
                 }[];
-                bySource: ({
+                bySource: {
                     source: string;
-                } & {
                     p95Reads?: number;
                     p50Reads?: number;
                     p95ContextTokens?: number;
@@ -6797,7 +6808,7 @@ export interface components {
                     navMapUsageBySource?: {
                         [key: string]: number;
                     };
-                })[];
+                }[];
                 trend: {
                     recent: {
                         p95Reads?: number;

package/src/api/primitives.ts

@@ -25,3 +25,47 @@ export type CursorPage<T> = {
   hasMore: boolean;
 };
 export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
+
+// =============================================================================
+// The RFC 3339 timestamp contract
+// =============================================================================
+//
+// Every `format: date-time` field on the public API surface is built from one of
+// the two schemas below, so the wire contract has exactly one definition site.
+//
+// The validators delegate to zod's built-in `.datetime()` rather than
+// reimplementing RFC 3339 by hand: that keeps `format: date-time` in the emitted
+// OpenAPI document and avoids a hand-rolled regex drifting from the runtime
+// check. The regex zod produces is therefore an *input* to our published
+// contract, and zod is a transitive dependency that Dependabot advances
+// automatically — so the emitted pattern is pinned below and asserted in
+// `src/__tests__/iso-datetime.test.ts`.
+//
+// That assertion is the point. A zod release that changes this regex changes the
+// documented format of 52 public fields; it must fail a test and be ratified,
+// not land silently inside a grouped `minor`/`patch` bump. See ADR-CONTRACTS-156.
+
+/** Emitted `pattern` for {@link IsoDateTime}. Pinned — see the note above. */
+export const ISO_DATETIME_PATTERN =
+  "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$";
+
+/** Emitted `pattern` for {@link IsoDateTimeWithOffset}. Pinned — see the note above. */
+export const ISO_DATETIME_OFFSET_PATTERN =
+  "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$";
+
+/**
+ * A UTC RFC 3339 timestamp — `2026-09-01T12:00:00.000Z`.
+ *
+ * Seconds are mandatory. `2026-09-01T12:00Z` is rejected: it is not valid
+ * RFC 3339, and the backend has rejected it since zod 4.5.x.
+ */
+export const IsoDateTime = z.string().datetime();
+
+/**
+ * An RFC 3339 timestamp that may carry a numeric UTC offset instead of `Z` —
+ * `2026-09-01T12:00:00.000+02:00`.
+ *
+ * Use only where a client legitimately reports local wall-clock time with its
+ * offset. Prefer {@link IsoDateTime} for anything the server mints.
+ */
+export const IsoDateTimeWithOffset = z.string().datetime({ offset: true });

package/src/chat/README.md

@@ -89,7 +89,6 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - `InvalidateChatListEventSchema`
 - `InvalidationReason` _(type)_ — Reason for cache invalidation.
 - `InvalidationReasonSchema`
-- `IsoDateString` — ISO 8601 datetime string — the runtime safety net for date serialization.
 - `ListSharesResponse` _(type)_ — Response for GET /api/chats/:chatId/shares
 - `ListSharesResponseSchema` — Response for GET /api/chats/:chatId/shares
 - `ProactiveChatResolution` _(type)_ — Resolving an occurrence id to the CURRENT reader's chat — one of the four bounded states `ready` (with…
@@ -117,6 +116,7 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 
 **Internal domains:**
 
+- `api`
 - `proactive`
 
 **External packages:**

package/src/chat/index.ts

@@ -61,7 +61,6 @@ export type {
 // =============================================================================
 
 export {
-  IsoDateString,
   ChatVisibilitySchema,
   TitleSourceSchema,
   InvalidationReasonSchema,

package/src/chat/schemas.ts

@@ -1,11 +1,5 @@
 import { z } from "zod";
-
-// =============================================================================
-// Reusable Primitives
-// =============================================================================
-
-/** ISO 8601 datetime string — the runtime safety net for date serialization. */
-export const IsoDateString = z.string().datetime();
+import { IsoDateTime } from "../api/primitives";
 
 // =============================================================================
 // Enums
@@ -78,15 +72,15 @@ export const ChatSummarySchema = z.object({
   id: z.string(),
   title: z.string().nullable(),
   messageCount: z.number().int(),
-  createdAt: IsoDateString,
-  updatedAt: IsoDateString,
+  createdAt: IsoDateTime,
+  updatedAt: IsoDateTime,
   isShared: z.boolean(),
 });
 
 export const ChatSummaryExtendedSchema = ChatSummarySchema.extend({
-  pinnedAt: IsoDateString.nullable(),
+  pinnedAt: IsoDateTime.nullable(),
   titleSource: TitleSourceSchema.nullable(),
-  titleGeneratedAt: IsoDateString.nullable(),
+  titleGeneratedAt: IsoDateTime.nullable(),
   ...proactiveChatFields,
 });
 
@@ -129,7 +123,7 @@ export const ChatShareInfoSchema = z.object({
   shareUrl: z.string().optional(),
   messageCountAtShare: z.number().int(),
   titleAtShare: z.string(),
-  createdAt: IsoDateString,
+  createdAt: IsoDateTime,
   createdByName: z.string(),
   isRevoked: z.boolean(),
 });
@@ -137,7 +131,7 @@ export const ChatShareInfoSchema = z.object({
 export const SharedChatViewSchema = z.object({
   title: z.string(),
   messages: z.array(SharedChatMessageSchema),
-  sharedAt: IsoDateString,
+  sharedAt: IsoDateTime,
   sharedByName: z.string(),
   visibility: ChatVisibilitySchema,
 });
@@ -148,7 +142,7 @@ export const SharedChatViewSchema = z.object({
 
 export const BaseEventSchema = z.object({
   v: z.literal(1),
-  timestamp: IsoDateString,
+  timestamp: IsoDateTime,
   eventId: z.string().optional(),
 });
 
@@ -167,10 +161,10 @@ export const ChatCreatedEventSchema = BaseEventSchema.extend({
     interactionId: z.string().optional(),
     title: z.string(),
     titleSource: TitleSourceSchema,
-    pinnedAt: IsoDateString.nullable(),
+    pinnedAt: IsoDateTime.nullable(),
     messageCount: z.number().int(),
-    createdAt: IsoDateString,
-    updatedAt: IsoDateString,
+    createdAt: IsoDateTime,
+    updatedAt: IsoDateTime,
     isShared: z.boolean(),
     ...proactiveChatFields,
   }),
@@ -182,11 +176,11 @@ export const ChatUpdatedEventSchema = BaseEventSchema.extend({
     chatId: z.string(),
     title: z.string(),
     titleSource: TitleSourceSchema.nullable(),
-    titleGeneratedAt: IsoDateString.nullable(),
-    pinnedAt: IsoDateString.nullable(),
+    titleGeneratedAt: IsoDateTime.nullable(),
+    pinnedAt: IsoDateTime.nullable(),
     messageCount: z.number().int(),
-    createdAt: IsoDateString,
-    updatedAt: IsoDateString,
+    createdAt: IsoDateTime,
+    updatedAt: IsoDateTime,
     isShared: z.boolean(),
     ...proactiveChatFields,
   }),
@@ -245,7 +239,7 @@ export const ChatMessageSchema = z.object({
   content: z.string(),
   parts: z.array(z.unknown()).optional(),
   sequenceNumber: z.number().int(),
-  createdAt: IsoDateString,
+  createdAt: IsoDateTime,
 });
 
 // =============================================================================
@@ -325,11 +319,11 @@ export const ChatDetailSchema = z.object({
   id: z.string(),
   title: z.string(),
   interactionId: z.string(),
-  pinnedAt: IsoDateString.nullable().optional(),
+  pinnedAt: IsoDateTime.nullable().optional(),
   titleSource: TitleSourceSchema.nullable().optional(),
-  titleGeneratedAt: IsoDateString.nullable().optional(),
-  createdAt: IsoDateString,
-  updatedAt: IsoDateString,
+  titleGeneratedAt: IsoDateTime.nullable().optional(),
+  createdAt: IsoDateTime,
+  updatedAt: IsoDateTime,
   // Opening the detail is what clears `unread`; the detail carries the flag so
   // the reader can tell a first open from a return visit. `proactiveKind` is
   // a list concern (the sidebar row) and does not ride the detail.

package/src/execution/README.md

@@ -102,6 +102,7 @@ TypeScript types and registry for execution kinds and their governance metadata.
 
 **Internal domains:**
 
+- `api`
 - `message-parts`
 
 **External packages:**

package/src/execution/schemas.ts

@@ -8,6 +8,7 @@
  */
 
 import { z } from "zod";
+import { IsoDateTimeWithOffset } from "../api/primitives";
 
 import type { ExecutionResultData } from "../message-parts/execution";
 import type { ExecutionKind } from "./kinds";
@@ -22,8 +23,8 @@ export const ExecutionSummarySchema = z.object({
   executionId: z.string().uuid(),
   kind: z.string(),
   status: z.enum(["pending", "succeeded", "failed"]),
-  decidedAt: z.string().datetime({ offset: true }),
-  completedAt: z.string().datetime({ offset: true }).optional(),
+  decidedAt: IsoDateTimeWithOffset,
+  completedAt: IsoDateTimeWithOffset.optional(),
   target: z.object({ type: z.string() }),
 });
 

package/src/execution/sse.ts

@@ -15,6 +15,7 @@
  */
 
 import { z } from "zod";
+import { IsoDateTimeWithOffset } from "../api/primitives";
 import { ExecutionEventTypeSchema } from "./events";
 import { ExecutionStateSchema } from "./status";
 
@@ -27,7 +28,7 @@ export const ExecutionSseEventSchema = z.object({
   /** Coarse actor class that produced the event (e.g. `user`, `system`). */
   actorType: z.string(),
   /** DB insert time of the event, ISO-8601 with offset. */
-  createdAt: z.string().datetime({ offset: true }),
+  createdAt: IsoDateTimeWithOffset,
 });
 
 export type ExecutionSseEvent = z.infer<typeof ExecutionSseEventSchema>;

package/src/identity/README.md

@@ -88,6 +88,7 @@ TypeScript types and functions for user identity and display name resolution.
 
 **Internal domains:**
 
+- `api`
 - `org`
 
 **External packages:**

package/src/identity/identity-link.ts

@@ -17,6 +17,7 @@
  * @see ADR-CONT-032 for identity vocabulary design rationale
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 // ---------------------------------------------------------------------------
 // IdentityLink — external system id → Person
@@ -31,8 +32,8 @@ export const IdentityLinkSchema = z.object({
   externalId: z.string().min(1),
   // The Person this external identity resolves to (Person.id).
   personId: z.string().uuid(),
-  createdAt: z.string().datetime(),
-  updatedAt: z.string().datetime(),
+  createdAt: IsoDateTime,
+  updatedAt: IsoDateTime,
 });
 
 export type IdentityLink = z.infer<typeof IdentityLinkSchema>;

package/src/impersonation/schemas.ts

@@ -9,6 +9,7 @@
  */
 
 import { z } from "zod";
+import { IsoDateTimeWithOffset } from "../api/primitives";
 
 export const ImpersonationSessionSchema = z.object({
   impersonationSessionId: z.string(),
@@ -16,9 +17,9 @@ export const ImpersonationSessionSchema = z.object({
   targetUserId: z.string(),
   reason: z.string(),
   reasonHash: z.string(),
-  startedAt: z.string().datetime({ offset: true }),
-  expiresAt: z.string().datetime({ offset: true }),
-  endedAt: z.string().datetime({ offset: true }).nullable(),
+  startedAt: IsoDateTimeWithOffset,
+  expiresAt: IsoDateTimeWithOffset,
+  endedAt: IsoDateTimeWithOffset.nullable(),
   ipAddress: z.string(),
   userAgent: z.string(),
 });
@@ -48,9 +49,9 @@ export const ImpersonationSessionWireDtoSchema = z
   .object({
     id: z.string(),
     targetUserId: z.string(),
-    startedAt: z.string().datetime({ offset: true }),
-    expiresAt: z.string().datetime({ offset: true }),
-    endedAt: z.string().datetime({ offset: true }).nullable(),
+    startedAt: IsoDateTimeWithOffset,
+    expiresAt: IsoDateTimeWithOffset,
+    endedAt: IsoDateTimeWithOffset.nullable(),
   })
   .strict();
 

package/src/integrations/README.md

@@ -47,7 +47,7 @@ alongside `Meetings`, `Comms`, and `Docs`.
 
 **Internal domains:**
 
-_None._
+- `api`
 
 **External packages:**
 

package/src/integrations/schemas.ts

@@ -16,6 +16,7 @@
  * stringified JSON blobs on the schema.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 // =============================================================================
 // HR connection status
@@ -87,7 +88,7 @@ export const HrConnectionStatusSchema = z
       description:
         "Departments mirrored from the HR provider; null when never synced.",
     }),
-    lastSyncAt: z.string().datetime().nullable().meta({
+    lastSyncAt: IsoDateTime.nullable().meta({
       description: "ISO timestamp of the last successful sync; null if never.",
     }),
     syncHealth: z.enum(["healthy", "degraded", "error"]).nullable().meta({

package/src/meetings/schemas.ts

@@ -21,6 +21,7 @@
  * stringified JSON blobs on the schema.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 // =============================================================================
 // Recording identity
@@ -237,7 +238,7 @@ export const TranscriptionSessionGrantSchema = z
     sessionId: RecordingIdSchema,
     connectUrl: z.string().url(),
     authHeaders: z.record(z.string(), z.string()),
-    expiresAt: z.string().datetime(),
+    expiresAt: IsoDateTime,
     audioConfig: z.object({
       sampleRateHz: z.literal(16000),
       channels: z.literal(2),
@@ -279,8 +280,8 @@ export const MeetingMetadataProjectionSchema = z
     visibility: MeetingVisibilitySchema,
     status: RecordingStatusSchema,
     quality: RecordingQualitySchema,
-    startedAt: z.string().datetime(),
-    endedAt: z.string().datetime().nullable(),
+    startedAt: IsoDateTime,
+    endedAt: IsoDateTime.nullable(),
     durationMs: z.number().int().nonnegative(),
     participantUserIds: z.array(z.string().uuid()),
     transcriptAvailable: z.boolean(),

package/src/org/occupancy.ts

@@ -25,6 +25,7 @@
  * account.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 import { FactProvenanceSchema } from "./structure-facts";
 
@@ -60,9 +61,9 @@ export const OccupancySchema = z.object({
   /** Lifecycle of this hold; only `active` makes the position occupied. */
   status: OccupancyStatusSchema,
   /** ISO start of the hold; `null`/absent when unknown or open-started. */
-  startsAt: z.string().datetime().nullable().optional(),
+  startsAt: IsoDateTime.nullable().optional(),
   /** ISO end of the hold; `null`/absent while the hold is still open. */
-  endsAt: z.string().datetime().nullable().optional(),
+  endsAt: IsoDateTime.nullable().optional(),
   /** Provenance of this occupancy fact (truth hierarchy + supersede model). */
   provenance: FactProvenanceSchema,
 });

package/src/org/reasoning-review.ts

@@ -20,6 +20,7 @@
  * `inferenceType` and is not part of the stable contract surface.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 // ---------------------------------------------------------------------------
 // OrgStructureReviewInference — one pending ('review') structure inference
@@ -43,7 +44,7 @@ export const OrgStructureReviewInferenceSchema = z.object({
   /** Human-meaningful WHY the engine proposed this change. */
   reason: z.string(),
   /** ISO timestamp the inference was created. */
-  createdAt: z.string().datetime(),
+  createdAt: IsoDateTime,
 });
 
 export type OrgStructureReviewInference = z.infer<

package/src/org/reconciliation.ts

@@ -39,6 +39,7 @@
  * remove an entry is the two sides agreeing.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 import { FactSourceTierSchema } from "./structure-facts";
 
@@ -92,7 +93,7 @@ export const OrgDivergenceSchema = z.object({
    */
   reason: z.string().max(2000).nullable(),
   /** ISO timestamp the workspace's current word on this field was recorded. */
-  recordedAt: z.string().datetime(),
+  recordedAt: IsoDateTime,
   /**
    * ISO timestamp someone in this workspace ACKNOWLEDGED this entry, or `null`.
    *
@@ -102,7 +103,7 @@ export const OrgDivergenceSchema = z.object({
    * the entry — arrives unacknowledged, which is the right default for a
    * statement nobody has read yet.
    */
-  acknowledgedAt: z.string().datetime().nullable(),
+  acknowledgedAt: IsoDateTime.nullable(),
   /** Who acknowledged it. `null` when nobody has, or when that user is gone. */
   acknowledgedByUserId: z.string().uuid().nullable(),
 });
@@ -146,7 +147,7 @@ export const ResolveOrgDivergenceResultSchema = z.object({
   /** How it was resolved. Local decisions only — see the module docblock. */
   resolution: OrgDivergenceResolutionSchema,
   /** ISO timestamp the decision was recorded in this workspace. */
-  resolvedAt: z.string().datetime(),
+  resolvedAt: IsoDateTime,
   /**
    * Whether anything was written back to the source system. Pinned to the
    * literal `false`: the HRIS client is read-only and no write scope is

package/src/org/schemas.ts

@@ -11,7 +11,7 @@
  *  - scope-check.ts (GET /api/scope/check, POST /api/scope/check-batch)
  */
 import { z } from "zod";
-import { CursorPageSchema } from "../api/primitives";
+import { CursorPageSchema, IsoDateTime } from "../api/primitives";
 import { OrgChartRoleSchema } from "../permissions/orgchart-roles";
 import { PositionRefSchema } from "../identity/position-ref";
 
@@ -1757,7 +1757,7 @@ export const OwnerAuthoritySchema = z.object({
    * the projection read filters `expires_at > now()` — so a present value is
    * always in the future.
    */
-  expiresAt: z.string().datetime().nullable().optional(),
+  expiresAt: IsoDateTime.nullable().optional(),
 });
 export type OwnerAuthority = z.infer<typeof OwnerAuthoritySchema>;
 
@@ -1817,7 +1817,7 @@ export const CreateDelegationRequestSchema = z.object({
    * Optional ISO-8601 expiry. Omitted or `null` ⇒ a permanent delegation. The
    * UI captures a date and sends end-of-day in the user's timezone.
    */
-  expiresAt: z.string().datetime().nullable().optional(),
+  expiresAt: IsoDateTime.nullable().optional(),
   /**
    * When true, the granted user is emailed a notification (carrying `note` as
    * the message). Not persisted — it only gates the side-effect email. Omitted
@@ -1836,7 +1836,7 @@ export type CreateDelegationRequest = z.infer<
  * on an existing delegate row.
  */
 export const UpdateDelegationRequestSchema = z.object({
-  expiresAt: z.string().datetime().nullable(),
+  expiresAt: IsoDateTime.nullable(),
 });
 export type UpdateDelegationRequest = z.infer<
   typeof UpdateDelegationRequestSchema

package/src/org/sync-run.ts

@@ -26,6 +26,7 @@
  * nullable string rather than wrapped in a page envelope.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 // ---------------------------------------------------------------------------
 // SyncRunSummary — the outcome record of one adapter sync run
@@ -35,9 +36,9 @@ export const SyncRunSummarySchema = z.object({
   /** Unique identifier for this sync run within the org graph. */
   id: z.string().uuid(),
   /** ISO start of the run. Always set once a run has begun. */
-  startedAt: z.string().datetime(),
+  startedAt: IsoDateTime,
   /** ISO end of the run; `null`/absent while the run is still in progress. */
-  endedAt: z.string().datetime().nullable().optional(),
+  endedAt: IsoDateTime.nullable().optional(),
   /** Count of facts examined by the run (the denominator). */
   processed: z.number().int().nonnegative(),
   /** Count of facts that resulted in a real mutation (insert/supersede). */

package/src/permissions/permission-introspection.ts

@@ -18,6 +18,7 @@
  * permission_decisions; the UI never re-derives.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 import { AccessLevelSchema } from "./access-levels";
 import { AccessSourceSchema } from "./access-source";
 import { PrincipalSchema } from "./share-api";
@@ -51,7 +52,7 @@ export const RecentDecisionSchema = z.object({
   allow: z.boolean(),
   reason: z.string(),
   source_chain: z.array(AccessSourceSchema),
-  decided_at: z.string().datetime(),
+  decided_at: IsoDateTime,
 });
 export type RecentDecision = z.infer<typeof RecentDecisionSchema>;
 

package/src/permissions/share-api.ts

@@ -21,6 +21,7 @@
  * changing (ADR-CONTRACTS-093).
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 import { AccessLevelSchema } from "./access-levels";
 import { AccessSourceSchema } from "./access-source";
 
@@ -77,7 +78,7 @@ export const AclGrantResponseSchema = z.object({
   principal: PrincipalSchema,
   access_level: GrantableAccessLevelSchema,
   granted_by_user_id: z.string().uuid(),
-  granted_at: z.string().datetime(),
+  granted_at: IsoDateTime,
 });
 export type AclGrantResponse = z.infer<typeof AclGrantResponseSchema>;
 

package/src/security/org-secrets.ts

@@ -13,6 +13,7 @@
  * `./secret.ts`) before storage / encryption.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 
 /**
  * Usage class of an org secret. Drives which resolver layer is allowed to read
@@ -75,10 +76,10 @@ export const OrgSecretSummarySchema = z.object({
   maskedPrefix: z.string().min(1).max(64),
   version: z.number().int().positive(),
   enabled: z.boolean(),
-  lastUsedAt: z.string().datetime().nullable(),
+  lastUsedAt: IsoDateTime.nullable(),
   usageCount: z.string(),
-  rotatedAt: z.string().datetime().nullable(),
-  createdAt: z.string().datetime(),
+  rotatedAt: IsoDateTime.nullable(),
+  createdAt: IsoDateTime,
 });
 export type OrgSecretSummary = z.infer<typeof OrgSecretSummarySchema>;
 

package/src/user-events/schemas.ts

@@ -29,6 +29,7 @@
  *   stream without first giving it a real commit-ordered log.
  */
 import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
 import type { ResourceKey } from "../resource-keys";
 import { isResourceKeyShape } from "../resource-keys";
 
@@ -36,7 +37,6 @@ import { isResourceKeyShape } from "../resource-keys";
  * Local, not chat's. `chat/schemas.ts` owns a structurally identical helper;
  * importing it would make a chat frame change a user-events breaking change.
  */
-const IsoDateString = z.string().datetime();
 
 /**
  * Fields every frame carries.
@@ -47,7 +47,7 @@ const IsoDateString = z.string().datetime();
  */
 export const UserEventBaseSchema = z.object({
   v: z.literal(1),
-  timestamp: IsoDateString,
+  timestamp: IsoDateTime,
 });
 
 // =============================================================================