@contractspec/bundle.library 3.10.0 → 3.10.2

package/src/components/docs/integrations/IntegrationsGoogleDrivePage.tsx

@@ -0,0 +1,88 @@
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function IntegrationsGoogleDrivePage() {
+	return (
+		<div className="space-y-8">
+			<div className="space-y-4">
+				<h1 className="font-bold text-4xl">Google Drive</h1>
+				<p className="text-muted-foreground">
+					Google Drive is modeled as a storage and knowledge-ingestion provider
+					with explicit delta watch state. The contract covers file listing,
+					file retrieval, Drive watches, channel/resource expiry, replay
+					checkpoints, dedupe, idempotency, and tombstones.
+				</p>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Provider contract</h2>
+				<CodeBlock
+					language="typescript"
+					filename="google-drive-provider.ts"
+					code={`interface GoogleDriveProvider {
+  listFiles(query?: GoogleDriveListFilesQuery): Promise<GoogleDriveListFilesResult>;
+  getFile(fileId: string): Promise<GoogleDriveFile | null>;
+  watchChanges?(input: GoogleDriveWatchInput): Promise<GoogleDriveWatchResult>;
+}`}
+				/>
+				<p className="text-muted-foreground text-sm">
+					The provider advertises <code>storage.objects</code>,{' '}
+					<code>knowledge.ingestion.drive</code>, and{' '}
+					<code>provider.delta.watch</code>. Runtime implementations should
+					persist returned deltas before acknowledging sync work.
+				</p>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Delta-aware ingestion</h2>
+				<CodeBlock
+					language="typescript"
+					filename="drive-sync.ts"
+					code={`await knowledge.syncDriveFiles(
+  {
+    query: "mimeType = 'text/plain' and trashed = false",
+  },
+  {
+    sourceId: "src_drive_support",
+    evidenceRef: "audit://sync/drive/support",
+  },
+);
+
+await knowledge.watchDriveChanges(
+  {
+    channelId: "drive-support-watch",
+    webhookUrl: "https://app.example.com/webhooks/google-drive",
+  },
+  { sourceId: "src_drive_support" },
+);`}
+				/>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Production checklist</h2>
+				<ul className="list-inside list-disc space-y-2 text-muted-foreground">
+					<li>Persist `ProviderDeltaSyncState` per Drive source.</li>
+					<li>Renew webhook channels before `webhookChannel.expiresAt`.</li>
+					<li>Skip tombstoned files before indexing or mutating them.</li>
+					<li>
+						Record replay checkpoint and idempotency evidence for retries.
+					</li>
+					<li>
+						Use mutation governance before changing permissions or sending
+						outbound notifications.
+					</li>
+				</ul>
+			</div>
+
+			<div className="flex items-center gap-4 pt-4">
+				<Link href="/docs/integrations/gmail" className="btn-ghost">
+					Previous: Gmail API
+				</Link>
+				<Link href="/docs/knowledge/governance" className="btn-primary">
+					Knowledge governance <ChevronRight size={16} />
+				</Link>
+			</div>
+		</div>
+	);
+}

package/src/components/docs/integrations/IntegrationsOverviewPage.tsx

@@ -24,6 +24,7 @@ const groups = [
 			{ title: 'Qdrant', href: '/docs/integrations/qdrant' },
 			{ title: 'S3 storage', href: '/docs/integrations/s3' },
 			{ title: 'Gmail', href: '/docs/integrations/gmail' },
+			{ title: 'Google Drive', href: '/docs/integrations/google-drive' },
 			{ title: 'Google Calendar', href: '/docs/integrations/google-calendar' },
 		],
 	},

package/src/components/docs/integrations/index.ts

@@ -3,6 +3,7 @@ export { IntegrationsElevenLabsPage } from './IntegrationsElevenLabsPage';
 export { IntegrationsGithubPage } from './IntegrationsGithubPage';
 export { IntegrationsGmailPage } from './IntegrationsGmailPage';
 export { IntegrationsGoogleCalendarPage } from './IntegrationsGoogleCalendarPage';
