@songsid/agend 2.3.5-alpha.4 → 2.3.5-alpha.5

package/dist/hub/protocol.js

@@ -0,0 +1,93 @@
+/** Strict P1 frame schemas; importing this file creates no state, sockets or timers. */
+import { z } from "zod";
+import { epoch, hash, identifier, person, plain, reason, uuid, validated, parseStrictJson } from "./validation.js";
+import { validHubAnswerButtons } from "./buttons-model.js";
+export const HUB_VERSION = 1;
+export const HUB_PATHS = { pair: "/hub/v1/pair", claim: "/hub/v1/claim", connect: "/hub/v1/connect" };
+export const HUB_CAPABILITIES = ["identity-v1", "receipts-v1", "reconcile-v1"];
+/** Optional link features this build offers, never required: an older peer that lacks one keeps working without it.
+ * `welcome-caps-v1` lets the Hub answer with its own list; a feature is enabled only when both ends list it. Each feature
+ * PR adds its own flag here (#3226: attachments-v1, buttons-v1, quota-band-v1) and checks `features` before sending. */
+export const HUB_OPTIONAL_CAPABILITIES = ["welcome-caps-v1", "attachments-v1", "buttons-v1", "quota-band-v1"];
+export const HUB_ATTACHMENT_FILE_MAX = 20 * 1024 * 1024;
+export const HUB_ATTACHMENTS_PER_MESSAGE = 10;
+/** Raw bytes per attachment chunk: base64 (4/3) plus the frame envelope stays under HUB_LIMITS.frame (256 KiB). */
+export const HUB_ATTACHMENT_CHUNK = 180 * 1024;
+export const HUB_LIMITS = { frame: 256 * 1024, question: 64 * 1024, answer: 128 * 1024, pending: 32, sendQueue: 1024 * 1024, heartbeat: 15_000, rpcTimeout: 5_000 };
+export const askerSchema = z.strictObject({
+    v: z.literal(1), issuer: uuid, issuerKeyId: identifier, messageId: uuid, asker: person, owner: person,
+    destinationFleetId: uuid, exposureId: uuid, roomId: uuid, grantId: uuid, grantRevision: epoch,
+    exposureRevision: epoch, revocationVersion: epoch, contentDigest: hash, issuedAt: epoch, expiresAt: epoch,
+    nonce: z.string().regex(/^[a-f0-9]{64}$/), signature: z.string().regex(/^[A-Za-z0-9_-]{86}$/),
+});
+export const exposureSchema = z.strictObject({ id: uuid, fleetId: uuid, owner: person, displayName: plain(256), revision: epoch,
+    state: z.enum(["published", "withdrawn", "frozen"]), dataViewId: identifier, allowedTools: z.array(identifier).max(64), policyDigest: hash });
+/** No extensible bag: percentages, provider/profile ids and precise reset times are refused. */
+export const quotaSchema = z.union([
+    z.strictObject({ band: z.enum(["available", "near_limit", "unknown"]) }),
+    z.strictObject({ band: z.literal("exhausted"), resetsAt: epoch.max(8.64e15).refine(n => n % 300_000 === 0).optional() }),
+]);
+export const exposureQuotaSchema = z.strictObject({ exposureId: uuid, quota: quotaSchema });
+/** A file's name as shown and saved: one path segment, no control characters, no leading dot. */
+export const attachmentName = plain(255).refine(s => s.length > 0 && !/[\\/\u0000-\u001f\u007f]/.test(s) && !s.startsWith(".") && s.trim() === s, "Invalid file name");
+export const attachmentMime = z.string().regex(/^(?:image|application|text)\/[a-z0-9][a-z0-9.+-]{0,99}$/);
+export const attachmentRefSchema = z.strictObject({ id: uuid, name: attachmentName, size: z.number().int().min(1).max(HUB_ATTACHMENT_FILE_MAX), mime: attachmentMime, sha256: hash });
+const attachmentList = z.array(attachmentRefSchema).min(1).max(HUB_ATTACHMENTS_PER_MESSAGE).refine(list => new Set(list.map(r => r.id)).size === list.length, "Duplicate attachment");
+/** `attachments` only ever goes to a peer whose link enabled attachments-v1 (an old peer's strict schema refuses it). */
+export const questionSchema = z.strictObject({ text: plain(HUB_LIMITS.question), identity: askerSchema, attachments: attachmentList.optional() });
+export const receiptSchema = z.strictObject({ messageId: uuid, contentDigest: hash,
+    stage: z.enum(["queued", "delivered", "consumed", "answered", "rejected", "cancelled", "failed", "uncertain"]),
+    sequence: epoch.min(1), at: epoch, memberDeliveryId: uuid.optional(), reasonCode: reason.optional() });
+const scope = { messageId: uuid, operationId: uuid, exposureRevision: epoch };
+export const authorizationSchema = z.union([
+    z.strictObject({ ...scope, phase: z.enum(["admit", "begin"]) }),
+    z.strictObject({ ...scope, phase: z.literal("tool"), tool: z.strictObject({ name: identifier, argumentsDigest: hash }) }),
+    z.strictObject({ ...scope, phase: z.literal("release-answer"), answer: z.strictObject({ answerId: uuid, contentDigest: hash }) }),
+]);
+export const leaseSchema = z.strictObject({ decisionId: uuid, messageId: uuid, operationId: uuid,
+    phase: z.enum(["admit", "begin", "tool", "release-answer"]), operationDigest: hash, revocationVersion: epoch,
+    exposureRevision: epoch, linkEpoch: epoch.min(1), expiresAt: epoch });
+/** buttons-v1 uses the fleet's normalized poll config (the raw tool uses show_voters instead). */
+export const answerButtonsSchema = z.strictObject({ id: z.string().regex(/^[a-f0-9]{32}$/), labels: z.array(z.string()).min(1).max(10),
+    values: z.array(z.string()).min(1).max(10).optional(),
+    poll: z.strictObject({ seconds: z.number().int().min(10).max(86400), multi: z.boolean(), reveal: z.enum(["close", "live"]),
+        showVoters: z.boolean(), question: plain(1200).refine(s => s.length <= 300) }).optional() }).refine(validHubAnswerButtons, "Invalid reply buttons/poll");
+export const answerSchema = z.strictObject({ messageId: uuid, answerId: uuid, text: plain(HUB_LIMITS.answer), contentDigest: hash, releaseLease: leaseSchema,
+    attachments: attachmentList.optional(), buttons: answerButtonsSchema.optional() });
+export const revocationSchema = z.strictObject({ revocationVersion: epoch, reasonCode: reason, scope: z.discriminatedUnion("kind", [
+        z.strictObject({ kind: z.literal("person"), personId: z.string().regex(/^[a-z][a-z0-9_-]{0,63}\/[a-f0-9-]{36}$/) }),
+        z.strictObject({ kind: z.literal("fleet"), fleetId: uuid }),
+        z.strictObject({ kind: z.literal("exposure"), exposureId: uuid }),
+        z.strictObject({ kind: z.literal("grant"), grantId: uuid }),
+    ]) });
+const errorSchema = z.strictObject({ code: reason, retryable: z.boolean() });
+const frame = (type, payload) => z.strictObject({ v: z.literal(1), type: z.literal(type), requestId: uuid, linkEpoch: epoch, payload });
+const hello = z.strictObject({ supportedVersions: z.array(epoch.min(1)).min(1).max(8), capabilities: z.array(identifier).max(16), memberBootId: uuid });
+const welcome = z.strictObject({ selectedVersion: z.literal(1), hubId: uuid, fleetId: uuid, linkEpoch: epoch.min(1), revocationVersion: epoch,
+    /** Sent only when the hello offered welcome-caps-v1: the Hub's own optional features. */
+    capabilities: z.array(identifier).max(16).optional() });
+const chunkData = z.string().regex(/^[A-Za-z0-9+/]*={0,2}$/).max(Math.ceil(HUB_ATTACHMENT_CHUNK / 3) * 4);
+const attachmentChunk = z.strictObject({ id: uuid, offset: epoch, total: z.number().int().min(1).max(HUB_ATTACHMENT_FILE_MAX), sha256: hash, data: chunkData });
+const reconcile = z.strictObject({ afterReceiptSequence: epoch, messages: z.array(z.strictObject({ messageId: uuid, contentDigest: hash })).max(128) });
+export const memberFrameSchema = z.union([
+    frame("hello", hello), frame("exposure.snapshot", z.strictObject({ revision: epoch, exposures: z.array(exposureSchema).max(64) })),
+    frame("receipt", receiptSchema), frame("answer", answerSchema), frame("reconcile", reconcile),
+    frame("authorize.request", authorizationSchema), frame("error", errorSchema),
+    // attachments-v1 only: pull a question's file; push an answer's file before its answer frame.
+    frame("attachment.get", z.strictObject({ id: uuid, offset: epoch })), frame("attachment.put", attachmentChunk),
+    frame("exposure.quota", exposureQuotaSchema),
+]);
+export const serverFrameSchema = z.union([
+    frame("welcome", welcome), frame("question", questionSchema), frame("receipt", receiptSchema),
+    frame("reconcile", z.strictObject({ receipts: z.array(receiptSchema).max(128), nextReceiptSequence: epoch, more: z.boolean() })),
+    frame("authorize.result", z.union([z.strictObject({ ok: z.literal(true), lease: leaseSchema }), z.strictObject({ ok: z.literal(false), reasonCode: reason })])),
+    frame("revoke", revocationSchema), frame("error", errorSchema),
+    frame("attachment.chunk", attachmentChunk), frame("attachment.ack", z.strictObject({ id: uuid, offset: epoch })),
+]);
+export const parseMemberFrame = (input) => validated(memberFrameSchema, parseStrictJson(input));
+export const parseServerFrame = (input) => validated(serverFrameSchema, parseStrictJson(input));
+export function encodeMemberFrame(value) { return JSON.stringify(parseMemberFrame(JSON.stringify(value))); }
+export function encodeServerFrame(value) { return JSON.stringify(parseServerFrame(JSON.stringify(value))); }
+export const validateAsker = (input) => validated(askerSchema, input);
+export const validateAuthorization = (input) => validated(authorizationSchema, input);
+//# sourceMappingURL=protocol.js.map

