Files
Assistant/architecture/CORE_SEMANTIC_MODEL_V1.md
T
2026-08-16 15:22:49 +03:00

165 lines
8.2 KiB
Markdown

# 3. CORE_SEMANTIC_MODEL_V1.md
## 3.1 Scope
This is a V1 semantic freeze, not an eternal ontology. It defines the minimum durable concepts required to build the walking skeleton and preserve future migration freedom.
## 3.2 Canonical Core V1 concepts
### Identity
Stable semantic identity independent of current name, locator, account, process or key. Supports identifier history and future merge/split corrections.
### Actor
Entity capable of requests/actions/representation. Actor is not automatically a Principal.
### Principal
The person/organization/accounting/legal/operational interest on whose behalf an action is performed. Same human may act for multiple principals.
### Scope
Boundary for data, authority, project/context and permissible propagation.
### AuthorityGrant / AuthorityContext
Evidence that an Actor may perform a class of actions for a Principal within Scope and validity conditions. Capability never implies grant.
### Situation
Time-bounded interpretation of “what is happening now”: actor, interface/session, focus, project/workspace/environment bindings, active task, relevant resources, confidence/provenance. Situation is derived and expires/revalidates.
### Observation
Something obtained from a source/sensor/tool/user report. Carries provenance, observed time, coverage and source semantics.
### Claim
A proposition asserted by a source or derived system. It is not automatically fact.
### Belief/Assessment
Current system interpretation supported by evidence; versioned/revisable and scoped.
### Intent
Current request/desired change inferred from interaction; can be revised/superseded. Intent is not automatically long-term preference.
### Goal
Desired world/state transition or outcome with lifecycle and lineage. Goal may be refined/superseded; method is not identical to goal.
### Task
Durable unit of work that must survive session/process, coordinate actors, or carry lifecycle significance. Ephemeral reasoning steps are not Tasks.
### Decision
Selection/commitment among alternatives with rationale/evidence refs where consequence warrants. Decision can have validity/revisit conditions.
### ActionProposal
Structured candidate to change canonical state, communicate, allocate resources or mutate external world. Proposal has no execution authority by itself.
### AuthorizedAction
Proposal that passed owner validation, current authority, revision/target/integrity checks and received commit identity.
### ActionAttempt
Concrete execution attempt of an AuthorizedAction. Multiple attempts may serve one ActionIntent; attempt is not outcome.
### Outcome
Observed/verifiable result attributable with stated confidence. Supports UNKNOWN/partial/provisional maturity.
### Commitment
A future obligation/expectation created by promise/agreement/explicit user request/policy. Must have owner/beneficiary, fulfilment or renegotiation path and prospective continuity.
### ProspectiveItem
Canonical future-relevance object used by Continuity for reminder/wake/review/expected transition. V1 may implement only reminder/wake subset; it remains independent of Temporal.
### Event
Meaningful semantic transition or occurrence. Event is not a log line and not every low-level tool callback becomes Event.
### Artifact
Durable content/resource with identity, content/schema metadata, provenance and scope. Payload may live outside PostgreSQL.
### Capability
Declared/tested ability to observe, reason, communicate or act, with contracts, limits, provenance, health and allowed-use metadata. Capability availability ≠ authority.
### Revision
Optimistic semantic version/precondition for mutable canonical objects and contracts.
### Provenance
Lineage linking observations, claims, derived states, actions and artifacts to sources/derivations without treating copies as independent evidence.
## 3.3 Concepts intentionally NOT Core primitives in V1
These remain extension/derived concepts until evidence requires promotion: `Thread`, `Journey`, `Program`, `Trajectory`, `Portfolio`, `Responsibility`, `Risk`, `Opportunity`, `Monitor`, `ControlLoop`, `Routine`, `Theory`, `Frontier`. Foundation must permit them later but Codex must not materialize separate Core tables/services merely because they were discussed.
## 3.4 Required semantic distinctions
`Actor ≠ Principal`
`Identity ≠ Identifier ≠ Locator`
`Situation ≠ RequestContext ≠ ModelContext`
`Observation ≠ Claim ≠ Belief`
`Intent ≠ Goal ≠ Task`
`Task ≠ ActionProposal ≠ AuthorizedAction ≠ ActionAttempt ≠ Outcome`
`Commitment ≠ Reminder delivery`
`Capability ≠ Authority`
`Event ≠ Integration message ≠ Log`
`Canonical state ≠ Projection ≠ Cache`
`Prediction ≠ Expected-by-process ≠ Required-by-commitment`.
## 3.5 Required state semantics
### Goal lifecycle (minimum)
`ACTIVE | WAITING | DORMANT | SATISFIED | SUPERSEDED | ABANDONED`
Transitions must preserve reason and lineage. `ABANDONED` does not mean failure; `SUPERSEDED` must point to successor when known.
### Task lifecycle (minimum)
`PENDING | ACTIVE | WAITING | COMPLETED | CANCELLED | FAILED`
Task has `revision`, `justification_ref`, optional `wake_condition_ref`, owner and completion evidence. `WAITING` must say what it waits for or be explicitly dormant at higher level.
### Action lifecycle
`PROPOSED → VALIDATED → AUTHORIZED/REJECTED → EXECUTING → SUCCEEDED | FAILED | UNKNOWN_OUTCOME | COMPENSATED`.
Retry preserves ActionIntent identity and creates a new attempt identity. `UNKNOWN_OUTCOME` blocks blind retry when duplicate effect is possible.
### Commitment lifecycle
`ACTIVE | WAITING | AT_RISK | FULFILLED | RENEGOTIATED | REVOKED | EXPIRED`.
Future promise is not fulfilled by notification delivery alone unless the promise itself was only to notify.
### Prospective item lifecycle
`REGISTERED | ARMED | TRIGGERED | REVALIDATING | DELIVERED/STARTED | SATISFIED | SUPPRESSED | EXPIRED`.
Trigger firing does not bypass relevance/authority revalidation.
## 3.6 Temporal model
Foundation must support distinguishing, where applicable:
- event/occurrence time;
- observed time;
- recorded time;
- validity interval;
- local-time intention vs absolute instant;
- relative schedule relation (`after Event X + duration`) vs prematurely flattened timestamp.
Do not put four timestamps on every row blindly. Use common temporal value objects/contracts only where semantics require them.
## 3.7 Strong identifiers
Go Core should use distinct types for at least: `IdentityID`, `ActorID`, `PrincipalID`, `ScopeID`, `SituationID`, `GoalID`, `TaskID`, `CommitmentID`, `ActionIntentID`, `ActionAttemptID`, `ArtifactID`, `CapabilityID`, plus revision types. They serialize to language-neutral primitives.
## 3.8 Ownership baseline
| Semantic area | Canonical owner V1 | Notes |
|---|---|---|
| Identity/Actor/Principal bindings | Identity module | Other modules reference IDs/projections only. |
| Scope/Authority grants | Authority module | Commit queries current validation; no hidden default authority. |
| Situation/focus bindings | Situation module | Derived/ephemeral portions may use cache, but durable bindings/provenance explicitly classified. |
| Goal/Task/Decision | Work module | Can later split; V1 owner chosen to preserve local consistency. |
| Commitment/Prospective items | Continuity module | Temporal is execution engine adapter, not owner. |
| Observations/Claims/Beliefs/Provenance | Epistemics module | Search/vector indexes derived. |
| Action commit state | Commit module | External executor isolated. |
| Artifact metadata/lineage | Artifact module or platform-owned artifact service | Payload storage replaceable. |
| Capability registry/bindings | Capability module | Provider-specific adapters outside semantic owner. |
## 3.9 Consistency baseline
- Authority validation and Action authorization: strong owner-local consistency + revision preconditions.
- Task state transitions: owner-local optimistic revision/CAS.
- Cross-owner projections: eventual/rebuildable unless an explicit use case requires stronger semantics.
- UI aggregate views: derived projections; no cross-owner canonical joins.
- Integration reactions: owner-local commit + transactional outbox; consumers idempotent.
- No global total event order requirement; causal/aggregate ordering only where needed.