165 lines
8.2 KiB
Markdown
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.
|