package/dist/hub/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/hub/protocol.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEnH,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAC7B,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,EAAW,CAAC;AAC/G,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,aAAa,EAAE,aAAa,EAAE,cAAc,CAAU,CAAC;AACxF;;wHAEwH;AACxH,MAAM,CAAC,MAAM,yBAAyB,GAAsB,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,YAAY,EAAE,eAAe,CAAC,CAAC;AACjI,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACxD,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAC9C,mHAAmH;AACnH,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,GAAG,IAAI,CAAC;AAC/C,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,EAAE,QAAQ,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAW,CAAC;AAC7K,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,YAAY,CAAC;IACxC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IACrG,kBAAkB,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK;IAC7F,gBAAgB,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK;IACzG,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,CAAC;CAC9F,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,KAAK;IAC7H,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;AAChJ,gGAAgG;AAChG,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC;IACjC,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC;IACxE,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;CACzH,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;AAC5F,iGAAiG;AACjG,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,mBAAmB,CAAC,CAAC;AACvK,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,yDAAyD,CAAC,CAAC;AAC1G,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,uBAAuB,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AACtL,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AACtL,yHAAyH;AACzH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAClJ,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI;IAChF,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC9G,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AACzG,MAAM,KAAK,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC;AAC9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC;IACzC,CAAC,CAAC,YAAY,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC/D,CAAC,CAAC,YAAY,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACzH,CAAC,CAAC,YAAY,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;CAClI,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI;IAC9F,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK;IAC5G,gBAAgB,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AACxE,kGAAkG;AAClG,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;IACpI,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IACrD,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACxH,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,qBAAqB,EAAE,4BAA4B,CAAC,CAAC;AAC7J,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW;IAC1J,WAAW,EAAE,cAAc,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,mBAAmB,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AACrF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,iBAAiB,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;QACjI,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,wCAAwC,CAAC,EAAE,CAAC;QACnH,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3D,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;QACjE,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;KAC5D,CAAC,EAAE,CAAC,CAAC;AACN,MAAM,WAAW,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC7E,MAAM,KAAK,GAAG,CAAwC,IAAO,EAAE,OAAU,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;AACrL,MAAM,KAAK,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;AACxJ,MAAM,OAAO,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,KAAK;IAC3I,yFAAyF;IACzF,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAC1D,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1G,MAAM,eAAe,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,uBAAuB,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;AAChK,MAAM,SAAS,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,oBAAoB,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACxJ,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC;IACvC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,mBAAmB,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAClI,KAAK,CAAC,SAAS,EAAE,aAAa,CAAC,EAAE,KAAK,CAAC,QAAQ,EAAE,YAAY,CAAC,EAAE,KAAK,CAAC,WAAW,EAAE,SAAS,CAAC;IAC7F,KAAK,CAAC,mBAAmB,EAAE,mBAAmB,CAAC,EAAE,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC;IAC5E,8FAA8F;IAC9F,KAAK,CAAC,gBAAgB,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,gBAAgB,EAAE,eAAe,CAAC;IAC9G,KAAK,CAAC,gBAAgB,EAAE,mBAAmB,CAAC;CAC7C,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC;IACvC,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,UAAU,EAAE,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,EAAE,aAAa,CAAC;IAC7F,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,mBAAmB,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAChI,KAAK,CAAC,kBAAkB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/J,KAAK,CAAC,QAAQ,EAAE,gBAAgB,CAAC,EAAE,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9D,KAAK,CAAC,kBAAkB,EAAE,eAAe,CAAC,EAAE,KAAK,CAAC,gBAAgB,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;CACjH,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAsB,EAAkB,EAAE,CAAC,SAAS,CAAC,iBAAiB,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;AACjI,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAsB,EAAkB,EAAE,CAAC,SAAS,CAAC,iBAAiB,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;AACjI,MAAM,UAAU,iBAAiB,CAAC,KAAqB,IAAY,OAAO,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpI,MAAM,UAAU,iBAAiB,CAAC,KAAqB,IAAY,OAAO,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpI,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAc,EAAoB,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;AACjG,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAc,EAA2B,EAAE,CAAC,SAAS,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAC"}

