254 lines
4.7 KiB
Markdown
254 lines
4.7 KiB
Markdown
# Primitive Ops vs Pluggable Ops
|
||
|
||
This section defines the execution boundary between deterministic kernel semantics and extensible domain execution.
|
||
|
||
It preserves:
|
||
|
||
* Kernel determinism
|
||
* Store-neutral traceability
|
||
* Backend substitutability
|
||
* Observational equivalence
|
||
|
||
---
|
||
|
||
# 1. Terminology
|
||
|
||
## 1.1 Kernel / Primitive Op
|
||
|
||
A **Kernel Op** (Primitive Op) is an operation defined in:
|
||
|
||
`OPREG/PEL1-KERNEL`
|
||
|
||
It is part of the `PEL/1-CORE` contract.
|
||
|
||
Kernel ops define fixed, deterministic semantics and are considered part of Amduat’s invariant semantic core.
|
||
|
||
---
|
||
|
||
## 1.2 Pluggable Op
|
||
|
||
A **Pluggable Op** is an operation defined outside `OPREG/PEL1-KERNEL`.
|
||
|
||
It is not part of `PEL/1-CORE`.
|
||
|
||
Its execution semantics:
|
||
|
||
* Are versioned independently
|
||
* May be effectful
|
||
* Are governed by profile or deployment policy
|
||
* Must emit execution artifacts for traceability
|
||
|
||
Pluggable ops extend behavior without extending the kernel.
|
||
|
||
---
|
||
|
||
# 2. Kernel / Primitive Ops
|
||
|
||
## 2.1 Properties
|
||
|
||
Kernel ops:
|
||
|
||
* Are defined in `OPREG/PEL1-KERNEL`
|
||
* Are pure and deterministic
|
||
* Have no side effects
|
||
* Depend only on explicit inputs
|
||
* Produce canonical artifacts
|
||
* Have stable semantics governed by spec revision
|
||
|
||
Kernel ops are portable across all backend tiers.
|
||
|
||
They cannot:
|
||
|
||
* Access external systems
|
||
* Read hidden state
|
||
* Depend on environmental configuration
|
||
* Produce nondeterministic outputs
|
||
|
||
---
|
||
|
||
## 2.2 Examples
|
||
|
||
* `bytes.concat`
|
||
* `bytes.slice`
|
||
* `hash.asl1_256`
|
||
|
||
These operations:
|
||
|
||
* Operate solely on canonical encoded inputs
|
||
* Produce deterministic outputs
|
||
* Are observationally equivalent across implementations
|
||
|
||
---
|
||
|
||
# 3. Pluggable Ops
|
||
|
||
Pluggable ops enable domain-specific execution without extending the kernel.
|
||
|
||
They may:
|
||
|
||
* Invoke LLMs
|
||
* Execute SSH commands
|
||
* Configure infrastructure
|
||
* Perform device operations
|
||
* Call external APIs
|
||
|
||
They are not part of the core semantic contract.
|
||
|
||
---
|
||
|
||
## 3.1 Properties
|
||
|
||
Pluggable ops:
|
||
|
||
* Are defined in external registries
|
||
* May be effectful
|
||
* May interact with external systems
|
||
* May be nondeterministic
|
||
* Must produce execution artifacts
|
||
* Must remain observationally separable from kernel semantics
|
||
|
||
They extend behavior while preserving traceability.
|
||
|
||
---
|
||
|
||
# 4. Execution Artifact Model
|
||
|
||
Every pluggable op MUST emit execution artifacts to ASL.
|
||
|
||
These artifacts preserve determinism at the semantic layer, even if the effect itself is nondeterministic.
|
||
|
||
## 4.1 Required Artifacts
|
||
|
||
At minimum:
|
||
|
||
### 1. ExecutionIntent
|
||
|
||
Declares:
|
||
|
||
* Target
|
||
* Parameters
|
||
* Configuration
|
||
* Version of pluggable op
|
||
|
||
Represents the desired action.
|
||
|
||
---
|
||
|
||
### 2. ExecutionReceipt
|
||
|
||
Confirms:
|
||
|
||
* Action dispatch
|
||
* Acceptance by executor
|
||
* Execution attempt metadata
|
||
|
||
Represents the attempt.
|
||
|
||
---
|
||
|
||
### 3. ExecutionOutput
|
||
|
||
Captures:
|
||
|
||
* Stdout/stderr
|
||
* Returned data
|
||
* Produced artifacts
|
||
* Exit codes
|
||
|
||
Represents the immediate result.
|
||
|
||
---
|
||
|
||
### 4. ExecutionObservation (Recommended)
|
||
|
||
Captures:
|
||
|
||
* Observed external state
|
||
* Post-condition checks
|
||
* Environment validation
|
||
|
||
Represents the verified outcome.
|
||
|
||
---
|
||
|
||
All execution artifacts:
|
||
|
||
* Are canonical ASL artifacts
|
||
* Are immutable
|
||
* Derive identity via `ENC/ASL1-CORE` + `ASL/1-CORE` + `HASH/ASL1`
|
||
* Participate in TGK projection
|
||
|
||
---
|
||
|
||
# 5. Traceability Requirements
|
||
|
||
All pluggable ops MUST be traceable in TGK by linking:
|
||
|
||
* `ExecutionIntent → ExecutionReceipt`
|
||
* `ExecutionReceipt → ExecutionOutput`
|
||
* Optional: `ExecutionOutput → ExecutionObservation`
|
||
|
||
These links are created via EdgeArtifacts written to ASL.
|
||
|
||
This ensures:
|
||
|
||
* Deterministic graph projection
|
||
* Provenance recoverability
|
||
* Replay safety
|
||
* Auditability
|
||
|
||
Even if external execution is nondeterministic, the trace is deterministic.
|
||
|
||
---
|
||
|
||
# 6. Governance Boundary
|
||
|
||
The boundary between kernel and pluggable ops is strict.
|
||
|
||
## 6.1 Kernel
|
||
|
||
* Small
|
||
* Deterministic
|
||
* Slow-moving
|
||
* Versioned with PEL core
|
||
* Subject to formal governance
|
||
|
||
## 6.2 Pluggable
|
||
|
||
* Extensible
|
||
* Fast-moving
|
||
* Policy-scoped
|
||
* Profile-scoped
|
||
* May be deployment-specific
|
||
|
||
No pluggable op may redefine kernel semantics.
|
||
|
||
---
|
||
|
||
# 7. Interaction with Backend Plug-in Model
|
||
|
||
This execution model aligns with the No Semantic Drift Rule:
|
||
|
||
* Kernel ops are invariant across all backends.
|
||
* Pluggable ops must emit artifacts.
|
||
* Backends must treat execution artifacts as ordinary ASL artifacts.
|
||
* TGK projection must remain deterministic.
|
||
|
||
Backend-specific optimizations must remain observationally equivalent to the artifact graph defined by execution artifacts.
|
||
|
||
---
|
||
|
||
# 8. Design Outcome
|
||
|
||
This separation:
|
||
|
||
* Preserves deterministic core semantics
|
||
* Enables real-world execution
|
||
* Prevents semantic leakage into infrastructure
|
||
* Maintains backend substitutability
|
||
* Ensures enterprise-grade auditability
|
||
* Supports edge and embedded deployments
|
||
|
||
Primitive ops define what Amduat *is*.
|
||
Pluggable ops define what Amduat *does*.
|