Dynamic World Model Requirements

Proposal status

This document defines a future design direction. It is a requirements proposal, not a statement of currently released TeaQL functionality.

1. Purpose

A Dynamic World Model (DWM) is a reasoning and explanation framework between human intent and executable software. It represents not only what exists in a domain, but also how the current situation came to exist, why it is valid, what may happen next, and how proposed actions would change it. Its meaning remains independent of any particular database, API style, programming language, or runtime.

Machine readability is necessary, but it is not the defining property. A DWM must provide enough explicit semantics for humans and AI systems to reason over reality rather than merely parse a description of it.

The model must let humans and AI systems answer at least these questions:

1. What exists, and which concepts and relationships describe it?
2. How did the current situation come to exist?
3. Why is each relationship or state considered valid?
4. Which events are possible, required, or prohibited next?
5. What would change if a proposed event occurred?
6. Which observations, rules, and assumptions support the explanation?

The defining statement is:

Concepts participate in events, under constraints, to create and evolve relationships. Software systems are executable projections of those dynamic relationships.

2. Goals

The DWM layer should:

• explain current reality through concepts, relationships, events, constraints, and evidence;
• support structural, causal, temporal, normative, and counterfactual reasoning;
• support controlled collapse and expansion of relationship boundaries;
• preserve business meaning separately from implementation details;
• make roles and capabilities explicit through relationships;
• distinguish facts, events, constraints, and derived projections;
• support temporal reasoning about past, current, and proposed states;
• provide deterministic inputs for code generation and agent actions;
• maintain traceability from source requirements to runtime evidence;
• detect and repair semantic inconsistencies as the domain evolves;
• project one domain definition into multiple technical targets.

Reasoning must be explainable: conclusions should be traceable to model elements, evidence, constraints, and declared assumptions rather than returned as unsupported answers.

3. Non-goals

The first version is not intended to:

• replace human ownership of business meaning;
• require event sourcing as the storage architecture;
• infer consequential rules and publish them without review;
• encode every operational detail in one universal ontology;
• make every technical projection structurally identical;
• replace retrieval, documentation, databases, or runtime policy engines.

4. Canonical Metamodel

4.1 Concept

A Concept is a semantically identifiable participant in the domain.

It must support:

• a stable identifier independent of display name;
• a human-readable name and definition;
• aliases and source vocabulary;
• optional attributes that describe intrinsic properties;
• provenance and version metadata;
• references to relationships and events in which it may participate.

A concept must not encode a contextual role as an intrinsic identity when that role exists only through a relationship. For example, Person is a concept; Employee is normally a role in Employment.

A contextual role may be exposed as a concept-like boundary at a declared lower resolution, but it must remain traceable to the relationship structure that gives it meaning. Section 4.7 defines this operation.

4.2 Relationship

A Relationship is a meaningful, potentially time-bound structure among two or more participants.

It must support:

• typed participant roles;
• cardinality and participation rules;
• lifecycle states and effective time;
• creation, transition, and termination events;
• invariants that remain true while it is active;
• capabilities granted to each role;
• evidence and provenance;
• attributes that belong to the relationship rather than a participant.

4.3 Event

An Event represents an occurrence that may create, modify, or terminate relationships or contribute to a projection.

It must support:

• event type and stable identity;
• participating concepts and their roles;
• preconditions;
• intended effects;
• event time and recording time;
• actor or initiating system;
• authorization requirements;
• outcome, failure reason, and supporting evidence;
• idempotency or duplicate-detection semantics where required.

The model must distinguish a proposed command from an observed event. A request to transfer ownership is not proof that ownership was transferred.

4.4 Constraint

A Constraint declares a condition that governs an event, relationship, capability, or projection.

It must support:

• a stable identity and plain-language rationale;
• machine-evaluable expression where possible;
• scope and applicability;
• severity and enforcement mode;
• temporal validity;
• jurisdiction, tenant, or policy context where relevant;
• source, owner, and review history;
• explicit handling when the required evidence is unavailable.

Constraints should be classifiable as preconditions, invariants, authorization policies, cardinality rules, temporal rules, or postconditions.

4.5 Capability

A Capability describes an action available to a participant because of an active relationship and role.

It must reference:

• the granting relationship and role;
• the event or command it permits;
• applicable constraints;
• validity period;
• revocation conditions.

Capabilities must not be inferred solely from a concept's type when they depend on a contextual relationship.

4.6 Projection

A Projection is a derived representation of model facts for a specific use.

Examples include a balance, current marital status, inventory availability, an API response, a database view, or an agent tool description.

