Skip to content

Commit 6b90d56

Browse files
mdhellermdheller
authored
Add learning representation envelope to agent proposals
Extends AgentLearningProposal with optional observation, representation, signal, and review-queue metadata while preserving review-only governed memory writeback. Adds documentation for the learning representation envelope and updates the canonical example proposal. Validation: validate-locks, python-validation, agent-learning-proposal, validate-runtime, test-finance-source-of-truth, deploy-assets-validation all passed on PR #28.
1 parent 593521a commit 6b90d56

3 files changed

Lines changed: 301 additions & 0 deletions

File tree

‎docs/architecture/learning-representation-envelope.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Learning representation envelope v0.1
2+
3+
## Status
4+
5+
Draft implementation slice for `memory-mesh#22`.
6+
7+
This document folds the communications-systems-derived learning representation doctrine into the existing governed memory proposal channel. It does not create a second durable-memory architecture. `AgentLearningProposal` remains the review-only ingress surface for agent-discovered operational learning.
8+
9+
## Placement
10+
11+
Memory Mesh owns durable memory proposal, review, promotion, writeback, revocation, and playbook reconciliation.
12+
13+
Ontogenesis owns the semantic vocabulary for claims, assertions, evidence, SHIR context, projection, and projection-loss reporting.
14+
15+
AgentPlane owns guarded execution, run evidence, stop-gate artifacts, typed traces, and detector/evaluator receipts.
16+
17+
Sociosphere owns queueing, topology, scheduler state, coherence barriers, and cross-repo orchestration.
18+
19+
Sherlock owns discovery/index packets and must not become the memory source of truth.
20+
21+
## Communications-system mapping
22+
23+
The MIT communications stack gives six constraints for governed learning memory:
24+
25+
1. Sampling: learning proposals must identify the bounded observation window and freshness posture behind the learning.
26+
2. Framing: a learning must be a typed frame with source session, destination, evidence, policy, review, redaction, and writeback state.
27+
3. Compression: summaries and playbook diffs are allowed only when they preserve evidence, provenance, authority, unresolved conflicts, and retention.
28+
4. Detection: detector-derived learnings must expose their signal class, noise assumption, confidence, and abstention boundary.
29+
5. Error/provenance: schema validity, checksum validity, semantic truth, and policy approval are separate states.
30+
6. Queueing: review/promotion should be measurable as a queue, including arrival, blocked reason, staleness, and promotion latency.
31+
32+
## Extension fields
33+
34+
The first implementation slice extends `AgentLearningProposal` with optional contract fields. They are optional for backward compatibility but should be populated by new producers.
35+
36+
### `observationContext`
37+
38+
Captures the sampling and compression basis behind a proposed learning.
39+
40+
Required when present:
41+
42+
- `observedAt`
43+
- `validTime`
44+
- `freshnessPolicy`
45+
- `samplingBasis`
46+
- `compressionBasis`
47+
48+
The field prevents unbounded transcript residue from being promoted as durable memory. It requires the producer to say what was observed and what was compressed.
49+
50+
### `representationEnvelope`
51+
52+
Captures frame, authority, cache/coherence, evidence, provenance, policy, and write policy.
53+
54+
Required when present:
55+
56+
- `frameType`
57+
- `authoritySource`
58+
- `sourceEpoch`
59+
- `validityWindow`
60+
- `cacheState`
61+
- `dirtyState`
62+
- `revocationStatus`
63+
- `correlationId`
64+
- `evidenceRefs`
65+
- `provenanceRefs`
66+
- `policyContext`
67+
- `writePolicy`
68+
69+
The cache/coherence vocabulary aligns with Sociosphere's scheduler/coherence lane. Memory Mesh records it as metadata; it does not become the global scheduler.
70+
71+
### `learningSignal`
72+
73+
Captures the signal/detector context when a proposed learning comes from an agent observation, detector, ranker, evaluator, or mixed process.
74+
75+
Required when present:
76+
77+
- `signalClass`
78+
- `noiseAssumption`
79+
- `confidence`
80+
- `abstentionBoundary`
81+
82+
This prevents a model or agent from hiding a detector assumption behind prose.
83+
84+
### `reviewQueue`
85+
86+
Captures queue metadata for proposal review and promotion.
87+
88+
Required when present:
89+
90+
- `proposalArrivedAt`
91+
- `reviewRequiredBy`
92+
- `blockedReason`
93+
- `staleAfter`
94+
95+
The purpose is observability. Review queue metrics should flow to DeliveryExcellence/Sociosphere rather than becoming local-only comments.
96+
97+
## Invariants
98+
99+
- No raw sensitive payload is stored by default.
100+
- No durable writeback occurs in `review_only` mode.
101+
- No accepted memory exists without evidence refs.
102+
- No cross-repo or global memory promotion occurs without policy decision refs.
103+
- No detector-derived learning is actionable without signal/noise assumptions.
104+
- No compressed playbook update may erase provenance or conflicts.
105+
- No rejected, revoked, superseded, or stale learning may remain silently active.
106+
107+
## First validation slice
108+
109+
This tranche updates:
110+
111+
- `schemas/agent-learning-proposal.schema.json`
112+
- `examples/agent-learning/proposal.example.json`
113+
114+
Existing validation remains:
115+
116+
```bash
117+
python -m pip install jsonschema
118+
make validate-agent-learning-proposal
119+
```
120+
121+
## Future slices
122+
123+
1. Add companion accepted-memory and revoked-memory examples.
124+
2. Add conflict/supersession examples for duplicate or contradictory playbook learnings.
125+
3. Emit derived queue metrics for pending proposal age, blocked reason, stale count, promotion latency, and rejection rate.
126+
4. Align Ontogenesis terms to SHIR `Assertion`, `Evidence`, `Receipt`, `Context`, and `ProjectionLossReport`.
127+
5. Align Sociosphere representation envelope fields with scheduler/coherence schemas.

