Contextfulv0.23.0

Docs / Specification

contract connector · 40-connector.md · 41-secrets.md · 42-drive-extensions.md · guide · card

Connectors and credentials — card

Generated by contextful-spec state from the contract’s files and spec/terms/connector.toml; not authored.

Operations

OperationCoversClausesProved
exportConnector interfaces: shared types, source and destination worlds, optional interfaces and compiled-in sources.90
importHost imports and the configuration table the host forwards to a guest.60
declare-capabilityManifest-declared host access, the probe that checks a bound credential’s granted scopes, and the window a connector’s destination deduplicates a key for.90
widenComparison of a candidate connector manifest with its admitted predecessor, and operator approval of additional host access.22
meterVendor quota declarations, limiter bindings, pre-send checks, permit reservations, denials and usage reports.210
inferModel requests: endpoint selection, data boundary markers and output provenance labels.150
packageDistribution form, digest pinning, per-connector resource bounds and world versioning.360
sourceThe declared behavior of each source compiled into the engine.1440
referenceOutbound credential references, the secret:// scheme and value templates.110
resolveThe provider interface, adapter order, request-time resolution, credential buffers and deployment security configurations.130
leaseThe first credential adapter: credential lease declarations, mint requests, expiry, failures and the mint credential.210
attachHost handling of outbound requests: network transport, permitted hosts and addresses, credential headers, redirects and URL scrubbing.230
rotateCredential rotation responsibilities and mechanisms.180
recordOptional operator metadata, provider observations, the inventory of configured bindings, and the provider attribution a run emits.160
principal-secretsPer-principal credential names and the adapter that serves their material.50
drive-picksFiles a principal selects through Picker, the selection position, and the rows a tenant connection stores.110
drive-sheetGoogle Sheets capture as structured rows, separate from PDF page capture.80
drive-changesChange cursors and complete listings of a selected Drive corpus.60
drive-domain-authOrganization-approved Drive access and the principal whose authority each request carries.40

Error cases

