Build products that stay current.
Worldstate turns bounded evidence into a ranked, actionable workspace while keeping domain authority inside one independently operated product.
Eight steps, each with one job.
The boundaries are the feature. Acquisition providers, models, and renderers can change without silently inheriting authority.
Sources produce validated observations; they do not write product truth. Exact decisions outrank inference. Unknown outcomes fail closed.
The primitives
Learn these ten concepts and you can reason about the complete extension surface without studying an existing product.
Product
An independently deployable composition and authority boundary.
Keeps one domain’s database, lifecycle meaning, ranking, and actions isolated from every other domain.Entity
A durably identified thing in a product’s domain.
Lets changing observations reconcile onto one stable subject without making the source canonical.Source
An origin, acquisition connector, and observation contract.
Separates where information came from from how it was acquired and what the product will accept.Observation
Source-stamped, validated evidence about an entity.
Carries provenance and bounded facts without directly writing lifecycle or ranking authority.Lifecycle
Domain-owned states, transitions, and reconciliation.
Turns evidence into current domain meaning under explicit transition rules.Ranking
Eligibility, typed features, scoring, explanation, and fallback.
Produces an interpretable order only after hard gates have passed.Queue
A versioned, ordered workspace projection.
Makes a ranking cycle inspectable and reproducible instead of presenting a floating model opinion.Intervention
A user-directed Decision or Action.
Marks the exact point where human intent or consequence enters the loop.Outcome
A product-owned causal interpretation of a result.
Lets the next cycle learn without rewriting the decision or overclaiming causality.Feature
Reusable vertical behavior spanning every layer it needs.
Moves stable behavior between products without merging their domain meaning or customer data.Provider is not provenance.
A Source names the underlying origin, the replaceable acquisition mechanism, and the only validated output the product can see.
Origin
Where the information ultimately came from.
public_roles_feedConnector
How it was acquired or refreshed.
bounded_feed_reader_v1Observation
The only validated product-facing output.
role_observation_v1Apify, Bright Data, Firecrawl, and similar systems are connectors or execution providers—not automatic product authorities. Output remains untrusted until validation, entity resolution, reconciliation, and product rules succeed.
Source Packs package trust boundaries, not authority.
A future marketplace can distribute reviewed Source Packs. Installing one never grants a provider the right to change lifecycle, ranking, decisions, actions, outcomes, or canonical product state.
Origin + schema
Origin semantics, observation contract, normalization, entity resolution, provenance, rights, and retention.
Connector + limits
Credential class, network capability, refresh behavior, record and byte ceilings, cost limit, tests, and revocation.
Validate + reconcile
Provider output remains untrusted until the product validates it and applies its own identity and authority rules.
Worldstate does not currently operate a Source Pack marketplace, provider activation flow, scheduler, or spend meter. Nonzero connector cost limits fail closed; generic prompts, arbitrary code, shell, filesystem, browser authority, undocumented egress, and unconstrained recursive execution are forbidden.
One definition. No silent discovery.
Every required and optional capability is bound in one typed ProductDefinition. Missing behavior fails during construction, before runtime assembly.
from packages.adapter_sdk import validate_product_definition
from packages.adapter_sdk.examples.synthetic_product import (
make_product_definition,
)
definition = make_product_definition()
validate_product_definition(definition)
assert definition.product == "synthetic_tasks"
assert definition.sources
assert definition.ranking
assert definition.interventionsThe current package identifier remains personal-agent-runtime. Worldstate is the external product name. This developer preview is not yet a public SDK release.
The complete capability surface
Required and optional behavior is visible in typed definitions. Optional capabilities are explicit None values; the runtime never discovers behavior through hidden methods.
EntityDefinitionIdentity schema and subject typesSourceDefinitionOrigin, Connector, Observation, route, limits, and jobsLifecycleDefinitionVersion and optional command handlerRankingDefinitionGates, components, versions, limits, and reranker projectionQueueDefinitionRanking job and refresh eventsInterventionDefinitionFeedback and outcome interpretationFeatureDefinitionFeature name, implementation, and versionPersistenceDefinitionExplicit optional projections and readersproduct_source_route_incompletefeature_implementation_requiredsource_connector_max_records_per_run_invalidsource_connector_network_capability_forbiddensource_observation_provenance_incompleteErrors contain bounded contract names—not payloads, credentials, private values, or local paths. Treat validation failure as no authority and perform no partial write.
Create your first product
Start fixture-only. Define every capability, prove conformance, and add production authorities only through separate reviewed gates.
- 1
Name the domain authority
Define entity identity, lifecycle meaning, outcome causality, and the exact actions the product may request.
- 2
Bind bounded sources
Declare origin, connector, observation schema, provenance, rights, refresh, record/byte ceilings, and cost limit.
- 3
Define ranking and interventions
Put hard gates first, keep baseline components interpretable, and separate durable Decisions from executable Actions.
- 4
Validate the composition
Construction checks identifiers, routing, capability signatures, provenance, execution bounds, and runtime bindings.
A clean fourth product
The synthetic tasks example composes fixture-only entities, one bounded source, deterministic ranking, a queue, interventions, outcomes, and Favorites without importing the Career, Events, or Industry adapters.
python -m packages.adapter_sdk.examples.synthetic_product
valid product=synthetic_tasks definition=synthetic-tasks-product-v1The example has no database role, authentication configuration, provider, network access, deployment manifest, or console entrypoint. Replace fixture contracts and review every live authority before production.
Make invalid products boring.
Validation names the primitive and failed invariant. The synthetic fourth-product example proves the composition path without importing Career, Events, or Industry adapters.
$ python -m packages.adapter_sdk.examples.synthetic_product
✓ valid product=synthetic_tasks
✓ definition=synthetic-tasks-product-v1A passing definition does not authorize databases, authentication, provider credentials, network access, migrations, spend, or live data. Those remain separate reviewed boundaries.
Authority attaches to the primitive it governs.
“Policy” is not a catch-all primitive. Privacy, retention, eligibility, approval, and consequence rules stay beside the Source, Ranking, Decision, or Action they constrain.
Raw private evidence
Gmail, Calendar detail, transcripts, browser sessions, exact location, credentials, and owner-only files.
Structured product state
Validated observations, lifecycle, queues, exact decisions, bounded actions, and domain-owned outcomes.
Optional local access
Typed capabilities, bounded arguments, minimized outputs, explicit expiry, and no generic remote execution.
What this preview does not promise
- No public SDK distribution or stability commitment yet.
- No live Source Pack marketplace, provider activation, or metered execution.
- No end-user workflow builder or arbitrary prompt, code, shell, filesystem, or browser authority.
- No shared customer database or universal product authority.