Sprint 1: project skeleton, type system, and all architecture specs
- src/types.hpp: complete UCWM type system in C++20 — 19 enums, 11 facet data types, all core structs (CanonicalObject, Constraint, Facet, GateSignal, WorldState, etc.) with full JSON round-trip serialization - src/main.cpp: smoke test — constructs apple-problem WorldState by hand, serializes to JSON - tests/test_types.cpp: 19 tests, 123 assertions, all passing - CMakeLists.txt: CMake + CPM build with nlohmann/json, spdlog, Catch2 - schemas/: JSON Schema contracts for all UCWM data types - gates/, specialists/, resolver/, synthesis/: language-agnostic interface contracts and domain specs for all pipeline layers - docs/: architecture, vocabulary, decision matrices, roadmap (6 phases, 28 sprints), sprint_001, implementation_constraints Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
155
schemas/constraints.json
Normal file
155
schemas/constraints.json
Normal file
@@ -0,0 +1,155 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "ucwm/schemas/constraints.json",
|
||||
"title": "Constraint",
|
||||
"description": "The core reasoning currency of UCWM. An explicit relation, restriction, incompatibility, requirement, or preference involving objects and/or facets.",
|
||||
"type": "object",
|
||||
"required": ["constraint_id", "constraint_type", "argument_refs", "polarity", "strength", "status", "source_module"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"constraint_id": {
|
||||
"type": "string",
|
||||
"description": "Unique identifier. Format: C{sequence} e.g. C1, C14"
|
||||
},
|
||||
"constraint_type": {
|
||||
"type": "string",
|
||||
"description": "Named relation type. Implementors should define allowed values per domain.",
|
||||
"examples": [
|
||||
"before",
|
||||
"after",
|
||||
"during",
|
||||
"causes",
|
||||
"enables",
|
||||
"blocks",
|
||||
"same_entity",
|
||||
"not_same_entity",
|
||||
"owns",
|
||||
"transfers",
|
||||
"inside",
|
||||
"outside",
|
||||
"adjacent",
|
||||
"quantity_equals",
|
||||
"quantity_sum",
|
||||
"quantity_difference",
|
||||
"quantity_product",
|
||||
"quantity_greater",
|
||||
"quantity_less",
|
||||
"truth_value",
|
||||
"implies",
|
||||
"negates",
|
||||
"contradicts",
|
||||
"prerequisite",
|
||||
"goal",
|
||||
"has_role"
|
||||
]
|
||||
},
|
||||
"argument_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"minItems": 1,
|
||||
"description": "Ordered list of object_ids or facet_ids this constraint relates. Order is significant for asymmetric relations."
|
||||
},
|
||||
"polarity": {
|
||||
"type": "string",
|
||||
"enum": ["positive", "negative"],
|
||||
"description": "Whether this constraint asserts or denies the relation."
|
||||
},
|
||||
"strength": {
|
||||
"type": "string",
|
||||
"enum": ["hard", "soft", "probabilistic", "defeasible"],
|
||||
"description": "hard=must hold; soft=preferred; probabilistic=holds with stated probability; defeasible=default, retractable by new evidence"
|
||||
},
|
||||
"probability": {
|
||||
"type": "number",
|
||||
"minimum": 0.0,
|
||||
"maximum": 1.0,
|
||||
"description": "Required when strength=probabilistic."
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["unresolved", "resolved", "contradicted", "suspended"],
|
||||
"description": "Resolver lifecycle status.",
|
||||
"default": "unresolved"
|
||||
},
|
||||
"expression": {
|
||||
"type": "string",
|
||||
"description": "Optional human-readable or formal logic expression of the constraint. Informational; not authoritative.",
|
||||
"examples": [
|
||||
"before(E1, E2)",
|
||||
"quantity(Q1) = quantity(Q2) - 3",
|
||||
"owner(O3) = Entity_Alice"
|
||||
]
|
||||
},
|
||||
"confidence": {
|
||||
"type": "number",
|
||||
"minimum": 0.0,
|
||||
"maximum": 1.0,
|
||||
"description": "Confidence that this constraint is correctly extracted."
|
||||
},
|
||||
"contradicted_by_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "constraint_ids that contradict this one. Populated by the resolver.",
|
||||
"default": []
|
||||
},
|
||||
"supports_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "constraint_ids that reinforce this one.",
|
||||
"default": []
|
||||
},
|
||||
"source_module": {
|
||||
"type": "string",
|
||||
"description": "Specialist or module that emitted this constraint."
|
||||
},
|
||||
"provenance_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"default": []
|
||||
}
|
||||
},
|
||||
"examples": [
|
||||
{
|
||||
"constraint_id": "C1",
|
||||
"constraint_type": "owns",
|
||||
"argument_refs": ["E1", "O_apples", "Q1"],
|
||||
"polarity": "positive",
|
||||
"strength": "hard",
|
||||
"status": "resolved",
|
||||
"expression": "owns(Alice, apples, count=5) at t0",
|
||||
"confidence": 0.98,
|
||||
"source_module": "ownership_specialist",
|
||||
"contradicted_by_refs": [],
|
||||
"supports_refs": [],
|
||||
"provenance_refs": ["P1"]
|
||||
},
|
||||
{
|
||||
"constraint_id": "C2",
|
||||
"constraint_type": "before",
|
||||
"argument_refs": ["EV_initial_possession", "EV_transfer"],
|
||||
"polarity": "positive",
|
||||
"strength": "hard",
|
||||
"status": "resolved",
|
||||
"expression": "before(E_initial_possession, E_transfer)",
|
||||
"confidence": 0.99,
|
||||
"source_module": "temporal_specialist",
|
||||
"contradicted_by_refs": [],
|
||||
"supports_refs": [],
|
||||
"provenance_refs": ["P2"]
|
||||
},
|
||||
{
|
||||
"constraint_id": "C3",
|
||||
"constraint_type": "quantity_difference",
|
||||
"argument_refs": ["Q_alice_final", "Q1", "Q2"],
|
||||
"polarity": "positive",
|
||||
"strength": "hard",
|
||||
"status": "resolved",
|
||||
"expression": "quantity(Q_alice_final) = quantity(Q1) - quantity(Q2)",
|
||||
"confidence": 0.99,
|
||||
"source_module": "quantity_specialist",
|
||||
"contradicted_by_refs": [],
|
||||
"supports_refs": [],
|
||||
"provenance_refs": ["P3"]
|
||||
}
|
||||
]
|
||||
}
|
||||
331
schemas/facets.json
Normal file
331
schemas/facets.json
Normal file
@@ -0,0 +1,331 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "ucwm/schemas/facets.json",
|
||||
"title": "Facets",
|
||||
"description": "Typed partial views that attach to CanonicalObjects. Facets are optional and additive — not every object exists in every relation type.",
|
||||
"$defs": {
|
||||
"BaseFacet": {
|
||||
"type": "object",
|
||||
"required": ["facet_id", "facet_kind", "object_ref", "confidence", "source_module"],
|
||||
"properties": {
|
||||
"facet_id": {
|
||||
"type": "string",
|
||||
"description": "Unique identifier for this facet instance."
|
||||
},
|
||||
"facet_kind": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"temporal",
|
||||
"spatial",
|
||||
"causal",
|
||||
"logical",
|
||||
"syntactic",
|
||||
"semantic",
|
||||
"social",
|
||||
"ownership",
|
||||
"code_structure",
|
||||
"quantity",
|
||||
"planning"
|
||||
]
|
||||
},
|
||||
"object_ref": {
|
||||
"type": "string",
|
||||
"description": "The object_id this facet is attached to."
|
||||
},
|
||||
"confidence": {
|
||||
"type": "number",
|
||||
"minimum": 0.0,
|
||||
"maximum": 1.0
|
||||
},
|
||||
"source_module": {
|
||||
"type": "string",
|
||||
"description": "Specialist module that produced this facet."
|
||||
},
|
||||
"provenance_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"default": []
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"TemporalFacet": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/$defs/BaseFacet" },
|
||||
{
|
||||
"type": "object",
|
||||
"description": "Temporal description: when this object exists, begins, ends, or recurs.",
|
||||
"properties": {
|
||||
"facet_kind": { "const": "temporal" },
|
||||
"time_point": {
|
||||
"type": "string",
|
||||
"description": "Absolute or relative time point. ISO 8601 when known."
|
||||
},
|
||||
"interval_start": { "type": "string" },
|
||||
"interval_end": { "type": "string" },
|
||||
"temporal_order_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "IDs of constraint records expressing before/after/during relations."
|
||||
},
|
||||
"is_recurring": { "type": "boolean", "default": false },
|
||||
"recurrence_pattern": {
|
||||
"type": "string",
|
||||
"description": "Natural language or ISO 8601 recurrence expression."
|
||||
},
|
||||
"duration": { "type": "string" }
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"SpatialFacet": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/$defs/BaseFacet" },
|
||||
{
|
||||
"type": "object",
|
||||
"description": "Spatial description: where this object is, was, or will be.",
|
||||
"properties": {
|
||||
"facet_kind": { "const": "spatial" },
|
||||
"location_label": { "type": "string" },
|
||||
"coordinates": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"x": { "type": "number" },
|
||||
"y": { "type": "number" },
|
||||
"z": { "type": "number" }
|
||||
}
|
||||
},
|
||||
"containment_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Constraint IDs expressing inside/outside/adjacent relations."
|
||||
},
|
||||
"reference_frame": {
|
||||
"type": "string",
|
||||
"description": "The coordinate system or reference object."
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"CausalFacet": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/$defs/BaseFacet" },
|
||||
{
|
||||
"type": "object",
|
||||
"description": "Causal description: what caused or was caused by this object.",
|
||||
"properties": {
|
||||
"facet_kind": { "const": "causal" },
|
||||
"cause_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "IDs of objects or events that caused this one."
|
||||
},
|
||||
"effect_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "IDs of objects or events caused by this one."
|
||||
},
|
||||
"enabling_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"blocking_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"causal_strength": {
|
||||
"type": "string",
|
||||
"enum": ["necessary", "sufficient", "contributing", "correlational"]
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"LogicalFacet": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/$defs/BaseFacet" },
|
||||
{
|
||||
"type": "object",
|
||||
"description": "Logical description: truth value, negation, quantification, implication.",
|
||||
"properties": {
|
||||
"facet_kind": { "const": "logical" },
|
||||
"truth_status": {
|
||||
"type": "string",
|
||||
"enum": ["true", "false", "unknown", "hypothetical", "negated", "asserted"]
|
||||
},
|
||||
"quantifier": {
|
||||
"type": "string",
|
||||
"enum": ["universal", "existential", "none"]
|
||||
},
|
||||
"implies_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "IDs of propositions this object implies."
|
||||
},
|
||||
"negates_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"contradicts_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"OwnershipFacet": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/$defs/BaseFacet" },
|
||||
{
|
||||
"type": "object",
|
||||
"description": "Ownership and possession description: who holds what, and when.",
|
||||
"properties": {
|
||||
"facet_kind": { "const": "ownership" },
|
||||
"owner_ref": {
|
||||
"type": "string",
|
||||
"description": "object_id of the current owner."
|
||||
},
|
||||
"owned_ref": {
|
||||
"type": "string",
|
||||
"description": "object_id of the thing owned."
|
||||
},
|
||||
"quantity_ref": {
|
||||
"type": "string",
|
||||
"description": "object_id of a quantity object if ownership is of a counted resource."
|
||||
},
|
||||
"temporal_ref": {
|
||||
"type": "string",
|
||||
"description": "Facet ID providing temporal scope for this ownership."
|
||||
},
|
||||
"transfer_type": {
|
||||
"type": "string",
|
||||
"enum": ["give", "sell", "take", "lose", "receive", "initial", "final"]
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"QuantityFacet": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/$defs/BaseFacet" },
|
||||
{
|
||||
"type": "object",
|
||||
"description": "Quantity description: numeric value, unit, precision.",
|
||||
"properties": {
|
||||
"facet_kind": { "const": "quantity" },
|
||||
"value": {
|
||||
"oneOf": [
|
||||
{ "type": "number" },
|
||||
{ "type": "string", "description": "Symbolic expression e.g. 'Q1 - 2'" }
|
||||
]
|
||||
},
|
||||
"unit": { "type": "string" },
|
||||
"precision": { "type": "number" },
|
||||
"is_exact": { "type": "boolean" },
|
||||
"derived_from_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "object_ids of quantities this was computed from."
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"SyntacticFacet": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/$defs/BaseFacet" },
|
||||
{
|
||||
"type": "object",
|
||||
"description": "Syntactic description: role in sentence structure.",
|
||||
"properties": {
|
||||
"facet_kind": { "const": "syntactic" },
|
||||
"grammatical_role": {
|
||||
"type": "string",
|
||||
"enum": ["subject", "object", "indirect_object", "adjunct", "predicate", "modifier", "other"]
|
||||
},
|
||||
"head_token": { "type": "string" },
|
||||
"dependency_arc": { "type": "string" }
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"SocialFacet": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/$defs/BaseFacet" },
|
||||
{
|
||||
"type": "object",
|
||||
"description": "Social and agentive description: beliefs, intentions, obligations, roles.",
|
||||
"properties": {
|
||||
"facet_kind": { "const": "social" },
|
||||
"agent_ref": { "type": "string" },
|
||||
"social_act": {
|
||||
"type": "string",
|
||||
"enum": ["assert", "request", "promise", "threaten", "deceive", "inform", "ask", "other"]
|
||||
},
|
||||
"belief_about_ref": { "type": "string" },
|
||||
"belief_truth_status": {
|
||||
"type": "string",
|
||||
"enum": ["true", "false", "unknown"]
|
||||
},
|
||||
"obligation_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"role": { "type": "string" }
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"PlanningFacet": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/$defs/BaseFacet" },
|
||||
{
|
||||
"type": "object",
|
||||
"description": "Planning description: steps, goals, prerequisites, dependencies.",
|
||||
"properties": {
|
||||
"facet_kind": { "const": "planning" },
|
||||
"step_index": { "type": "integer" },
|
||||
"prerequisite_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"goal_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"blocks_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["pending", "in_progress", "complete", "blocked", "skipped"]
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
|
||||
"oneOf": [
|
||||
{ "$ref": "#/$defs/TemporalFacet" },
|
||||
{ "$ref": "#/$defs/SpatialFacet" },
|
||||
{ "$ref": "#/$defs/CausalFacet" },
|
||||
{ "$ref": "#/$defs/LogicalFacet" },
|
||||
{ "$ref": "#/$defs/OwnershipFacet" },
|
||||
{ "$ref": "#/$defs/QuantityFacet" },
|
||||
{ "$ref": "#/$defs/SyntacticFacet" },
|
||||
{ "$ref": "#/$defs/SocialFacet" },
|
||||
{ "$ref": "#/$defs/PlanningFacet" }
|
||||
]
|
||||
}
|
||||
128
schemas/objects.json
Normal file
128
schemas/objects.json
Normal file
@@ -0,0 +1,128 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "ucwm/schemas/objects.json",
|
||||
"title": "CanonicalObject",
|
||||
"description": "The primary reusable referent inside UCWM. A stable anchor that facets and constraints attach to.",
|
||||
"type": "object",
|
||||
"required": ["object_id", "object_kind", "status", "confidence"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"object_id": {
|
||||
"type": "string",
|
||||
"description": "Unique identifier. Format: {kind_prefix}_{sequence} e.g. E1, O4, Q7",
|
||||
"pattern": "^[A-Z][A-Z0-9]*_[0-9]+$|^[A-Z][0-9]+$"
|
||||
},
|
||||
"object_kind": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"entity",
|
||||
"event",
|
||||
"concept",
|
||||
"proposition",
|
||||
"relation_instance",
|
||||
"procedure_step",
|
||||
"code_object",
|
||||
"quantity",
|
||||
"claim",
|
||||
"state"
|
||||
],
|
||||
"description": "The ontological kind of this object."
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["proposed", "active", "merged", "split", "invalidated"],
|
||||
"description": "Lifecycle status. Proposed objects are unconfirmed. Merged objects were unified with another. Split objects produced multiple descendants.",
|
||||
"default": "proposed"
|
||||
},
|
||||
"confidence": {
|
||||
"type": "number",
|
||||
"minimum": 0.0,
|
||||
"maximum": 1.0,
|
||||
"description": "Aggregate confidence that this object is correctly proposed."
|
||||
},
|
||||
"surface_span": {
|
||||
"type": "object",
|
||||
"description": "The text span(s) that evidence this object.",
|
||||
"properties": {
|
||||
"text": { "type": "string" },
|
||||
"start": { "type": "integer" },
|
||||
"end": { "type": "integer" }
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"canonical_label": {
|
||||
"type": "string",
|
||||
"description": "Human-readable canonical name for this object."
|
||||
},
|
||||
"aliases": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Alternative names, pronouns, or references that may corefer to this object."
|
||||
},
|
||||
"merged_into": {
|
||||
"type": "string",
|
||||
"description": "object_id of the object this was merged into. Populated only when status=merged."
|
||||
},
|
||||
"split_from": {
|
||||
"type": "string",
|
||||
"description": "object_id of the object this was split from. Populated only when status=split."
|
||||
},
|
||||
"facet_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "IDs of Facet objects attached to this canonical object.",
|
||||
"default": []
|
||||
},
|
||||
"constraint_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "IDs of Constraints that reference this object.",
|
||||
"default": []
|
||||
},
|
||||
"evidence_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "IDs of evidence or provenance records supporting this object.",
|
||||
"default": []
|
||||
},
|
||||
"provenance_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "IDs of Provenance records tracking how this object was created.",
|
||||
"default": []
|
||||
},
|
||||
"source_module": {
|
||||
"type": "string",
|
||||
"description": "Module ID that proposed this object."
|
||||
}
|
||||
},
|
||||
"examples": [
|
||||
{
|
||||
"object_id": "E1",
|
||||
"object_kind": "entity",
|
||||
"status": "active",
|
||||
"confidence": 0.97,
|
||||
"surface_span": { "text": "Alice", "start": 0, "end": 5 },
|
||||
"canonical_label": "Alice",
|
||||
"aliases": ["she", "her"],
|
||||
"facet_refs": ["F_E1_ownership", "F_E1_temporal"],
|
||||
"constraint_refs": ["C1", "C3"],
|
||||
"evidence_refs": [],
|
||||
"provenance_refs": ["P1"],
|
||||
"source_module": "entity_specialist"
|
||||
},
|
||||
{
|
||||
"object_id": "Q1",
|
||||
"object_kind": "quantity",
|
||||
"status": "active",
|
||||
"confidence": 0.99,
|
||||
"surface_span": { "text": "5 apples", "start": 10, "end": 17 },
|
||||
"canonical_label": "5",
|
||||
"facet_refs": ["F_Q1_quantity"],
|
||||
"constraint_refs": ["C1"],
|
||||
"evidence_refs": [],
|
||||
"provenance_refs": ["P2"],
|
||||
"source_module": "quantity_specialist"
|
||||
}
|
||||
]
|
||||
}
|
||||
80
schemas/provenance.json
Normal file
80
schemas/provenance.json
Normal file
@@ -0,0 +1,80 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "ucwm/schemas/provenance.json",
|
||||
"title": "Provenance",
|
||||
"description": "Tracks where every fact, object, facet, and constraint came from. Enables failure localization and explainability.",
|
||||
"type": "object",
|
||||
"required": ["provenance_id", "record_type", "source_module", "timestamp"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"provenance_id": {
|
||||
"type": "string",
|
||||
"description": "Unique identifier. Format: P{sequence}"
|
||||
},
|
||||
"record_type": {
|
||||
"type": "string",
|
||||
"enum": ["object_proposal", "facet_attachment", "constraint_emission", "resolver_operation", "object_merge", "object_split", "synthesis_step"],
|
||||
"description": "What kind of operation created this provenance record."
|
||||
},
|
||||
"source_module": {
|
||||
"type": "string",
|
||||
"description": "Module ID that triggered this event."
|
||||
},
|
||||
"input_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "IDs of objects, facets, or constraints that were inputs to the operation.",
|
||||
"default": []
|
||||
},
|
||||
"output_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "IDs of objects, facets, or constraints produced by the operation.",
|
||||
"default": []
|
||||
},
|
||||
"evidence_span": {
|
||||
"type": "object",
|
||||
"description": "Text span that provided evidence for this operation.",
|
||||
"properties": {
|
||||
"text": { "type": "string" },
|
||||
"start": { "type": "integer" },
|
||||
"end": { "type": "integer" }
|
||||
}
|
||||
},
|
||||
"confidence": {
|
||||
"type": "number",
|
||||
"minimum": 0.0,
|
||||
"maximum": 1.0
|
||||
},
|
||||
"timestamp": {
|
||||
"type": "string",
|
||||
"description": "ISO 8601 timestamp of when this operation occurred."
|
||||
},
|
||||
"notes": {
|
||||
"type": "string",
|
||||
"description": "Optional free-text note. For debugging only — not part of the reasoning chain."
|
||||
}
|
||||
},
|
||||
"examples": [
|
||||
{
|
||||
"provenance_id": "P1",
|
||||
"record_type": "object_proposal",
|
||||
"source_module": "entity_specialist",
|
||||
"input_refs": [],
|
||||
"output_refs": ["E1"],
|
||||
"evidence_span": { "text": "Alice", "start": 0, "end": 5 },
|
||||
"confidence": 0.97,
|
||||
"timestamp": "2026-05-01T00:00:00Z"
|
||||
},
|
||||
{
|
||||
"provenance_id": "P4",
|
||||
"record_type": "resolver_operation",
|
||||
"source_module": "resolver",
|
||||
"input_refs": ["C1", "C2", "C3"],
|
||||
"output_refs": ["Q_alice_final"],
|
||||
"confidence": 0.99,
|
||||
"timestamp": "2026-05-01T00:00:01Z",
|
||||
"notes": "Arithmetic resolution: 5 - 2 = 3"
|
||||
}
|
||||
]
|
||||
}
|
||||
196
schemas/routing.json
Normal file
196
schemas/routing.json
Normal file
@@ -0,0 +1,196 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "ucwm/schemas/routing.json",
|
||||
"title": "Routing Schemas",
|
||||
"description": "GateSignal and RoutingDecision schemas for the RSA relay layer.",
|
||||
"$defs": {
|
||||
"GateSignal": {
|
||||
"type": "object",
|
||||
"title": "GateSignal",
|
||||
"description": "Output of a single relation gate. Does not solve anything — only informs the router.",
|
||||
"required": ["gate_id", "activated", "confidence"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"gate_id": {
|
||||
"type": "string",
|
||||
"description": "Identifier of the gate that produced this signal.",
|
||||
"examples": [
|
||||
"is_math",
|
||||
"has_temporal_relation",
|
||||
"has_entity_reference",
|
||||
"has_ownership_transfer",
|
||||
"has_quantity"
|
||||
]
|
||||
},
|
||||
"activated": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the gate fired. High-recall design: prefer true when uncertain."
|
||||
},
|
||||
"confidence": {
|
||||
"type": "number",
|
||||
"minimum": 0.0,
|
||||
"maximum": 1.0,
|
||||
"description": "Confidence in the activation decision."
|
||||
},
|
||||
"evidence_spans": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"text": { "type": "string" },
|
||||
"start": { "type": "integer" },
|
||||
"end": { "type": "integer" }
|
||||
}
|
||||
},
|
||||
"description": "Text spans that triggered this gate."
|
||||
},
|
||||
"method": {
|
||||
"type": "string",
|
||||
"enum": ["regex", "rule", "classifier", "neural", "hybrid"],
|
||||
"description": "Implementation method used by this gate instance."
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"BudgetSpec": {
|
||||
"type": "object",
|
||||
"title": "BudgetSpec",
|
||||
"description": "Resource budget granted to a specialist by the relay.",
|
||||
"properties": {
|
||||
"level": {
|
||||
"type": "string",
|
||||
"enum": ["minimal", "bounded", "full"],
|
||||
"description": "minimal=one fast pass; bounded=normal depth; full=exhaust all evidence"
|
||||
},
|
||||
"max_objects": {
|
||||
"type": "integer",
|
||||
"description": "Maximum number of objects the specialist may inspect."
|
||||
},
|
||||
"max_constraints": {
|
||||
"type": "integer",
|
||||
"description": "Maximum number of constraints the specialist may emit."
|
||||
},
|
||||
"max_iterations": {
|
||||
"type": "integer",
|
||||
"description": "Maximum processing iterations for iterative specialists."
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"SpecialistAssignment": {
|
||||
"type": "object",
|
||||
"title": "SpecialistAssignment",
|
||||
"description": "Activation of a single specialist within a RoutingDecision.",
|
||||
"required": ["specialist_id", "target_refs", "budget"],
|
||||
"properties": {
|
||||
"specialist_id": {
|
||||
"type": "string",
|
||||
"description": "Registered ID of the specialist to activate.",
|
||||
"examples": [
|
||||
"temporal",
|
||||
"spatial",
|
||||
"entity",
|
||||
"quantity",
|
||||
"logic",
|
||||
"causal",
|
||||
"ownership",
|
||||
"social",
|
||||
"planning",
|
||||
"code"
|
||||
]
|
||||
},
|
||||
"target_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "object_ids the specialist should inspect."
|
||||
},
|
||||
"budget": { "$ref": "#/$defs/BudgetSpec" },
|
||||
"priority": {
|
||||
"type": "integer",
|
||||
"description": "Relative priority for constraint merging. Lower number = higher priority."
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"RoutingDecision": {
|
||||
"type": "object",
|
||||
"title": "RoutingDecision",
|
||||
"description": "Composite routing decision emitted by the RSA relay. Activates multiple specialists on the same targets.",
|
||||
"required": ["decision_id", "assignments", "mode"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"decision_id": {
|
||||
"type": "string",
|
||||
"description": "Unique ID for this routing decision."
|
||||
},
|
||||
"assignments": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/$defs/SpecialistAssignment" },
|
||||
"minItems": 1,
|
||||
"description": "Ordered list of specialist assignments."
|
||||
},
|
||||
"mode": {
|
||||
"type": "string",
|
||||
"enum": ["parallel", "sequential", "iterative", "conflict_checking"],
|
||||
"description": "Execution mode for specialists in this decision."
|
||||
},
|
||||
"gate_signals": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/$defs/GateSignal" },
|
||||
"description": "The gate signals that informed this routing decision."
|
||||
},
|
||||
"input_object_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "All canonical object IDs available at routing time."
|
||||
},
|
||||
"provenance_refs": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"default": []
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"examples": [
|
||||
{
|
||||
"decision_id": "RD_001",
|
||||
"mode": "parallel",
|
||||
"gate_signals": [
|
||||
{ "gate_id": "has_entity_reference", "activated": true, "confidence": 0.99 },
|
||||
{ "gate_id": "has_quantity", "activated": true, "confidence": 0.99 },
|
||||
{ "gate_id": "has_ownership_transfer", "activated": true, "confidence": 0.96 },
|
||||
{ "gate_id": "is_math", "activated": true, "confidence": 0.94 },
|
||||
{ "gate_id": "has_temporal_relation", "activated": true, "confidence": 0.88 }
|
||||
],
|
||||
"input_object_refs": ["E1", "E2", "O_apples", "Q1", "Q2", "EV_transfer"],
|
||||
"assignments": [
|
||||
{
|
||||
"specialist_id": "entity",
|
||||
"target_refs": ["E1", "E2"],
|
||||
"budget": { "level": "bounded" },
|
||||
"priority": 1
|
||||
},
|
||||
{
|
||||
"specialist_id": "quantity",
|
||||
"target_refs": ["Q1", "Q2"],
|
||||
"budget": { "level": "full" },
|
||||
"priority": 2
|
||||
},
|
||||
{
|
||||
"specialist_id": "ownership",
|
||||
"target_refs": ["E1", "E2", "O_apples"],
|
||||
"budget": { "level": "bounded" },
|
||||
"priority": 3
|
||||
},
|
||||
{
|
||||
"specialist_id": "temporal",
|
||||
"target_refs": ["EV_transfer"],
|
||||
"budget": { "level": "minimal" },
|
||||
"priority": 4
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
98
schemas/world_state.json
Normal file
98
schemas/world_state.json
Normal file
@@ -0,0 +1,98 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "ucwm/schemas/world_state.json",
|
||||
"title": "WorldState",
|
||||
"description": "The active UCWM state at a given processing stage. Passed between pipeline stages. The resolver stabilizes it; synthesis reads from it.",
|
||||
"type": "object",
|
||||
"required": ["state_id", "stage", "objects", "facets", "constraints"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"state_id": {
|
||||
"type": "string",
|
||||
"description": "Unique ID for this state snapshot."
|
||||
},
|
||||
"stage": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"post_gate",
|
||||
"post_proposal",
|
||||
"post_routing",
|
||||
"post_specialist",
|
||||
"post_resolver",
|
||||
"resolved",
|
||||
"synthesized"
|
||||
],
|
||||
"description": "Which pipeline stage produced this state snapshot."
|
||||
},
|
||||
"input_text": {
|
||||
"type": "string",
|
||||
"description": "Original user input text."
|
||||
},
|
||||
"objects": {
|
||||
"type": "object",
|
||||
"description": "Map of object_id to CanonicalObject.",
|
||||
"additionalProperties": { "$ref": "objects.json" }
|
||||
},
|
||||
"facets": {
|
||||
"type": "object",
|
||||
"description": "Map of facet_id to Facet.",
|
||||
"additionalProperties": { "$ref": "facets.json" }
|
||||
},
|
||||
"constraints": {
|
||||
"type": "object",
|
||||
"description": "Map of constraint_id to Constraint.",
|
||||
"additionalProperties": { "$ref": "constraints.json" }
|
||||
},
|
||||
"provenance": {
|
||||
"type": "object",
|
||||
"description": "Map of provenance_id to Provenance record.",
|
||||
"additionalProperties": { "$ref": "provenance.json" }
|
||||
},
|
||||
"routing_decision": {
|
||||
"$ref": "routing.json#/$defs/RoutingDecision"
|
||||
},
|
||||
"gate_signals": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "routing.json#/$defs/GateSignal" }
|
||||
},
|
||||
"resolution_log": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"operation": { "type": "string" },
|
||||
"affected_refs": { "type": "array", "items": { "type": "string" } },
|
||||
"result": { "type": "string" },
|
||||
"note": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"description": "Ordered log of resolver operations applied to reach this state."
|
||||
},
|
||||
"open_contradictions": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"constraint_refs": { "type": "array", "items": { "type": "string" } },
|
||||
"description": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"description": "Contradictions that the resolver could not resolve. Synthesis must account for these."
|
||||
},
|
||||
"synthesis_answer": {
|
||||
"type": "string",
|
||||
"description": "Final synthesized answer. Populated only at stage=synthesized."
|
||||
},
|
||||
"synthesis_confidence": {
|
||||
"type": "number",
|
||||
"minimum": 0.0,
|
||||
"maximum": 1.0,
|
||||
"description": "Confidence in the synthesis answer."
|
||||
},
|
||||
"derivation_trace": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Ordered list of constraint_ids and resolver operations used to derive the synthesis answer."
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user