@kubun/plugin-p2p 0.11.0 → 0.12.1

package/lib/groups/group-protocols.d.ts

@@ -16,24 +16,34 @@ import type { FromSchema } from '@sozai/schema';
  * records), so the lane provides ordering + delivery, not authorization.
  */
 export declare const controlProtocol: {
-    readonly 'control/ledgerEntry': {
-        readonly type: "event";
-        readonly description: "A self-signed control-ledger entry appended by its author.";
-        readonly data: {
+    readonly 'control/ledgerCatchup': {
+        readonly type: "request";
+        readonly retain: "ephemeral";
+        readonly description: "Ask current members for the group control ledger to backfill missed entries. Gathered: each member replies with its entries; the requester re-verifies every token.";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {};
+            readonly additionalProperties: false;
+        };
+        readonly result: {
             readonly type: "object";
             readonly properties: {
-                readonly token: {
-                    readonly type: "string";
-                    readonly description: "Signed control-ledger entry token.";
+                readonly entries: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Signed control-ledger entry tokens.";
                 };
             };
-            readonly required: readonly ["token"];
+            readonly required: readonly ["entries"];
             readonly additionalProperties: false;
         };
     };
-    readonly 'control/ledgerCatchup': {
+    readonly 'control/policyCatchup': {
         readonly type: "request";
-        readonly description: "Ask current members for the group control ledger to backfill missed entries. Gathered: each member replies with its entries; the requester re-verifies every token.";
+        readonly retain: "ephemeral";
+        readonly description: "Ask current members to restate their OWN model access-defaults, for a member whose read position fell below the hub retention floor and can no longer read the frames that carried them. Gathered: each member replies with signed tokens for its own rules; the requester verifies every token and applies it under the same sender-bound LWW rules as a live frame.";
         readonly param: {
             readonly type: "object";
             readonly properties: {};
@@ -42,20 +52,21 @@ export declare const controlProtocol: {
         readonly result: {
             readonly type: "object";
             readonly properties: {
-                readonly entries: {
+                readonly defaults: {
                     readonly type: "array";
                     readonly items: {
                         readonly type: "string";
                     };
-                    readonly description: "Signed control-ledger entry tokens.";
+                    readonly description: "Signed access-default set tokens, one per rule the responder owns.";
                 };
             };
-            readonly required: readonly ["entries"];
+            readonly required: readonly ["defaults"];
             readonly additionalProperties: false;
         };
     };
     readonly 'control/delegationShare': {
         readonly type: "event";
+        readonly retain: "log";
         readonly description: "Distribute a minted document/write capability token to group co-members.";
         readonly data: {
             readonly type: "object";
@@ -75,6 +86,7 @@ export declare const controlProtocol: {
     };
     readonly 'control/delegationRevoke': {
         readonly type: "event";
+        readonly retain: "log";
         readonly description: "Distribute a signed revocation record for a previously minted capability.";
         readonly data: {
             readonly type: "object";
@@ -92,8 +104,102 @@ export declare const controlProtocol: {
             readonly additionalProperties: false;
         };
     };
+    readonly 'control/accessDefaultSet': {
+        readonly type: "event";
+        readonly retain: "log";
+        readonly description: "Distribute a member's own model access-default to co-members. `auth` is the signed statement; every other field mirrors it so the receiver can rebuild the frame before verifying.";
+        readonly data: {
+            readonly type: "object";
+            readonly properties: {
+                readonly modelID: {
+                    readonly type: "string";
+                };
+                readonly permissionType: {
+                    readonly type: "string";
+                    readonly enum: readonly ["read", "write"];
+                };
+                readonly rule: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly level: {
+                            readonly type: "string";
+                        };
+                        readonly allowedDIDs: {
+                            readonly type: readonly ["array", "null"];
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly allowedCircles: {
+                            readonly type: readonly ["array", "null"];
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly allowedGroups: {
+                            readonly type: readonly ["array", "null"];
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                    readonly required: readonly ["level", "allowedDIDs", "allowedCircles", "allowedGroups"];
+                    readonly additionalProperties: false;
+                };
+                readonly ownerDID: {
+                    readonly type: "string";
+                    readonly description: "Claimed owner; checked against the `auth` issuer.";
+                };
+                readonly hlc: {
+                    readonly type: "string";
+                    readonly description: "Owner-stamped LWW anchor, mirroring the stored row.";
+                };
+                readonly auth: {
+                    readonly type: "string";
+                    readonly description: "Signed access-default token.";
+                };
+            };
+            readonly required: readonly ["modelID", "permissionType", "rule", "ownerDID", "hlc", "auth"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'control/accessDefaultRemove': {
+        readonly type: "event";
+        readonly retain: "log";
+        readonly description: "Distribute a member's own model access-default removal to co-members.";
+        readonly data: {
+            readonly type: "object";
+            readonly properties: {
+                readonly modelID: {
+                    readonly type: "string";
+                };
+                readonly permissionTypes: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly enum: readonly ["read", "write"];
+                    };
+                };
+                readonly ownerDID: {
+                    readonly type: "string";
+                    readonly description: "Claimed owner; checked against the `auth` issuer.";
+                };
+                readonly hlc: {
+                    readonly type: "string";
+                    readonly description: "Owner-stamped LWW anchor for the removal.";
+                };
+                readonly auth: {
+                    readonly type: "string";
+                    readonly description: "Signed access-default removal token.";
+                };
+            };
+            readonly required: readonly ["modelID", "permissionTypes", "ownerDID", "hlc", "auth"];
+            readonly additionalProperties: false;
+        };
+    };
     readonly 'control/groupLeaveRequest': {
         readonly type: "event";
+        readonly retain: "ephemeral";
         readonly description: "Advisory voluntary-leave notice. Not authoritative — an admin must issue a real removeMember; receivers surface it as an event and never tombstone on it.";
         readonly data: {
             readonly type: "object";
@@ -118,6 +224,7 @@ export declare const controlProtocol: {
 export declare const syncProtocol: {
     readonly 'sync/mutationApply': {
         readonly type: "event";
+        readonly retain: "ephemeral";
         readonly description: "Broadcast a batch of signed document mutations to group members.";
         readonly data: {
             readonly type: "object";
@@ -151,35 +258,174 @@ export declare const syncProtocol: {
         };
     };
 };
+export declare const peerProtocol: {
+    readonly 'peer/announce': {
+        readonly type: "event";
+        readonly retain: "log";
+        readonly description: "Advertise this device to its co-members: display label, availability class, and the exact capabilities it answers on. The announcer is taken from the authenticated sender, so the body names nobody.";
+        readonly data: {
+            readonly type: "object";
+            readonly properties: {
+                readonly label: {
+                    readonly type: "string";
+                    readonly description: "Self-declared display hint, Bluetooth-style. Rendered beside the DID, never read as an identity.";
+                };
+                readonly availability: {
+                    readonly type: "string";
+                    readonly enum: readonly ["always-on", "interactive", "mobile"];
+                    readonly description: "Steers automatic selection only; it never refuses to serve.";
+                };
+                readonly capabilities: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly protocol: {
+                                readonly type: "string";
+                            };
+                            readonly version: {
+                                readonly type: "number";
+                            };
+                            readonly transports: {
+                                readonly type: readonly ["array", "null"];
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                                readonly description: "Addressing hints for a capability the hub tunnel does not already reach. Null for one it does.";
+                            };
+                        };
+                        readonly required: readonly ["protocol", "version", "transports"];
+                        readonly additionalProperties: false;
+                    };
+                    readonly description: "Matched EXACTLY on protocol AND version.";
+                };
+                readonly hlc: {
+                    readonly type: "string";
+                    readonly description: "Announcer-stamped LWW anchor for its own projection row.";
+                };
+            };
+            readonly required: readonly ["label", "availability", "capabilities", "hlc"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'peer/query': {
+        readonly type: "request";
+        readonly retain: "ephemeral";
+        readonly description: "Ask who is reachable right now, optionally narrowed to devices answering named protocols. Gathered: every matching device replies with its own advertisement within the window. A result is \"who answered\", never \"who exists\".";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly protocols: {
+                    readonly type: readonly ["array", "null"];
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Only devices answering one of these reply. Null means any. Nullable-and-required, as the announce body's `transports` is.";
+                };
+            };
+            readonly required: readonly ["protocols"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly label: {
+                    readonly type: "string";
+                    readonly description: "Self-declared display hint, Bluetooth-style. Rendered beside the DID, never read as an identity.";
+                };
+                readonly availability: {
+                    readonly type: "string";
+                    readonly enum: readonly ["always-on", "interactive", "mobile"];
+                    readonly description: "Steers automatic selection only; it never refuses to serve.";
+                };
+                readonly capabilities: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly protocol: {
+                                readonly type: "string";
+                            };
+                            readonly version: {
+                                readonly type: "number";
+                            };
+                            readonly transports: {
+                                readonly type: readonly ["array", "null"];
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                                readonly description: "Addressing hints for a capability the hub tunnel does not already reach. Null for one it does.";
+                            };
+                        };
+                        readonly required: readonly ["protocol", "version", "transports"];
+                        readonly additionalProperties: false;
+                    };
+                    readonly description: "Matched EXACTLY on protocol AND version.";
+                };
+                readonly hlc: {
+                    readonly type: "string";
+                    readonly description: "Announcer-stamped LWW anchor for its own projection row.";
+                };
+            };
+            readonly required: readonly ["label", "availability", "capabilities", "hlc"];
+            readonly additionalProperties: false;
+        };
+    };
+};
 export type ControlProtocol = typeof controlProtocol;
 export type SyncProtocol = typeof syncProtocol;
-export type LedgerEntryData = FromSchema<(typeof controlProtocol)['control/ledgerEntry']['data']>;
+export type PeerProtocol = typeof peerProtocol;
 export type LedgerCatchupResult = FromSchema<(typeof controlProtocol)['control/ledgerCatchup']['result']>;
 export type DelegationShareData = FromSchema<(typeof controlProtocol)['control/delegationShare']['data']>;
 export type DelegationRevokeData = FromSchema<(typeof controlProtocol)['control/delegationRevoke']['data']>;
+export type AccessDefaultSetData = FromSchema<(typeof controlProtocol)['control/accessDefaultSet']['data']>;
+export type AccessDefaultRemoveData = FromSchema<(typeof controlProtocol)['control/accessDefaultRemove']['data']>;
 export type GroupLeaveRequestData = FromSchema<(typeof controlProtocol)['control/groupLeaveRequest']['data']>;
 export type MutationApplyData = FromSchema<(typeof syncProtocol)['sync/mutationApply']['data']>;
-/** The two app-lane protocols, keyed for `createGroupPeer({ protocols })`. */
+export type PeerAnnounceData = FromSchema<(typeof peerProtocol)['peer/announce']['data']>;
+export type PeerQueryParam = FromSchema<(typeof peerProtocol)['peer/query']['param']>;
+/**
+ * A gather reply. The same type as {@link PeerAnnounceData} by construction —
+ * both read one schema object — not by two declarations agreeing.
+ */
+export type PeerQueryResult = FromSchema<(typeof peerProtocol)['peer/query']['result']>;
+/** One of `always-on`, `interactive`, `mobile`. */
+export type PeerAvailability = PeerAnnounceData['availability'];
+export type PeerCapability = PeerAnnounceData['capabilities'][number];
+/**
+ * The app-lane protocols, keyed for `createGroupPeer({ protocols })`. Each key
+ * names its own topic, so adding one moves no existing lane.
+ */
 export declare const groupProtocols: {
     control: {
-        readonly 'control/ledgerEntry': {
-            readonly type: "event";
-            readonly description: "A self-signed control-ledger entry appended by its author.";
-            readonly data: {
+        readonly 'control/ledgerCatchup': {
+            readonly type: "request";
+            readonly retain: "ephemeral";
+            readonly description: "Ask current members for the group control ledger to backfill missed entries. Gathered: each member replies with its entries; the requester re-verifies every token.";
+            readonly param: {
+                readonly type: "object";
+                readonly properties: {};
+                readonly additionalProperties: false;
+            };
+            readonly result: {
                 readonly type: "object";
                 readonly properties: {
-                    readonly token: {
-                        readonly type: "string";
-                        readonly description: "Signed control-ledger entry token.";
+                    readonly entries: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "Signed control-ledger entry tokens.";
                     };
                 };
-                readonly required: readonly ["token"];
+                readonly required: readonly ["entries"];
                 readonly additionalProperties: false;
             };
         };
-        readonly 'control/ledgerCatchup': {
+        readonly 'control/policyCatchup': {
             readonly type: "request";
-            readonly description: "Ask current members for the group control ledger to backfill missed entries. Gathered: each member replies with its entries; the requester re-verifies every token.";
+            readonly retain: "ephemeral";
+            readonly description: "Ask current members to restate their OWN model access-defaults, for a member whose read position fell below the hub retention floor and can no longer read the frames that carried them. Gathered: each member replies with signed tokens for its own rules; the requester verifies every token and applies it under the same sender-bound LWW rules as a live frame.";
             readonly param: {
                 readonly type: "object";
                 readonly properties: {};
@@ -188,20 +434,21 @@ export declare const groupProtocols: {
             readonly result: {
                 readonly type: "object";
                 readonly properties: {
-                    readonly entries: {
+                    readonly defaults: {
                         readonly type: "array";
                         readonly items: {
                             readonly type: "string";
                         };
-                        readonly description: "Signed control-ledger entry tokens.";
+                        readonly description: "Signed access-default set tokens, one per rule the responder owns.";
                     };
                 };
-                readonly required: readonly ["entries"];
+                readonly required: readonly ["defaults"];
                 readonly additionalProperties: false;
             };
         };
         readonly 'control/delegationShare': {
             readonly type: "event";
+            readonly retain: "log";
             readonly description: "Distribute a minted document/write capability token to group co-members.";
             readonly data: {
                 readonly type: "object";
@@ -221,6 +468,7 @@ export declare const groupProtocols: {
         };
         readonly 'control/delegationRevoke': {
             readonly type: "event";
+            readonly retain: "log";
             readonly description: "Distribute a signed revocation record for a previously minted capability.";
             readonly data: {
                 readonly type: "object";
@@ -238,8 +486,102 @@ export declare const groupProtocols: {
                 readonly additionalProperties: false;
             };
         };
+        readonly 'control/accessDefaultSet': {
+            readonly type: "event";
+            readonly retain: "log";
+            readonly description: "Distribute a member's own model access-default to co-members. `auth` is the signed statement; every other field mirrors it so the receiver can rebuild the frame before verifying.";
+            readonly data: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly modelID: {
+                        readonly type: "string";
+                    };
+                    readonly permissionType: {
+                        readonly type: "string";
+                        readonly enum: readonly ["read", "write"];
+                    };
+                    readonly rule: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly level: {
+                                readonly type: "string";
+                            };
+                            readonly allowedDIDs: {
+                                readonly type: readonly ["array", "null"];
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly allowedCircles: {
+                                readonly type: readonly ["array", "null"];
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly allowedGroups: {
+                                readonly type: readonly ["array", "null"];
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                        readonly required: readonly ["level", "allowedDIDs", "allowedCircles", "allowedGroups"];
+                        readonly additionalProperties: false;
+                    };
+                    readonly ownerDID: {
+                        readonly type: "string";
+                        readonly description: "Claimed owner; checked against the `auth` issuer.";
+                    };
+                    readonly hlc: {
+                        readonly type: "string";
+                        readonly description: "Owner-stamped LWW anchor, mirroring the stored row.";
+                    };
+                    readonly auth: {
+                        readonly type: "string";
+                        readonly description: "Signed access-default token.";
+                    };
+                };
+                readonly required: readonly ["modelID", "permissionType", "rule", "ownerDID", "hlc", "auth"];
+                readonly additionalProperties: false;
+            };
+        };
+        readonly 'control/accessDefaultRemove': {
+            readonly type: "event";
+            readonly retain: "log";
+            readonly description: "Distribute a member's own model access-default removal to co-members.";
+            readonly data: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly modelID: {
+                        readonly type: "string";
+                    };
+                    readonly permissionTypes: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                            readonly enum: readonly ["read", "write"];
+                        };
+                    };
+                    readonly ownerDID: {
+                        readonly type: "string";
+                        readonly description: "Claimed owner; checked against the `auth` issuer.";
+                    };
+                    readonly hlc: {
+                        readonly type: "string";
+                        readonly description: "Owner-stamped LWW anchor for the removal.";
+                    };
+                    readonly auth: {
+                        readonly type: "string";
+                        readonly description: "Signed access-default removal token.";
+                    };
+                };
+                readonly required: readonly ["modelID", "permissionTypes", "ownerDID", "hlc", "auth"];
+                readonly additionalProperties: false;
+            };
+        };
         readonly 'control/groupLeaveRequest': {
             readonly type: "event";
+            readonly retain: "ephemeral";
             readonly description: "Advisory voluntary-leave notice. Not authoritative — an admin must issue a real removeMember; receivers surface it as an event and never tombstone on it.";
             readonly data: {
                 readonly type: "object";
@@ -260,6 +602,7 @@ export declare const groupProtocols: {
     sync: {
         readonly 'sync/mutationApply': {
             readonly type: "event";
+            readonly retain: "ephemeral";
             readonly description: "Broadcast a batch of signed document mutations to group members.";
             readonly data: {
                 readonly type: "object";
@@ -293,5 +636,119 @@ export declare const groupProtocols: {
             };
         };
     };
+    peer: {
+        readonly 'peer/announce': {
+            readonly type: "event";
+            readonly retain: "log";
+            readonly description: "Advertise this device to its co-members: display label, availability class, and the exact capabilities it answers on. The announcer is taken from the authenticated sender, so the body names nobody.";
+            readonly data: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly label: {
+                        readonly type: "string";
+                        readonly description: "Self-declared display hint, Bluetooth-style. Rendered beside the DID, never read as an identity.";
+                    };
+                    readonly availability: {
+                        readonly type: "string";
+                        readonly enum: readonly ["always-on", "interactive", "mobile"];
+                        readonly description: "Steers automatic selection only; it never refuses to serve.";
+                    };
+                    readonly capabilities: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly protocol: {
+                                    readonly type: "string";
+                                };
+                                readonly version: {
+                                    readonly type: "number";
+                                };
+                                readonly transports: {
+                                    readonly type: readonly ["array", "null"];
+                                    readonly items: {
+                                        readonly type: "string";
+                                    };
+                                    readonly description: "Addressing hints for a capability the hub tunnel does not already reach. Null for one it does.";
+                                };
+                            };
+                            readonly required: readonly ["protocol", "version", "transports"];
+                            readonly additionalProperties: false;
+                        };
+                        readonly description: "Matched EXACTLY on protocol AND version.";
+                    };
+                    readonly hlc: {
+                        readonly type: "string";
+                        readonly description: "Announcer-stamped LWW anchor for its own projection row.";
+                    };
+                };
+                readonly required: readonly ["label", "availability", "capabilities", "hlc"];
+                readonly additionalProperties: false;
+            };
+        };
+        readonly 'peer/query': {
+            readonly type: "request";
+            readonly retain: "ephemeral";
+            readonly description: "Ask who is reachable right now, optionally narrowed to devices answering named protocols. Gathered: every matching device replies with its own advertisement within the window. A result is \"who answered\", never \"who exists\".";
+            readonly param: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly protocols: {
+                        readonly type: readonly ["array", "null"];
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "Only devices answering one of these reply. Null means any. Nullable-and-required, as the announce body's `transports` is.";
+                    };
+                };
+                readonly required: readonly ["protocols"];
+                readonly additionalProperties: false;
+            };
+            readonly result: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly label: {
+                        readonly type: "string";
+                        readonly description: "Self-declared display hint, Bluetooth-style. Rendered beside the DID, never read as an identity.";
+                    };
+                    readonly availability: {
+                        readonly type: "string";
+                        readonly enum: readonly ["always-on", "interactive", "mobile"];
+                        readonly description: "Steers automatic selection only; it never refuses to serve.";
+                    };
+                    readonly capabilities: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly protocol: {
+                                    readonly type: "string";
+                                };
+                                readonly version: {
+                                    readonly type: "number";
+                                };
+                                readonly transports: {
+                                    readonly type: readonly ["array", "null"];
+                                    readonly items: {
+                                        readonly type: "string";
+                                    };
+                                    readonly description: "Addressing hints for a capability the hub tunnel does not already reach. Null for one it does.";
+                                };
+                            };
+                            readonly required: readonly ["protocol", "version", "transports"];
+                            readonly additionalProperties: false;
+                        };
+                        readonly description: "Matched EXACTLY on protocol AND version.";
+                    };
+                    readonly hlc: {
+                        readonly type: "string";
+                        readonly description: "Announcer-stamped LWW anchor for its own projection row.";
+                    };
+                };
+                readonly required: readonly ["label", "availability", "capabilities", "hlc"];
+                readonly additionalProperties: false;
+            };
+        };
+    };
 };
 export type GroupProtocols = typeof groupProtocols;