assembly-economics/concepts/NetworkObjectModel.md

<!--
Created 2026-10-12 under ASSEMBLY-WP-0002-T08, as proposed in
AdaptiveInformationProcessingNetworkConcept.md § 53.
Sources: AdaptiveInformationProcessingNetworkConcept.md §§ 4–18, 21, 34,
39–42; MembraneModel.md Part I §§ 8, 9, 11, 17, 18.
-->

# Network Object Model

**Status:** v0.1, exploratory. Part of the information-organism lens (INTENT.md, Two Lenses).

## 1. Purpose

This document turns the entities of the AIPN concept into a precise object
model: what objects exist, which fields they carry, how they relate, and which
invariants hold between them.

It stays **implementation-neutral**, as the AIPN concept § 52 requires. It does
not choose a storage engine, graph database, programming language, message
protocol or numeric representation. Field types are conceptual (`identifier`,
`vector`, `time`, `reference`), not machine types.

Normative keywords (MUST, SHOULD, MAY) carry over from the source concepts.

---

## 2. Notation

```text
ObjectName
  field: ConceptualType            meaning
  field: [ConceptualType]          zero or more
  field?: ConceptualType           optional
```

`ref(X)` is a reference to an object of kind X by identity.
`vector<D>` is a multi-dimensional value whose dimensions are named in D.

---

## 3. Common envelope

Every object in the network carries the same envelope. It implements the
provenance (§ 41), uncertainty (§ 42), governance envelope (Membrane § 9) and
historical state (Membrane § 11) requirements once, instead of per object.

```text
Envelope
  id: identifier                   stable identity, independent of activation state
  kind: ObjectKind
  provenance: [ref(Evidence)]      why this object exists or has its current state
  governance: GovernanceEnvelope
  valid_time: interval             when the represented fact holds in the world
  record_time: interval            when the network believed it (bi-temporal)
  confidence?: number              absent = not assessed, which differs from 0
  learnable: LearnabilityMode      see § 7
```

```text
GovernanceEnvelope
  classification: label            e.g. public, internal, confidential
  tenant?: identifier
  owner?: identifier
  purpose: [label]                 permitted purposes of processing
  retention?: policy-reference
  allowed_processing: [label]
  inherited_from: [ref(Envelope)]  derived knowledge inherits restrictions
```

**Invariant E1.** A derived object's `governance` is at least as restrictive
as the union of the envelopes it was derived from, unless an `Authority`
explicitly relaxed it (§ 7).

**Invariant E2.** Unknown is representable. A missing `confidence` or a value
in the `unknown` state MUST NOT be read as zero or false.

---

## 4. Structure objects

### 4.1 Node

```text
Node : Envelope
  semantic_kind: NodeKind          EntityType | State | Role | Capability | Process |
                                   Resource | Context | Goal | Risk | Observer |
                                   Policy | Concept | Chunk
  label: text
  state: NodeState
```

```text
NodeState
  activation: ActivationState
  statistics: vector<frequency, recency, ...>
  predictors: [ref(PredictionModel)]
  utility_estimates: vector<goal dimensions>
```

### 4.2 Edge

```text
Edge : Envelope
  source: ref(Node)
  target: ref(Node)
  relation: RelationType           is-a | part-of | uses | requires | precedes |
                                   associated-with | predicts | enables | inhibits |
                                   routes-to | observed-by | contributes-to | ...
  context?: [ref(Context)]         A + Context X → B is a different edge from A → B
  properties: EdgeProperties
  activation: ActivationState
```

```text
EdgeProperties                     (AIPN § 21: four independent properties)
  association: number              co-occurrence strength
  prediction: number               transition / conditional probability
  utility: vector<goal dimensions> e.g. correctness, latency, cost
  confidence: number               evidence-weighted trust in the above
```

**Invariant S1.** `association`, `prediction`, `utility` and `confidence` MUST
be stored and updated independently. No operation may collapse them into one
scalar.

### 4.3 Chunk

```text
Chunk : Node                       semantic_kind = Chunk
  members: [ref(Node | Edge | Chunk)]
  pattern: PatternDescription      sequence, subgraph, recurring context, workflow, ...
  formation: ref(Episode)          episodes that justified formation
```

A Chunk is a Node and can be activated, linked and chunked again (hierarchy).
Across lenses, a chunk is an *assembly at organism scale* (Glossary).

