Contextfulv0.23.0

Docs / Specification

contract surface · 70-control-plane.md · 71-console.md · guide · card

Operator surfaces — card

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

Operations

OperationCoversClausesProved
armThe schedule grammar and cron dialect, the trigger adapter and its durability, the wake route, and how an entry computes its next fire.130
reconcileThe control source, snapshot pointer, signed pulled-head validation against local declarations, schedule diff, and what a failed poll leaves running.90
fireJob declaration, the closed kind union, same-tick order, the fire watermark, and one-shot evaluation.270
dispatchThe bounded fire pool and its exclusion keys, the reconciler’s hold on the cadence lease, step results, and the worker adapter with its attempt-fenced callback.280
delegateA delegate is deploy-bound code outside the binary that runs a store-driven item’s body over one signed call request and answers with a closed outcome vocabulary.150
editThe configuration document, the records it presents read-only, the structured schedule specification, and connector configuration.30
applyValidation, the immutable version claim, the pointer advance, the owner’s storage, and the authority an apply carries.220
resideWhere the data plane runs, the region allow-set gating placement, and operation with no external reach.30
connectionRuntime lifecycle of one tenant’s external source connection and its scheduled pipeline.110
open-consoleThe hosted console’s two pages, their API routes, identity gates, page grants and engine capabilities.160
register-storeWhich stores a deployment serves, how each store’s credential and binding names derive, and how a request reaches a store’s origin.40
visualizeThe Admin page’s operational views: the workflow canvas, run history and data lineage.110
packageThe client library, its four deployment shapes and transports, and the credential each shape carries.30
speakThe language every Query-visible string carries, the audience contract, and the deterministic backstops beneath it.30
groundWhere an answer’s material comes from: the closed tool set, the two trust layers, the per-reader credential, the web supplement and the sources block.120
plan-turnThe shape of one turn: planner scaffolding, the replanning round, the answerability test, the code path, and the store’s prompt overlay.60
set-vantageA session’s time basis: its vantage, the bound each leg carries, the snapshot timeline and the arrivals strip.30
browseWhat a store advertises before a question: discovered chips, humanized labels, the insights panel and the file gallery.50
learnThe reading loop’s memory: recall ahead of planning, the per-turn distillation and the labels its conclusions inherit.40
renderThe three channels, the component union, deterministic component choice, view hints and the sanitizer walk.30
briefThe proactive greeting card: its derivation, payload, matching tiers, client-side clock and the absence it earns.60
publish-answerThe moment an answer computed for one operator reaches a place other people read.30

Error cases