‎examples/agent-learning/proposal.example.json‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,70 @@
3232
"confidence": 0.91,
3333
"retention": "repo-durable"
3434
},
35+
"observationContext": {
36+
"sourceWindowRef": "urn:srcos:source-window:agent-learning-example",
37+
"observedAt": "2026-05-06T00:00:00Z",
38+
"validTime": {
39+
"start": "2026-05-06T00:00:00Z",
40+
"end": null
41+
},
42+
"freshnessPolicy": {
43+
"staleAfter": null,
44+
"expiryRef": null
45+
},
46+
"samplingBasis": "Derived from bounded AgentPlane stop-gate evidence artifacts, not from raw transcript scraping.",
47+
"compressionBasis": "Condenses repeated stop-gate failure observations into one repo-local playbook update while preserving source artifacts and policy refs."
48+
},
49+
"representationEnvelope": {
50+
"frameType": "proposal",
51+
"authoritySource": "SocioProphet/agentplane",
52+
"sourceEpoch": "agent-learning-example-epoch-0001",
53+
"validityWindow": {
54+
"start": "2026-05-06T00:00:00Z",
55+
"end": null
56+
},
57+
"cacheState": "pending_review",
58+
"dirtyState": "dirty",
59+
"revocationStatus": "active",
60+
"correlationId": "urn:srcos:correlation:agent-learning-example",
61+
"evidenceRefs": [
62+
"urn:srcos:artifact:stop-gate:example",
63+
"urn:srcos:artifact:guarded-invocation:example"
64+
],
65+
"provenanceRefs": [
66+
"urn:srcos:artifact:guarded-workcell:example"
67+
],
68+
"policyContext": {
69+
"policyDecisionRefs": [
70+
"sourceos/core/baseline-allow",
71+
"agentplane/stop-gate/branch-pushed"
72+
],
73+
"capabilityRefs": [
74+
"agentplane:guarded-command-invocation"
75+
]
76+
},
77+
"writePolicy": {
78+
"mode": "no-writeback",
79+
"reviewRequired": true
80+
}
81+
},
82+
"learningSignal": {
83+
"signalClass": "agent-observed",
84+
"noiseAssumption": "A missing upstream branch is treated as stop-gate evidence failure, not as successful completion noise.",
85+
"confidence": 0.91,
86+
"abstentionBoundary": "If branch push was intentionally prohibited by policy, the proposal must remain pending until the relevant break-glass or exception receipt is attached.",
87+
"detectorRef": "agentplane/stop-gate/branch-pushed",
88+
"evaluationReceiptRefs": [
89+
"urn:srcos:artifact:stop-gate:example"
90+
]
91+
},
92+
"reviewQueue": {
93+
"proposalArrivedAt": "2026-05-06T00:00:00Z",
94+
"reviewRequiredBy": null,
95+
"blockedReason": "pending-human-review",
96+
"staleAfter": null,
97+
"promotionLatency": null
98+
},
3599
"review": {
36100
"required": true,
37101
"status": "pending",

‎schemas/agent-learning-proposal.schema.json‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,116 @@
7171
},
7272
"additionalProperties": false
7373
},
74+
"observationContext": {
75+
"type": "object",
76+
"required": ["observedAt", "validTime", "freshnessPolicy", "samplingBasis", "compressionBasis"],
77+
"properties": {
78+
"sourceWindowRef": { "type": ["string", "null"] },
79+
"observedAt": { "type": "string", "format": "date-time" },
80+
"validTime": {
81+
"type": "object",
82+
"required": ["start", "end"],
83+
"properties": {
84+
"start": { "type": ["string", "null"], "format": "date-time" },
85+
"end": { "type": ["string", "null"], "format": "date-time" }
86+
},
87+
"additionalProperties": false
88+
},
89+
"freshnessPolicy": {
90+
"type": "object",
91+
"required": ["staleAfter", "expiryRef"],
92+
"properties": {
93+
"staleAfter": { "type": ["string", "null"], "format": "date-time" },
94+
"expiryRef": { "type": ["string", "null"] }
95+
},
96+
"additionalProperties": false
97+
},
98+
"samplingBasis": { "type": "string", "minLength": 1 },
99+
"compressionBasis": { "type": "string", "minLength": 1 }
100+
},
101+
"additionalProperties": false
102+
},
103+
"representationEnvelope": {
104+
"type": "object",
105+
"required": [
106+
"frameType",
107+
"authoritySource",
108+
"sourceEpoch",
109+
"validityWindow",
110+
"cacheState",
111+
"dirtyState",
112+
"revocationStatus",
113+
"correlationId",
114+
"evidenceRefs",
115+
"provenanceRefs",
116+
"policyContext",
117+
"writePolicy"
118+
],
119+
"properties": {
120+
"frameType": { "enum": ["observation", "proposal", "accepted-memory", "playbook-update", "policy-note", "evidence-receipt"] },
121+
"authoritySource": { "type": "string", "minLength": 1 },
122+
"sourceEpoch": { "type": "string", "minLength": 1 },
123+
"validityWindow": {
124+
"type": "object",
125+
"required": ["start", "end"],
126+
"properties": {
127+
"start": { "type": ["string", "null"], "format": "date-time" },
128+
"end": { "type": ["string", "null"], "format": "date-time" }
129+
},
130+
"additionalProperties": false
131+
},
132+
"cacheState": { "enum": ["invalid", "shared_valid", "exclusive_authoritative", "modified_uncommitted", "stale", "revoked", "pending_review", "promoted"] },
133+
"dirtyState": { "enum": ["clean", "dirty", "unknown"] },
134+
"revocationStatus": { "enum": ["active", "revoked", "superseded", "unknown"] },
135+
"correlationId": { "type": "string", "minLength": 1 },
136+
"evidenceRefs": { "type": "array", "minItems": 1, "items": { "type": "string" } },
137+
"provenanceRefs": { "type": "array", "items": { "type": "string" } },
138+
"policyContext": {
139+
"type": "object",
140+
"required": ["policyDecisionRefs", "capabilityRefs"],
141+
"properties": {
142+
"policyDecisionRefs": { "type": "array", "items": { "type": "string" } },
143+
"capabilityRefs": { "type": "array", "items": { "type": "string" } }
144+
},
145+
"additionalProperties": false
146+
},
147+
"writePolicy": {
148+
"type": "object",
149+
"required": ["mode", "reviewRequired"],
150+
"properties": {
151+
"mode": { "enum": ["no-writeback", "reviewed-writeback", "approved-writeback"] },
152+
"reviewRequired": { "type": "boolean" }
153+
},
154+
"additionalProperties": false
155+
}
156+
},
157+
"additionalProperties": false
158+
},
159+
"learningSignal": {
160+
"type": "object",
161+
"required": ["signalClass", "noiseAssumption", "confidence", "abstentionBoundary"],
162+
"properties": {
163+
"signalClass": { "enum": ["human-observed", "agent-observed", "detector-derived", "ranker-derived", "evaluator-derived", "mixed"] },
164+
"noiseAssumption": { "type": "string", "minLength": 1 },
165+
"confidence": { "type": "number", "minimum": 0, "maximum": 1 },
166+
"abstentionBoundary": { "type": "string", "minLength": 1 },
167+
"detectorRef": { "type": ["string", "null"] },
168+
"evaluationReceiptRefs": { "type": "array", "items": { "type": "string" } }
169+
},
170+
"additionalProperties": false
171+
},
172+
"reviewQueue": {
173+
"type": "object",
174+
"required": ["proposalArrivedAt", "reviewRequiredBy", "blockedReason", "staleAfter"],
175+
"properties": {
176+
"proposalArrivedAt": { "type": "string", "format": "date-time" },
177+
"reviewRequiredBy": { "type": ["string", "null"], "format": "date-time" },
178+
"blockedReason": { "type": ["string", "null"] },
179+
"staleAfter": { "type": ["string", "null"], "format": "date-time" },
180+
"promotionLatency": { "type": ["string", "null"] }
181+
},
182+
"additionalProperties": false
183+
},
74184
"review": {
75185
"type": "object",
76186
"required": ["required", "status", "reviewerRefs", "approvalRef"],

0 commit comments

Comments
 (0)