SIL Technical Charter (v1)
🧭 Navigation: Before You Read This
This is a formal specification document (Dense, 2+ hours)
You should read this if:
- ✅ You're implementing a SIL-compliant system
- ✅ You need to understand formal contracts & guarantees
- ✅ You're designing operators, domain modules, or engines
- ✅ You need to know exactly what's required vs optional
Read these FIRST:
- ../architecture/UNIFIED_ARCHITECTURE_GUIDE.md ⭐ (30 min) - Get the mental model
- ./SIL_GLOSSARY.md (15 min) - Learn the vocabulary (keep open while reading)
- ./SIL_PRINCIPLES.md (15 min) - Understand evaluation criteria
Read these AFTER for deeper context:
- ./SIL_MANIFESTO.md - Why these contracts matter
Related Documents:
- Glossary: ./SIL_GLOSSARY.md - Look up terms while reading
- Principles: ./SIL_PRINCIPLES.md - Why these constraints exist
- Pattern: ../architecture/UNIFIED_ARCHITECTURE_GUIDE.md - High-level framework
- Navigation: ../READING_GUIDE.md - All documentation paths
Time Required: 2-4 hours (reference document, can read sections as needed)
1. Purpose of the Technical Charter
This charter defines the formal structure, interfaces, constraints, and invariants of the Semantic Operating System (Semantic OS) developed by the Semantic Infrastructure Lab (SIL). It specifies what the system is, how components relate, what rules govern their interaction, and what guarantees they must uphold. This document is a specification of architectural foundations and system contracts. It is not an implementation guide and not a roadmap.
2. System Overview
The Semantic OS is a layered semantic substrate intended to support explicit meaning representation, provenance-complete transformation, deterministic workflow execution where feasible, and cross-domain interoperability.
The architecture consists of six layers:
Semantic Memory (Layer 0):
Persistent storage of semantic objects, their schemas, temporal lineage, and provenance.
USIR (Layer 1):
A typed, explicit, graph-structured intermediate representation for cross-domain semantic structures and transformations.
Domain Modules (Layer 2):
Domain-specific schemas, invariants, operator families, and tool adapters integrated through USIR.
Orchestration (Layer 3):
Deterministic workflow and agent execution semantics, including memory access protocols and provenance requirements.
Engines (Layer 4):
Deterministic or bounded-reproducible execution of operators over USIR, including symbolic and numeric engines.
Interfaces / SIM (Layer 5):
Human-facing inspection, visualization, debugging, and exploration surfaces for interacting with the substrate and its transformations.
3. Core Definitions
The following definitions apply throughout this charter.
Semantic object
A typed, addressable entity stored in Semantic Memory that represents a concept, relation, artifact, operator, workflow, derivation, state snapshot, or domain construct. Each semantic object conforms to a schema and is subject to integrity constraints.
Operator
A defined transformation with a typed signature, preconditions, postconditions, declared effects, and mandated provenance emission. Operators consume and produce semantic objects and/or USIR graphs.
Invariant
A declarative constraint that must hold over one or more semantic objects, USIR graphs, workflows, or domain structures. Invariants may be enforced by validation, checked by engines, or asserted with explicit status and scope.
Provenance record
A structured record describing the lineage of a semantic object or transformation, including the operator invoked, inputs, outputs, parameters, assumptions, execution context, state references, and validation outcomes.
Schema
A versioned specification defining the structure, typing, required fields, allowed relations, and integrity constraints of a semantic object class or USIR subgraph pattern.
Domain module
A bounded semantic package that defines a domain’s schemas, invariants, operator families, validation rules, and tool adapters, integrated into the Semantic OS via USIR contracts.
USIR node
A typed node in a USIR graph representing an entity such as a value, structure, operator application, constraint, workflow element, or domain construct.
USIR graph
A typed, explicit, directed multigraph composed of USIR nodes and typed relations. USIR graphs represent semantic structures, operator applications, workflows, and derivations.
Workflow
A structured representation of a task as an operator graph with execution semantics, dependencies, inputs/outputs, state requirements, and provenance obligations.
State snapshot
A versioned capture of relevant semantic memory and execution context sufficient to enable replay, validation, and inspection of a workflow or operator chain.
Engine
A computational component that executes operators over USIR under specified reproducibility contracts, emitting typed outputs and provenance records.
Agent
An entity executing workflows under orchestration rules, including explicit state transitions, constrained memory access, and mandatory provenance emission for actions.
Transformation
Any operator-driven change to semantic objects, USIR graphs, or workflows, including creation, mutation (where permitted), derivation, lowering, lifting, and composition.
Validity / consistency conditions
Formal checks that determine whether semantic objects, USIR graphs, workflows, and provenance satisfy schemas, typing rules, invariants, integrity constraints, and execution contracts.
4. Layer Specifications
4.1 Semantic Memory (Layer 0)
Responsibilities
Persist semantic objects, versions, schemas, and relationships.
Maintain temporal lineage and provenance graphs.
Provide query, snapshot, and validation interfaces.
Required properties
Addressability and stable identifiers.
Typed storage with schema conformance.
Versioned objects and schema evolution support.
Queryable provenance and lineage.
Constraints
Mutations must be explicit, validated, and recorded.
Provenance records are append-only once committed.
Referential integrity must be enforceable.
Guarantees
Stored objects retrievable by identifier and version.
Provenance and lineage are reconstructable for compliant operations.
Validation outcomes are recordable and queryable.
Interface boundaries
Consumes: schema definitions, object writes, provenance events.
Produces: object reads, graph queries, snapshots, validation results.
4.2 USIR (Layer 1)
Responsibilities
Provide a unified typed graph representation for cross-domain structures.
Represent operator applications and transformations explicitly.
Support lowering/lifting contracts between domain representations.
Required properties
Explicit typed nodes and typed relations.
Validation rules for type soundness and graph integrity.
Canonical representation for operator binding and provenance references.
Constraints
All USIR graphs must be schema-valid and type-valid for execution.
Cross-domain constructs must use shared relation semantics.
Guarantees
Operator applications in USIR are representable and inspectable.
Relations have defined semantics and validation rules.
Lowering/lifting operations are defined as formal contracts.
Interface boundaries
Consumes: domain module schemas, operator definitions.
Produces: typed graphs, operator application subgraphs, validation artifacts.
4.3 Domain Modules (Layer 2)
Responsibilities
Define domain schemas, invariants, operator families, and adapters.
Provide domain validation and correctness conditions.
Specify domain lowering/lifting mappings to/from USIR.
Required properties
Versioned schemas and invariants.
Declared operator families with signatures and contracts.
Tool adapters with deterministic or bounded-reproducible execution contracts.
Constraints
Domain authority is limited to declared schemas and invariants.
Domain constructs must be representable in USIR-compatible forms.
Domain operators must emit required provenance.
Guarantees
Domain objects can be validated against domain rules.
Domain operators have explicit correctness claims and failure modes.
Interface boundaries
Consumes: USIR core relations and type fragments.
Produces: domain-typed USIR subgraphs, domain validations, adapter execution traces.
4.4 Orchestration (Layer 3)
Responsibilities
Represent workflows as operator graphs with explicit execution semantics.
Manage agent lifecycle and memory access protocols.
Enforce reproducible execution constraints and provenance requirements.
Required properties
Workflow representation with explicit dependencies and state requirements.
Agent state machine with defined transitions and logging.
Deterministic scheduling semantics where declared.
Constraints
Every executed action must be represented as an operator application.
Memory access must obey protocol constraints and isolation policies.
Conflicts must be resolved via defined rules with explicit records.
Guarantees
Workflows are replayable under defined conditions.
Agent actions are inspectable with provenance and state context.
Interface boundaries
Consumes: operator graphs, snapshot references, policy constraints.
Produces: execution traces, provenance records, replay artifacts, conflict reports.
4.5 Engines (Layer 4)
Responsibilities
Execute operators over USIR graphs according to execution contracts.
Produce typed outputs and validation artifacts.
Emit provenance and metadata sufficient for inspection and replay.
Required properties
Uniform engine interface for operator execution.
Explicit reproducibility contracts and equivalence relations.
Metadata emission including configuration, environment, and numeric tolerances.
Constraints
Engines must not mutate semantic memory outside declared operator effects.
Outputs must be typed and schema-valid prior to commit.
Guarantees
Execution results are attributable to operator invocations and state.
Divergence from reproducibility contracts is detectable and reportable.
Interface boundaries
Consumes: operator invocation objects, USIR graphs, engine configs.
Produces: outputs, diagnostics, validation results, provenance/metadata.
4.6 Interfaces / SIM (Layer 5)
Responsibilities
Provide inspection of semantic objects, USIR graphs, workflows, and provenance.
Support visualization and debugging of transformations and invariants.
Provide controlled mutation surfaces where authorized.
Required properties
Read-only inspection is always available for committed artifacts.
Visualization contracts correspond to underlying semantic structures.
Debug surfaces can enumerate operator chains, state diffs, and validation outcomes.
Constraints
Any mutation must be performed via operators and recorded provenance.
Interfaces must not bypass validation gates.
Guarantees
Cross-layer visibility for compliant objects and transformations.
Users can inspect reasoning chains, provenance, and state context for results.
Interface boundaries
Consumes: semantic memory objects, USIR graphs, provenance queries.
Produces: interactive views, inspection reports, operator invocation requests.
5. Semantic Memory Specification
5.1 Schema requirements
Every semantic object class MUST have a defined schema.
Schemas MUST specify:
required fields and types
allowed relations to other objects
integrity constraints
version identifier and compatibility metadata
5.2 Typing requirements
Semantic objects MUST be typed according to schema-defined types.
Type references MUST resolve to versioned schema definitions.
5.3 Versioning
Every semantic object MUST have a version identifier.
Semantic Memory MUST support:
retrieval by (id, version)
retrieval of latest compatible version per policy
explicit migration records when transformations change schema versions
5.4 Permanence vs. mutability
Semantic objects MAY be mutable only via declared operators.
Provenance records MUST be append-only once committed.
Prior versions MUST remain retrievable unless explicitly revoked by policy (see Security & Integrity Constraints).
5.5 Provenance structures
Provenance records MUST include:
operator identifier and version
input object identifiers and versions
output object identifiers and versions
parameters and assumptions (typed)
execution context references (engine/tool, config, environment)
state snapshot reference (where required)
validation outcomes and diagnostics references
5.6 Temporal lineage
Semantic Memory MUST represent temporal chains:
creation events
transformation events
derivation relationships
dependency closures where defined by schemas
Temporal lineage MUST be queryable.
5.7 Required queries
Semantic Memory MUST support, at minimum:
get object by (id, version)
resolve schema by (schema_id, version)
traverse provenance: backward (inputs) and forward (derived)
fetch workflow execution trace by workflow identifier and version
fetch operator invocation history by operator id
compute dependency closure for a semantic object (as defined by schema)
retrieve state snapshot references and associated object sets
5.8 Integrity constraints
Semantic Memory MUST enforce or validate:
referential integrity (no dangling references)
schema conformance for stored objects
version integrity (referenced versions exist)
provenance completeness for committed transformations subject to charter requirements
6. USIR Specification
6.1 Graph structure
USIR is a typed directed multigraph:
Nodes: typed entities (values, structures, operator applications, constraints, workflow elements)
Edges: typed relations with defined semantics
USIR graphs MUST be serializable and persistable.
6.2 Typing system
USIR nodes MUST have a type.
Types MUST be drawn from:
USIR core type fragments
domain module type extensions registered through integration rules
Type checking MUST be defined for operator binding and relation validity.
6.3 Relations
USIR MUST define relation semantics for at least:
containment:
hierarchical structure (component-of)
dependency:
required-for evaluation or construction
derivation:
produced-by transformation lineage
constraint:
declared invariants and restrictions
binding:
association of operator inputs/outputs to nodes
reference:
stable identity links to semantic memory objects
Each relation type MUST define:
allowed source/target types
integrity constraints (e.g., acyclicity where applicable)
validation procedures
6.4 Operator binding semantics
Operator applications MUST be representable as USIR subgraphs that bind:
operator identity/version
typed input bindings
typed output bindings
preconditions/postconditions references
effect declarations (including intended memory writes)
Operator applications MUST be uniquely identifiable for provenance linkage.
6.5 Lowering/lifting contract definitions
Lowering/lifting in USIR is specified as contracts with required artifacts, not algorithms.
A lowering/lifting contract MUST define:
source schema/type requirements
target schema/type requirements
preservation requirements (what invariants and provenance must be maintained)
lossiness declaration:
lossless, lossy-with-recorded-loss, or partial
equivalence relation for validating correctness (where applicable)
required provenance emission (including mapping references between source and target elements)
6.6 Validation requirements
USIR graphs MUST be validatable for:
type correctness of nodes and bindings
relation validity constraints
schema conformance for domain-extended subgraphs
operator application well-formedness
Validation MUST produce machine-readable diagnostics.
6.7 Invariants USIR must preserve
USIR MUST preserve:
type soundness for declared type fragments
referential integrity for semantic memory references
traceability of derivations via derivation relations and provenance links
stable operator application identity for replay/inspection
7. Operator Model
7.1 Operator signatures
Every operator operates under a semantic contract (see Glossary).
Every operator MUST declare:
identifier and version
input types (arity, named parameters)
output types
required state context (if any)
allowed side effects on semantic memory
7.2 Input/output type rules
Operator invocation MUST fail validation if inputs are not type-compatible.
Outputs MUST be type-valid and schema-valid prior to commit.
7.3 Preconditions / postconditions
Operators MUST declare preconditions and postconditions as:
invariants to check
constraints to enforce
validation procedures to apply
Postconditions MUST specify what must hold for outputs and mutated state.
7.4 Effects on semantic memory
Operators MAY:
create new semantic objects
create new USIR graphs
record new provenance records
mutate existing objects only if mutation is permitted by schema and policy
Operators MUST declare effect scope explicitly.
7.5 Provenance emission requirements
Each operator invocation MUST emit a provenance record containing:
operator identity/version
full input bindings (ids/versions)
full output bindings (ids/versions)
parameterization and assumptions
execution context and config references
validation outcomes and diagnostics references
state snapshot reference if required by orchestration policy
7.6 Failure modes
Operators MUST define:
validation failure (type/schema/invariant violation)
execution failure (engine/tool errors, non-convergence)
contract failure (postconditions not met)
Failures MUST be recorded with diagnostics and preserved provenance links to attempted invocation.
7.7 Determinism / reproducibility boundaries
Operators MUST declare one of:
Deterministic:
same inputs and state yield identical outputs under declared environment constraints.
Reproducible (bounded):
outputs are equivalent under a declared equivalence relation and tolerance.
Non-reproducible:
allowed only with explicit opt-in policy; must emit expanded metadata explaining sources of variability.
8. Domain Module Specification
8.1 Required components
A domain module MUST provide:
versioned schemas and type extensions
domain invariants (declarative constraints)
operator families with signatures and contracts
validation procedures for domain objects and transformations
tool adapters (where appropriate) with execution contracts
8.2 Integration rules with USIR
Domain schemas MUST map to USIR subgraph patterns.
Domain types MUST register as extensions with explicit versioning.
Domain operators MUST be expressible as USIR operator applications and must adhere to the global operator model.
8.3 Validation requirements
Domain modules MUST define:
object validation (schema + domain invariants)
transformation validation (operator pre/postconditions)
adapter validation (inputs/outputs and provenance completeness)
8.4 Operator correctness conditions
Domain operators MUST state correctness conditions as:
invariants preserved or violated (with explicit failure)
equivalence relations for validation where strict equality is not applicable
8.5 Boundaries of domain authority
Domain modules MAY define domain-specific invariants and constraints but MUST NOT:
redefine USIR core relation semantics
violate global provenance requirements
bypass orchestration mutation policies
introduce untyped or schema-less objects
8.6 Shared constraints across domains
Domains MUST support cross-domain coherence via:
compatible typing fragments where intersecting concepts exist (e.g., units, constraints, workflows)
explicit lowering/lifting contracts
shared provenance linking between representations
9. Orchestration Specification
9.1 Workflow representation
Workflows MUST be represented as:
operator graphs with typed nodes and relations
explicit dependencies and execution order constraints
explicit artifact inputs/outputs
required state snapshot references or snapshot policy
Workflow versioning
Workflows MUST have a version identifier.
Workflow versions MUST be:
immutable once committed to semantic memory
referenced in all provenance records from workflow executions
resolvable for replay operations against historical workflow definitions
Workflow schema changes (operator additions/removals, dependency changes, artifact binding changes) MUST increment workflow version.
9.2 Agent lifecycle
Agents MUST have a defined lifecycle state machine with:
enumerated states
allowed transitions
transition triggers and recorded causes
All transitions MUST be recorded as semantic objects with provenance links.
9.3 Memory access protocols
Orchestration MUST define:
read scopes and write scopes
locking or conflict strategies (as policy)
snapshot semantics for reproducibility
permission model for agent actions (see Security & Integrity Constraints)
9.4 Reproducible execution constraints
Orchestration MUST provide:
a replay mechanism that re-executes workflows against specified snapshots
a divergence detection mechanism referencing equivalence relations
a record of execution environment constraints relevant to reproducibility
9.5 Provenance requirements
Orchestration MUST ensure:
every executed operator invocation is recorded
every memory write is attributable to an operator
agent decisions and routing actions are recorded as semantic objects (decision artifacts) with scope-limited requirements
9.6 Scheduling and operator application semantics
Scheduling MUST be:
deterministic when policy declares deterministic scheduling
otherwise explicitly parameterized and recorded
Operator application MUST:
bind to validated USIR graphs
adhere to memory mutation and validation gates
emit provenance on success and on failure as applicable
9.7 Conflict resolution rules
When conflicts occur (simultaneous mutations, version mismatch, invariant violations), orchestration MUST:
apply a defined resolution policy (reject, merge-with-rules, serialize, or fork)
record resolution outcomes in semantic memory with provenance
10. Engine Specification
10.1 Engine interface
Engines MUST expose an interface that accepts:
operator invocation identity/version
validated USIR graph (or references)
engine configuration (typed)
state snapshot reference (when required)
Engines MUST produce:
typed outputs (objects/graphs)
execution diagnostics
validation artifacts (where applicable)
provenance and metadata sufficient for inspection and replay
10.2 Operator execution semantics
Engine execution MUST:
respect operator preconditions and postconditions
execute within declared effect scope
not directly mutate semantic memory except through approved commit interfaces controlled by orchestration and validation gates
10.3 Reproducibility contracts
Engines MUST declare reproducibility profile per operator or engine class:
deterministic
bounded reproducible (equivalence + tolerance)
non-reproducible (policy-restricted)
10.4 Numeric vs. symbolic distinctions
Symbolic engines SHOULD support equivalence validation where possible (e.g., rewrite correctness within defined fragments).
Numeric engines MUST specify tolerances, convergence criteria, and environment constraints affecting reproducibility.
10.5 Metadata and provenance emission
Engines MUST emit metadata including:
engine/tool identity and version
configuration and parameters (typed)
relevant environment identifiers (as policy requires)
runtime status (success, failure, non-convergence)
equivalence relation identifiers and tolerance values when applicable
10.6 Equivalence relations for non-deterministic outputs
For bounded reproducibility, engines MUST define:
equivalence relation (e.g., norm-bounded difference, constraint satisfaction set equality, structure-preserving equivalence)
tolerance parameters and validation method
reporting requirements when equivalence fails
11. Interface / SIM Specification
11.1 Required inspection capabilities
Interfaces MUST allow inspection of:
semantic objects with schemas and versions
USIR graphs and typing
operator chains and workflow graphs
provenance records and temporal lineage
validation results and diagnostics
11.2 Visualization contracts
Visualizations MUST be rooted in semantics:
every displayed entity MUST reference underlying semantic objects or USIR nodes
displayed relationships MUST correspond to defined relations
views MUST be reproducible given the same state snapshot and view parameters
11.3 Allowed mutating vs. non-mutating operations
Read-only inspection MUST always be supported for committed artifacts.
Mutations MUST occur only through operator invocation pathways governed by orchestration.
Interfaces MUST not provide mutation mechanisms that bypass validation and provenance.
11.4 Debugging surfaces
Interfaces MUST provide:
operator-level step tracing for workflows
provenance diff inspection between versions
invariant violation reporting and localization (where possible)
replay controls and divergence diagnostics surfaced to the user
11.5 Cross-layer visibility guarantees
Interfaces MUST guarantee that for any compliant result artifact:
its provenance lineage can be traversed
its operator chain can be enumerated
its validation outcomes can be inspected
its state snapshot references can be retrieved (when required by policy)
12. Global Invariants
The following invariants MUST hold system-wide unless explicitly exempted by a recorded policy exception.
12.1 Semantic consistency
All stored semantic objects conform to a schema version.
Relations between objects satisfy declared relation constraints.
12.2 Type soundness
USIR graphs used for execution are type-valid under declared type rules.
Operator bindings satisfy signature typing.
12.3 Provenance completeness
All committed transformations attributable to operators MUST have provenance records meeting minimum required fields.
Provenance graphs MUST be queryable and reconstructable.
12.4 Version stability
Identifiers and versions are stable and retrievable according to versioning policies.
Schema and operator changes follow evolution policy.
12.5 Cross-domain coherence
Domain representations interoperate through USIR-defined relations and contracts.
Domain extensions do not conflict with USIR core semantics.
12.6 Replayability conditions
For workflows marked replayable, required state snapshots and execution metadata exist.
Replay equivalence relations are defined and enforced.
12.7 Schema integrity
Schemas are versioned, validated, and reference-resolvable.
Migrations are recorded and reversible where declared.
13. Cross-Layer Interaction Rules
13.1 Accepted data types
Cross-layer data exchange MUST occur via:
semantic objects (schema-valid, versioned)
USIR graphs (type-valid, relation-valid)
workflows (operator graphs with explicit execution semantics)
provenance records (structured, queryable)
13.2 Transformation boundaries
Transformations MUST occur only through operator invocations.
Lowering/lifting MUST conform to declared contracts and emit mapping provenance.
13.3 Interface stability requirements
Each layer MUST provide stable interface contracts:
schema and type definitions versioned under evolution policy
operator signatures versioned and validated
workflow execution semantics documented and regression-tested
13.4 Versioning rules
Cross-layer references MUST include version identifiers.
“Latest” resolution is permitted only through explicit policy and must be recorded as a resolution event.
13.5 Forward/backward compatibility constraints
Schema and operator evolution MUST specify compatibility class:
backward compatible
forward compatible
breaking
Breaking changes MUST include migration rules and deprecation phases.
14. Versioning & Evolution Policy
14.1 Semantic versioning
Schemas, operators, workflows, and domain modules MUST use semantic versioning:
MAJOR: breaking semantic changes
MINOR: additive compatible changes
PATCH: bug fixes without semantic change
14.2 Migration rules
Breaking changes MUST provide:
migration operators (where feasible)
mapping provenance between old and new representations
validation procedures for migrated artifacts
14.3 Deprecation policy
Deprecations MUST be:
announced in documentation and metadata
marked in schemas/operators with deprecation identifiers
supported for a defined compatibility window as policy dictates
14.4 Test and validation requirements
Changes to schemas/operators/relations MUST include:
validation tests for schema/type correctness
provenance completeness tests
replay/regression tests for marked workflows
cross-domain compatibility tests where applicable
15. Security & Integrity Constraints
15.1 Memory isolation rules
Semantic Memory MUST support isolation domains (namespaces or equivalent) to separate:
experimental branches
production/stable artifacts
restricted artifacts (policy controlled)
15.2 Allowed/forbidden mutations
Forbidden:
direct mutation of provenance records after commit
bypassing schema/type validation gates
unlogged transformations
Allowed only via operators:
object creation
versioned updates where schema permits mutability
schema migrations with recorded provenance
15.3 Validation gates
Writes to stable namespaces MUST pass:
schema validation
type validation (where applicable)
invariant checks (where enforceable)
provenance completeness checks
15.4 Constraints on agent actions
Agents MUST:
operate under explicit permission scopes
record actions as operator applications
be denied direct write access outside orchestration-controlled commit pathways
be auditable through provenance and state snapshots
15.5 Protection of provenance and invariant structures
Provenance structures and invariant definitions MUST be protected from unauthorized modification.
Any modification to invariants MUST be versioned, reviewed under policy, and accompanied by revalidation requirements.
16. Non-Goals
This charter does not:
prescribe implementation choices (databases, languages, kernels, UI frameworks)
define an execution schedule or roadmap
specify complete lowering/lifting algorithms
guarantee strict bitwise determinism for all numeric computations
define product features or commercial packaging
attempt universal domain coverage or encyclopedic ontologies
define training or evaluation of probabilistic language models
This document constitutes the SIL Technical Charter (v1).