ErrorWhenClause
ScheduleUnreadableA schedule string the grammar or cron dialect cannot read.surface.arm.unreadable-schedule
TriggerAdapterUnknownA trigger value naming no adapter.surface.arm.unknown-trigger
TriggerFaceMissingThe external trigger on a deployment serving no route for the wake.surface.arm.trigger-face-missing
ControlPointerMalformedA snapshot pointer body that is not wholly a version.surface.reconcile.pointer-malformed
ControlSnapshotUnreadableA poll that could not read its pointer or parse the named document.surface.reconcile.fail-static
ControlSourceNotLoopbackA control URL whose host is not a loopback address.surface.reconcile.loopback-only
ControlSnapshotUntrustedA pulled control head fails attestation, ancestry or local validation.surface.reconcile.pulled-control-untrusted
JobKindUnknownA job block naming a kind outside the union, or carrying a command.surface.fire.job-kind-unknown
JobTargetUnboundA job target binding to no produced table or declared model.surface.fire.target-unbound
CycleControlSourceUnresolvedA control source that does not resolve under one-shot evaluation.surface.fire.cycle-control-source
JobConcurrencyUnsetA store-driven job block declaring no positive max_in_flight.surface.fire.store-driven-concurrency
JobBodyUnregisteredA store-driven job block naming a body the binary does not register.surface.fire.store-driven-body
JobKindUndispatchedA job block naming a maintenance kind no fire runs.surface.fire.kind-undispatched
DispatchUnitNotAHeadA due id that is a step of a dependent run rather than its head.surface.dispatch.not-a-head
StepResultRefusedA step callback body that is no pointer, object-store key, catalog row id or failure line, or passes the cap.surface.dispatch.step-result
DispatchCallbackRejectedA heartbeat or callback carrying a bad signature, a superseded attempt, a skewed timestamp or a closed step.surface.dispatch.callback-rejected
DispatchSubmitRejectedA worker submission unsigned, skewed, or naming a callback off the worker’s relay.surface.dispatch.submit-signed
FireCredentialMissingA serve scheduling a store-driven or synthesize job with neither an issuer key nor an inherited credential.surface.dispatch.fire-credential-missing
FireCredentialZoneUnsetA serve minting fire credentials under a root whose project declares no default zone.surface.dispatch.fire-credential-zone
JobDelegateUnboundA store-driven body naming a delegate the daemon’s configuration does not bind.surface.delegate.binding
DelegateHostRefusedA delegate URL that is not plain HTTP to a loopback host or the delegate virtual host, or carries a credential.surface.delegate.host
DelegateAnswerRejectedA delegate answer unsigned, skewed, outside the outcome vocabulary, naming an undeclared table or over the step-result cap.surface.delegate.rejected
DelegateSubmitUnfilledA store-driven fire whose delegate binds the submit mode, which no fire dispatches.surface.delegate.submit-unfilled
DelegateTimeoutRefusedA call delegate’s timeout declared above the ceiling.surface.delegate.call-timeout-ceiling
SecretMaterialInDocumentA credential value written into the configuration document.surface.edit.secret-in-document
ConnectorUploadRefusedA connector artifact offered through the operator surface.surface.edit.connector-upload
ManifestVersionConflictAn apply whose pointer compare-and-swap lost to a concurrent apply.surface.apply.version-race
ApplyValidationRefusedA document engine validation refused; no version was claimed.surface.apply.validation
ConfigOwnerUnconfiguredA configuration owner with no storage or no credential behind it.surface.apply.owner-unconfigured
ConditionalWriteUnsupportedA configuration owner or catalog backend lacking linearizable conditional replacement.surface.apply.weak-conditional-backend
StoreNotInitializedAn edit or apply against a store that has taken no guarded import.surface.apply.uninitialized-store
ControlAttestationUnavailableA synced control claim lacks an admitted admin capability or signing port.surface.apply.attestation-unavailable
ControlOperatorAttestationInvalidAn Admin mutation without a fresh single-use console signature for its verified operator and request.surface.apply.operator-attestation
ControlDraftAbsentAn Admin apply with no validated store draft.surface.apply.draft-absent
ControlAdminGrantMissingA served control request lacking an untenanted Admin grant over every table.surface.apply.served-admin-grant
ControlRequestMalformedA served control edit or apply body outside its route’s exact fields.surface.apply.served-malformed
ControlUnavailableA served control request failing without an authority or surface refusal.surface.apply.served-unavailable
EnforceRegionMismatchA configured resource resolving outside the residency allow-set.surface.reside.region-mismatch
ResidencySitesDivergeA push whose residency allow-set differs from the one another site recorded in the bucket manifest.surface.reside.site-regions
ConnectionScopeDeniedA connection mutation names a tenant or principal outside the admitted credential.surface.connection.authority
ConnectionIdConflictA connection id already binds a different declaration.surface.connection.idempotent-create
ConnectionRequestMalformedA connection request body outside its route’s exact fields.surface.connection.malformed
ConnectionUnknownA pause or delete naming no standing connection.surface.connection.unknown
ConsolePageForbiddenA page or API call lacking verified identity and its page grant.surface.open-console.wrong-page
ConsoleAdminGrantMissingAn Admin edit or apply lacking a server-held admin capability.surface.open-console.admin-grant
StoreRegistryUnreadableA store registry payload that does not parse.surface.register-store.registry-unreadable
StoreEntryMalformedOne registry entry that does not decode.surface.register-store.malformed-entry
StoreIdReservedA configured store claiming a built-in id.surface.register-store.reserved-id
StoreNameAuthoredA store entry carrying its own credential or binding name.surface.register-store.authored-name
ExternalStepUnboundAn external step input or output naming no declared table, model, pipeline or job.surface.visualize.external-unbound
ExternalStepCollisionAn external step name repeating another external, a job or a pipeline.surface.visualize.external-collision
StdioCredentialMissingA process-transport client with no credential.surface.package.stdio-credential
StoreSelectorAbsentA spawned engine finding no project manifest above its working directory.surface.package.store-selector
OwnerCredentialInvalidA process owner flag with no signed claim for the selected local store.surface.package.owner-flag
ConsoleSuggestionUnanswerableA suggested prompt whose answer is a decline.surface.speak.unanswerable-suggestion
ConsoleUngroundedAnswerAnswer prose composed in a turn holding no tool result.surface.ground.ungrounded-answer
ConsoleToolNotAdmittedA tool call outside the turn’s admitted packs.surface.ground.unadmitted-tool
ConsoleMutatingToolRequestedA client-reachable path naming a write.surface.ground.mutating-tool
ConsoleWriteToolOnOrgFaceA write tool registered on an organization-wide face.surface.ground.org-face-read-only
ConsoleFileAccessDirectA table function reading stored bytes by path on the caller surface.surface.ground.direct-file-read
ConsoleTokenExchangeRefusedA per-reader mint the store’s exchange route refused.surface.ground.mint-refused
ConsoleAnswerModelUnlistedAn Admin request named an answer model the deployment does not list.surface.ground.answer-model
ConsolePlannerReachedMemoryPlanner scaffolding naming a memory relation.surface.plan-turn.planner-reached-memory
ConsoleVantageUnparseableA vantage that is neither a calendar day nor an instant.surface.set-vantage.unparseable
ConsoleWebBoundUnparseableA web leg whose publication bound does not parse.surface.set-vantage.web-bound-unparseable
ConsoleGalleryPathUnlistedA gallery preview path absent from the reader’s governed file listing.surface.browse.gallery-path-unlisted
ConsoleLearningUnscopedA distilled conclusion landing without the reading-session scope.surface.learn.unscoped
ConsoleLearningWriteRefusedA served claim write that refuses or returns no scope-bound receipt.surface.learn.write-refused
ConsoleViewNotServerBuiltA view from a client or the model rather than inferred from a result.surface.render.client-authored-view
ConsoleBriefUnavailableA greeting derivation that errored or overran its budget.surface.brief.absence-is-earned
VisibilityShareAffordanceA share control offered on access-explanation output.surface.publish-answer.share-affordance
VisibilityAskerlessAudienceA scheduled post to an audience under a service identity.surface.publish-answer.askerless-audience

