Plugins & packages

A plugin installs a verified semantic boundary for an external system: 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 with zero app-authored ontology. Plugins are semantic packages, portable across hosted and local runtimes — 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 — no app reads, no cross-plugin reads.

Credentials and effects

Plugin intents bind capabilities in the pack manifest; the host app satisfies them with named resource bindings and a credential_ref — 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, yielding 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 — explicitly labeled, never silently substituted.

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 plus 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 locked bytes only — nothing re-resolves mutable channels unless 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 — they own their own namespace, depend on the plugin’s surface, and drive only declared plugin inputs. Enabling one changes locked identity; installing the plugin alone never silently enables it.

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, …) — never last-write-wins — and 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 — deterministically verifiable with no API key. See Examples.