It must support:

• declared source facts and events;
• transformation or derivation rules;
• freshness and consistency expectations;
• rebuild or reconciliation behavior;
• target-specific schema metadata;
• traceability to the semantic elements it represents.

4.7 Relationship boundary and resolution

A RelationshipBoundary is a controlled abstraction that exposes part of a relationship graph as a simpler, concept-like participant for a particular viewpoint and reasoning scope.

For example:

Expanded:  Person -> Employment -> Company
Collapsed: Employee -> Company

In the collapsed view, Employee represents the boundary projection of a person participating in active employment, as viewed from the company. This can be sufficient when the observable lifecycle consists only of employment start, active participation, and termination. When the system must reason about hiring, contract negotiation, concurrent employments, legal identity, or detailed transitions, the boundary must be expandable to the underlying Person, Employment, events, and constraints.

A relationship boundary must declare:

• the viewpoint and reasoning purpose for which it is valid;
• the source subgraph that it collapses;
• the stable identities preserved across collapse and expansion;
• the roles, capabilities, states, and events exposed at the boundary;
• the internal details intentionally hidden;
• the constraints and invariants lifted into the boundary contract;
• the set of observations and decisions for which the collapse is sound;
• whether the operation is lossless, reconstructable, or intentionally lossy;
• the conditions that require automatic or explicit expansion.

The abstract operation is:

collapse(graph, viewpoint, observable_scope) -> boundary
expand(boundary, required_scope) -> graph

state(boundary, time)
  = project(state(source_graph, time), viewpoint, observable_scope)

For every query or decision inside the declared observable scope, reasoning over the collapsed boundary must produce a result semantically equivalent to reasoning over the expanded graph. Equivalence outside that scope is not implied.

Collapse must not erase provenance or silently weaken constraints. If a hidden distinction can change the outcome of a decision, that decision is outside the collapsed boundary's valid scope and the model must expand before reasoning continues.

5. Behavioral Semantics

5.1 Event evaluation

Before accepting a proposed event, an implementation must be able to determine:

1. whether all required participants and evidence are present;
2. whether the initiating actor has the required capability;
3. whether all applicable preconditions are satisfied;
4. which relationships and projections would change;
5. whether the resulting state would preserve all invariants.

The evaluation result must be explainable. A rejection should identify the failed constraint, its source, and the missing or conflicting evidence without exposing protected data.

5.2 Time

The model must distinguish at least:

• effective time: when a fact is true in the domain;
• recording time: when the system learned or stored the fact.

This distinction is required for delayed events, corrections, backdated changes, audits, and reconstruction of historical states.

5.3 Identity and roles

Concept identity must remain stable as roles change. Ending employment must not end the identity of the person or company. The same concept may participate in several relationships simultaneously, subject to explicit constraints.

5.4 Facts and derived state

The model must identify whether a value is:

• an asserted fact;
• an observed event;
• relationship state;
• a derived projection;
• a cached copy of a projection.

Cached values must retain a declared derivation path so they do not silently become competing sources of truth.

5.5 Recursive interpretation

The model must support recursive changes of resolution:

• a relationship may be expanded into participants, roles, events, constraints, and evidence;
• a relationship may participate as a semantic unit in another relationship;
• a relationship subgraph may collapse into a concept-like boundary;
• an event or capability at one resolution may expand into a workflow at the next resolution;
• reasoning may continue recursively until the current question can be answered without crossing a hidden semantic distinction.

State at one resolution may be derived from state at a deeper resolution and then participate in relationships at a higher resolution. This makes world state recursively composable rather than a single flat collection of attributes. Each derived boundary state must retain its projection rule, source resolution, effective time, and dependency trace.

For example, Employment may participate in an Assignment relationship with a project. A project application may collapse that structure into ProjectMember, while an HR or compliance application expands it to inspect the employment that authorizes the assignment.

The reasoning engine must record which resolution was used for a conclusion. When a constraint, query, or proposed event refers to hidden information, it must request expansion rather than guess through the boundary.

6. Projection Requirements

A conforming implementation should be able to project the same model into more than one target while preserving traceability.

Semantic element	Example target projections
Concept	type, schema definition, identifier, vocabulary
Relationship	entity, aggregate, table, foreign key, graph edge
Event	command, endpoint, message, workflow transition
Constraint	validation, policy, guard, database constraint
Capability	generated business method, permission, agent tool
Projection	query model, view, report, cache

Each generated artifact must carry or expose a reference to its source model element. Target limitations must be reported explicitly; a generator must not silently drop semantics it cannot represent.

