buzz/docs/nips/NIP-PMA.md

NIP-PMA: Private Managed-Agent Aggregate

draft — protocol/codec reservation only. Relays MUST reject this kind until privacy, transactional CAS, backup/restore, revocation, and capability gates are deployed.

Purpose and kind

Kind 30179 is an owner-authored, addressable, owner-readable aggregate for one runnable managed agent. Its coordinate is (owner pubkey, 30179, agent pubkey). It is the only durable authority after a per-agent migration is independently verified. Kinds 30175 and 30177 remain public/compatibility projections.

This reservation does not change current agent authority, storage, startup, mutation, deletion, catalog, or sharing behavior.

Signed outer envelope

Exactly these two-element tags are permitted:

• d = <64 lowercase hex agent pubkey> exactly once;
• g = <canonical positive decimal generation> exactly once;
• prev = <64 lowercase hex predecessor event id> exactly once after generation 1 and absent at generation 1;
• state = active|deleted exactly once.

Content is bounded NIP-44 v2 ciphertext encrypted owner-to-owner. Event ID and signature, exact kind/author/tag grammar, canonical curve-valid agent keys, and size are validated before decrypt. The decrypted payload repeats owner, agent, generation, predecessor, and state; any mismatch is corruption.

Decrypted v1 payload

Top-level and nested core schemas reject unknown and duplicate JSON member names. Forward-compatible data is confined to namespaced extensions entries; core semantics never depend on an extension. Projection recovery v1 contains the complete signed public event; validation verifies its signature and ID, owner, kind and d coordinate, and hashes its exact content bytes against the binding. This makes reconstruction deterministic rather than an agreement over an untyped JSON blob.

An active payload binds exact signed 30175 and 30177 event IDs, SHA-256 of their exact content bytes, and complete versioned recovery material. It also contains the preserved agent nsec and an optional NIP-OA attestation, plus explicitly allowlisted private runnable configuration. When present, the attestation MUST be a cryptographically valid unconditional (conditions = "") owner-to-agent authorization: its owner equals the aggregate author and its agent equals the nsec-derived d coordinate. Conditional, malformed, wrong-owner, or wrong-agent attestations are rejected. The nsec MUST derive the d coordinate.

All active aggregates require a stable 30175 definition binding. Before a legacy definition-less agent can be encoded, the migrator MUST deterministically materialize its definition fields as a non-shared 30175 under the owner, with a stable collision-safe slug derived from the agent pubkey. Materialization and read-back verification are prerequisites: failure leaves the agent LegacyOnly and preserves its local record/key unchanged. No client may synthesize a default or mint a replacement identity to satisfy this schema.

A deleted payload is minimal: it contains no active body, advances generation from its predecessor, and includes deleted_at. Relay anti-resurrection and undelete rules are specified by the later transactional CAS contract; generic NIP-33 LWW is explicitly insufficient.

Field authority

• 30175 definition projection: display name, prompt, runtime/model/provider, name pool, definition behavior defaults, sharing/provenance, public avatar.
• 30177 instance projection: agent pubkey/name/definition linkage, parallelism, respond_to, and allowlist.
• private portable canonical: nsec, auth tag, env, durable timeout/team fields, and secret-bearing backend configuration.
• private but device-validated: relay URL, explicit command/args, backend remote identity, and any explicitly portable path/provider reference.
• local device policy/derived: start-on-launch, auto-restart, effective binary paths, installed team directory, and catalog-derived commands.
• legacy conversion only: create-time command/model/provider mirrors, deprecated MCP/turn timeout, source-version drift markers, and relay-mesh fallback markers where a definition is authoritative.
• transient local only: PID and all last start/stop/exit/error receipts/logs.

Adding a ManagedAgentRecord field must update an exhaustive Desktop classification/conversion fixture before migration-writing code can merge. This inert core-only reservation does not yet depend on the Desktop type and therefore does not claim to provide that compile-time tripwire.

Aggregate submission boundary

Three ordinary Nostr EVENT writes cannot atomically commit an aggregate. The future relay contract accepts independently signed projection candidates plus the signed private head through one authenticated aggregate submission and one PostgreSQL transaction. It validates CAS predecessor/generation, signatures, hashes, recovery material, definition revision, tombstone watermark, and all coordinates before exposing any candidate. Fan-out begins only after commit.

Public catalog definitions require an independently verifiable public CAS/revision head; browsing must never require decrypting kind 30179.

Required deployment order

1. this inert codec/kind reservation while ingest still rejects 30179;
2. author-only privacy gates, SQL visibility before LIMIT, and verification that the positive FTS allowlist continues to exclude 30179;
3. dark CAS schema/transaction;
4. feature-gated aggregate submission;
5. read/repair/export/import and destructive restore drill;
6. tombstone revocation across authentication/ingest/session caches;
7. owner rotation epoch/freeze/receipts/activation;
8. Desktop reader and verified dual-write migration.

No phase may publish secrets before step 2 or retire local recovery evidence before the complete migration exit gate passes.