@company-semantics/contracts 0.126.0 → 0.128.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.126.0",
+  "version": "0.128.0",
   "private": false,
   "repository": {
     "type": "git",

package/schemas/repo-ci-result.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://company-semantics.dev/schemas/repo-ci-result.json",
+  "title": "RepoCiResult",
+  "description": "Per-repo result of a cross-repo CI health aggregation run (e.g. pnpm ci:all). Denormalized view of guard-result.schema.json: the top-level errors and warnings are scalar counts; guardResult is the full tiered detail. The scalars MUST equal the aggregated totals in guardResult.results when guardResult is present. Producers derive the scalars from guardResult, never the reverse.",
+  "type": "object",
+  "required": ["repo", "status", "errors", "warnings", "durationMs"],
+  "additionalProperties": false,
+  "properties": {
+    "repo": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Sibling repo name without the company-semantics- prefix (e.g. 'backend', 'contracts')."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pass", "fail"],
+      "description": "pass when the repo's ci:local exited 0 and the guard artifact was produced; fail otherwise."
+    },
+    "errors": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total errors across all guard tiers. MUST equal the sum of guardResult.results[tier].errors.length across all tiers when guardResult is present."
+    },
+    "warnings": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total warnings across all guard tiers. MUST equal the sum of guardResult.results[tier].warnings.length across all tiers when guardResult is present."
+    },
+    "durationMs": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Wall-clock duration of the repo's ci:local run in milliseconds."
+    },
+    "guardResult": {
+      "$ref": "guard-result.schema.json",
+      "description": "Optional full guard orchestrator output for the repo. When present, errors and warnings MUST be derived from it."
+    }
+  }
+}

package/src/ci-results/index.ts

@@ -0,0 +1,16 @@
+/**
+ * CI Results Vocabulary Barrel
+ *
+ * Re-exports the per-repo cross-repo CI aggregation result vocabulary.
+ * Import from '@company-semantics/contracts/ci-results' or '@company-semantics/contracts'.
+ *
+ * @see ADR-CONT-033 for contracts boundary rationale
+ */
+
+export type {
+  GuardTier,
+  GuardResultPayload,
+  RepoCiResult,
+} from './repo-ci-result';
+
+export { assertRepoCiResultConsistent } from './repo-ci-result';

package/src/ci-results/repo-ci-result.ts

@@ -0,0 +1,94 @@
+/**
+ * RepoCiResult — per-repo result of a cross-repo CI health aggregation run.
+ *
+ * Mirrors schemas/repo-ci-result.schema.json. The JSON schema is the source
+ * of truth; this file is the TypeScript projection.
+ */
+
+export type GuardTier =
+  | 'structural'
+  | 'behavioral'
+  | 'invariants'
+  | 'evolution'
+  | 'meta';
+
+/**
+ * Minimal structural shape of a guard orchestrator result payload.
+ * The full shape is described by guard-result.schema.json; this is the
+ * subset assertRepoCiResultConsistent needs to cross-check against the
+ * RepoCiResult scalars.
+ */
+export interface GuardResultPayload {
+  readonly results: Readonly<
+    Record<
+      GuardTier,
+      { readonly errors: readonly unknown[]; readonly warnings: readonly unknown[] }
+    >
+  >;
+}
+
+/**
+ * Per-repo result of a cross-repo CI health aggregation run.
+ *
+ * Load-bearing invariant: when guardResult is present, errors and warnings
+ * MUST equal the aggregated counts across all tiers in guardResult.results.
+ * Producers derive the scalars from guardResult, never the reverse.
+ * Consumers can enforce this at runtime via assertRepoCiResultConsistent.
+ */
+export interface RepoCiResult {
+  /** Sibling repo name without the 'company-semantics-' prefix. */
+  readonly repo: string;
+  /** pass when ci:local exited 0 and the guard artifact was produced; fail otherwise. */
+  readonly status: 'pass' | 'fail';
+  /**
+   * Total errors across all guard tiers.
+   * MUST equal the sum of guardResult.results[tier].errors.length across
+   * all tiers when guardResult is present.
+   */
+  readonly errors: number;
+  /**
+   * Total warnings across all guard tiers.
+   * MUST equal the sum of guardResult.results[tier].warnings.length across
+   * all tiers when guardResult is present.
+   */
+  readonly warnings: number;
+  /** Wall-clock duration of ci:local in milliseconds. */
+  readonly durationMs: number;
+  /** Optional full guard orchestrator output. */
+  readonly guardResult?: GuardResultPayload;
+}
+
+const TIERS: readonly GuardTier[] = [
+  'structural',
+  'behavioral',
+  'invariants',
+  'evolution',
+  'meta',
+];
+
+/**
+ * Throws when result.guardResult is present and its aggregated tier counts
+ * do not match result.errors / result.warnings. Enforces the load-bearing
+ * derivation invariant of the RepoCiResult contract at runtime.
+ */
+export function assertRepoCiResultConsistent(result: RepoCiResult): void {
+  if (!result.guardResult) return;
+  let errorSum = 0;
+  let warningSum = 0;
+  for (const tier of TIERS) {
+    const tierResult = result.guardResult.results[tier];
+    if (!tierResult) continue;
+    errorSum += tierResult.errors.length;
+    warningSum += tierResult.warnings.length;
+  }
+  if (errorSum !== result.errors) {
+    throw new Error(
+      `RepoCiResult invariant violation: repo=${result.repo} errors=${result.errors} but guardResult aggregates to ${errorSum}`,
+    );
+  }
+  if (warningSum !== result.warnings) {
+    throw new Error(
+      `RepoCiResult invariant violation: repo=${result.repo} warnings=${result.warnings} but guardResult aggregates to ${warningSum}`,
+    );
+  }
+}