package/dist/hub/quota.d.ts

@@ -0,0 +1,24 @@
+import type { HubCore } from "./http/core.js";
+import type { HubLinkContext } from "./server.js";
+import type { HubExposureQuota, HubQuota, HubRequestContext, HubRoom } from "./types.js";
+export declare class HubQuotaService {
+    private readonly core;
+    private readonly links;
+    private readonly values;
+    private readonly pending;
+    constructor(core: HubCore);
+    noteLink(link: HubLinkContext): void;
+    receive(raw: HubExposureQuota, link: HubLinkContext): void;
+    /** Called only after the caller's room/catalog authorization. Hidden always omits the whole value. */
+    projection(exposureId: string): {
+        quota?: HubQuota;
+    };
+    visible(exposureId: string): boolean;
+    roomProjection(room: HubRoom): {
+        quota?: HubQuota;
+    };
+    setVisible(ctx: HubRequestContext, exposureId: string, revision: number, visible: boolean): Promise<void>;
+    prune(): void;
+    private cancelPending;
+    close(): void;
+}

package/dist/hub/quota.js

@@ -0,0 +1,112 @@
+/** Hub quota is a volatile hint, never audit content or exposure consent. Only visibility is durable. */
+import { exposureOf, grantApplies, grantOf, readExposure, readGrant } from "./catalog.js";
+import { personKeyString } from "./identity.js";
+import { exposureQuotaSchema } from "./protocol.js";
+import { HubProtocolError, validated } from "./validation.js";
+import { HUB_QUOTA_CAPABILITY, HUB_QUOTA_INTERVAL_MS } from "./member/quota.js";
+export class HubQuotaService {
+    core;
+    links = new Map();
+    values = new Map();
+    pending = new Map();
+    constructor(core) {
+        this.core = core;
+    }
+    noteLink(link) {
+        const old = this.links.get(link.fleetId);
+        if (old && old.linkEpoch > link.linkEpoch)
+            return;
+        if (old !== link) {
+            for (const [id, value] of this.values)
+                if (value.link.fleetId === link.fleetId) {
+                    this.values.delete(id);
+                    this.cancelPending(id);
+                }
+            this.links.set(link.fleetId, link);
+        }
+    }
+    receive(raw, link) {
+        if (!link.current() || !link.features.has(HUB_QUOTA_CAPABILITY) || !link.features.has("welcome-caps-v1"))
+            throw new HubProtocolError("denied");
+        const input = validated(exposureQuotaSchema, raw);
+        this.core.atomic(db => {
+            const exposure = readExposure(db, input.exposureId);
+            if (!exposure || exposure.fleet_id !== link.fleetId || exposure.owner !== personKeyString(link.owner)
+                || exposure.state === "withdrawn")
+                throw new HubProtocolError("denied");
+            const old = this.values.get(input.exposureId), now = this.core.now();
+            this.cancelPending(input.exposureId);
+            if (old?.link === link && old.quota.band === input.quota.band)
+                return;
+            if (old?.link === link && now >= old.at && now - old.at < HUB_QUOTA_INTERVAL_MS) {
+                // Arrival jitter must not drop the only changed-band update forever. Coalesce the latest, then recheck its link.
+                const timer = setTimeout(() => {
+                    this.pending.delete(input.exposureId);
+                    try {
+                        this.receive(input, link);
+                    }
+                    catch { /* retired or withdrawn while waiting */ }
+                }, HUB_QUOTA_INTERVAL_MS - (now - old.at));
+                timer.unref?.();
+                this.pending.set(input.exposureId, { link, timer });
+                return;
+            }
+            this.values.set(input.exposureId, { link, quota: structuredClone(input.quota), at: now });
+        });
+    }
+    /** Called only after the caller's room/catalog authorization. Hidden always omits the whole value. */
+    projection(exposureId) {
+        return this.core.atomic(db => {
+            const setting = db.prepare("SELECT visible FROM hub_quota_preferences WHERE exposure_id=?").get(exposureId);
+            if (setting?.visible === 0)
+                return {};
+            const e = readExposure(db, exposureId), value = this.values.get(exposureId);
+            const link = e ? this.links.get(e.fleet_id) : null;
+            if (!e || e.state === "withdrawn" || !link?.current() || value?.link !== link)
+                return { quota: { band: "unknown" } };
+            // A passed reset cannot still promise capacity. The next changed band from the member replaces this hint.
+            if (value.quota.resetsAt !== undefined && value.quota.resetsAt <= this.core.now())
+                return { quota: { band: "unknown" } };
+            return { quota: structuredClone(value.quota) };
+        });
+    }
+    visible(exposureId) {
+        return this.core.atomic(db => db.prepare("SELECT visible FROM hub_quota_preferences WHERE exposure_id=?").get(exposureId)?.visible !== 0);
+    }
+    roomProjection(room) {
+        const allowed = this.core.atomic(db => {
+            const e = readExposure(db, room.exposureId), g = readGrant(db, room.grantId);
+            return room.state === "active" && !!e && !!g && exposureOf(e).state === "published"
+                && grantApplies(grantOf(g), exposureOf(e), room.asker, this.core.now()) && grantOf(g).permissions.includes("read-own-room");
+        });
+        return allowed ? this.projection(room.exposureId) : {};
+    }
+    async setVisible(ctx, exposureId, revision, visible) {
+        const owner = personKeyString(await ctx.requirePerson());
+        this.core.atomic(db => {
+            const e = readExposure(db, exposureId);
+            if (!e || e.owner !== owner)
+                throw new HubProtocolError("not-found");
+            if (e.revision !== revision)
+                throw new HubProtocolError("conflict");
+            db.prepare(`INSERT INTO hub_quota_preferences(exposure_id, visible) VALUES(?,?)
+        ON CONFLICT(exposure_id) DO UPDATE SET visible=excluded.visible`).run(exposureId, visible ? 1 : 0);
+        });
+    }
+    prune() {
+        this.core.atomic(db => {
+            for (const id of this.values.keys()) {
+                const e = readExposure(db, id);
+                if (!e || e.state === "withdrawn") {
+                    this.values.delete(id);
+                    this.cancelPending(id);
+                }
+            }
+        });
+    }
+    cancelPending(id) { const p = this.pending.get(id); if (p)
+        clearTimeout(p.timer); this.pending.delete(id); }
+    close() { for (const id of this.pending.keys())
+        this.cancelPending(id); this.links.clear(); this.values.clear(); }
+}
+//# sourceMappingURL=quota.js.map

