Plugins & packages
Installable semantic packs for external systems, with designated namespaces, load-checked surface tiers, typed HTTP receipts, and locked package management.
A plugin installs a verified semantic boundary for an external system. It is a
directory of text files (tarski-plugin.toml, ontology/*.ta, mappings/*.rhai,
schemas/*.json, and golden fixtures/) that composes into a workspace and yields
queryable, provenance-carrying facts without any app-authored ontology. Plugins are
semantic packages that are portable across hosted and local runtimes. They are not native
runtime extensions.
Namespaces and surface tiers
A plugin owns its normalized name as a namespace (searchapi-shopping →
searchapi_shopping), with reserved forms per kind: intent.<ns>.*, source.<ns>.*,
helper.<ns>.*, decision.<outcome>.<ns>.*, and plain <ns>.* for facts, projections,
and write policies. Namespaces are pairwise exclusive across packs, and the app cannot
declare inside a plugin’s namespace.
The surface is tiered and load-enforced (stable diagnostics E2701–E2707):
exports: relations and projections the app may read.inputs: the only plugin relations app rules may derive into (also how plugin intents are gated).- Everything else is internal. Plugin rules read only their own namespace plus runtime built-ins. They cannot read app relations or other plugins’ relations.
Credentials and effects
Plugin intents bind capabilities in the pack manifest. The host app satisfies them with
named resource bindings and a credential_ref, which are checked fail-closed at load and
at tarski plugin add. Credentials never appear in templates, observations, fixtures, or
package artifacts. Missing credentials block before any network I/O with
http.credential.unresolved.
Plugin-owned http.fetch bindings may declare a receipt_kind plus a request template.
These bindings produce typed, schema-validated receipt observations (e.g.
searchapi_shopping.product_page.fetch.result) that mappers consume directly. A
deterministic provider mode (provider_mode = "deterministic") runs the same typed loops
with no network for fixtures and demos. Deterministic mode is explicitly labeled and is
never silently substituted for the live provider.
The plugin lifecycle
tarski plugin new # scaffold a pack that passes verification
tarski plugin verify # replay packaged fixtures deterministically, no credentials
tarski plugin try # replay into a scratch lineage before binding credentials
tarski plugin add ./plugins/searchapi-shopping
tarski plugin list --json
tarski plugin show searchapi-shopping
tarski plugin remove # refuses while app sources still reference the pack
Workspace tarski verify runs your app’s fixtures against the composed evaluator, runs
every pack’s standalone fixtures, and diagnoses stale vendored first-party copies against
published baselines. The dev loop watches plugin directories under the same sub-250ms
reload gate.
Package management
Installing a plugin as a managed package gives it locked identity: package id, version, artifact digest, semantic-pack digest, export-surface digest (the semver surface), publisher identity, signature state, and enabled companion modules. Replay, verify, export, and activation use only locked bytes. Mutable channels are re-resolved only when you explicitly run a package command.
tarski package plan
tarski package update
tarski package rollback
tarski package audit
tarski package source list
Companion modules are opt-in semantic modules inside a plugin package. Each one owns its own namespace, depends on the plugin’s surface, and drives only declared plugin inputs. Enabling one changes locked identity. Installing the plugin alone does not enable its companion modules.
First-party plugins
SearchAPI Shopping (searchapi-shopping 1.0.0) covers all nine SearchAPI Google
Shopping engines as per-operation surfaces (search, product, product page, offers, specs,
reviews, filters, autocomplete, store) with typed receipts and lifecycle facts. Data
conflicts surface as facts (price_conflict, seller_price_conflict, …), and the plugin
does not resolve them by last-write-wins. Provider pagination is authoritative. Its
companion module searchapi_google_offers runs bounded full-offer collection driven by
provider next_page evidence, with progress, at-risk, page-ledger, and completion facts.
SearchAPI Rank Tracking (searchapi-rank-tracking 0.1.0) turns Google organic SERP
positions into time-indexed facts with latest_capture, current_ranking,
best_position, and position_change derivations over app-declared target.domain
inputs.
The Google Shopping Price Monitor example shows a plugin, its companion module, a Collector, schedules, and blob archival working together. You can verify it deterministically without an API key. See Examples.