7. Ingestion and Model Construction

The system may propose model elements from:

• natural-language requirements;
• policies and operating procedures;
• API specifications;
• database schemas and data profiles;
• source code and tests;
• workflows and process logs;
• runtime events and audit evidence.

Every extracted element must record provenance, extraction time, confidence, and review status. Conflicting sources must remain visible until an authorized reviewer resolves them.

AI-generated model changes are proposals. They must not become authoritative solely because the model assigned them high confidence.

8. Validation and World-Model Repair

Validation must detect at least:

• duplicate concepts with conflicting definitions;
• contextual roles modeled as incompatible intrinsic identities;
• relationships with missing roles or invalid cardinality;
• lifecycle states with no creating or terminating event;
• events with unspecified participants, preconditions, or effects;
• constraints that cannot identify their scope or source;
• capabilities without a granting relationship;
• projections with missing derivation rules;
• generated artifacts that no longer match their source elements;
• runtime evidence that contradicts declared invariants;
• collapsed boundaries with no source subgraph, viewpoint, or observable scope;
• collapsed boundaries that hide distinctions required by a permitted decision;
• collapse and expansion mappings that lose stable identity or provenance.

A repair proposal must include:

• the detected inconsistency;
• affected model and software artifacts;
• supporting evidence and confidence;
• the proposed semantic change;
• migration and compatibility impact;
• required reviewer and rollback boundary.

9. Versioning and Governance

The model must provide:

• immutable version identifiers;
• human-readable change descriptions;
• semantic diffs at the element level;
• ownership and approval metadata;
• compatibility classification;
• migration links between model and projection versions;
• audit history for automated and human changes;
• rollback or supersession without erasing history.

Breaking changes include changes that reinterpret existing facts, invalidate active relationships, remove capabilities, or alter event effects. They require explicit review even when generated software still compiles.

10. Agent Interaction Contract

An AI agent operating on the model must be able to query:

• the current relationships for a concept;
• the roles and capabilities granted by those relationships;
• the events currently available;
• the constraints and evidence required for each event;
• the predicted effects of a proposed event;
• the provenance and confidence of relevant facts.

The agent must separate read, simulate, propose, and execute operations. Simulation must not mutate authoritative state. Execution must use the same constraint evaluation and audit boundaries as non-agent callers.

11. Minimum Conformance Criteria

An initial implementation is conforming only if it can demonstrate all of the following:

1. Model a person participating in multiple time-bound roles without duplicating person identity.
2. Define an event with participants, preconditions, effects, and evidence.
3. Reject an event that violates a declared constraint and explain why.
4. Derive at least one current-state projection from underlying facts or events.
5. Generate or bind at least two technical projections from the same semantic model.
6. Trace each generated artifact back to stable model identifiers.
7. Detect a runtime or source conflict and produce a reviewable repair proposal.
8. Reconstruct the model's relevant state for a historical effective time.
9. Show that an agent can simulate an allowed action without executing it.
10. Preserve an auditable history of model changes and approvals.
11. Collapse an expanded employment relationship into an employee boundary for a declared scope.
12. Detect a question outside that scope, expand the boundary, and preserve identity and reasoning traceability.

12. Proposed Delivery Stages

Stage 1: Metamodel and examples

• define the canonical schema and identifiers;
• publish representative domains such as employment, payment, and ownership;
• create semantic validation fixtures;
• agree on terminology and review ownership.

Stage 2: Deterministic projections

• map model elements to database, API, policy, and generated business API artifacts;
• add source-to-artifact traceability;
• report unsupported semantics during generation;
• introduce conformance tests for projections.

Stage 3: Agent reasoning interface

• expose relationship, capability, event, and constraint queries;
• support read-only simulation and impact explanation;
• enforce authorization, audit, and human-review gates;
• measure semantic correctness, not only code compilation.

Stage 4: Model extraction and repair

• extract candidate elements from legacy assets;
• reconcile conflicting sources with provenance;
• compare runtime evidence with declared semantics;
• produce governed repair proposals and migrations.

13. Relationship to TeaQL

TeaQL already emphasizes model-driven generation, generated business APIs, explicit query purpose, audit-aware mutations, and runtime boundaries. Those properties make it a useful projection environment for this proposal.

The DWM layer would remain implementation-independent. TeaQL could consume a validated world model and project parts of it into generated entities, queries, behaviors, policies, and agent-facing APIs. Other runtimes could project the same semantics differently.

See also the companion blog post: Dynamic World Models: The Missing Requirements Layer for AI-Native Software Engineering.