+export { IntegrationsGoogleDrivePage } from './IntegrationsGoogleDrivePage';
 export { IntegrationsHealthRoutingPage } from './IntegrationsHealthRoutingPage';
 export { IntegrationsMistralPage } from './IntegrationsMistralPage';
 export { IntegrationsOpenAIPage } from './IntegrationsOpenAIPage';

package/src/components/docs/knowledge/KnowledgeGovernancePage.tsx

@@ -0,0 +1,94 @@
+import { CodeBlock } from '@contractspec/lib.design-system';
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function KnowledgeGovernancePage() {
+	return (
+		<div className="space-y-8">
+			<div className="space-y-4">
+				<h1 className="font-bold text-4xl">Knowledge mutation governance</h1>
+				<p className="text-muted-foreground">
+					Provider-backed knowledge is not read-only forever. Email sends, Drive
+					permission changes, tombstone handling, replay repairs, and source
+					metadata updates all need explicit governance before they mutate an
+					external system.
+				</p>
+			</div>
+
+			<div className="grid gap-4 md:grid-cols-2">
+				<div className="card-subtle space-y-2 p-4">
+					<h2 className="font-semibold text-lg">Fail closed</h2>
+					<p className="text-muted-foreground text-sm">
+						Non-dry-run mutations require an idempotency key and audit evidence.
+						Approval-required operations need approval refs. Outbound sends also
+						need an approved send gate.
+					</p>
+				</div>
+				<div className="card-subtle space-y-2 p-4">
+					<h2 className="font-semibold text-lg">Leave evidence</h2>
+					<p className="text-muted-foreground text-sm">
+						Every evaluation returns an audit envelope with status, missing
+						evidence, idempotency, approval refs, and the decision timestamp.
+					</p>
+				</div>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Runtime gate</h2>
+				<CodeBlock
+					language="typescript"
+					filename="knowledge-governance.ts"
+					code={`const result = await executeGovernedKnowledgeMutation(
+  {
+    operation: "drive.permission.update",
+    sourceId: "src_drive_support",
+    requiresApproval: true,
+    governance: {
+      idempotencyKey: "tenant:drive-permission:123",
+      auditEvidence: { evidenceRef: "audit://drive/permission/123" },
+      approvalRefs: [{ id: "approval-123" }],
+    },
+  },
+  () => drive.updatePermission(input),
+  { audit: (envelope) => auditTrail.write(envelope) },
+);
+
+if (result.status === "blocked") {
+  return result.auditEnvelope.requiredEvidence;
+}`}
+				/>
+			</div>
+
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">ContractSpec surface</h2>
+				<p className="text-muted-foreground">
+					Use <code>knowledge.mutation.evaluateGovernance</code> when an app or
+					control-plane workflow needs to expose mutation decisions as a
+					contracted action. It mirrors the runtime helper and gives Connect,
+					ops tools, and review packets one stable contract to reference.
+				</p>
+				<CodeBlock
+					language="typescript"
+					filename="knowledge-operation.ts"
+					code={`import {
+  EvaluateKnowledgeMutationGovernance,
+} from "@contractspec/lib.contracts-spec/knowledge/operations";
+
+registry.register(EvaluateKnowledgeMutationGovernance);`}
+				/>
+			</div>
+
+			<div className="flex items-center gap-4 pt-4">
+				<Link href="/docs/knowledge/sources" className="btn-ghost">
+					Knowledge sources
+				</Link>
+				<Link
+					href="/docs/guides/provider-backed-knowledge"
+					className="btn-primary"
+				>
+					Adoption guide <ChevronRight size={16} />
+				</Link>
+			</div>
+		</div>
+	);
+}

package/src/components/docs/knowledge/KnowledgeOverviewPage.tsx