package/src/execution/index.ts

@@ -157,6 +157,7 @@ export {
   ExecutionTimelineResponseSchema,
   ConfirmExecutionResponseSchema,
   RejectExecutionResponseSchema,
+  StartExecutionResponseSchema,
 } from './schemas'
 
 export type {
@@ -166,4 +167,5 @@ export type {
   ExecutionTimelineResponse,
   ConfirmExecutionResponse,
   RejectExecutionResponse,
+  StartExecutionResponse,
 } from './schemas'

package/src/execution/schemas.ts

@@ -93,3 +93,10 @@ export const RejectExecutionResponseSchema = z.object({
 })
 
 export type RejectExecutionResponse = z.infer<typeof RejectExecutionResponseSchema>
+
+export const StartExecutionResponseSchema = z.object({
+  executionId: z.string().uuid(),
+  redirectUrl: z.string().optional(),
+})
+
+export type StartExecutionResponse = z.infer<typeof StartExecutionResponseSchema>

package/src/identity/index.ts

@@ -42,6 +42,8 @@ export {
   AccountDeleteResponseSchema,
   AccountConfirmDeletionResponseSchema,
   AccountCancelDeletionResponseSchema,
+  BannerDismissedListResponseSchema,
+  BannerDismissResponseSchema,
 } from './schemas';
 export type {
   MeResponse,
@@ -55,4 +57,6 @@ export type {
   AccountDeleteResponse,
   AccountConfirmDeletionResponse,
   AccountCancelDeletionResponse,
+  BannerDismissedListResponse,
+  BannerDismissResponse,
 } from './schemas';

package/src/identity/schemas.ts

@@ -222,3 +222,23 @@ export const AccountCancelDeletionResponseSchema = z.object({
 });
 
 export type AccountCancelDeletionResponse = z.infer<typeof AccountCancelDeletionResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /api/user/preferences/dismissed-banners
+// ---------------------------------------------------------------------------
+
+export const BannerDismissedListResponseSchema = z.object({
+  bannerIds: z.array(z.string()),
+});
+
+export type BannerDismissedListResponse = z.infer<typeof BannerDismissedListResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /api/user/preferences/dismissed-banners/:bannerId
+// ---------------------------------------------------------------------------
+
+export const BannerDismissResponseSchema = z.object({
+  success: z.literal(true),
+});
+
+export type BannerDismissResponse = z.infer<typeof BannerDismissResponseSchema>;

package/src/index.ts

@@ -98,6 +98,17 @@ export {
   SOC2_SCHEMA_VERSION,
 } from './guards/index'
 
+// Cross-repo CI aggregation vocabulary
+// @see ADR-CONT-033 for contracts boundary rationale
+// Note: GuardTier is already exported above from './guards/index' (structurally
+// identical); not re-exported here to avoid a duplicate-identifier collision.
+export type {
+  GuardResultPayload,
+  RepoCiResult,
+} from './ci-results/index'
+
+export { assertRepoCiResultConsistent } from './ci-results/index'
+
 // Compatibility manifest (CI guard vocabulary)
 // @see ADR-2025-12-011 for design rationale
 export { COMPATIBILITY } from './compatibility'
@@ -133,6 +144,8 @@ export {
   AccountDeleteResponseSchema,
   AccountConfirmDeletionResponseSchema,
   AccountCancelDeletionResponseSchema,
+  BannerDismissedListResponseSchema,
+  BannerDismissResponseSchema,
 } from './identity/index'
 export type {
   MeResponse,
@@ -145,6 +158,8 @@ export type {
   AccountDeleteResponse,
   AccountConfirmDeletionResponse,
   AccountCancelDeletionResponse,
+  BannerDismissedListResponse,
+  BannerDismissResponse,
 } from './identity/index'
 
 // Auth domain types