### 4.4 Context

```text
Context : Node                     semantic_kind = Context
  condition: ConditionDescription
```

---

## 5. Activity objects

### 5.1 Token

```text
Token : Envelope
  source_binding?: ref(SourceBinding)   absent for internally generated tokens
  external_ref?: identifier             identity in the system of record
  persistence: transient | persistent | external | reconstructed
  activates: [ref(Node)]                one token may activate many nodes
```

### 5.2 ActivationState

Activation is *state*, not an object with its own identity.

```text
ActivationState
  level: number
  sources: [ActivationSource]      token | neighbor | goal | context | prediction |
                                   surprise | attention | regulation | memory
  decay: DecayRule                 activation decays unless sustained
  as_of: time
```

### 5.3 Episode

```text
Episode : Envelope
  inputs: [ref(Token)]
  context: [ref(Context)]
  activations: [ActivationRecord]  node or edge, level, time
  predictions: [ref(Prediction)]
  actions: [ref(Action)]
  observations: [ref(Claim)]
  signals: [ref(Signal)]
  boundary: interval
```

Episodes are the unit of learning, replay, explanation, attribution and audit.

### 5.4 Prediction

```text
Prediction : Envelope
  made_in: ref(Episode)
  subject: ref(Node | Token | Context)
  expectation: ExpectationDescription   occurrence OR absence
  horizon: interval
  resolution?: ref(Claim)               the observation that confirmed or refuted it
  error?: vector<dimensions>
```

### 5.5 Action

```text
Action : Envelope
  kind: ref(Node)                  e.g. RouteToHumanReview, Escalate
  target?: ref(Token | SourceBinding)
  state: ActionState
  state_history: [(ActionState, time, ref(Authority)?)]
  caused_by: ref(Episode)
```

```text
ActionState = possible | permitted | recommended | selected | executed | mandatory
```

**Invariant A1.** These states MUST NOT be treated as equivalent. A
transition into `permitted` or `mandatory` MUST name an `Authority`; the
network may not grant these states to itself.

**Invariant A2.** "Something happened" (a Claim) and "the network caused
something to happen" (an executed Action) are distinct objects.

### 5.6 EligibilityTrace

```text
EligibilityTrace
  subject: ref(Node | Edge | Prediction | Action)
  episode: ref(Episode)
  strength: number
  decay: DecayRule
```

Like ActivationState, a trace is temporary state used for delayed credit
assignment, not a durable object.

---

## 6. Evaluation objects

### 6.1 Observer

```text
Observer : Node                    semantic_kind = Observer
  observes: [ref(Node | Goal | ViabilityVariable)]
  method: EvaluationDescription
  operator?: human | artificial | institutional
```

Multiple observers MAY evaluate the same episode differently. Their signals
are kept side by side, not averaged at the source.

### 6.2 Signal

```text
Signal : Envelope
  emitted_by: ref(Observer)
  about: ref(Episode)
  kind: success | failure | reward | penalty | prediction-error | novelty |
        surprise | constraint-violation | human-feedback | viability-deviation
  value: vector<dimensions>        multi-dimensional by default
```

**Invariant V1.** A signal's `value` MUST stay multi-dimensional through
storage. Any aggregation is a separate, explicit step that records its
weights.

### 6.3 Goal

```text
Goal : Node                        semantic_kind = Goal
  tendency: GoalDescription        desired condition, outcome or constraint
  source: ref(Authority)           goals are received from the environment
  priority?: number
  conflicts: [ref(Goal)]           conflicts stay visible, never silently flattened
```

### 6.4 ViabilityVariable

```text
ViabilityVariable : Node
  measure: ref(Node | SourceBinding)
  corridor: range                  acceptable operating range
  floor_kind: corridor | constitutional
  current: value
```

`constitutional` corridors are non-tradeable floors. They correspond to GADM's
constitutional constraints (Glossary, "Viability").

**Invariant V2.** Viability precedes optimization. No utility gain may justify
an action that is predicted to push a `constitutional` variable out of its
corridor.

---

## 7. Governance objects

### 7.1 Authority

```text
Authority : Envelope
  holder: human | institution | delegated-role
  scope: [label]                   what it may permit, mandate, relax or make learnable
  granted_by?: ref(Authority)
```

### 7.2 Learnability

```text
LearnabilityMode = learnable | learnable-with-authority | frozen
```