ErrorWhenClause
ConnectorConfigRejectedA forwarded guest configuration value of the wrong type, above its size bound, or carrying a reference.connector.import.config-shape
ConnectorConfigUnclaimedA guest configuration table declared against a guest exporting no configuration interface.connector.import.config-unclaimed
ConnectorUndeclaredAccessHost access a connector reaches for that its manifest does not list.connector.declare-capability.undeclared-access
ConnectorAllowlistRejectedAn allowlist that is empty or bare-wildcard, or an entry carrying a scheme, port or path.connector.declare-capability.allowlist-shape
ConnectorScopeProbeRejectedA scope probe declaring a scopes header that is empty or not an HTTP field name.connector.declare-capability.probe-shape
ConnectorScopeExceededA granted scope outside the manifest’s declared expectation.connector.declare-capability.scope-exceeded
ConnectorScopeUnverifiedA scope probe response carrying no granted-scopes header, or one naming no scope or holding a byte outside visible ASCII.connector.declare-capability.scope-unverified
ConnectorForwardRejectedA limiter declaration forwarding a credential-bearing response header.connector.meter.forward-credential
ConnectorQuotaUnboundA declared limiter quota with no operator binding.connector.meter.quota-unbound
ConnectorLimiterBindingRejectedA non-HTTPS limiter endpoint, one carrying a query, fragment or userinfo, or a limiter token that is not a secret reference.connector.meter.binding-transport
ConnectorLimiterUnreadableA limiter response the engine cannot parse.connector.meter.unreadable-answer
ConnectorUnmeteredA vendor request without a granted reservation under a declared limiter.connector.meter.unmetered-request
ConnectorEgressRefusedAn outbound hop the pre-send hook refused before name resolution.connector.meter.hook-refusal
InferHostedToolUnderHorizonA model call under a credential horizon declares a provider-hosted tool.connector.infer.hosted-tools
ConnectorOciReferenceInvalidAn OCI reference with an empty registry, repository or selector.connector.package.oci-reference
ConnectorOciArtifactUnsupportedAn OCI manifest that is not schema 2 with exactly one WebAssembly component layer.connector.package.oci-component-layer
ConnectorOciLayerMismatchOCI layer bytes differing from their manifest descriptor digest.connector.package.oci-layer-integrity
ConnectorArtifactCacheCorruptProject-cached artifact bytes differing from their digest key.connector.package.remote-cache-corrupt
ConnectorArtifactFetchFailedA remote artifact manifest or byte fetch that fails.connector.package.remote-fetch-failure
ConnectorRemoteUnpinnedA remote artifact reference with no 64-hex content pin.connector.package.remote-unpinned
ConnectorInsecureArtifactA connector artifact referenced over plain HTTP.connector.package.insecure-artifact
ConnectorDigestMismatchResolved artifact bytes whose re-hash differs from the pin.connector.package.digest-mismatch
ConnectorLocalUnpinnedAn unpinned local artifact under a set pin requirement.connector.package.local-unpinned
ConnectorHostPinRefusedA pin written from a host-toolchain build.connector.package.host-built-pin
ConnectorManifestRejectedA component source with no manifest, or a manifest carrying an unread key or a value off its shape.connector.package.manifest-keys
ConnectorPositionOwnedAn incremental field declared beside a component source, whose position the guest owns.connector.package.component-position
ConnectorConditionalRejectedA conditional read beside a pagination shape or a declared incremental field.connector.source.conditional-rejected
ConnectorPaginationAmbiguousTwo pagination shapes on one source.connector.source.pagination-ambiguity
ConnectorPointerAmbiguousBoth expansion pointer forms on one block.connector.source.pagination-ambiguity
ConnectorPageLoopA paging token or link the vendor already served.connector.source.page-loop
ConnectorTableUnmatchedA table off the source’s table pattern, or binding a dot segment.connector.source.table-unmatched
ConnectorPlaceholderUnboundA URL or bound-column placeholder with no table pattern to bind it.connector.source.placeholder-unbound
ConnectorBoundColumnOccupiedA fetched row already carrying a column the source binds from the table name.connector.source.bound-column-occupied
ConnectorExpansionFailedA failed expansion follow-up, failing the whole read.connector.source.follow-up-failure
ConnectorTemplateRejectedA pointer template with no placeholder, or one binding into the URL authority.connector.source.template-shape
ConnectorPointerColumnMissingAn expansion placeholder naming a column the rows lack as a scalar.connector.source.pointer-column-missing
ConnectorTargetColumnOccupiedAn expansion target column the index rows already carry.connector.source.target-column-occupied
ConnectorFormatKeyRejectedA record path, pagination shape or decode key the chosen format does not read.connector.source.format-key-mismatch
ConnectorEncodingInvalidA delimited body invalid under its declared encoding.connector.source.declared-encoding
ConnectorClockColumnRejectedA delimited clock column neither RFC 3339 nor a fixed-width digit stamp.connector.source.clock-column-spelling
ConnectorCellOutOfRangeA worksheet cell holding a value past the header’s width.connector.source.cell-out-of-range
ConnectorExternalReferenceA workbook declaration, part or relationship pointing outside the archive.connector.source.external-reference
ConnectorIncrementalUnsupportedAn incremental position against a workbook source.connector.source.workbook-incremental
ConnectorObjectAddressRejectedAn object source declaring both or neither of a key and a prefix.connector.source.object-address
ConnectorFrontmatterRejectedA nested map, block scalar or reserved-prefix key in a note’s frontmatter.connector.source.frontmatter-shape
ConnectorConversionRequiredA compound-binary office container, answered with the conversion command.connector.source.conversion-required
ConnectorPageCursorMissingA next-page announcement naming no cursor.connector.source.page-cursor-missing
ConnectorMetricGrainRejectedA metric read at a grain the vendor estimates.connector.source.metric-grain
ConnectorOrderingColumnRejectedA report stream ordered by the engine-injected ingest stamp.connector.source.ordering-column
ConnectorAuthTerminalAn authentication failure on a report read.connector.source.report-auth
ConnectorReportFailedA report run the vendor answered with a declared failed state.connector.source.report-failed
ConnectorImageHeaderUnreadableAn image file header that does not parse.connector.source.image-header
ConnectorQuotabilityMismatchAn image body and its quotability marker not null together.connector.source.marker-body-pairing
ConnectorProviderOriginRejectedA search call to a non-TLS transport or a host other than the provider’s.connector.source.provider-origin
ConnectorDriveRootsInvalidAn empty, oversized, repeated or ambiguous Drive root selection.connector.source.drive-root-set
ConnectorDriveRootRejectedA selected Drive root that does not exist or lies outside the declared Shared Drive.connector.source.drive-root-validation
ConnectorDriveModeUnknownA Drive capture mode other than bytes-and-pages or metadata-only.connector.source.drive-mode
ConnectorDriveVersionMovedA Drive file whose version changes during metadata-only capture.connector.source.drive-version-consistency
ConnectorDriveListingExceededA Drive listing reaching its request cap before all selected folders are exhausted.connector.source.drive-list-bound
SecretForeignPlaceholderA template carrying ${env://NAME} or a bare ${NAME}.connector.reference.foreign-placeholder
SecretMalformedTemplateAn unclosed, empty or nested placeholder.connector.reference.malformed-placeholder
SecretMaterialInDeclarationA credential-shaped literal where a reference belongs.connector.reference.material-in-a-declaration
SecretNameShadowedA logical name answered by two assembled adapters.connector.resolve.shadowed-name
SecretUnresolvedReferenceA logical name no assembled adapter answers.connector.resolve.unresolved-name
SecretInlineCredentialA plaintext credential written inline in a manifest outside the development profile.connector.resolve.inline-outside-development
SecretLeaseScopesEmptyThe lease backend selected with no scope declared.connector.lease.empty-scope-set
SecretMalformedLeaseA lease with no expiry, or one already past on arrival.connector.lease.malformed-lease
SecretLeaseScopeUnknownThe mint endpoint answering 404 for a declared scope.connector.lease.unknown-scope
SecretMintRejectedThe mint endpoint answering 401 or 403.connector.lease.mint-rejected
SecretLeaseRequestRejectedThe mint endpoint answering another 4xx.connector.lease.request-rejected
SecretBootstrapUnresolvedNo adapter behind the lease provider answering the bootstrap reference.connector.lease.bootstrap-unserved
SecretBootstrapLeasedThe bootstrap name among the declared lease scopes.connector.lease.bootstrap-declared-leased
SecretLeaseRedirectThe mint endpoint answering a redirect.connector.lease.redirect
SecretUnpermittedRequestA request to a host the declaration does not cover.connector.attach.unpermitted-request
ConnectorPrivateAddressA permitted host name resolving to a private, link-local, loopback or metadata address.connector.attach.private-address
ConnectorPrivateRangeRejectedAn admitted private range overlaps loopback, link-local or the metadata address.connector.attach.private-range-rejected
SecretWildcardHostA wildcard or table-bound endpoint host beside a bound credential.connector.attach.bound-host
SecretLiteralAttachValueAn attach value embedding no reference.connector.attach.literal-attach-value
SecretRedirectOffOriginA hop or next link weakening the transport or leaving the configured host and port.connector.attach.weakened-hop
SecretCleartextEndpointA sensitive header bound for a cleartext endpoint outside loopback.connector.attach.cleartext-endpoint
SecretCredentialInUrlA configured endpoint carrying userinfo.connector.attach.credential-in-a-url
SecretRotationWriteDeniedA refused put of a refreshed token, or an answering adapter with no write half.connector.rotate.write-back-denied
SecretRefreshRejectedA token endpoint answering a refresh with a redirect, a 4xx other than 429, or no access token.connector.rotate.refresh-refused
SecretRecordRejectedAn operator record naming no configured binding, or carrying an unknown key, mistyped value or credential-shaped string.connector.record.record-rejected
ConnectorDriveFilesInvalidAn empty, repeated or mixed individual-file selection.connector.drive-picks.file-selection-invalid
ConnectorDriveFileRejectedA selected id is inaccessible or is not a file.connector.drive-picks.file-access
ConnectorDriveDomainRejectedA delegated subject lies outside the approved Workspace domain.connector.drive-domain-auth.domain-boundary

Bounds

BoundValueBasisClause
connector-attribution-entries512 entrieschosenconnector.export.attribution-budget
connector-attribution-value512 Bchosenconnector.export.attribution-budget
connector-guest-config64 KiBchosenconnector.import.config-shape
connector-limiter-call5 schosenconnector.meter.acquire-call
connector-fence-token16 Bchosenconnector.infer.marker-derivation
connector-fence-label200 charschosenconnector.infer.label-hygiene
connector-memory-ceiling2 GiBchosenconnector.package.linear-memory
connector-memory-default256 MiBchosenconnector.package.linear-memory
connector-deadline-granularity100 mschosenconnector.package.call-deadline
connector-discovery-deadline60 schosenconnector.package.call-deadline
connector-read-deadline30 schosenconnector.package.call-deadline
connector-in-flight8 requestschosenconnector.package.session-budget
connector-session-log1 MiBchosenconnector.package.session-budget
connector-request-body8 MiBchosenconnector.package.request-body
connector-walk-pages1000 requestschosenconnector.source.page-cap
connector-expansion-buffer256 MiBchosenconnector.source.expansion-budget
connector-expansion-elapsed600 schosenconnector.source.expansion-budget
connector-expansion-follow-ups200 requestschosenconnector.source.expansion-budget
connector-office-decompression64 MiBchosenconnector.source.decompression-budget
connector-worksheet-entry32 Bchosenconnector.source.worksheet-landing
connector-worksheet-rows1048576 rowschosenconnector.source.worksheet-landing
connector-worksheet-text64 MiBchosenconnector.source.worksheet-landing
connector-object-expansion256 MiBchosenconnector.source.object-expansion
connector-document-chunk8192 Bchosenconnector.source.heading-threshold
connector-document-file-bytes64 MiBchosenconnector.source.file-cap
connector-drive-roots16 entrieschosenconnector.source.drive-root-set
connector-drive-file-bytes64 MiBchosenconnector.source.drive-file-cap
connector-secret-name128 charschosenconnector.reference.reference-scheme
connector-resolve-cache300 schosenconnector.resolve.cache-ttl
connector-lease-retire-cap30 schosenconnector.lease.retirement-margin
connector-lease-retire-share10 percentchosenconnector.lease.retirement-margin
connector-lease-vendor-requests0 requestschosenconnector.lease.vendor-requests-on-failure
connector-lease-mint-calls1 callschosenconnector.lease.calls-per-resolver
connector-exec-proxy-body64 MiBchosenconnector.attach.exec-proxy-request
connector-exec-proxy-head64 KiBchosenconnector.attach.exec-proxy-request
connector-record-expiry-warning30 dchosenconnector.record.expiry-warning
connector-drive-file-selection128 entrieschosenconnector.drive-picks.file-selection-limit

Types

Each struct or enum a {{type:<path>}} pointer names, with the keys serde reads and their doc comments.

contextful_connectors::image::BodyDeclaration

The struct at crates/contextful-connectors/src/image.rs, named by connector.source.image-body.

KeyDoc
urlThe reader each image’s bytes are posted to.
headersHeader name to value template, hydrated onto every request.
textThe JSON pointer to the body text in the answer, /text by default.
quotabilityThe JSON pointer to the quotability marker in the answer, /quotability by default.

contextful_connectors::report::ReportConfig

The struct at crates/contextful-connectors/src/report.rs, named by connector.source.report-declaration.

KeyDoc
partitions
metrics
estimatedPer metric, the grains the vendor estimates rather than computes.
entity
date
order_by
pages_per_read
poll_budget
lookback_days
window_days
throttle_codes
rows
more
cursor
next
cursor_param
error_code

contextful_connectors::report::declared::VendorDeclaration

The struct at crates/contextful-connectors/src/report/declared.rs, named by connector.source.report-declaration.

KeyDoc
headersHeader name to value template, hydrated onto every request.
createThe request that creates a report run for one partition and window.
pollThe request that reads a run’s state.
stateWhere a poll’s answer holds the run’s state, and the values naming each outcome.
resultWhere a ready run’s rows are read.

contextful_connectors::search::SearchDeclaration

The struct at crates/contextful-connectors/src/search.rs, named by connector.source.search-config.

KeyDoc
urlThe provider URL template, holding {query} and {since}.
queriesQuery name to query text; each name holds its own watermark.
freshnessThe span before the fire’s instant a query holding no watermark reads from, such as 7d.
max_resultsThe most results one query’s pass lands.
headersHeader name to value template, hydrated onto every request.
resultsThe JSON pointer to a page’s result array, /results by default.
cursorThe JSON pointer to a page’s next cursor, /next by default.
cursor_paramThe query parameter carrying the cursor, cursor by default.
timeThe result field holding its instant, published_at by default.

contextful_core::connector::manifest::Raw

The struct at crates/contextful-core/src/connector/manifest.rs, named by connector.package.manifest-keys.

KeyDoc
name
version
world
wasm
wasm_sha256
require_wasm_pin
build
capabilities
dedup_window_secs
auth

contextful_core::connector::manifest::RawAuth

The struct at crates/contextful-core/src/connector/manifest.rs, named by connector.rotate.auth-policy.

KeyDoc
token_endpointThe token endpoint each refresh posts to, TLS or loopback.
client_idThe OAuth client identifier.
client_secretThe client secret, one ${secret://<name>} reference.
refresh_tokenThe refresh token, one ${secret://<name>} reference whose adapter stores each replacement.
access_tokenThe access token, one ${secret://<name>} reference attach templates name and the host alone answers.
scopeThe scope each refresh requests.

contextful_core::connector::record::OperatorRecord

The struct at crates/contextful-core/src/connector/record.rs, named by connector.record.record-table.

Decisions

SectionCited by
A-connector#content-pin-trustconnector.package.oci-component-layer, connector.package.oci-registry-bearer, connector.package.remote-unpinned, connector.package.component-load
A-connector#credential-custody-staysconnector.record.operator-record, connector.record.provider-custody, connector.record.record-table, connector.record.observe-port
A-connector#credentials-references-workloadconnector.source.http-headers, connector.reference.foreign-placeholder, connector.reference.environment-is-a-miss, connector.reference.material-in-a-declaration, connector.resolve.provider-chain, connector.resolve.hydration-is-just-in-time, connector.lease.lease, connector.lease.unknown-scope, connector.lease.bootstrap-credential, connector.lease.bootstrap-unserved, connector.lease.bootstrap-declared-leased
A-connector#drive-capture-bindsconnector.source.drive-root-set, connector.source.drive-root-validation, connector.source.drive-root-walk, connector.source.drive-overlap, connector.source.drive-mode, connector.source.drive-metadata-only, connector.source.drive-selection-position, connector.source.drive-selection-removals
A-connector#egress-passes-transporttopology.package.transport-optional, connector.meter.binding-transport, connector.meter.pre-send-hook, connector.meter.hook-composition, connector.meter.hook-settle, connector.infer.mediated-call
A-connector#exec-egress-proxiedrun.exec.env-credential, connector.attach.exec-environment, connector.attach.exec-proxy, connector.attach.exec-proxy-attach
A-connector#executables-content-pinnedrun.own.pinned-plan-changed, run.own.admission-pin, run.exec.missing-binary, run.exec.unpinned-path, run.exec.digest-mismatch, connector.package.remote-cache, connector.package.insecure-artifact, connector.package.digest-mismatch, connector.package.local-unpinned
A-connector#guest-world-targetsconnector.export.authoring-path, connector.import.config-shape
A-connector#host-access-quotarun.select.unmetered-grant, run.select.metered-client, run.bind.reach-client, run.bind.reach-grant, connector.declare-capability.declared-grant, connector.declare-capability.undeclared-access, connector.declare-capability.allowlist-shape, connector.declare-capability.scope-exceeded, connector.meter.quota-unbound, connector.meter.unreadable-answer, connector.meter.unmetered-request
A-connector#manifest-widening-bindsconnector.widen.host-inclusion, connector.widen.host-witness
A-connector#outbound-transport-originrun.fetch.scheme, run.fetch.address-literal, connector.source.next-link-origin, connector.source.external-reference, connector.source.provider-origin, connector.lease.mint-transport, connector.lease.redirect, connector.attach.no-material-to-a-guest, connector.attach.unpermitted-request, connector.attach.transport-port, connector.attach.resolve-once, connector.attach.bound-host, connector.attach.redirect-pinning, connector.attach.weakened-hop, connector.attach.cleartext-endpoint, connector.attach.mediation-covers-every-egress
A-connector#picker-files-bindconnector.principal-secrets.write-serialization, connector.drive-picks.file-selection, connector.drive-picks.file-withdrawn, connector.drive-picks.file-position
A-connector#pin-builder-runsconnector.package.oci-layer-integrity, connector.package.build-source, connector.package.pin-verb, connector.package.host-built-pin, connector.package.component-grant
A-connector#precompiled-components-reuseconnector.package.artifact-cache
A-connector#remote-artifacts-useconnector.package.remote-transport, connector.package.remote-cache
A-connector#rotation-writes-forwardconnector.lease.head-of-chain, connector.rotate.division-of-labor, connector.rotate.oauth-credential, connector.rotate.write-back-denied, connector.rotate.conditional-put, connector.rotate.access-token, connector.rotate.refresh-answer
A-connector#unreadable-objects-filesconnector.source.object-unreadable, connector.source.file-unreadable
A-connector#untrusted-input-decodestopology.package.decode-network-free, run.land.unreadable-input, run.land.dead-letter, run.land.partial-parse, run.land.parse-boundary, run.land.parse-crashed, run.fetch.charset, run.fetch.not-utf8, connector.source.parse-containment, connector.source.office-part-selection, connector.source.decompression-budget, connector.source.cell-out-of-range, connector.source.workbook-cell-typing, connector.source.frontmatter-shape, connector.source.conversion-required, connector.source.image-header, connector.source.marker-body-pairing