[codex] Add enterprise API change governance

README.md

@@ -1,2 +1,6 @@
 # deepevents.ai
 deepevents.ai main codebase
+
+## SCIBASE contribution modules
+
+- [Enterprise API Change Governance](enterprise-api-change-governance/README.md): contract-change review for institutional REST APIs and webhook integrations.

enterprise-api-change-governance/README.md

@@ -0,0 +1,38 @@
+# Enterprise API Change Governance
+
+This module adds a focused Enterprise Tooling slice for institutional REST API and webhook contract governance. It helps university, institute, and corporate R&D admins decide whether an integration-facing change is ready to ship, needs review, should be held, or must be blocked before it breaks downstream systems.
+
+## What It Covers
+
+- Versioned REST route and webhook event change review.
+- Breaking-change detection for removed fields, type changes, new required fields, and short deprecation windows.
+- Critical consumer readiness checks for notice acknowledgement, sandbox evidence, migration tickets, and version negotiation.
+- Restricted research data gates that require DPA evidence before funder or repository integrations receive sensitive payloads.
+- Admin dashboard metrics, prioritized remediation actions, migration plans, export evidence manifests, and signed webhook review events.
+
+## Why This Is Distinct
+
+Existing Enterprise Tooling submissions cover broad dashboards, export packages, compliance evidence packets, audit routing, webhook replay, identity drift, retention/legal hold, data residency, SLA, secret rotation, lab inventory, and compute/storage quotas. This slice focuses specifically on contract-change governance before APIs and webhook schemas are released to enterprise consumers.
+
+## References Reviewed
+
+- OpenAPI-style machine-readable contract diffs for REST API route review.
+- CloudEvents-style event envelopes for routing, replay, and event metadata consistency.
+- Backward-compatible API evolution practices such as versioned releases, deprecation windows, and consumer migration evidence.
+
+## Local Usage
+
+```bash
+npm run check
+npm test
+npm run demo
+```
+
+The demo writes:
+
+- `docs/demo.svg`
+- `docs/governance-report.json`
+
+This PR also includes a short synthetic walkthrough video at `docs/demo.mp4`.
+
+The committed sample data is synthetic and does not contain credentials, private research data, bank details, or personally identifying documents.

enterprise-api-change-governance/data/sample-change-plan.json

