Provider SDK reference

The tables below map each package and feature of the provider SDK to the section of the SDK README that specifies it and to the decision record behind it. The rules themselves live in the README. The tables describe the SDK release that the minimal provider example requires:

go.mod

  github.com/stokaro/ptah/provider-sdk v0.26.0

The README links below open that release. The README in the latest development source can describe later additions. An ADR number names a decision record in the docs/adr directory of the Ptah repository, and the README section links it.

Packages

The SDK is one Go module, github.com/stokaro/ptah/provider-sdk, with five packages:

Package	What it holds
protocol/experimental	The generated Protobuf messages and the gRPC Provider service. provider.proto in this directory is the wire contract.
provider	The service interfaces, the feature names, the contract version, the request and reply validators, and the error types.
runtime	Serve and Server for a provider; Start, Options and Client for a host or a test; ErrorWithReason; the call timeouts and message bounds.
modeljson	Canonical, the JSON normalization that model definitions and their digests use.
conformance	Check and Run, the suite that acts as a strict host against a provider’s executable or its in-process server; the command cmd/ptah-provider-conformance runs it and prints the report.

The README sections that apply to every service: Contract versions, Trust and process lifetime (ADR 0080), Bootstrap specification, Reply validation (ADR 0082) and Versions.

Contract, negotiation and errors

Name	Package	Use
Revision, ContractMinor, Contract	provider	The contract major, the minor this SDK speaks, and both as a version.
MinimumContract, CheckContract, ContractError	provider	A provider’s minimum contract, the host’s check of it, and the refusal that names both versions.
TwoWayFeatures	provider	The features a host lists for a provider to use them.
HostFeatures, ContextWithHostFeatures	provider	What the host listed, as a service reads it, and a context that carries a list for a test.
NegotiatedDescription, ValidateDescription	provider	The description a host with given features receives, and its check.
ErrorWithReason, ValidateDiagnostic	runtime, provider	A failed call with a provider-written reason, and the check of a reason’s shape.
ErrStartup	runtime	A failed launch or bootstrap.
ErrProtocol, ErrIncomplete	provider	A malformed exchange, and a read that is not complete.
ErrOutcomeUnknown, ErrExecution, ErrStatementTimeout	provider	An unresolved outcome, a confirmed failure, and a stop at the statement timeout.
ExecutionError, TransactionError, LockError, HistoryError	provider	The outcome and the provider’s reason of a call that did not succeed.
ErrLockBusy, ErrLockLost	provider	A lock another session holds, and a lock that no longer establishes ownership.
CallTimeout, ProvisionTimeout, MaxMessageBytes, LargeMessageBytes	runtime	The bound of a fixed-size call, of a dev database call, and of one message without and with transport.large-messages.

Services and features

Each table lists a feature, the runtime.Server field of the service it selects, the README section that specifies it, and its decision record. A feature with no service changes messages that already exist. runtime.Server.Validate refuses a service without its feature and a feature without its service, and provider.TwoWayFeatures() returns the features a host must also list.

The README in the latest development source gives these subjects sections that the release does not have. The tables below link the section of the release that holds the rules.

Subject	Section of the release	Section in the latest development source
sql.analyze	Validation	SQL analysis (latest development source)
The table policies	Validation	Table policies (latest development source)
lint.migrations	Service contract	Migration lint (latest development source)
Engine.release_lines	Offline capabilities	Release lines (latest development source)

Services Ptah requires

Ptah starts a provider only when it offers these services, and every provider has the session service.

Feature	Service	README section	ADR
—	Sessions	Service contract	—
schema.inspect	Inspector	Observed model coverage	—
schema.render	Renderer	Service contract	—
units.execute	Executor	Execution uncertainty	—
sql.analyze	SQLAnalyzer	Validation	—

Sessions, execution and locks

Transactions, revision storage, the migration log and locks back the migration commands and ptah schema apply.

Feature	Service	README section	ADR
sessions.transactions	Transactions	Session transactions	—
sessions.history	History	Revision storage	—
sessions.migration-metadata	Metadata	Migration logs and tags	—
sessions.locks	Locks	Session-owned locks	—
sessions.statements	Statements	Operator statements	0038
sessions.typed-arguments	—	Typed arguments	0058
units.statement-timeout	—	Execution uncertainty	—
units.migration-split	MigrationSplits	Migration splits	0055
units.sensitive-inputs	ExecutionInputs	Sensitive execution inputs	0043
errors.reasons	—	Error reasons	0059, 0061

Tables and the common model

These features decide how an engine’s tables, columns, indexes and common objects reach Ptah’s comparison.