Bounds

BoundValueBasisClause
surface-wake-answer25 schosensurface.arm.wake-answer
surface-tick-interval500 mschosensurface.arm.tick-interval
surface-poll-interval30 schosensurface.reconcile.poll-cadence
surface-daemon-drain5 schosensurface.fire.daemon-drain
surface-step-result1 MiBchosensurface.dispatch.step-result
surface-callback-skew300 schosensurface.dispatch.callback-skew
surface-heartbeat-beat15 schosensurface.dispatch.heartbeat-beat
surface-heartbeat-lapse60 schosensurface.dispatch.heartbeat-lapse
surface-fire-pool4 unitschosensurface.dispatch.pool-bound
surface-child-grace10 schosensurface.dispatch.children-reaped
surface-fire-credential600 schosensurface.dispatch.fire-credential-lifetime
surface-delegate-call-timeout300 schosensurface.delegate.call-timeout
surface-delegate-call-ceiling3600 schosensurface.delegate.call-timeout-ceiling
surface-region-entries16 entrieschosensurface.reside.region-entries
surface-run-history-page1000 runschosensurface.visualize.run-history-page
surface-redactor-lookahead128 charschosensurface.speak.redactor-lookahead
surface-sources-per-turn8 entrieschosensurface.ground.sources-per-turn
surface-code-path-rows5000 rowschosensurface.plan-turn.code-path-bounds
surface-code-path-time10 schosensurface.plan-turn.code-path-bounds
surface-overlay-cache5 minchosensurface.plan-turn.overlay-cache
surface-overlay-length8000 charschosensurface.plan-turn.overlay-length
surface-sample-labels3 entrieschosensurface.set-vantage.sample-labels
surface-learnings-per-turn3 entrieschosensurface.learn.distillation
surface-line-chart-floor3 rowschosensurface.render.component-choice
surface-topic-tier-tokens2 tokenschosensurface.brief.topic-tier
surface-card-subjects3 subjectschosensurface.brief.card-subjects
surface-articles-per-subject3 entrieschosensurface.brief.articles-per-subject
surface-catchup-window7 dchosensurface.brief.catchup-window

Types

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

contextful_cli::connection::Declaration

The struct at crates/contextful-cli/src/connection.rs, named by surface.connection.malformed.

KeyDoc
id
tenant
principal
file_ids
refresh_secret
schedule

contextful_core::surface::delegate::Answer

The enum at crates/contextful-core/src/surface/delegate.rs, named by run.items.delegated-item, surface.delegate.outcome.

KeyDoc
okRows per declared output table; they land as the item’s rows.
deferPark the item until retry_at, spending no attempt (surface.delegate.defer-parks).
transientSpend one failed attempt.
permanentWrite a terminal receipt.