@@ -16,6 +16,16 @@ const knowledgeTracks = [
 		body: 'Connect tenant-owned sources explicitly instead of letting context leak in through prompts alone.',
 		href: '/docs/knowledge/sources',
 	},
+	{
+		title: 'Governance',
+		body: 'Gate provider-backed mutations with dry-runs, approvals, idempotency, audit evidence, and outbound-send policy.',
+		href: '/docs/knowledge/governance',
+	},
+	{
+		title: 'Provider-backed adoption',
+		body: 'Wire Gmail and Google Drive ingestion through checkpointed deltas, tombstones, watches, and Connect evidence.',
+		href: '/docs/guides/provider-backed-knowledge',
+	},
 	{
 		title: 'Examples',
 		body: 'See how support, compliance, and product systems consume trusted knowledge at runtime.',

package/src/components/docs/knowledge/KnowledgeSourcesPage.tsx

@@ -230,6 +230,43 @@ export function KnowledgeSourcesPage() {
 				</ol>
 			</div>
 
+			<div className="space-y-4">
+				<h2 className="font-bold text-2xl">Provider delta state</h2>
+				<p className="text-muted-foreground">
+					Runtime-backed providers should persist a{' '}
+					<strong>ProviderDeltaSyncState</strong> per source before sync work is
+					acknowledged. Gmail and Google Drive adapters use that checkpoint to
+					resume cursors, renew watches, skip tombstones, dedupe webhook events,
+					and replay from a known point after retries.
+				</p>
+				<div className="overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm">
+					<pre>{`type ProviderDeltaSyncState = {
+  lease?: { holder: string; expiresAt: string; renewalWindowMs: number };
+  cursor?: { cursor?: string; watermark?: string; watermarkVersion?: string };
+  webhookChannel?: { channelId: string; resourceId?: string; expiresAt?: string };
+  providerEventId?: string;
+  dedupeKey?: string;
+  idempotencyKey?: string;
+  replayCheckpoint?: { checkpointId: string; sequence?: string | number };
+  tombstone?: { deletedAt: string; reason?: string };
+};`}</pre>
+				</div>
+				<div className="flex flex-wrap gap-3">
+					<Link href="/docs/integrations/gmail" className="btn-ghost">
+						Gmail integration
+					</Link>
+					<Link href="/docs/integrations/google-drive" className="btn-ghost">
+						Google Drive integration
+					</Link>
+					<Link
+						href="/docs/guides/provider-backed-knowledge"
+						className="btn-ghost"
+					>
+						Provider-backed guide
+					</Link>
+				</div>
+			</div>
+
 			<div className="space-y-4">
 				<h2 className="font-bold text-2xl">Best practices</h2>
 				<ul className="list-inside list-disc space-y-2 text-muted-foreground">
@@ -247,6 +284,14 @@ export function KnowledgeSourcesPage() {
 						Document the purpose and ownership of each source for your team
 					</li>
 					<li>Use manual sync for sensitive or infrequently updated content</li>
+					<li>
+						Run external mutations through{' '}
+						<Link href="/docs/knowledge/governance" className="text-primary">
+							knowledge mutation governance
+						</Link>{' '}
+						before sending email, changing Drive permissions, or repairing
+						replay state.
+					</li>
 				</ul>
 			</div>
 

package/src/components/docs/knowledge/index.ts

@@ -1,5 +1,6 @@
 export { KnowledgeCategoriesPage } from './KnowledgeCategoriesPage';
 export { KnowledgeExamplesPage } from './KnowledgeExamplesPage';
+export { KnowledgeGovernancePage } from './KnowledgeGovernancePage';
 export { KnowledgeOverviewPage } from './KnowledgeOverviewPage';
 export { KnowledgeSourcesPage } from './KnowledgeSourcesPage';
 export { KnowledgeSpacesPage } from './KnowledgeSpacesPage';