**Invariant G1.** The learning operation `L` (§ 9) MUST NOT modify an object
whose mode is `frozen`. It may modify a `learnable-with-authority` object only
when a referenced Authority covers that scope (AIPN § 39: learning and
authority are distinct).

---

## 8. Membrane objects

### 8.1 SourceBinding

```text
SourceBinding : Envelope
  semantic_entity: ref(Node)
  source_system: identifier
  source_type: label
  identity_mapping: MappingDescription
  projection_rule: ProjectionDescription   read model, not a replica
  access_policy: PolicyReference
  freshness_policy: PolicyReference
  write_capabilities: [label]              what actions may write back, if anything
  membrane_layer: constitutional | operational | adaptive | ephemeral
```

### 8.2 Claim

```text
Claim : Envelope
  subject: ref(Token | Node)
  predicate: label
  object: value | ref(Token | Node)
  source: ref(SourceBinding | Observer)
  authority?: ref(Authority)
  observed_time: time
```

Claims allow contradictions: two claims with the same subject and predicate
and different objects can coexist without corrupting the model.

### 8.3 Evidence

```text
Evidence : Envelope
  supports: [ref(Claim | Node | Edge | Chunk)]
  origin: ref(SourceBinding | Episode | Observer)
  locator: identifier              pointer into the source; the artefact stays at its source
```

**Invariant M1.** Every semantic assertion entering through the membrane is a
Claim backed by Evidence. Learning MUST NOT remove provenance.

---

## 9. Operations

The formal model of AIPN § 34 is \(N=(V,E,T,G,O,H)\). The objects map onto it
as follows:

| Formal | Objects |
|---|---|
| \(V\) nodes | Node, Chunk, Context, Goal, Observer, ViabilityVariable |
| \(E\) edges | Edge (with EdgeProperties) |
| \(T\) tokens | Token |
| \(G\) goals | Goal, ViabilityVariable |
| \(O\) observers | Observer |
| \(H\) history | Episode, Prediction, Action, Signal, Claim, Evidence (bi-temporal) |

The two operations:

```text
evaluate:  O(τ, G) → [Signal]          observers evaluate an episode against goals
learn:     L(N, τ, [Signal]) → N'      the network changes, subject to G1, M1, S1, V1
```

`learn` covers the four core learning modes (associative, predictive,
instrumental, structural) and optionally regulatory learning. Structural
learning creates or removes Edges and Chunks. Every structural change produces
Evidence that references the Episodes justifying it.

---

## 10. Worked example: invoice processing

```text
Token        inv-4711      (SourceBinding: SAP AccountingDocument)
  activates  Invoice, SupplierInvoice, HighValueTransaction, Supplier:Acme, MonthEnd
Edge         Invoice --routes-to--> HumanReview   context: [MonthEnd]
  properties association 0.42, prediction 0.18, utility {correctness .94, latency .31, cost .22}, confidence .91
Prediction   "approval within 2 days"   horizon 2d
Action       RouteToHumanReview   state: recommended → selected → executed
  permitted by Authority: AP-Policy-2026
Claim        inv-4711 approved-at 2026-10-03   source: SAP binding
Signal       Observer:LatencyObserver → {latency: -0.4, correctness: +0.9}
learn        edge confidence and utility updated; Evidence → episode ep-1182
```

---

## 11. Extension points

The following belong to other organism-lens concepts and are left as named
extension points, so this model can grow without reshaping its core:

| Extension | From | Expected objects |
|---|---|---|
| Membrane layers and sampling | MembraneModel.md | Membrane, SamplingPolicy, Habituation |
| Development | SeedKernel.md | Kernel, DevelopmentalStage |
| Evolution | EvolutionModel.md | Genotype, Phenotype, Lineage, FitnessAssessment |
| Metabolism | MetabolismModel.md | MetabolicBudget, SubstrateFlow, ResourceAccount |
| Resource ontology | ResourceOntology.md | ResourceClass, ConversionFunction, SentientBoundary |

## 12. Open questions

1. Should Activation be modeled as an event stream (replayable) or only as
   current state plus Episode records?
2. Is `Context` best treated as a Node kind or as an edge qualifier only?
3. What is the minimum bi-temporal guarantee: full valid-time history, or
   only record-time for audit?
4. How should a Signal's dimensions be governed, so that observers stay
   comparable without forcing a fixed schema?