contextful_core::surface::delegate::Envelope

The struct at crates/contextful-core/src/surface/delegate.rs, named by surface.delegate.envelope.

KeyDoc
job
execution_id
stepThe row-scoped step label the answer records under.
input_hashThe SHA-256 hex of the input row’s canonical bytes.
attemptThe delegate call’s ordinal within the item’s journal.
idempotency_key
entity
as_of
versionThe applied snapshot version the job fires from; absent for a fire from the local declaration.
pinsThe execution’s owner pins, as the engine compares them.
tables
row
deadlineThe send instant plus the delegate’s timeout on the engine’s clock, RFC 3339 UTC.

contextful_core::surface::external::External

The struct at crates/contextful-core/src/surface/external.rs, named by surface.visualize.external-shape.

KeyDoc
name
label
inputs
outputs

Decisions

SectionCited by
A-surface#answer-surfaces-readauthority.resist.read-only-face, authority.resist.write-tool, surface.speak.unanswerable-suggestion, surface.speak.stream-redaction, surface.ground.unadmitted-tool, surface.ground.mutating-tool, surface.ground.org-face-read-only, surface.ground.sources-block, surface.plan-turn.planner-reached-memory, surface.plan-turn.turn-flow, surface.browse.discovered-chips, surface.learn.unscoped, surface.learn.subject-resolution, surface.render.client-authored-view, surface.render.older-transcript, surface.brief.absence-is-earned, surface.brief.greeting, surface.publish-answer.share-affordance, surface.publish-answer.askerless-audience, surface.publish-answer.one-operator-principal
A-surface#applied-jobs-retainsurface.fire.applied-data-contract, surface.apply.draft-table-contracts
A-surface#configuration-reaches-engineconnector.import.forwarded-config, surface.reconcile.loopback-only, surface.fire.job-kind-unknown, surface.fire.store-driven-concurrency, surface.fire.store-driven-body, surface.fire.scheduled-body, surface.fire.scheduled-history, surface.fire.job-snapshot, surface.fire.model-snapshot, surface.fire.standalone-snapshot, surface.fire.applied-data-contract, surface.fire.applied-contract-missing, surface.fire.executable-pin, surface.fire.scheduled-build, surface.fire.build-dependency, surface.fire.plan-job, surface.apply.weak-conditional-backend, surface.register-store.malformed-entry, surface.register-store.authored-name
A-surface#connections-claim-versionsurface.apply.draft-claim, surface.connection.create, surface.connection.schedule-scale
A-surface#console-lives-besidesurface.open-console.engine-faces, surface.open-console.source-draft
A-surface#console-page-shipssurface.open-console.page-routes, surface.open-console.query-surface
A-surface#control-document-cassurface.arm.unreadable-schedule, surface.reconcile.fail-static, surface.reconcile.pulled-control-untrusted, surface.reconcile.learns-by-reading, surface.edit.store-draft, surface.apply.version-race
A-surface#delegated-body-deployrun.items.delegated-item, surface.delegate.binding, surface.delegate.call-mode, surface.delegate.outcome
A-surface#due-units-admitsurface.dispatch.not-a-head, surface.dispatch.admission-order, surface.dispatch.refill
A-surface#maintenance-kindsstore.fold.job-pass, store.push.job-push, surface.fire.scheduled-maintenance, surface.fire.kind-undispatched
A-surface#native-model-buildssurface.fire.model-snapshot, surface.fire.scheduled-build
A-surface#never-run-firstsurface.dispatch.admission-order
A-surface#query-admin-usesurface.open-console.identity-gate, surface.open-console.page-grants, surface.open-console.engine-faces, surface.open-console.wrong-page, surface.open-console.admin-grant
A-surface#residency-divergence-detectedsurface.reside.region-entries, surface.reside.site-regions
A-surface#store-driven-jobrun.journal.store-input, run.journal.input-pin
A-surface#synced-control-headstore.push.control-artifact, store.push.control-diverged, store.pull.control-head, surface.reconcile.pulled-control, surface.apply.synced-attestation, surface.apply.receipt-message, surface.apply.receipt-digest, surface.apply.receipt-file, surface.apply.attestation-unavailable
A-surface#turn-compatibility-preservessurface.package.owner-flag, surface.plan-turn.overlay-audience
A-surface#workers-reach-orchestratorsurface.dispatch.heartbeat-beat, surface.dispatch.worker-target, surface.visualize.workflow-canvas