OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

Adopt provider-backed knowledge

Turn Gmail and Google Drive into queryable knowledge without hiding provider state, webhook expiry, or mutation risk in background jobs. The contract layer models the source, the integration layer models provider deltas, and the knowledge runtime owns ingestion/query orchestration.

What you'll build

  • Gmail and Drive sources bound to explicit knowledge spaces.
  • A checkpoint store for leases, cursors, webhook channel expiry, and replay evidence.
  • A mutation gate that blocks unsafe external sends or provider writes.
  • Connect adoption evidence proving you reused the existing ContractSpec surfaces before adding custom provider code.

1) Start from specs and sources

Define the knowledge space and source binding before runtime sync. Provider credentials stay in integration connections; source config stores only identity, scope, and replayable sync state.

knowledge-source.ts
const source = {
  meta: {
    id: "src_drive_support",
    tenantId: "tenant-acme",
    integrationConnectionId: "conn_google_drive",
    spaceKey: "knowledge.support-faq",
    spaceVersion: "1.0.0",
    label: "Support Drive",
    sourceType: "google_drive",
    createdAt: new Date(),
    updatedAt: new Date(),
  },
  syncState: {
    cursorId: "drive-start-page-token",
    watermarkVersion: "drive-v1",
    lease: {
      holder: "knowledge-sync-worker",
      expiresAt: new Date(Date.now() + 5 * 60_000),
      renewalWindowMs: 60_000,
    },
  },
  config: {
    query: "mimeType = 'text/plain' and trashed = false",
  },
};

2) Sync with checkpoints, not blind polling

`KnowledgeRuntime` can load a stored provider delta before listing Gmail or Drive, then save the next checkpoint after indexing. The store can be a database table, workflow state, or Connect-backed replay artifact.

knowledge-runtime.ts
const knowledge = createKnowledgeRuntime({
  collection: "knowledge-support",
  namespace: "tenant-acme",
  embeddings,
  vectorStore,
  gmail,
  drive,
  deltaCheckpointStore,
});

await knowledge.syncGmail(
  { label: "support" },
  { sourceId: "src_gmail_support", evidenceRef: "audit://sync/gmail" },
);

await knowledge.syncDriveFiles(
  { query: "mimeType = 'text/plain' and trashed = false" },
  { sourceId: "src_drive_support", evidenceRef: "audit://sync/drive" },
);

await knowledge.watchDriveChanges(
  {
    channelId: "drive-watch-support",
    webhookUrl: "https://app.example.com/webhooks/google-drive",
  },
  { sourceId: "src_drive_support" },
);

3) Gate mutations before provider writes

External sends and provider mutations should produce a decision envelope whether they execute, block, or run as dry-run. Persist that envelope with the same audit trail as the provider checkpoint.

governed-mutation.ts
const result = await knowledge.runGovernedMutation(
  {
    operation: "gmail.message.send",
    sourceId: "src_gmail_support",
    requiresApproval: true,
    outboundSend: true,
    governance: {
      idempotencyKey: "tenant:gmail-send:123",
      auditEvidence: { evidenceRef: "audit://gmail-send/123" },
      approvalRefs: [{ id: "approval-123" }],
      outboundSendGate: {
        status: "approved",
        evidenceRef: "gate://gmail-send/123",
      },
    },
  },
  () => gmail.sendEmail(message),
  { audit: (envelope) => auditTrail.write(envelope) },
);

4) Adoption evidence

  • ProviderDeltaSyncState persisted for each source after sync or watch renewal.
  • Tombstoned provider records are skipped before indexing or mutation.
  • Outbound mutations carry dry-run, approval, idempotency, audit, and send-gate evidence.
  • Connect adoption resolves existing knowledge and integration surfaces before new runtime code is added.
connect-adoption
contractspec connect adoption sync --json

printf '{"goal":"Wire provider-backed knowledge for Gmail and Drive"}' | \
  contractspec connect adoption resolve --family knowledge --stdin --json
Knowledge sourcesGoogle Drive integration
OSS docsbuildStart with OSS. Adopt Studio when you want the operating layer.
Previous

Use Connect in a repo

Enable Connect in workspace config, verify agent actions, and inspect local review and replay artifacts.

Next

Libraries overview

Navigate the core libraries, runtimes, and system packages that make up the open foundation.

Why ContractSpec

Keep educational and comparison content reachable without letting it define the primary OSS learning path.

ManifestoContract-first APISpec-driven development