package/dist/hub/quota.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota.js","sourceRoot":"","sources":["../../src/hub/quota.ts"],"names":[],"mappings":"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"}

package/dist/hub/representative.d.ts

@@ -0,0 +1,141 @@
+import type Database from "better-sqlite3";
+import { type HubMemberFiles } from "./member/attachments.js";
+import { type HubMemberJournal, type HubRestrictedOutbox } from "./member-journal.js";
+import type { HubAuthorizationLease, HubAuthorizationRequest, HubServerFrame, HubMemberFrame } from "./types.js";
+import type { HubLocalExposure, HubExecutionReadiness } from "./execution/service.js";
+import type { HubExecutionAttentionInput } from "../needs-you.js";
+/** The S3 agent tuple (one copy, S3c's): routing, readiness and the store can never disagree. */
+export { HUB_AGENT_MODE as HUB_AGENT_PROVIDER, agentPolicyDigest, isAgentDescriptor as isAgentTuple } from "./member/agent-mode.js";
+/** The reserved report_result target for Hub answers. Only a live Hub-issued correlation id from its agent matches. */
+export { HUB_REPORT_TARGET, type HubReportOutcome } from "../hub-report-target.js";
+import { type HubReportExtras, type HubReportOutcome } from "../hub-report-target.js";
+export declare const HUB_ANSWER_MAX: number;
+export declare function migrateHubRepresentative(db: Database.Database): void;
+export declare const HUB_REPRESENTATIVE_MIGRATION: Readonly<{
+    component: "s5-representative";
+    version: 1;
+    up: typeof migrateHubRepresentative;
+}>;
+/** The member binding as createMemberBinding() hands it out (captured per call). */
+export interface HubRepresentativeBinding {
+    fleetId: string;
+    owner: {
+        realm: string;
+        objectId: string;
+    };
+    linkEpoch: number;
+    revocationVersion: number;
+    current(): boolean;
+}
+export interface HubRepresentativeLink {
+    linkEpoch: number;
+    current(): boolean;
+    /** The link's enabled optional features (attachments-v1 …); absent or empty: none. */
+    readonly features?: ReadonlySet<string>;
+    exchange(frame: HubMemberFrame, responseType: HubServerFrame["type"]): Promise<HubServerFrame>;
+}
+export interface HubRepresentativeDelivery {
+    agent: string;
+    correlationId: string;
+    text: string;
+    /** Run by the fleet immediately before the IPC hand-off; false sends nothing. */
+    beforeInput(): Promise<boolean>;
+    /** The fleet's own fence through wake/idle/hand-off. */
+    stillCurrent(): boolean;
+}
+export interface HubRepresentativeOptions {
+    db: Database.Database;
+    journal: HubMemberJournal;
+    binding(): HubRepresentativeBinding;
+    /** The committed local mapping (null: none or withdrawn). */
+    localExposure(id: string): HubLocalExposure | null;
+    /** The agent's current lifecycle token (name generation, backend, folder…); null: not a deliverable agent now. */
+    agentToken(agent: string): string | null;
+    authorize(request: HubAuthorizationRequest): Promise<HubAuthorizationLease>;
+    /** The member link, once a handshake completed on it (null: offline). */
+    link(): HubRepresentativeLink | null;
+    deliver(input: HubRepresentativeDelivery): Promise<boolean>;
+    /** attachments-v1 files: into the agent's inbox for a question, out of the agent's own paths for an answer. */
+    files?: HubMemberFiles;
+    audit(event: {
+        action: string;
+        result: "completed" | "held" | "denied";
+        messageId?: string;
+        exposureId?: string;
+        reasonCode?: string;
+    }, db: Database.Database): void;
+    attentionChanged(): void;
+    log(level: "info" | "warn", message: string, meta?: Record<string, unknown>): void;
+    now?: () => number;
+}
+export declare class HubRepresentativeExecution {
+    private readonly options;
+    private closed;
+    private recovered;
+    private readonly running;
+    private receiptsTail;
+    constructor(options: HubRepresentativeOptions);
+    private now;
+    private row;
+    private setState;
+    /** The exposure, consent and agent lifecycle the question was admitted under — all still exactly current. */
+    private currentFor;
+    private consentToken;
+    private fenceOf;
+    /** Readiness for a published mapping: the agent tuple, this owner/fleet, the agent deliverable now. */
+    readiness(exposureId: string, expectedRevision: number): HubExecutionReadiness;
+    /**
+     * Capability check for a candidate. S3c asks it again inside the atomic publish transaction: there (only), the agent's
+     * current lifecycle token is recorded against the candidate's consent id, so a later replacement, retarget or mode
+     * change no longer matches it and needs an explicit republish.
+     */
+    readinessCandidate(candidate: HubLocalExposure): HubExecutionReadiness;
+    private ready;
+    /** No provider exists in P1: nothing to explain. */
+    providerReason(): null;
+    /** S1's journal outbox: the unique source row, in the journal's own admission transaction. */
+    restrictedOutbox(): HubRestrictedOutbox;
+    /**
+     * Startup. The journal's own recovery runs first (queued + input intent → uncertain). Then a row that was dispatching
+     * goes back to the queue ONLY if the journal still has it queued with no input intent (a crash between the intent and
+     * the representative's own transition is uncertain and held, never a fresh queue item); anything past it is held.
+     */
+    recover(): void;
+    /**
+     * Deliver queued questions the link can authorize now (after commits, on each completed handshake, and again as each
+     * dispatch settles, so a backlog larger than one page keeps draining). Input-bearing work is never picked up again.
+     */
+    pump(): void;
+    /** The row's current state from the database (another path — fence, report — may have moved it). */
+    private refresh;
+    private dispatch;
+    /** The fleet's last step before input (at the connected hand-off): consent and lifecycle again, the begin lease, spent at once. */
+    private beforeInput;
+    /**
+     * The outbound hook: a report_result to HUB_REPORT_TARGET. Returns null when the correlation id is not a live Hub id
+     * issued to this caller (the call then takes its ordinary route); otherwise consumes it once and releases the answer.
+     * callerCurrent: the reporting daemon generation is still the agent's current one (asked again before every release step).
+     */
+    report(input: {
+        correlationId: string;
+        caller: string;
+        text: string;
+        callerCurrent?: () => boolean;
+        extras?: HubReportExtras;
+    }): Promise<HubReportOutcome> | null;
+    private release;
+    /** Local evidence to the Hub, in order, each ACK recorded. A failure waits for the next handshake (it sends the rest). */
+    private pushReceipts;
+    private question;
+    /** A required audit record (its own transaction): a failure throws to the caller. */
+    private auditRequired;
+    /** A hold always lands (state first); its audit record is attempted and a failure is logged. */
+    private hold;
+    private uncertain;
+    /** The agent's daemon could not get the question into its pane after accepting it: uncertain, never resent. */
+    deliveryFailed(correlationId: string, agent: string): void;
+    /** Off / withdraw / revoke / link replacement for one message: its correlation id stops being live at once. */
+    fence(messageId: string, reasonCode?: string): void;
+    attentionItems(): HubExecutionAttentionInput[];
+    close(): Promise<void>;
+}