@byollm/protocol 0.1.0-alpha.85 → 0.1.0-alpha.87

package/README.md

@@ -1,5 +1,5 @@
 > [!WARNING]
-> **Alpha (`0.1.0-alpha.85`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.87`) — under active development. Don't use this yet.**
 >
 > Install it deliberately: `npm install @byollm/protocol@alpha`.
 >

package/dist/index.d.ts

@@ -1828,6 +1828,39 @@ declare const MAX_ENVELOPE_BYTES: number;
  * this function is that one number answers both questions.
  */
 declare function envelopeBytes(envelope: unknown): number;
+/**
+ * A size somebody can act on, rounded **up** and only ever up.
+ *
+ * The rounding rule, in one place, because it has now been got wrong twice —
+ * B072. `toFixed` rounds to nearest, so a message one byte over the line
+ * printed "this message is 10.5 MB and the limit is 10.5 MB": a refusal that
+ * reads as a contradiction, given to somebody who now has no idea what to
+ * change.
+ *
+ * The relay found that, fixed it, and wrote the reasoning down beside the
+ * fix. The SDK's refusal then rediscovered the identical bug, because it
+ * copied the SENTENCE rather than the function — which is the same shape as
+ * `MAX_BODY_BYTES` diverging from `MAX_ENVELOPE_BYTES`, and the same answer:
+ * neither side holds the rule.
+ *
+ * Up is also the honest direction. Understating how far over a message is
+ * sends somebody to trim a hundred bytes off something that needs to lose a
+ * megabyte; overstating by a tenth costs them nothing.
+ */
+declare function describeBytes(bytes: number): string;
+/**
+ * What a message that is too big is told, minus anything about pricing.
+ *
+ * Shared because both planes refuse the same thing for the same reason. What
+ * is NOT shared is the relay's "every plan has the same ceiling" — a hosted
+ * sentence, and meaningless to somebody self-hosting the direct lane, where
+ * there are no plans. One rule, two audiences: the rule travels, the words
+ * about our billing do not.
+ */
+declare function tooLargeMessage(input: {
+    readonly bytes: number;
+    readonly limit: number;
+}): string;
 /** Where the bucket boundaries sit, in characters of payload text. */
 declare const SIZE_CLASS_LIMITS: Readonly<{
     small: 4000;
@@ -2842,4 +2875,4 @@ declare const MUST_IDS: readonly ("PAIR_ONE_USER" | "PAIR_INTERACTIVE" | "PAIR_C
 /** Every MUST verified a particular way. */
 declare function mustsVerifiedBy(kind: MustVerification): MustId[];
 
-export { ABOUT, ABOUT_SHORT, ABOUT_SHORT_LEDE, ABOUT_SHORT_TAIL, AUDIENCES, Audience, BACKENDS, BACKEND_CLASSES, BACKEND_IDS, BackendClass, BackendCost, type BackendDescriptor, type BackendId, BackendIdSchema, CLOCK_ATTRIBUTION_MS, CLOCK_SKEW_WARN_MS, Capability, CapabilityMatrix, ChatMessage, ChatPayload, ClaimRequest, ClaimResponse, ClaimedJob, ClaimedStub, DeliveredResult, ENCRYPTION_KEY_CONTEXT, ENDPOINTS, ENVELOPE_MAX_AGE_MS, ERROR_STATUS, type Endpoint, type EnvelopeContext, EnvelopeDirection, type EnvelopeFailure, FetchRequest, FetchResponse, type FloorRefusal, GRANT_CONTEXT, GRANT_MAX_AGE_MS, GRANT_SIGNED_FIELDS, GeneratePayload, type GrantClaims, GrantRef, type GrantRefusal, HeartbeatRequest, HeartbeatResponse, JOB_KINDS, JobKind, JobOutcome, JobPayload, JobRefused, JobResultCanceled, JobResultError, JobResultOk, JobState, JobStub, KindedPayload, Lease, MAX_CLOCK_SKEW_MS, MAX_ENVELOPE_BYTES, MAX_PURPOSES, MAX_SUCCESSION_CHAIN, MIN_PROTOCOL_VERSION, MUSTS, MUST_IDS, Manifest, type MatchDaemon, type MatchJob, MatchRefusal, type MatchResult, type Must, type MustEnforcer, type MustId, type MustVerification, type MustVerifiedBy, OFFER_SCOPES, OfferScope, type OpenResult, PAYLOAD_LIMITS, PROTOCOL_PREFIX, PROTOCOL_VERSION, PairPollRequest, PairPollResponse, PairRequest, PairStartRequest, PairStartResponse, type PayloadFor, PublicIdentity, Purpose, REFUSAL_MESSAGES, RESERVED_PURPOSE, RETIREMENT_WINDOW_MS, RefusalReason, ReleaseRequest, ReleaseResponse, RequestSignature, ResultDisposition, ResultProvenance, ResultRequest, ResultResponse, RunMetadata, SIZE_CLASSES, SIZE_CLASS_LIMITS, SUCCESSION_CONTEXT, SUPPORTED_PROTOCOL_VERSIONS, SealedEnvelope, SealedOutcome, type SignatureFailure, SignedGrant, SizeClass, type SpendConsent, StoredKeys, Succession, type SuccessionFailure, type SuccessionWalk, TERMINAL_STATES, UPDATE_OFFER_SINCE, UPGRADE_COMMAND, type VersionRefusal, WireError, WireErrorCode, WithheldKind, backendDescriptor, backendName, canTransition, canonicalRequest, checkDaemonFloor, checkProtocolVersion, classifyCost, compareVersions, cryptoReady, declaredVersion, effectiveOfferScope, envelopeBytes, fingerprint, generateKeys, grantStatement, isBackendId, isCloudTaggedModel, isJobKind, isLocalHost, isTerminal, keyId, kindsOf, matchAudience, mayOfferUpdate, mentionsWireField, mustsVerifiedBy, open, payloadTextLength, provenanceFor, publicIdentityOf, resolveCost, seal, signGrant, signRequest, signSiteRequest, signSuccession, signWith, singlePurposeManifest, sizeClassCeiling, sizeClassOf, successionStatement, updateOfferFor, verifyGrant, verifyLink, verifyPublicIdentity, verifyRequest, verifySiteRequest, verifyWith, walkSuccession, withoutComments };
+export { ABOUT, ABOUT_SHORT, ABOUT_SHORT_LEDE, ABOUT_SHORT_TAIL, AUDIENCES, Audience, BACKENDS, BACKEND_CLASSES, BACKEND_IDS, BackendClass, BackendCost, type BackendDescriptor, type BackendId, BackendIdSchema, CLOCK_ATTRIBUTION_MS, CLOCK_SKEW_WARN_MS, Capability, CapabilityMatrix, ChatMessage, ChatPayload, ClaimRequest, ClaimResponse, ClaimedJob, ClaimedStub, DeliveredResult, ENCRYPTION_KEY_CONTEXT, ENDPOINTS, ENVELOPE_MAX_AGE_MS, ERROR_STATUS, type Endpoint, type EnvelopeContext, EnvelopeDirection, type EnvelopeFailure, FetchRequest, FetchResponse, type FloorRefusal, GRANT_CONTEXT, GRANT_MAX_AGE_MS, GRANT_SIGNED_FIELDS, GeneratePayload, type GrantClaims, GrantRef, type GrantRefusal, HeartbeatRequest, HeartbeatResponse, JOB_KINDS, JobKind, JobOutcome, JobPayload, JobRefused, JobResultCanceled, JobResultError, JobResultOk, JobState, JobStub, KindedPayload, Lease, MAX_CLOCK_SKEW_MS, MAX_ENVELOPE_BYTES, MAX_PURPOSES, MAX_SUCCESSION_CHAIN, MIN_PROTOCOL_VERSION, MUSTS, MUST_IDS, Manifest, type MatchDaemon, type MatchJob, MatchRefusal, type MatchResult, type Must, type MustEnforcer, type MustId, type MustVerification, type MustVerifiedBy, OFFER_SCOPES, OfferScope, type OpenResult, PAYLOAD_LIMITS, PROTOCOL_PREFIX, PROTOCOL_VERSION, PairPollRequest, PairPollResponse, PairRequest, PairStartRequest, PairStartResponse, type PayloadFor, PublicIdentity, Purpose, REFUSAL_MESSAGES, RESERVED_PURPOSE, RETIREMENT_WINDOW_MS, RefusalReason, ReleaseRequest, ReleaseResponse, RequestSignature, ResultDisposition, ResultProvenance, ResultRequest, ResultResponse, RunMetadata, SIZE_CLASSES, SIZE_CLASS_LIMITS, SUCCESSION_CONTEXT, SUPPORTED_PROTOCOL_VERSIONS, SealedEnvelope, SealedOutcome, type SignatureFailure, SignedGrant, SizeClass, type SpendConsent, StoredKeys, Succession, type SuccessionFailure, type SuccessionWalk, TERMINAL_STATES, UPDATE_OFFER_SINCE, UPGRADE_COMMAND, type VersionRefusal, WireError, WireErrorCode, WithheldKind, backendDescriptor, backendName, canTransition, canonicalRequest, checkDaemonFloor, checkProtocolVersion, classifyCost, compareVersions, cryptoReady, declaredVersion, describeBytes, effectiveOfferScope, envelopeBytes, fingerprint, generateKeys, grantStatement, isBackendId, isCloudTaggedModel, isJobKind, isLocalHost, isTerminal, keyId, kindsOf, matchAudience, mayOfferUpdate, mentionsWireField, mustsVerifiedBy, open, payloadTextLength, provenanceFor, publicIdentityOf, resolveCost, seal, signGrant, signRequest, signSiteRequest, signSuccession, signWith, singlePurposeManifest, sizeClassCeiling, sizeClassOf, successionStatement, tooLargeMessage, updateOfferFor, verifyGrant, verifyLink, verifyPublicIdentity, verifyRequest, verifySiteRequest, verifyWith, walkSuccession, withoutComments };

package/dist/index.js

@@ -632,6 +632,83 @@ function verifyGrant(input) {
   ) ? null : "bad-signature";
 }
 
+// src/json-size.ts
+function jsonLength(value) {
+  try {
+    return count(value, /* @__PURE__ */ new Set());
+  } catch {
+    return void 0;
+  }
+}
+var OutOfDomain = class extends Error {
+};
+function bail() {
+  throw new OutOfDomain("not a JSON value");
+}
+function count(value, seen) {
+  if (value === null) return 4;
+  switch (typeof value) {
+    case "boolean":
+      return value ? 4 : 5;
+    // true / false
+    case "number":
+      return Number.isFinite(value) ? String(value).length : 4;
+    case "string":
+      return stringLength(value);
+    case "object":
+      break;
+    default:
+      return bail();
+  }
+  const object = value;
+  if (seen.has(object)) return bail();
+  seen.add(object);
+  try {
+    if (Array.isArray(object)) {
+      let total2 = 2 + Math.max(0, object.length - 1);
+      for (const element of object) {
+        total2 += element === void 0 || typeof element === "function" ? 4 : count(element, seen);
+      }
+      return total2;
+    }
+    if ("toJSON" in object) return bail();
+    const proto = Object.getPrototypeOf(object);
+    if (proto !== Object.prototype) return bail();
+    let total = 2;
+    let first = true;
+    for (const [key, entry] of Object.entries(object)) {
+      if (entry === void 0 || typeof entry === "function") continue;
+      total += (first ? 0 : 1) + stringLength(key) + 1 + count(entry, seen);
+      first = false;
+    }
+    return total;
+  } finally {
+    seen.delete(object);
+  }
+}
+function stringLength(text) {
+  let total = 2;
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+    if (code === 34 || code === 92) {
+      total += 2;
+    } else if (code < 32) {
+      total += code === 8 || code === 9 || code === 10 || code === 12 || code === 13 ? 2 : 6;
+    } else if (code >= 55296 && code <= 57343) {
+      const paired = code <= 56319 && index + 1 < text.length && text.charCodeAt(index + 1) >= 56320 && text.charCodeAt(index + 1) <= 57343;
+      if (paired) {
+        total += 2;
+        index += 1;
+      } else {
+        total += 6;
+      }
+    } else {
+      total += 1;
+    }
+  }
+  return total;
+}
+
 // src/kinds.ts
 import { z as z6 } from "zod";
 var PAYLOAD_LIMITS = Object.freeze({
@@ -902,9 +979,17 @@ var SizeClass = z7.enum(["small", "medium", "large", "unbounded"]);
 var SIZE_CLASSES = Object.freeze(SizeClass.options);
 var MAX_ENVELOPE_BYTES = 10 * 1024 * 1024;
 function envelopeBytes(envelope) {
+  const counted = jsonLength(envelope);
+  if (counted !== void 0) return counted;
   const serialised = JSON.stringify(envelope);
   return serialised === void 0 ? 0 : serialised.length;
 }
+function describeBytes(bytes) {
+  return `${(Math.ceil(bytes / (1024 * 1024) * 10) / 10).toFixed(1)} MB`;
+}
+function tooLargeMessage(input) {
+  return `this message is ${describeBytes(input.bytes)} and the limit is ${describeBytes(input.limit)} \u2014 it is a limit on one message rather than on how many you send. Split the work into smaller jobs and send them separately.`;
+}
 var SIZE_CLASS_LIMITS = Object.freeze({
   small: 4e3,
   medium: 64e3,
@@ -2627,6 +2712,7 @@ export {
   compareVersions,
   cryptoReady,
   declaredVersion,
+  describeBytes,
   effectiveOfferScope,
   envelopeBytes,
   fingerprint,
@@ -2658,6 +2744,7 @@ export {
   sizeClassCeiling,
   sizeClassOf,
   successionStatement,
+  tooLargeMessage,
   updateOfferFor,
   verifyGrant,
   verifyLink,