memex: update AGENTS.md, add passepartout design-decisions notes, SWOT + agora notes, bump submodules → v0.8.1
This commit is contained in:
314
notes/passepartout-agora.org
Normal file
314
notes/passepartout-agora.org
Normal file
@@ -0,0 +1,314 @@
|
||||
#+TITLE: Passepartout-Agora Integration — Unified Container Format
|
||||
#+AUTHOR: Agent
|
||||
#+FILETAGS: :notes:integration:agora:passepartout:design:
|
||||
#+CREATED: [2026-05-08 Fri]
|
||||
|
||||
* Summary
|
||||
|
||||
Org files and Agora Notes are the same container. Both are text with headers,
|
||||
tags, properties, and prose body. Both contain zero or more symbolic facts
|
||||
extractable by Passepartout's archivist. The only difference is that an Agora
|
||||
Note carries a DID signature and a CID for cryptographic provenance on the
|
||||
network. An Org file without a signature is a local Note. A signed Org file
|
||||
pushed to the PDS is an Agora Note.
|
||||
|
||||
Passepartout's =memory-object= struct serves as the storage format for both.
|
||||
The archivist extracts facts from one unified store. Authorship is distinguished
|
||||
by provenance, not location.
|
||||
|
||||
* The Unification
|
||||
|
||||
** Org files and Notes are the same container
|
||||
|
||||
| Property | Org file (local) | Agora Note (network) |
|
||||
|------------------+------------------------------+-------------------------------------|
|
||||
| Format | Org-mode text | Org-mode text |
|
||||
| Identity | Merkle hash (=memory-object=) | CIDv1 (same hash) |
|
||||
| Contains facts | Yes (archivist extracts) | Yes (archivist extracts) |
|
||||
| Author identity | Implicit (file in =~/memex/=) | Explicit (DID signature in =proof=) |
|
||||
| Access control | Filesystem permissions | =access_control= flags |
|
||||
| Routing | N/A (local disk) | =notify= + =references= + Relay |
|
||||
| Ephemeral | No | =ephemeral_duration= |
|
||||
| Behavioral flag | Implicit (convention) | =is_feed= field |
|
||||
|
||||
The structure converges in a single plist:
|
||||
|
||||
#+begin_src lisp
|
||||
(:cid <merkle-hash> ;; Identity across local and network
|
||||
:title <string> ;; Org headline title
|
||||
:content <org-text> ;; Full Org body (headings, prose, source blocks)
|
||||
:owner <did-or-nil> ;; For Agora Notes: the signing Persona DID. nil for local
|
||||
:proof <plist-or-nil> ;; ( :editor <did> :signature <bytes> )
|
||||
;; Agora behavioral flags (nil for local files)
|
||||
:is-feed <boolean-or-nil>
|
||||
:access-control <did-list-or-nil>
|
||||
:notify <did-list-or-nil>
|
||||
:references <cid-list-or-nil>
|
||||
:reply-to <cid-or-nil>
|
||||
:thread-root <cid-or-nil>
|
||||
:ephemeral-duration <integer-or-nil>
|
||||
;; Passepartout metadata
|
||||
:created-at <timestamp>
|
||||
:tags <string-list> ;; Org tags
|
||||
:properties <plist> ;; Org property drawer
|
||||
:extracted-facts <fact-list>) ;; Populated by archivist after extraction
|
||||
#+end_src
|
||||
|
||||
** Facts are extracted from both, identically
|
||||
|
||||
An Org file in =~/memex/literature/pale-fire.org= and an Agora Note from
|
||||
=did:agora:heather= with =:references <post-CID>= both contain prose. The
|
||||
archivist scans both, proposes triples via the LLM, verifies via Screamer,
|
||||
and admits facts to the symbolic index. The facts carry different provenance:
|
||||
|
||||
#+begin_src lisp
|
||||
;; Extracted from local Org file
|
||||
(:entity :pale-fire :relation :theme :value :unreliable-narration
|
||||
:provenance :local-prose :grounding "heading-42")
|
||||
|
||||
;; Extracted from Agora Note
|
||||
(:entity :kafka :relation :influence :value :nabokov
|
||||
:provenance :agora-note :grounding <incoming-note-cid> :author "did:agora:heather")
|
||||
#+end_src
|
||||
|
||||
No new extraction path. The archivist already walks containers and extracts
|
||||
facts. The container type determines the provenance tag and the grounding
|
||||
identifier (local heading ID vs. Note CID).
|
||||
|
||||
** The memex distinguishes provenance by location, not format
|
||||
|
||||
Incoming Agora Notes arrive at =~/memex/social/notes/<did>/<cid>.org=.
|
||||
The directory structure encodes authorship:
|
||||
|
||||
| Path | Meaning |
|
||||
|---------------------------------------------------+------------------------------------|
|
||||
| ~/memex/daily/ | Local diary entries |
|
||||
| ~/memex/projects/ | Local project files |
|
||||
| ~/memex/literature/ | Local reading notes |
|
||||
| ~/memex/notes/ | Local design and thinking notes |
|
||||
| ~/memex/social/notes/<did>/<cid>.org | Incoming Notes from other DIDs |
|
||||
| ~/memex/social/outbox/<cid>.org | Outgoing Notes signed by the user |
|
||||
|
||||
The archivist scans all directories. Local files produce facts with
|
||||
=:provenance :local-prose=. Agora files produce facts with =:provenance
|
||||
:agora-note= + =:author <did>=. The symbolic index maps the provenance
|
||||
to the cardinality policy: local prose is =:plural= (the human's own notes —
|
||||
multiple interpretations coexist). Agora Notes are =:plural= by default (the
|
||||
author's claim, not authoritative over local facts). Agora Notes can be promoted
|
||||
to =:singular= or =:dual= if they carry cryptographic proofs of specific claims.
|
||||
|
||||
** Publishing Org content as Agora Notes
|
||||
|
||||
When the user wants to publish a diary entry, project log, or literary note as
|
||||
an Agora Note, the operation is:
|
||||
|
||||
1. Select the Org heading or file.
|
||||
2. Compute the Merkle hash (=memory-object= hash → CIDv1).
|
||||
3. Sign with the user's Persona DID key (Phase 0b key registry).
|
||||
4. Set Agora flags: =:is-feed= t/nil, =:access-control= [], =:references= [previous-note-cid].
|
||||
5. Push to the PDS. The Note is an Org plist with a DID signature.
|
||||
6. The PDS stores and relays it. The Note remains in =~/memex/social/outbox/= with its CID.
|
||||
|
||||
All of this is a single function: =(note-publish heading-id &key is-feed access-control references)=.
|
||||
~40 lines, extending the vault (key signing), the fact store (CID generation),
|
||||
and the memex (output directory).
|
||||
|
||||
* Implications for Passepartout's Architecture
|
||||
|
||||
** The symbolic index now has a second ingestion path
|
||||
|
||||
Facts enter through three gates:
|
||||
1. Gate outcomes (bootstrap + runtime, =:provenance :gate-outcome=)
|
||||
2. Screamer deductions (=:provenance :deduced=)
|
||||
3. Archivist extraction (=:provenance :local-prose= or =:provenance :agora-note=)
|
||||
|
||||
The third path now covers both local Org files and incoming Agora Notes. No new
|
||||
path needed. The archivist gains no new code — only a new directory to walk
|
||||
(=~/memex/social/notes/=) and a new provenance tag to assign.
|
||||
|
||||
** Authentication Layer 1 now has Agora-native verification
|
||||
|
||||
Phase 0b's cryptographic gate (vector 0) verifies DID signatures. An incoming
|
||||
Agora Note carries =:owner <did>= and =:proof.signature <bytes>=. Gate vector 0
|
||||
verifies the signature against the DID's public key (from the key registry, which
|
||||
is now also an Agora DID registry). Verification is identical for local signals
|
||||
and Agora signals — the same gate, the same key lookup.
|
||||
|
||||
** Self-preservation gains an Agora dimension
|
||||
|
||||
The resource monitor (Phase 1a) tracks =~/memex/social/= as a source of storage
|
||||
growth. Incoming Notes from network sources are lower preservation priority than
|
||||
local prose — if disk pressure hits, incoming Agora Notes are evicted first
|
||||
(their source is the remote PDS; they can be re-fetched). Quarantine (Phase 1a)
|
||||
extends to Agora channels: if a DID is sending spam or malformed Notes, their
|
||||
incoming directory is quarantined and the DID is flagged for human review.
|
||||
|
||||
** Sufficiency tracks Agora as a provenance source
|
||||
|
||||
The sufficiency score (Phase 4) gains a new provenance category:
|
||||
|
||||
#+begin_example
|
||||
Symbolic Index
|
||||
Facts: 3,847
|
||||
Gate outcomes: 847 (22%)
|
||||
Deduced: 921 (24%)
|
||||
Human-authored: 72 (2%)
|
||||
Local prose: 1,247 (32%)
|
||||
Agora Notes: 760 (20%)
|
||||
─────────────────────────
|
||||
Non-lossy: 1,840 (48%)
|
||||
LLM-proposed: 2,007 (52%)
|
||||
#+end_example
|
||||
|
||||
Agora Notes are a provenance source, not a lossiness category. Facts from Agora
|
||||
Notes carry =:provenance :agora-note= — they are LLM-extracted (the archivist
|
||||
proposes them) but the source is cryptographically signed by a known DID. They
|
||||
are neither =:gate-outcome= (mechanical) nor =:llm-proposed= from local prose
|
||||
(uncertain source). They occupy a middle ground: verified source, uncertain
|
||||
extraction.
|
||||
|
||||
* Implications for Agora
|
||||
|
||||
** Passepartout IS the PDS
|
||||
|
||||
The TODO.org in =projects/agora/= already captures this: "Passepartout IS the
|
||||
PDS — the agent runs a personal data store in-process." With Org files as the
|
||||
Note format, this is literal. The PDS stores Org files. The agent reads them.
|
||||
The network accesses them via the PDS API. There is no separate PDS process.
|
||||
|
||||
** Level 0 pre-arbitration via Screamer
|
||||
|
||||
Section 07 of the Agora requirements describes a "Tier 0 Arbitrator" — a local
|
||||
AI that provides a sanity check before human arbitration. Passepartout's
|
||||
Screamer + fact store provides this at zero LLM tokens when working from
|
||||
existing facts:
|
||||
|
||||
- "Contract CID X references arbitrator DID Y. DID Y is active. Verified."
|
||||
- "All parties have signed. The HODL invoice is locked. Verified."
|
||||
- "The buyer's claim of non-delivery is supported by 3 signed messages with
|
||||
timestamps after the delivery deadline."
|
||||
- "The seller's proof-of-delivery field is empty. No QR scan recorded."
|
||||
|
||||
Each check is a Screamer query against the contract-lifecycle domain. Results
|
||||
are a plist, not a ruling. Both parties see the same evidence summary before
|
||||
escalating to Level 1.
|
||||
|
||||
** Reputation as deduced facts
|
||||
|
||||
Screamer deduces reputation from signed contract chains, not asserted claims:
|
||||
|
||||
#+begin_src lisp
|
||||
(:entity "did:agora:heather" :relation :contract-reputation
|
||||
:value (:completed 47 :defaulted 0 :disputes 3 :won 3 :escalated 0)
|
||||
:provenance :deduced :derived-from (<list of 47 contract CIDs>))
|
||||
#+end_src
|
||||
|
||||
This is the strong version of Agora's Trust Score. It's a fact deduced from
|
||||
cryptographic evidence, not a claim by the persona (self-reporting could be
|
||||
false) and not a claim by a centralized reputation service (could be bought).
|
||||
The deduction is auditable — `/audit did:agora:heather` shows every contract,
|
||||
every outcome, every ruling.
|
||||
|
||||
** Agent Behavioral Contracts — formal enforcement for the ABC of Agora
|
||||
|
||||
Bhardwaj (2026) introduces a formal framework that brings Design-by-Contract
|
||||
principles to autonomous AI agents. An ABC contract =C = (P, I, G, R)=
|
||||
specifies /Preconditions/, /Invariants/ (hard and soft), /Governance/ policies
|
||||
(hard and soft), and /Recovery/ mechanisms as first-class runtime-enforceable
|
||||
components.
|
||||
|
||||
This maps directly onto Agora's contract lifecycle:
|
||||
|
||||
| ABC component | Agora mapping |
|
||||
|------------------------+--------------------------------------------------------------|
|
||||
| =P= (Preconditions) | Contract Note validity checks: all signers' DIDs active, |
|
||||
| | contract CID correctly referenced, HODL invoice locked |
|
||||
| =I= (Invariants) | Hard: payment amount unchanged, arbitrator DID unchanged. |
|
||||
| | Soft: delivery within estimated window |
|
||||
| =G= (Governance) | Hard: no party modifies contract terms unilaterally. |
|
||||
| | Soft: parties communicate through designated channels |
|
||||
| =R= (Recovery) | Arbitration escalation, HODL invoice release, reputation |
|
||||
| | deduction |
|
||||
|
||||
The framework's key mathematical results have direct implications for Agora:
|
||||
|
||||
- /Drift Bounds Theorem/: contracts with recovery rate γ > α (natural drift rate
|
||||
from LLM non-determinism in agent behavior) bound behavioral drift to D* = α/γ.
|
||||
For Agora, this means contract enforcement can be /predictive/ — detecting drift
|
||||
before violation — rather than just /corrective/ after breach.
|
||||
|
||||
- /Compositionality Theorem/: sufficient conditions (interface compatibility,
|
||||
assumption discharge, governance consistency, recovery independence) under
|
||||
which individual contract guarantees compose end-to-end for multi-agent chains.
|
||||
This is essential for Agora's multi-party contracts, where a buyer, seller,
|
||||
arbitrator, and escrow agent form a chain of interdependent behavioral
|
||||
expectations.
|
||||
|
||||
- /(p, δ, k)-satisfaction/: probabilistic compliance accounting for LLM
|
||||
non-determinism — contracts hold with probability p, deviations stay within
|
||||
tolerance δ, recovery within k steps. This formalizes what Screamer's
|
||||
contract-lifecycle domain queries verify: whether the current state of a
|
||||
contract satisfies its agreed-upon conditions, given the inherent uncertainty
|
||||
in any agent's behavior.
|
||||
|
||||
The empirical results are significant: across 1,980 sessions on 7 models,
|
||||
contracted agents (with ABC enforcement) detected 5.2-6.8 soft violations per
|
||||
session that uncontracted agents missed entirely, with <10ms per-action overhead.
|
||||
Overhead is critical for Passepartout as the PDS — contract enforcement must not
|
||||
add latency to Note processing.
|
||||
|
||||
ABC does not replace Screamer. ABC specifies /what/ must hold; Screamer verifies
|
||||
/whether/ it holds against the fact store. The contract-lifecycle domain already
|
||||
planned for Phase 0b (signal chain) can be implemented as an ABC-like structure:
|
||||
a tuple of preconditions, invariants, governance rules, and recovery mechanisms,
|
||||
each expressed as Screamer-verifiable facts with Merkle provenance.
|
||||
|
||||
See also:
|
||||
- Bhardwaj, V.P. (2026). Agent Behavioral Contracts: Formal Specification and
|
||||
Runtime Enforcement for Reliable Autonomous AI Agents. arXiv:2602.22302.
|
||||
|
||||
** The merkle DAG IS the Key Event Log
|
||||
|
||||
Agora's KEL specification (Section 02) describes an append-only log of key
|
||||
events — inception, rotation, revocation, follow events. Passepartout's Merkle
|
||||
DAG (Phase 5, built on v0.2.0 memory-object infrastructure) is this log. Each
|
||||
key event is a fact in the =:key-lifecycle= domain. Each event has a
|
||||
=:parent-id= chaining to the previous event. The DAG is content-addressed —
|
||||
every event is a CID. The full KEL is queryable: `/audit did:agora:heather`
|
||||
renders every key event, every follow event, every contract signature, with
|
||||
provenance chains.
|
||||
|
||||
* Relation to the Neurosymbolic Roadmap
|
||||
|
||||
The Agora integration is not a new phase. It is a consequence of decisions
|
||||
already made:
|
||||
|
||||
| Roadmap item | Agora consequence |
|
||||
|-------------------------+----------------------------------------------------------------|
|
||||
| Phase 0b (key registry) | Key registry uses Agora DIDs. DID store is =:key-lifecycle= domain |
|
||||
| Phase 1 (fact store) | Fact store is also Note store. Same API, same hash table |
|
||||
| Phase 1a (self-pres.) | Incoming Notes tracked. Spam DIDs quarantined. Disk eviction |
|
||||
| Phase 3 (archivist) | Archivist walks =~/memex/social/notes/= alongside local dirs |
|
||||
| Phase 4 (sufficiency) | Agora Notes are a provenance category in the sufficiency score |
|
||||
| Phase 5 (Merkle DAG) | DAG = KEL. DAG = contract audit trail |
|
||||
| Phase 0b (signal chain) | Signal chain = contract lifecycle chain. Same Merkle linking |
|
||||
|
||||
No new lines in the roadmap. The Note publishing function (~40 lines) is a
|
||||
utility, not a phase.
|
||||
|
||||
* What Is NOT Built
|
||||
|
||||
1. *A separate Note parser.* Agora Notes ARE Org files. The existing Org parser
|
||||
reads both.
|
||||
2. *A separate Note store.* The =memory-object= struct stores both. The
|
||||
=*memory-store*= hash table holds both.
|
||||
3. *A separate extraction path for Agora content.* The archivist extracts facts
|
||||
from prose regardless of origin. The provenance tag distinguishes source.
|
||||
4. *A new authentication mechanism for Agora signals.* Gate vector 0 verifies
|
||||
DID signatures. The key registry is the DID registry.
|
||||
|
||||
See also:
|
||||
- =projects/agora/docs/= — Agora requirements (overview, identity, primitive, social, contracts, governance)
|
||||
- =projects/agora/TODO.org= — Passepartout integration track
|
||||
- =passepartout-neurosymbolic-design-decisions-and-options.org= — the full design rationale
|
||||
- =passepartout-neurosymbolic-roadmap.org= — the phased implementation plan
|
||||
Reference in New Issue
Block a user