@@ -0,0 +1,165 @@
+{
+  "portfolioId": "enterprise-api-governance-demo",
+  "asOf": "2026-05-17T02:30:00.000Z",
+  "policy": {
+    "minimumBreakingDeprecationDays": 90,
+    "criticalConsumerNoticeDays": 60,
+    "minimumRollbackDays": 14,
+    "requireOpenApiDiff": true,
+    "requireWebhookSchemaVersion": true,
+    "requireSandboxEvidence": true,
+    "requireDpaForRestrictedExports": true
+  },
+  "integrations": [
+    {
+      "integrationId": "dspace-archive-prod",
+      "institution": "Northbridge University Library",
+      "systemType": "repository",
+      "criticality": "critical",
+      "contactGroup": "library-platforms",
+      "pinnedApiVersions": ["v1"],
+      "subscribedWebhookTypes": ["project.published.v1", "export.completed.v1"],
+      "lastSuccessfulSandboxRun": "2026-05-05",
+      "supportsVersionNegotiation": true,
+      "notificationStatus": "acknowledged",
+      "migrationTicket": "NBUL-4421",
+      "hasDataProcessingAgreement": true
+    },
+    {
+      "integrationId": "canvas-outcomes-sync",
+      "institution": "Westlake Medical School",
+      "systemType": "lms",
+      "criticality": "standard",
+      "contactGroup": "learning-systems",
+      "pinnedApiVersions": ["v2"],
+      "subscribedWebhookTypes": ["review.completed.v1"],
+      "lastSuccessfulSandboxRun": "2026-05-12",
+      "supportsVersionNegotiation": false,
+      "notificationStatus": "acknowledged",
+      "migrationTicket": "WMS-1180",
+      "hasDataProcessingAgreement": true
+    },
+    {
+      "integrationId": "funder-reporter-nightly",
+      "institution": "Horizon Bioinformatics Institute",
+      "systemType": "funder_portal",
+      "criticality": "critical",
+      "contactGroup": "grants-ops",
+      "pinnedApiVersions": ["v1"],
+      "subscribedWebhookTypes": ["compliance.flagged.v1", "export.completed.v1"],
+      "lastSuccessfulSandboxRun": null,
+      "supportsVersionNegotiation": false,
+      "notificationStatus": "missing",
+      "migrationTicket": null,
+      "hasDataProcessingAgreement": false
+    }
+  ],
+  "changes": [
+    {
+      "changeId": "api-project-export-v3",
+      "title": "Introduce v3 project export manifest with versioned metadata blocks",
+      "ownerTeam": "enterprise-integrations",
+      "surface": "rest_api",
+      "changeKind": "additive_version",
+      "currentVersion": "v2",
+      "proposedVersion": "v3",
+      "effectiveDate": "2026-09-01",
+      "affectedRoutes": ["GET /api/projects/{projectId}/exports", "POST /api/projects/{projectId}/exports"],
+      "affectedWebhookTypes": [],
+      "breaking": false,
+      "restrictedResearchData": false,
+      "openApiDiffAttached": true,
+      "rollbackPlanDays": 30,
+      "parallelRunDays": 120,
+      "schemaDiff": {
+        "removedFields": [],
+        "renamedFields": [],
+        "typeChanges": [],
+        "newRequiredFields": [],
+        "newOptionalFields": ["metadata.versionHistory", "metadata.repositoryTargets"]
+      },
+      "webhookEnvelope": {
+        "usesCloudEvents": true,
+        "schemaVersionField": "data.schemaVersion",
+        "idempotencyKeyField": "data.deliveryId",
+        "signatureVersion": "v2"
+      },
+      "sandboxEvidence": {
+        "fixturePack": "exports-v3-2026-05",
+        "passingIntegrations": ["dspace-archive-prod", "canvas-outcomes-sync"],
+        "failingIntegrations": []
+      }
+    },
+    {
+      "changeId": "api-review-score-removal",
+      "title": "Remove legacy peerReview.score field from review completed payloads",
+      "ownerTeam": "peer-review-platform",
+      "surface": "webhook",
+      "changeKind": "breaking_removal",
+      "currentVersion": "review.completed.v1",
+      "proposedVersion": "review.completed.v2",
+      "effectiveDate": "2026-06-15",
+      "affectedRoutes": [],
+      "affectedWebhookTypes": ["review.completed.v1"],
+      "breaking": true,
+      "restrictedResearchData": false,
+      "openApiDiffAttached": false,
+      "rollbackPlanDays": 3,
+      "parallelRunDays": 29,
+      "schemaDiff": {
+        "removedFields": ["peerReview.score"],
+        "renamedFields": ["peerReview.rubric -> peerReview.rubricBreakdown"],
+        "typeChanges": ["peerReview.reviewerCount:number -> string"],
+        "newRequiredFields": ["peerReview.decisionCode"],
+        "newOptionalFields": []
+      },
+      "webhookEnvelope": {
+        "usesCloudEvents": false,
+        "schemaVersionField": null,
+        "idempotencyKeyField": null,
+        "signatureVersion": null
+      },
+      "sandboxEvidence": {
+        "fixturePack": null,
+        "passingIntegrations": [],
+        "failingIntegrations": ["canvas-outcomes-sync"]
+      }
+    },
+    {
+      "changeId": "api-compliance-flag-pii",
+      "title": "Add restricted compliance flag webhook for funder reporting",
+      "ownerTeam": "compliance-ops",
+      "surface": "webhook",
+      "changeKind": "new_event",
+      "currentVersion": null,
+      "proposedVersion": "compliance.flagged.v2",
+      "effectiveDate": "2026-07-20",
+      "affectedRoutes": ["GET /api/compliance/flags"],
+      "affectedWebhookTypes": ["compliance.flagged.v2"],
+      "breaking": false,
+      "restrictedResearchData": true,
+      "openApiDiffAttached": true,
+      "rollbackPlanDays": 21,
+      "parallelRunDays": 90,
+      "schemaDiff": {
+        "removedFields": [],
+        "renamedFields": [],
+        "typeChanges": [],
+        "newRequiredFields": ["flag.category", "flag.evidenceDigest"],
+        "newOptionalFields": ["flag.funderMandateId"]
+      },
+      "webhookEnvelope": {
+        "usesCloudEvents": true,
+        "schemaVersionField": "data.schemaVersion",
+        "idempotencyKeyField": "data.deliveryId",
+        "signatureVersion": "v2"
+      },
+      "sandboxEvidence": {
+        "fixturePack": "compliance-v2-2026-05",
+        "passingIntegrations": ["dspace-archive-prod"],
+        "failingIntegrations": ["funder-reporter-nightly"]
+      }
+    }
+  ],
+  "signingKeyId": "synthetic-key-2026-05"
+}

enterprise-api-change-governance/docs/acceptance-notes.md

@@ -0,0 +1,41 @@
+# Acceptance Notes
+
+This contribution targets issue `#19` by adding a distinct Enterprise Tooling module for API and webhook contract-change governance.
+
+## Review Scope
+
+- Self-contained dependency-free Node module.
+- Synthetic data only.
+- No external credentials, accounts, payment details, bank information, private research data, or KYC material.
+- No changes to existing application code paths.
+
+## Distinctness
+
+This does not duplicate existing SCIBASE Enterprise Tooling submissions for:
+
+- admin dashboard foundations
+- export packages
+- compliance evidence packets
+- audit signal routing
+- webhook replay ledgers
+- identity provisioning drift
+- retention/legal hold
+- grant portfolio compliance
+- data residency
+- SLA/uptime monitoring
+- secret rotation
+- lab inventory readiness
+- compute/storage quota governance
+
+It covers a narrower pre-release governance layer: whether enterprise-facing API routes and webhook contracts can safely change without breaking institutional consumers.
+
+## Validation Commands
+
+```bash
+cd enterprise-api-change-governance
+npm run check
+npm test
+npm run demo
+```
+
+Demo video: `enterprise-api-change-governance/docs/demo.mp4`.