TarskiTarski/ docsJoin the waitlist

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.