Peer Capabilities: Core Implementation Plan

Status: initial C1/C2 contracts implemented and locally checked. The approved product revision requires C3 below: owner setup handoffs and pre-grant invitations are not implemented contracts yet. Deployed revised acceptance remains open. FIPS owns grant storage, authenticated delivery, invitation carrier and owner-command UI. Teams Todo's new target uses SQLite semantic events; the earlier application-signing proposal is deferred and is not a required capability change. Source of decisions: architecture. Next owner: core; follow with FIPS phases and then Teams Todo.

Execution rules

Initial baseline and concrete files (historical)

C1 — initial v1 message and callback contracts (historical implementation)

Implemented in src/capabilities/peer-network.v1.ts and peer-channel.v1.ts. Text/binary payload schemas, explicit node addressing, six required network operations plus optional owner member selection, protocol declarations and connection callbacks are now the active code contract. Errors are explicit result objects on send/connect, not implicit remote receipts.

Outbound peer-network:v1

Operation names below describe the implemented surface. Exact exported Zod shapes are authoritative in the two source files.

Operation Semantics
list-peers Caller-authorized nodes only, explicit FIPS keys, owner/alias metadata, connection state and last confirmed activity/error
get-limits Provider's byte limits, queue/concurrency bounds and supported text/binary forms
connect Explicit destination FIPS key; caller must have an active grant for that paired peer; no payload authority is implied
send One destination FIPS key, protocol, exact topic and typed text/binary payload; bounded auto-connect; one transport result
list-grants Only the calling app's grant records, including retained unavailable references
request-access Record/provide an explicit review request for peers/protocol/topics; cannot approve it or trigger an unsolicited prompt
select-members (optional) Store calling app/local-key/protocol/topics intent; return an explicit FIPS owner-command descriptor for paired-node selection and exact-scope approval; no roster or grant on capability invocation
list-invitations (optional) Current caller/identity/protocol invitation records, delivery/decision status and stored incoming review command
decline-invitation (optional) Decline only the calling app's stored incoming invitation; no access grant
retry-invitation (optional) Explicitly retry an existing outgoing offer/status check; no new invitation or grant

Grant records: opaque record ID, app alias, local FIPS key, nonempty deduplicated remote key list, one protocol, nonempty deduplicated exact topic list, timestamps. No signature, publisher key, direction, expiry or wildcard. Requests derive app identity from normal caller context, not an app alias that the caller submits.

Payload proposal:

{ kind: "text", text: string }
{ kind: "binary", bytes: Uint8Array }

FIPS validates UTF-8 byte size for text, not JS character count. Native bytes stay inside the runtime. peerPayloadToJson explicitly encodes JSON binary callers as { kind: "binary", bytes: { encoding: "base64", data } }; the schema decodes this back into Uint8Array. Arbitrary numeric-key objects are rejected. The JSON decoder has a bounded input; provider payload limits still apply. No unbounded stream.

Replace delivered with a documented single-peer transport send result. Define whether sentAt timestamps submission or completion. No remote durable receipt, exactly-once or ordering guarantee. Remove nullable signature from generic send; signed app events may live inside payloads.

Define typed error codes including permission-denied, unsupported-protocol, peer-unavailable, payload-too-large, busy/resource-limit, timeout and transport-error. Do not equate permission denial with transient network failure.

Inbound peer-channel:v1

Keep the capability name for now; "channel" no longer names a message field.

No subscribe/unsubscribe/publish/authorize-subscription operations: those are ordinary messages defined and stored by consumer apps.

Checklist and exit criteria

Original exit: core types defined the initial agreed interface; C3 extends it for the approved revision. Temporary breakage while core/FIPS are changed is accepted in this research phase; compatibility is not a gate.

C2 — owner-driven management surfaces and broker wiring

The FIPS provider owns grant SQL and grant-management rendering. Existing generic command/form actions and authenticated owner-command paths were sufficient; no FIPS-specific core/web rendering branches were added. A management-command descriptor is data, not an automatic prompt or an app write permission.

C3 — approved revision: contracts and owner workflows

Dependency for Teams Todo owner setup and FIPS revision. Status: owner member selection, scoped completion commands and bounded pre-grant invitations implemented; deployed authenticated onboarding acceptance remains open. Finalize precise operation names/schemas before provider/consumer implementation; do not imply the existing six network operations already cover these functions.

The SQLite/direct-origin decision supersedes the pending NIP-01/JCS application signing work. No generic signing capability or core entity/hash/causality schema is required. Existing FIPS pairing and signaling signatures remain unchanged.

Implemented optional operations: select-members accepts a stored small invitation draft; list-invitations, decline-invitation, retry-invitation are caller/identity scoped. peer-channel.describe.invitationProtocols opts in, and optional invitation-received validates app metadata/returns local completion data, never approves access. The FIPS owner command is the only acceptance/grant path. See exact carrier/storage bounds.

Exit: generic broker contracts let an owner select/create/join once with exact grants and deliver narrowly scoped app invitations before grants. They do not implement app membership, source storage, manual publication, review/merge/agreement or peer durable receipts in core.

Retained boundaries after revision

No grant auto-cleanup on unpair, local identity change, disable or uninstall. Unavailable records stay visible and editable. No permission signatures, grant expiry, wildcard scope, transport-owned subscriptions, general app-data replay queue, global namespace cryptography or paid-app licensing subsystem. Bounded onboarding invitation retry state is the explicitly scoped new exception, not a general ordinary-send queue.

Progress / verification log

Targeted ESLint passed. Native 512-byte binary and explicit JSON/base64 round trips, malformed-byte rejection, legacy-shape rejection and inconsistent-send-result rejection passed. Root tsc --noEmit reports only the three pre-existing FIPS vendor Noble/WebRTC errors. sentAt is local send completion time; failure has a null time and a structured error.

Added generic BotPlugin.onStop and reverse-registration shutdown with a five-second deadline per hook, called on normal signals and startup failure before closing the shared relay pool. FIPS and Teams Todo release their own timers/sockets/databases there. This is host-shutdown support, not a new hot-unload implementation.

The scaffold's boolean options are required function inputs, without parameter defaults. Manager checkboxes and CLI prompts resolve defaults at the caller: draft commands enabled, hook configuration disabled. Teams Todo passed false for hooks; this creation did not configure or execute them. The initial app used root xitdb@0.30.0; its code/data and plugin/root dependency were subsequently removed after confirming no other runtime consumer. Teams Todo currently uses SQLite-only simulation and declares no peer capabilities until the new FIPS event path is implemented.