Feature	Service	README section	ADR
schema.common-table-identity.v1	—	Validation	—
schema.prepare-tables	TablePreparer	Validation	—
schema.project-table-creations	TableCreations	Validation	—
schema.columns	Columns	Common column semantics	0045
schema.observed-columns	—	Complete column observations	0048
schema.observed-primary-keys	—	Ordered primary-key observations	0051
planning.primary-key-changes	—	Primary key changes	0078
schema.observed-indexes	—	Common index observations	0052
schema.observed-index-facets	—	Index facets on inspected indexes	0068
schema.index-methods	—	Prepared index kinds	0057
planning.index-renames	—	Index renames	0060
schema.unread-tables	—	Unread tables	0063
schema.subtree-coverage	—	Subtree coverage	0064
schema.database-kinds	—	Database kinds	0065
schema.common-objects	CommonObjects	Common objects	0033
schema.common-view-facets	—	View facets and replacement observations	0047
schema.common-access	—	Independent access observations	0042
schema.role-scope-reasons	—	Role scope reasons	0076
schema.password-inputs	—	Password inputs	0071

Values, models and planning

These features carry the provider’s own models and its part of a plan.

Feature	Service	README section	ADR
values.normalize	ValueNormalizer	Owner-defined value normalization	0022
values.convert	ValueConverter	Desired and observed conversion	—
models.compare	ModelComparer	Contextual model comparison	—
models.compare-counts	—	Comparison counts	0056
models.plan	FeaturePlanner	Contextual feature planning	0024
models.reverse	ChangeReverser	Change reversal	0062
models.report-counts	ValueReporter	Report counts	0067
models.predecessors	—	Model predecessors	0075, 0084
models.own-predecessors	—	Own model predecessors	0084
planning.policy, planning.statement-style	—	Planning policy	0035, 0050
planning.lifecycle	—	Lifecycle placement	0044
planning.object-context	—	Native object assessment	0049
planning.context-inventory	—	Planning context of a filtered read	0054
planning.table-outlines	—	Table outlines	0081
render.text-units	—	Text units	0034
schema.declarations	Declarations	Authored declaration planning	0041
schema.validate	SchemaValidator	Offline schema validation	—

Source syntax

These features let a provider read and write its part of a YAML, HCL, Go or SQL source.

Feature	Service	README section	ADR
source.decode	SourceDecoder	Captured extension sources	0025
source.encode	SourceEncoder	Source encoding	0037, 0040
source.encode-groups, source.limits	—	Source encoding	0040
source.entry-keys, source.hcl	—	YAML entry keys and HCL claims	0036
source.hcl-platform	—	HCL platform groups	0072
source.index-kinds	—	Index kinds	0074
source.go-placements	—	Go placements	0077
schema.read-sql	SQLSchemaReader	SQL schema documents	0027
schema.sql-facets	—	Facets of a SQL schema reading	0066
sql.scan	SQLScanner	SQL scanning	0069
scope.selections	—	Scope selections	0039

Database context and dev databases

These features cover addresses, the databases Ptah rehearses and replays on, and the facts an offline command plans with.

Feature	Service	README section	ADR
database.context	DatabaseContexts	Database interpretation context	0046
values.context	—	Database interpretation context	0046
database.dev	DevProvisioner	Dev database cleanup and the replay guard	—
database.dev-realms	—	Dev database cleanup and the replay guard	—
database.dev-cleanup	DevCleaner	Dev database cleanup and the replay guard	—
database.dev-replay-guard	ReplayGuard	Dev database cleanup and the replay guard	—
engine.default-capabilities	—	Offline capabilities	0070
query.dialect	—	Query-builder spelling	—

Data, lint and embeddings

These features serve declared rows and seeds, migration lint, and ptah inference.

Feature	Service	README section	ADR
data.type-rows	RowTyper	Rows, row writes and seeds	0028
data.read-rows	RowReader	Rows, row writes and seeds	0028
data.render-writes	RowWriter	Rows, row writes and seeds	0028
data.seeds	Seeds	Rows, row writes and seeds	0028
lint.migrations	Linter	Service contract	—
lint.statement-facts	—	Statement facts for SQL lint	—
lint.transaction-owner	—	Transaction owner of a lint check	0073
embeddings.store	EmbeddingStore	Embedding store	0032

Transport

These features keep a large schema within one request. The SDK applies them on both sides, and no service sees the difference.

Feature	Service	README section	ADR
models.references	—	Model references and large messages	0079
transport.large-messages	—	Model references and large messages	0079
transport.shared-coverage	—	Shared coverage	0083

Related pages

• How a provider works and Engines, models and planning explain how the services fit together.
• Test a provider lists the validator of each core service.