@fitzzero/quickdraw-core 5.0.1 → 5.1.1

package/dist/{chunk-HQ6WIRE2.js → chunk-SHEGLZEP.js}

@@ -13,15 +13,15 @@ import {
   searchTargetOf,
   streamMaxOf,
   viewPredicate
-} from "./chunk-O2PWC2YW.js";
+} from "./chunk-OECZPRPW.js";
 import {
   MAX_SUBSCRIBE_IDS,
   PROTOCOL_VERSION,
   QUICKDRAW_VERSION
-} from "./chunk-WVIRXYI4.js";
+} from "./chunk-VSQBHPWH.js";
 import {
   isScopedStream
-} from "./chunk-5YRQ26LF.js";
+} from "./chunk-RT6OILOI.js";
 import {
   buildCaller,
   methodKey,
@@ -849,4 +849,4 @@ function createMockClient(contracts, options = {}) {
 export {
   createMockClient
 };
-//# sourceMappingURL=chunk-HQ6WIRE2.js.map
+//# sourceMappingURL=chunk-SHEGLZEP.js.map

package/dist/{chunk-WVIRXYI4.js → chunk-VSQBHPWH.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-4YO5H5ON.js";
 
 // src/version.ts
-var QUICKDRAW_VERSION = "5.0.1";
+var QUICKDRAW_VERSION = "5.1.1";
 
 // src/contract/names.ts
 function entityRoom(service, id, level) {
@@ -127,4 +127,4 @@ export {
   MAX_SUBSCRIBE_IDS,
   MAX_SCOPE_LENGTH
 };
-//# sourceMappingURL=chunk-WVIRXYI4.js.map
+//# sourceMappingURL=chunk-VSQBHPWH.js.map

package/dist/{chunk-WVIRXYI4.js.map → chunk-VSQBHPWH.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts","../src/contract/names.ts","../src/protocol/version.ts","../src/contract/access.ts"],"sourcesContent":["/** The published version of `@fitzzero/quickdraw-core`. Kept in step with package.json. */\nexport const QUICKDRAW_VERSION = \"5.0.1\";\n","// Room and event names for protocol v5 (RFC 0003 sections 6, 7 and 8). Ported\n// from the 4.1 room helpers (4.1 `src/shared/types.ts:364-405`), which were\n// plain template strings so shared code could name a room without holding a\n// service instance. The 5.0 rooms live under a `qd:` prefix so they never\n// collide with an app's own rooms; the per-user room keeps its 4.1 name.\n\nimport type { AccessLevel } from \"./access\";\n\n/**\n * The room for one entity at one access tier: `qd:e:{service}:{id}@{level}`.\n * A subscriber joins the room for its own level, so a frame is built once and\n * stripped once per occupied tier.\n */\nexport function entityRoom(service: string, id: string, level: AccessLevel): string {\n  return `qd:e:${service}:${id}@${level}`;\n}\n\n/** The room for one scope of a collection: `qd:c:{service}:{collection}:{scope}`. */\nexport function collectionRoom(service: string, collection: string, scope: string): string {\n  return `qd:c:${service}:${collection}:${scope}`;\n}\n\n/** The room for a watched topic of a service: `qd:t:{service}:{topic}`. */\nexport function topicRoom(service: string, topic: string): string {\n  return `qd:t:${service}:${topic}`;\n}\n\n/**\n * The change topic of a whole service (RFC 0003 section 11.3): every flush\n * that changes one of its rows or collection scopes signals it.\n */\nexport const SERVICE_TOPIC = \"service\";\n\n/** The change topic of one scope of a collection: `{collection}:{scope}` (RFC 0003 section 11.3). */\nexport function collectionTopic(collection: string, scope: string): string {\n  return `${collection}:${scope}`;\n}\n\n/**\n * The room of a stream's feed (RFC 0003 section 12.5):\n * `qd:s:{service}:{stream}:{scope}` for one scope of a scoped stream, and\n * `qd:s:{service}:{stream}` for a global stream. Stream names hold no colon.\n */\nexport function streamRoom(service: string, stream: string, scope?: string): string {\n  return scope === undefined ? `qd:s:${service}:${stream}` : `qd:s:${service}:${stream}:${scope}`;\n}\n\n/** The room every authenticated socket of a user joins: `user:{userId}`, as in 4.1. */\nexport function userRoom(userId: string): string {\n  return `user:${userId}`;\n}\n\n/**\n * The prefixes of the rooms the framework manages: entity, collection, topic\n * and stream rooms (`qd:`) and user rooms (`user:`). `ctx.rooms.join` refuses\n * them; a socket enters those rooms only through their authorized paths.\n */\nexport const RESERVED_ROOM_PREFIXES: readonly string[] = Object.freeze([\"qd:\", \"user:\"]);\n\n/**\n * The reserved prefix `room` starts with (`qd:` or `user:`), or `undefined`\n * when an app room may have that name.\n */\nexport function reservedRoomPrefix(room: string): string | undefined {\n  return RESERVED_ROOM_PREFIXES.find((prefix) => room.startsWith(prefix));\n}\n\n/** Events a client sends to the server (RFC 0003 section 8.2). */\nexport const CLIENT_EVENTS = Object.freeze({\n  /** A method call: `{ id, s, m, i, v? }`, answered by ack. */\n  call: \"qd:call\",\n  /** Cancels an in-flight call: `{ id }`. */\n  cancel: \"qd:cancel\",\n  /** Subscribes to entities by id, with the revisions held. */\n  sub: \"qd:sub\",\n  /** Unsubscribes from entities. */\n  unsub: \"qd:unsub\",\n  /** Subscribes to a collection scope, or resumes it from a revision. */\n  collectionSub: \"qd:col:sub\",\n  /** Unsubscribes from a collection scope. */\n  collectionUnsub: \"qd:col:unsub\",\n  /** Loads collection items by id. */\n  collectionItems: \"qd:col:items\",\n  /** Joins a watched topic: `{ s, topic }`. */\n  watch: \"qd:watch\",\n  /** Leaves a watched topic. */\n  unwatch: \"qd:unwatch\",\n  /** Subscribes to a stream and receives its seed. */\n  streamSub: \"qd:stream:sub\",\n  /** Unsubscribes from a stream. */\n  streamUnsub: \"qd:stream:unsub\",\n  /** A fire-and-forget channel message, sent volatile: `[s, channel, payload]`. */\n  channel: \"qd:ch\",\n} as const);\n\n/** Events the server sends to a client (RFC 0003 section 8.3). */\nexport const SERVER_EVENTS = Object.freeze({\n  /** The handshake reply: `{ protocol, server, limits, features, userId, serviceAccess }`. */\n  hello: \"qd:hello\",\n  /** Entity frames: full update, patch or removal. */\n  entity: \"qd:e\",\n  /** Collection deltas, batched per flush. */\n  collection: \"qd:c\",\n  /** A watched topic changed; the client invalidates its queries. */\n  changed: \"qd:changed\",\n  /** Access to a subscription was revoked. */\n  revoked: \"qd:revoked\",\n  /** Stream items. */\n  stream: \"qd:stream\",\n  /** Typed custom room events declared in a contract's `events`. */\n  event: \"qd:event\",\n  /** Who is in an app room the socket is in: the list on joining, then each user who joins or leaves. */\n  presence: \"qd:presence\",\n  /** Reconnect within a jitter window. */\n  rotate: \"qd:rotate\",\n  /** The user's service grants changed. */\n  access: \"qd:access\",\n} as const);\n\n/** The name of an event a client sends. */\nexport type ClientEventName = (typeof CLIENT_EVENTS)[keyof typeof CLIENT_EVENTS];\n\n/** The name of an event the server sends. */\nexport type ServerEventName = (typeof SERVER_EVENTS)[keyof typeof SERVER_EVENTS];\n","// The protocol version and the connection handshake (RFC 0003 section 8.1).\n// A v5 client connects with `auth: { token, qd: { protocol: 5, client } }`.\n// The server answers with `qd:hello`, or refuses a client that names another\n// protocol with `PROTOCOL_MISMATCH` in the `connect_error` data, and one whose\n// authentication failed with `UNAUTHENTICATED` there. A client that sends no\n// `auth.qd` is a 4.x client, which only the legacy shim serves (section 8.5).\n// There is no capability negotiation: the version decides.\n\nimport type { AccessLevel } from \"../contract/access\";\nimport { isRecord } from \"./guards\";\n\n/** The wire protocol this package speaks. */\nexport const PROTOCOL_VERSION = 5;\n\n/** `auth.qd`: what a v5 client sends when it connects. */\nexport interface QdHandshake {\n  /** The protocol the client speaks. The server refuses any but its own. */\n  readonly protocol: number;\n  /** The client package's version, for logs. */\n  readonly client: string;\n}\n\n/** The Socket.IO `auth` a v5 client connects with. */\nexport interface HandshakeAuth {\n  /** The session token the server's `authenticate` reads. */\n  readonly token?: string;\n  /** The protocol the client speaks. A client without it is a 4.x client (RFC 0003 section 8.5). */\n  readonly qd: QdHandshake;\n}\n\n/**\n * True when `value` has the shape of `auth.qd`, whatever protocol it names.\n * Compare `protocol` with {@link PROTOCOL_VERSION} to decide whether to serve it.\n */\nexport function isQdHandshake(value: unknown): value is QdHandshake {\n  return isRecord(value) && Number.isInteger(value.protocol) && typeof value.client === \"string\";\n}\n\n/** The code in the `connect_error` data of a connection refused for its protocol. */\nexport const PROTOCOL_MISMATCH = \"PROTOCOL_MISMATCH\";\n\n/**\n * The `data` of the error a server refuses a connection with when the client\n * speaks another protocol, or none. It is not an `ErrorCode`: no call failed.\n */\nexport interface ProtocolMismatch {\n  readonly code: typeof PROTOCOL_MISMATCH;\n  /** The protocol the server speaks. */\n  readonly expected: number;\n}\n\n/** True when a `connect_error`'s `data` says the server speaks another protocol. */\nexport function isProtocolMismatch(value: unknown): value is ProtocolMismatch {\n  return isRecord(value) && value.code === PROTOCOL_MISMATCH && Number.isInteger(value.expected);\n}\n\n/**\n * The `data` of the error a server refuses a connection with when\n * authenticating it failed: the app's `authenticate` threw, so the\n * credentials are bad or could not be checked. A client tells it apart from\n * {@link ProtocolMismatch} by `code`; reconnecting needs other credentials.\n */\nexport interface AuthenticationRefused {\n  readonly code: \"UNAUTHENTICATED\";\n}\n\n/** True when a `connect_error`'s `data` says authenticating the connection failed. */\nexport function isAuthenticationRefused(value: unknown): value is AuthenticationRefused {\n  return isRecord(value) && value.code === \"UNAUTHENTICATED\";\n}\n\n/** The most ids one `qd:sub` may name (RFC 0003 section 6), as `qd:hello` announces it. */\nexport const MAX_SUBSCRIBE_IDS = 500;\n\n/** The longest collection scope value or change topic a frame may name, in characters. */\nexport const MAX_SCOPE_LENGTH = 256;\n\n/**\n * Each socket's lane of subscription events (`qd:sub`, `qd:col:sub`,\n * `qd:col:items`, `qd:watch`; RFC 0003 section 8.2), as `qd:hello` announces it.\n */\nexport interface HelloSubscriptionLimits {\n  /** Subscription events one socket may have running at once. */\n  readonly maxInFlight: number;\n  /** Subscription events one socket may have waiting; past that one fails with `RATE_LIMITED`. */\n  readonly maxQueued: number;\n}\n\n/** The limits a server announces in `qd:hello`, so a client can stay inside them. */\nexport interface HelloLimits {\n  /** Queries one socket may have running at once; more wait in a queue (RFC 0003 section 9). */\n  readonly maxInFlightQueries: number;\n  /** Queries one socket may have waiting; past that a query fails with `RATE_LIMITED`. */\n  readonly maxQueuedQueries: number;\n  /** Ids one `qd:sub` may name (RFC 0003 section 6). */\n  readonly maxSubscribeIds: number;\n  /**\n   * A call's default time limit in milliseconds, after which it fails with\n   * `TIMEOUT`. A v5 client waits this long plus 2 s for an answer, so a slow\n   * call ends with the server's `TIMEOUT` rather than its own.\n   */\n  readonly callTimeoutMs: number;\n  /** The socket's lane of subscription events. */\n  readonly subscriptions: HelloSubscriptionLimits;\n}\n\n/**\n * `qd:hello`: the server's answer to a v5 handshake, sent once per\n * connection, after the socket's listeners are in place. It says who the\n * socket acts for, so a client knows its user without another call.\n */\nexport interface HelloFrame {\n  /** The protocol the server speaks. */\n  readonly protocol: typeof PROTOCOL_VERSION;\n  /** The server package's version. */\n  readonly server: string;\n  /**\n   * This server's id: random, new each time a server starts. A client that\n   * reconnects to the same id came back after a blip, to another id to a\n   * restarted server (a game's world and clock start over) or, behind a\n   * cluster, to another node, each of which has its own.\n   */\n  readonly serverId: string;\n  /** What a client must stay within. */\n  readonly limits: HelloLimits;\n  /** Names of optional server features that are on. Informational only. */\n  readonly features: readonly string[];\n  /** The user the socket acts for, or `null` when it is anonymous. */\n  readonly userId: string | null;\n  /**\n   * The principal's service-wide grants when the socket connected, by\n   * service name: `{ taskService: \"Admin\" }`. Empty for an anonymous socket\n   * or a principal without grants. Later changes arrive as `qd:access`.\n   */\n  readonly serviceAccess: Readonly<Record<string, AccessLevel>>;\n}\n","// Access levels and access-control lists, unchanged from 4.1\n// (4.1 `src/shared/types.ts:7-14`). The level names are stored in app data\n// (`User.serviceAccess`, JSON access lists), so they never change.\n\nexport type AccessLevel = \"Public\" | \"Read\" | \"Moderate\" | \"Admin\";\n\n/** Every access level, lowest first. */\nexport const ACCESS_LEVELS: readonly AccessLevel[] = Object.freeze([\n  \"Public\",\n  \"Read\",\n  \"Moderate\",\n  \"Admin\",\n]);\n\n/** True when `value` is one of the four access level names. */\nexport function isAccessLevel(value: unknown): value is AccessLevel {\n  return typeof value === \"string\" && (ACCESS_LEVELS as readonly string[]).includes(value);\n}\n\nexport type ACE = {\n  userId: string;\n  level: AccessLevel;\n};\n\nexport type ACL = ACE[];\n"],"mappings":";;;;;AACO,IAAM,oBAAoB;;;ACY1B,SAAS,WAAW,SAAiB,IAAY,OAA4B;AAClF,SAAO,QAAQ,OAAO,IAAI,EAAE,IAAI,KAAK;AACvC;AAGO,SAAS,eAAe,SAAiB,YAAoB,OAAuB;AACzF,SAAO,QAAQ,OAAO,IAAI,UAAU,IAAI,KAAK;AAC/C;AAGO,SAAS,UAAU,SAAiB,OAAuB;AAChE,SAAO,QAAQ,OAAO,IAAI,KAAK;AACjC;AAMO,IAAM,gBAAgB;AAGtB,SAAS,gBAAgB,YAAoB,OAAuB;AACzE,SAAO,GAAG,UAAU,IAAI,KAAK;AAC/B;AAOO,SAAS,WAAW,SAAiB,QAAgB,OAAwB;AAClF,SAAO,UAAU,SAAY,QAAQ,OAAO,IAAI,MAAM,KAAK,QAAQ,OAAO,IAAI,MAAM,IAAI,KAAK;AAC/F;AAGO,SAAS,SAAS,QAAwB;AAC/C,SAAO,QAAQ,MAAM;AACvB;AAOO,IAAM,yBAA4C,OAAO,OAAO,CAAC,OAAO,OAAO,CAAC;AAMhF,SAAS,mBAAmB,MAAkC;AACnE,SAAO,uBAAuB,KAAK,CAAC,WAAW,KAAK,WAAW,MAAM,CAAC;AACxE;AAGO,IAAM,gBAAgB,OAAO,OAAO;AAAA;AAAA,EAEzC,MAAM;AAAA;AAAA,EAEN,QAAQ;AAAA;AAAA,EAER,KAAK;AAAA;AAAA,EAEL,OAAO;AAAA;AAAA,EAEP,eAAe;AAAA;AAAA,EAEf,iBAAiB;AAAA;AAAA,EAEjB,iBAAiB;AAAA;AAAA,EAEjB,OAAO;AAAA;AAAA,EAEP,SAAS;AAAA;AAAA,EAET,WAAW;AAAA;AAAA,EAEX,aAAa;AAAA;AAAA,EAEb,SAAS;AACX,CAAU;AAGH,IAAM,gBAAgB,OAAO,OAAO;AAAA;AAAA,EAEzC,OAAO;AAAA;AAAA,EAEP,QAAQ;AAAA;AAAA,EAER,YAAY;AAAA;AAAA,EAEZ,SAAS;AAAA;AAAA,EAET,SAAS;AAAA;AAAA,EAET,QAAQ;AAAA;AAAA,EAER,OAAO;AAAA;AAAA,EAEP,UAAU;AAAA;AAAA,EAEV,QAAQ;AAAA;AAAA,EAER,QAAQ;AACV,CAAU;;;ACzGH,IAAM,mBAAmB;AAsBzB,SAAS,cAAc,OAAsC;AAClE,SAAO,SAAS,KAAK,KAAK,OAAO,UAAU,MAAM,QAAQ,KAAK,OAAO,MAAM,WAAW;AACxF;AAGO,IAAM,oBAAoB;AAa1B,SAAS,mBAAmB,OAA2C;AAC5E,SAAO,SAAS,KAAK,KAAK,MAAM,SAAS,qBAAqB,OAAO,UAAU,MAAM,QAAQ;AAC/F;AAaO,SAAS,wBAAwB,OAAgD;AACtF,SAAO,SAAS,KAAK,KAAK,MAAM,SAAS;AAC3C;AAGO,IAAM,oBAAoB;AAG1B,IAAM,mBAAmB;;;ACpEzB,IAAM,gBAAwC,OAAO,OAAO;AAAA,EACjE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAGM,SAAS,cAAc,OAAsC;AAClE,SAAO,OAAO,UAAU,YAAa,cAAoC,SAAS,KAAK;AACzF;","names":[]}
+{"version":3,"sources":["../src/version.ts","../src/contract/names.ts","../src/protocol/version.ts","../src/contract/access.ts"],"sourcesContent":["/** The published version of `@fitzzero/quickdraw-core`. Kept in step with package.json. */\nexport const QUICKDRAW_VERSION = \"5.1.1\";\n","// Room and event names for protocol v5 (RFC 0003 sections 6, 7 and 8). Ported\n// from the 4.1 room helpers (4.1 `src/shared/types.ts:364-405`), which were\n// plain template strings so shared code could name a room without holding a\n// service instance. The 5.0 rooms live under a `qd:` prefix so they never\n// collide with an app's own rooms; the per-user room keeps its 4.1 name.\n\nimport type { AccessLevel } from \"./access\";\n\n/**\n * The room for one entity at one access tier: `qd:e:{service}:{id}@{level}`.\n * A subscriber joins the room for its own level, so a frame is built once and\n * stripped once per occupied tier.\n */\nexport function entityRoom(service: string, id: string, level: AccessLevel): string {\n  return `qd:e:${service}:${id}@${level}`;\n}\n\n/** The room for one scope of a collection: `qd:c:{service}:{collection}:{scope}`. */\nexport function collectionRoom(service: string, collection: string, scope: string): string {\n  return `qd:c:${service}:${collection}:${scope}`;\n}\n\n/** The room for a watched topic of a service: `qd:t:{service}:{topic}`. */\nexport function topicRoom(service: string, topic: string): string {\n  return `qd:t:${service}:${topic}`;\n}\n\n/**\n * The change topic of a whole service (RFC 0003 section 11.3): every flush\n * that changes one of its rows or collection scopes signals it.\n */\nexport const SERVICE_TOPIC = \"service\";\n\n/** The change topic of one scope of a collection: `{collection}:{scope}` (RFC 0003 section 11.3). */\nexport function collectionTopic(collection: string, scope: string): string {\n  return `${collection}:${scope}`;\n}\n\n/**\n * The room of a stream's feed (RFC 0003 section 12.5):\n * `qd:s:{service}:{stream}:{scope}` for one scope of a scoped stream, and\n * `qd:s:{service}:{stream}` for a global stream. Stream names hold no colon.\n */\nexport function streamRoom(service: string, stream: string, scope?: string): string {\n  return scope === undefined ? `qd:s:${service}:${stream}` : `qd:s:${service}:${stream}:${scope}`;\n}\n\n/** The room every authenticated socket of a user joins: `user:{userId}`, as in 4.1. */\nexport function userRoom(userId: string): string {\n  return `user:${userId}`;\n}\n\n/**\n * The prefixes of the rooms the framework manages: entity, collection, topic\n * and stream rooms (`qd:`) and user rooms (`user:`). `ctx.rooms.join` refuses\n * them; a socket enters those rooms only through their authorized paths.\n */\nexport const RESERVED_ROOM_PREFIXES: readonly string[] = Object.freeze([\"qd:\", \"user:\"]);\n\n/**\n * The reserved prefix `room` starts with (`qd:` or `user:`), or `undefined`\n * when an app room may have that name.\n */\nexport function reservedRoomPrefix(room: string): string | undefined {\n  return RESERVED_ROOM_PREFIXES.find((prefix) => room.startsWith(prefix));\n}\n\n/** Events a client sends to the server (RFC 0003 section 8.2). */\nexport const CLIENT_EVENTS = Object.freeze({\n  /** A method call: `{ id, s, m, i, v? }`, answered by ack. */\n  call: \"qd:call\",\n  /** Cancels an in-flight call: `{ id }`. */\n  cancel: \"qd:cancel\",\n  /** Subscribes to entities by id, with the revisions held. */\n  sub: \"qd:sub\",\n  /** Unsubscribes from entities. */\n  unsub: \"qd:unsub\",\n  /** Subscribes to a collection scope, or resumes it from a revision. */\n  collectionSub: \"qd:col:sub\",\n  /** Unsubscribes from a collection scope. */\n  collectionUnsub: \"qd:col:unsub\",\n  /** Loads collection items by id. */\n  collectionItems: \"qd:col:items\",\n  /** Joins a watched topic: `{ s, topic }`. */\n  watch: \"qd:watch\",\n  /** Leaves a watched topic. */\n  unwatch: \"qd:unwatch\",\n  /** Subscribes to a stream and receives its seed. */\n  streamSub: \"qd:stream:sub\",\n  /** Unsubscribes from a stream. */\n  streamUnsub: \"qd:stream:unsub\",\n  /** A fire-and-forget channel message, sent volatile: `[s, channel, payload]`. */\n  channel: \"qd:ch\",\n} as const);\n\n/** Events the server sends to a client (RFC 0003 section 8.3). */\nexport const SERVER_EVENTS = Object.freeze({\n  /** The handshake reply: `{ protocol, server, limits, features, userId, serviceAccess }`. */\n  hello: \"qd:hello\",\n  /** Entity frames: full update, patch or removal. */\n  entity: \"qd:e\",\n  /** Collection deltas, batched per flush. */\n  collection: \"qd:c\",\n  /** A watched topic changed; the client invalidates its queries. */\n  changed: \"qd:changed\",\n  /** Access to a subscription was revoked. */\n  revoked: \"qd:revoked\",\n  /** Stream items. */\n  stream: \"qd:stream\",\n  /** Typed custom room events declared in a contract's `events`. */\n  event: \"qd:event\",\n  /** Who is in an app room the socket is in: the list on joining, then each user who joins or leaves. */\n  presence: \"qd:presence\",\n  /** Reconnect within a jitter window. */\n  rotate: \"qd:rotate\",\n  /** The user's service grants changed. */\n  access: \"qd:access\",\n} as const);\n\n/** The name of an event a client sends. */\nexport type ClientEventName = (typeof CLIENT_EVENTS)[keyof typeof CLIENT_EVENTS];\n\n/** The name of an event the server sends. */\nexport type ServerEventName = (typeof SERVER_EVENTS)[keyof typeof SERVER_EVENTS];\n","// The protocol version and the connection handshake (RFC 0003 section 8.1).\n// A v5 client connects with `auth: { token, qd: { protocol: 5, client } }`.\n// The server answers with `qd:hello`, or refuses a client that names another\n// protocol with `PROTOCOL_MISMATCH` in the `connect_error` data, and one whose\n// authentication failed with `UNAUTHENTICATED` there. A client that sends no\n// `auth.qd` is a 4.x client, which only the legacy shim serves (section 8.5).\n// There is no capability negotiation: the version decides.\n\nimport type { AccessLevel } from \"../contract/access\";\nimport { isRecord } from \"./guards\";\n\n/** The wire protocol this package speaks. */\nexport const PROTOCOL_VERSION = 5;\n\n/** `auth.qd`: what a v5 client sends when it connects. */\nexport interface QdHandshake {\n  /** The protocol the client speaks. The server refuses any but its own. */\n  readonly protocol: number;\n  /** The client package's version, for logs. */\n  readonly client: string;\n}\n\n/** The Socket.IO `auth` a v5 client connects with. */\nexport interface HandshakeAuth {\n  /** The session token the server's `authenticate` reads. */\n  readonly token?: string;\n  /** The protocol the client speaks. A client without it is a 4.x client (RFC 0003 section 8.5). */\n  readonly qd: QdHandshake;\n}\n\n/**\n * True when `value` has the shape of `auth.qd`, whatever protocol it names.\n * Compare `protocol` with {@link PROTOCOL_VERSION} to decide whether to serve it.\n */\nexport function isQdHandshake(value: unknown): value is QdHandshake {\n  return isRecord(value) && Number.isInteger(value.protocol) && typeof value.client === \"string\";\n}\n\n/** The code in the `connect_error` data of a connection refused for its protocol. */\nexport const PROTOCOL_MISMATCH = \"PROTOCOL_MISMATCH\";\n\n/**\n * The `data` of the error a server refuses a connection with when the client\n * speaks another protocol, or none. It is not an `ErrorCode`: no call failed.\n */\nexport interface ProtocolMismatch {\n  readonly code: typeof PROTOCOL_MISMATCH;\n  /** The protocol the server speaks. */\n  readonly expected: number;\n}\n\n/** True when a `connect_error`'s `data` says the server speaks another protocol. */\nexport function isProtocolMismatch(value: unknown): value is ProtocolMismatch {\n  return isRecord(value) && value.code === PROTOCOL_MISMATCH && Number.isInteger(value.expected);\n}\n\n/**\n * The `data` of the error a server refuses a connection with when\n * authenticating it failed: the app's `authenticate` threw, so the\n * credentials are bad or could not be checked. A client tells it apart from\n * {@link ProtocolMismatch} by `code`; reconnecting needs other credentials.\n */\nexport interface AuthenticationRefused {\n  readonly code: \"UNAUTHENTICATED\";\n}\n\n/** True when a `connect_error`'s `data` says authenticating the connection failed. */\nexport function isAuthenticationRefused(value: unknown): value is AuthenticationRefused {\n  return isRecord(value) && value.code === \"UNAUTHENTICATED\";\n}\n\n/** The most ids one `qd:sub` may name (RFC 0003 section 6), as `qd:hello` announces it. */\nexport const MAX_SUBSCRIBE_IDS = 500;\n\n/** The longest collection scope value or change topic a frame may name, in characters. */\nexport const MAX_SCOPE_LENGTH = 256;\n\n/**\n * Each socket's lane of subscription events (`qd:sub`, `qd:col:sub`,\n * `qd:col:items`, `qd:watch`; RFC 0003 section 8.2), as `qd:hello` announces it.\n */\nexport interface HelloSubscriptionLimits {\n  /** Subscription events one socket may have running at once. */\n  readonly maxInFlight: number;\n  /** Subscription events one socket may have waiting; past that one fails with `RATE_LIMITED`. */\n  readonly maxQueued: number;\n}\n\n/** The limits a server announces in `qd:hello`, so a client can stay inside them. */\nexport interface HelloLimits {\n  /** Queries one socket may have running at once; more wait in a queue (RFC 0003 section 9). */\n  readonly maxInFlightQueries: number;\n  /** Queries one socket may have waiting; past that a query fails with `RATE_LIMITED`. */\n  readonly maxQueuedQueries: number;\n  /** Ids one `qd:sub` may name (RFC 0003 section 6). */\n  readonly maxSubscribeIds: number;\n  /**\n   * A call's default time limit in milliseconds, after which it fails with\n   * `TIMEOUT`. A v5 client waits this long plus 2 s for an answer, so a slow\n   * call ends with the server's `TIMEOUT` rather than its own.\n   */\n  readonly callTimeoutMs: number;\n  /** The socket's lane of subscription events. */\n  readonly subscriptions: HelloSubscriptionLimits;\n}\n\n/**\n * `qd:hello`: the server's answer to a v5 handshake, sent once per\n * connection, after the socket's listeners are in place. It says who the\n * socket acts for, so a client knows its user without another call.\n */\nexport interface HelloFrame {\n  /** The protocol the server speaks. */\n  readonly protocol: typeof PROTOCOL_VERSION;\n  /** The server package's version. */\n  readonly server: string;\n  /**\n   * This server's id: random, new each time a server starts. A client that\n   * reconnects to the same id came back after a blip, to another id to a\n   * restarted server (a game's world and clock start over) or, behind a\n   * cluster, to another node, each of which has its own.\n   */\n  readonly serverId: string;\n  /** What a client must stay within. */\n  readonly limits: HelloLimits;\n  /** Names of optional server features that are on. Informational only. */\n  readonly features: readonly string[];\n  /** The user the socket acts for, or `null` when it is anonymous. */\n  readonly userId: string | null;\n  /**\n   * The principal's service-wide grants when the socket connected, by\n   * service name: `{ taskService: \"Admin\" }`. Empty for an anonymous socket\n   * or a principal without grants. Later changes arrive as `qd:access`.\n   */\n  readonly serviceAccess: Readonly<Record<string, AccessLevel>>;\n}\n","// Access levels and access-control lists, unchanged from 4.1\n// (4.1 `src/shared/types.ts:7-14`). The level names are stored in app data\n// (`User.serviceAccess`, JSON access lists), so they never change.\n\nexport type AccessLevel = \"Public\" | \"Read\" | \"Moderate\" | \"Admin\";\n\n/** Every access level, lowest first. */\nexport const ACCESS_LEVELS: readonly AccessLevel[] = Object.freeze([\n  \"Public\",\n  \"Read\",\n  \"Moderate\",\n  \"Admin\",\n]);\n\n/** True when `value` is one of the four access level names. */\nexport function isAccessLevel(value: unknown): value is AccessLevel {\n  return typeof value === \"string\" && (ACCESS_LEVELS as readonly string[]).includes(value);\n}\n\nexport type ACE = {\n  userId: string;\n  level: AccessLevel;\n};\n\nexport type ACL = ACE[];\n"],"mappings":";;;;;AACO,IAAM,oBAAoB;;;ACY1B,SAAS,WAAW,SAAiB,IAAY,OAA4B;AAClF,SAAO,QAAQ,OAAO,IAAI,EAAE,IAAI,KAAK;AACvC;AAGO,SAAS,eAAe,SAAiB,YAAoB,OAAuB;AACzF,SAAO,QAAQ,OAAO,IAAI,UAAU,IAAI,KAAK;AAC/C;AAGO,SAAS,UAAU,SAAiB,OAAuB;AAChE,SAAO,QAAQ,OAAO,IAAI,KAAK;AACjC;AAMO,IAAM,gBAAgB;AAGtB,SAAS,gBAAgB,YAAoB,OAAuB;AACzE,SAAO,GAAG,UAAU,IAAI,KAAK;AAC/B;AAOO,SAAS,WAAW,SAAiB,QAAgB,OAAwB;AAClF,SAAO,UAAU,SAAY,QAAQ,OAAO,IAAI,MAAM,KAAK,QAAQ,OAAO,IAAI,MAAM,IAAI,KAAK;AAC/F;AAGO,SAAS,SAAS,QAAwB;AAC/C,SAAO,QAAQ,MAAM;AACvB;AAOO,IAAM,yBAA4C,OAAO,OAAO,CAAC,OAAO,OAAO,CAAC;AAMhF,SAAS,mBAAmB,MAAkC;AACnE,SAAO,uBAAuB,KAAK,CAAC,WAAW,KAAK,WAAW,MAAM,CAAC;AACxE;AAGO,IAAM,gBAAgB,OAAO,OAAO;AAAA;AAAA,EAEzC,MAAM;AAAA;AAAA,EAEN,QAAQ;AAAA;AAAA,EAER,KAAK;AAAA;AAAA,EAEL,OAAO;AAAA;AAAA,EAEP,eAAe;AAAA;AAAA,EAEf,iBAAiB;AAAA;AAAA,EAEjB,iBAAiB;AAAA;AAAA,EAEjB,OAAO;AAAA;AAAA,EAEP,SAAS;AAAA;AAAA,EAET,WAAW;AAAA;AAAA,EAEX,aAAa;AAAA;AAAA,EAEb,SAAS;AACX,CAAU;AAGH,IAAM,gBAAgB,OAAO,OAAO;AAAA;AAAA,EAEzC,OAAO;AAAA;AAAA,EAEP,QAAQ;AAAA;AAAA,EAER,YAAY;AAAA;AAAA,EAEZ,SAAS;AAAA;AAAA,EAET,SAAS;AAAA;AAAA,EAET,QAAQ;AAAA;AAAA,EAER,OAAO;AAAA;AAAA,EAEP,UAAU;AAAA;AAAA,EAEV,QAAQ;AAAA;AAAA,EAER,QAAQ;AACV,CAAU;;;ACzGH,IAAM,mBAAmB;AAsBzB,SAAS,cAAc,OAAsC;AAClE,SAAO,SAAS,KAAK,KAAK,OAAO,UAAU,MAAM,QAAQ,KAAK,OAAO,MAAM,WAAW;AACxF;AAGO,IAAM,oBAAoB;AAa1B,SAAS,mBAAmB,OAA2C;AAC5E,SAAO,SAAS,KAAK,KAAK,MAAM,SAAS,qBAAqB,OAAO,UAAU,MAAM,QAAQ;AAC/F;AAaO,SAAS,wBAAwB,OAAgD;AACtF,SAAO,SAAS,KAAK,KAAK,MAAM,SAAS;AAC3C;AAGO,IAAM,oBAAoB;AAG1B,IAAM,mBAAmB;;;ACpEzB,IAAM,gBAAwC,OAAO,OAAO;AAAA,EACjE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAGM,SAAS,cAAc,OAAsC;AAClE,SAAO,OAAO,UAAU,YAAa,cAAoC,SAAS,KAAK;AACzF;","names":[]}

package/dist/chunk-XNLWBZIG.js

@@ -0,0 +1,9 @@
+// src/contract/toolName.ts
+function defaultToolName(service, method) {
+  return `${service}_${method}`;
+}
+
+export {
+  defaultToolName
+};
+//# sourceMappingURL=chunk-XNLWBZIG.js.map

package/dist/chunk-XNLWBZIG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contract/toolName.ts"],"sourcesContent":["// A method tool's default name. It lives with the contracts, not in the MCP\n// bridge, so `quickdraw-docs` prints it without the bridge's entry: the\n// bridge's own files ship in `./server/mcp` alone (scripts/dist-smoke.mjs).\n\n/**\n * The name the MCP bridge gives a method's tool when the registry has no\n * `name` option: `{service}_{method}` (RFC 0003 section 10).\n */\nexport function defaultToolName(service: string, method: string): string {\n  return `${service}_${method}`;\n}\n"],"mappings":";AAQO,SAAS,gBAAgB,SAAiB,QAAwB;AACvE,SAAO,GAAG,OAAO,IAAI,MAAM;AAC7B;","names":[]}

package/dist/{chunk-ZACRRYWL.js → chunk-ZIVPHYRG.js}

@@ -43,15 +43,15 @@ import {
   useQuickdrawContext,
   userOf,
   viewPredicate
-} from "./chunk-O2PWC2YW.js";
+} from "./chunk-OECZPRPW.js";
 import {
   CLIENT_EVENTS,
   SERVICE_TOPIC,
   collectionTopic
-} from "./chunk-WVIRXYI4.js";
+} from "./chunk-VSQBHPWH.js";
 import {
   isScopedStream
-} from "./chunk-5YRQ26LF.js";
+} from "./chunk-RT6OILOI.js";
 import {
   buildCaller,
   collectionKey,
@@ -1410,4 +1410,4 @@ export {
   QuickdrawProvider,
   useQuickdraw
 };
-//# sourceMappingURL=chunk-ZACRRYWL.js.map
+//# sourceMappingURL=chunk-ZIVPHYRG.js.map

package/dist/cli/quickdraw-docs.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
+import {
+  defaultToolName
+} from "../chunk-XNLWBZIG.js";
 import {
   CHANNEL_DEFAULT_RATE,
   DEFAULT_COLLECTION_LIMIT,
   DEFAULT_COLLECTION_MAX_LIMIT,
   isScopedStream
-} from "../chunk-5YRQ26LF.js";
+} from "../chunk-RT6OILOI.js";
 import {
   hasJsonSchema,
   isStandardSchema
@@ -76,6 +79,12 @@ function recordsOf(value) {
   }
   return value;
 }
+function kindsOf(value) {
+  return Array.isArray(value) && value.every((kind) => typeof kind === "string") ? value : void 0;
+}
+function namesOf(value) {
+  return Array.isArray(value) ? value.filter((name) => typeof name === "string") : [];
+}
 function mapEach(records, read) {
   return new Map([...records].map(([name, record]) => [name, read(record)]));
 }
@@ -94,13 +103,17 @@ function serviceDocOf(value) {
   }
   return Object.freeze({
     name: value.name,
+    model: typeof value.model === "string" ? value.model : void 0,
+    writes: namesOf(value.writes),
+    affects: Array.isArray(value.affects) ? value.affects.map((link) => contractName(isRecord(link) ? link.service : void 0)).filter((name) => name !== void 0) : [],
     policy: value.access,
     adminBypass: value.adminBypass !== false,
+    kinds: kindsOf(value.kinds),
     watchAccess: value.watchAccess,
     methods: new Map(
       Object.entries(methods).map(([name, method]) => [
         name,
-        { access: method.access, rowless: method.rowless === true }
+        { access: method.access, rowless: method.rowless === true, kinds: kindsOf(method.kinds) }
       ])
     ),
     collections: mapEach(collections, (collection) => ({
@@ -140,8 +153,11 @@ function servicesOf(exports) {
     [...found].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([name, { doc }]) => [name, doc])
   );
 }
+function contractName(contract) {
+  return isRecord(contract) && typeof contract.name === "string" ? contract.name : void 0;
+}
 function serviceName(contract) {
-  return isRecord(contract) && typeof contract.name === "string" ? contract.name : "another service";
+  return contractName(contract) ?? "another service";
 }
 function idOf(id) {
   if (id === void 0) {
@@ -220,13 +236,164 @@ function collectionAccessText(collection) {
   return `${String(collection.level)} or more on the ${code(serviceName(collection.anchor))} row the scope names`;
 }
 
+// src/cli/dependencies.ts
+var KINDS = ["inherit", "writes", "affects", "scope", "anchor"];
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function modelKey(model) {
+  return `${model.charAt(0).toLowerCase()}${model.slice(1)}`;
+}
+var MAX_POLICY_DEPTH2 = 3;
+function inheritsOf(policy, depth = 0) {
+  if (!isRecord2(policy)) {
+    return [];
+  }
+  if (policy.kind === "inherit") {
+    const from = contractName(policy.from);
+    return from === void 0 ? [] : [{ from, via: String(policy.via) }];
+  }
+  if (policy.kind === "anyOf" && Array.isArray(policy.policies) && depth < MAX_POLICY_DEPTH2) {
+    return policy.policies.flatMap((member) => inheritsOf(member, depth + 1));
+  }
+  return [];
+}
+function scopeOf(form) {
+  return isRecord2(form) && typeof form.scope === "string" ? contractName(form.of) : void 0;
+}
+function dependenciesOfService(service, contract, owners) {
+  const found = /* @__PURE__ */ new Map();
+  const add = (target, kind, text) => {
+    if (target === void 0 || target === service.name) {
+      return;
+    }
+    found.set(target, [...found.get(target) ?? [], { kind, text }]);
+  };
+  for (const { from, via } of inheritsOf(service.policy)) {
+    add(from, "inherit", `row policy: ${code("inherit")} through the ${code(via)} column`);
+  }
+  const models = [];
+  for (const model of service.writes) {
+    const serving = owners.get(modelKey(model)) ?? [];
+    if (serving.length === 0) {
+      models.push(model);
+    }
+    for (const owner of serving) {
+      add(owner, "writes", `${code("writes")}: its ${code(model)} model`);
+    }
+  }
+  for (const target of new Set(service.affects)) {
+    add(target, "affects", `${code("affects")}: a write to a row here changes its rows`);
+  }
+  for (const [name, method] of service.methods) {
+    add(scopeOf(method.access), "scope", `method ${code(name)}: ${code("{ scope, of }")}`);
+  }
+  for (const [name, access] of service.channels) {
+    add(scopeOf(access), "scope", `channel ${code(name)}: ${code("{ scope, of }")}`);
+  }
+  for (const [name, stream] of Object.entries(contract?.streams ?? {})) {
+    add(scopeOf(stream.access), "scope", `stream ${code(name)}: ${code("{ scope, of }")}`);
+  }
+  for (const [name, collection] of service.collections) {
+    add(
+      contractName(collection.anchor),
+      "anchor",
+      `collection ${code(name)}: anchored on its rows`
+    );
+  }
+  return {
+    services: [...found].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([name, reasons]) => ({
+      service: name,
+      reasons: KINDS.flatMap((kind) => reasons.filter((reason) => reason.kind === kind))
+    })),
+    models
+  };
+}
+function dependenciesOf(contracts, services) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const service of services.values()) {
+    if (service.model !== void 0) {
+      const key = modelKey(service.model);
+      owners.set(key, [...owners.get(key) ?? [], service.name]);
+    }
+  }
+  const byName = new Map(contracts.map((contract) => [contract.name, contract]));
+  return new Map(
+    [...services.values()].map((service) => [
+      service.name,
+      dependenciesOfService(service, byName.get(service.name), owners)
+    ])
+  );
+}
+function kindsOf2(dependency) {
+  return KINDS.filter((kind) => dependency.reasons.some((reason) => reason.kind === kind));
+}
+function dependsOnSection(dependencies) {
+  const { services, models } = dependencies;
+  const unserved = models.length === 0 ? [] : [`It also ${code("writes")} models no service's rows live in: ${list(models)}.`];
+  if (services.length === 0) {
+    return section("## Depends on", ["No other service: its declarations name none.", ...unserved]);
+  }
+  return section("## Depends on", [
+    `The other services its declarations name: its row policy, ${code("writes")}, ${code("affects")}, ${code("{ scope, of }")} access forms and collection anchors. A handler's undeclared reads are not listed.`,
+    table(
+      ["Service", "Declared by"],
+      services.map(({ service, reasons }) => [
+        code(service),
+        reasons.map((reason) => reason.text).join("; ")
+      ])
+    ),
+    ...unserved
+  ]);
+}
+function nodeIds(names) {
+  const ids = /* @__PURE__ */ new Map();
+  const taken = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    const safe = name.replace(/\W/g, "_");
+    let id = /^end$/i.test(safe) ? `${safe}_` : safe;
+    for (let n = 2; taken.has(id); n += 1) {
+      id = `${safe}_${n}`;
+    }
+    taken.add(id);
+    ids.set(name, id);
+  }
+  return ids;
+}
+function dependencyGraph(dependencies) {
+  const edges = [...dependencies].flatMap(
+    ([from, { services }]) => services.map((dependency) => ({
+      from,
+      to: dependency.service,
+      label: kindsOf2(dependency).join(", ")
+    }))
+  );
+  if (edges.length === 0) {
+    return section("## Dependencies", ["No service's declarations name another service."]);
+  }
+  const names = [...new Set(edges.flatMap(({ from, to }) => [from, to]))].sort();
+  const ids = nodeIds(names);
+  const id = (name) => ids.get(name) ?? name;
+  const nodes = names.filter((name) => id(name) !== name).map((name) => `  ${id(name)}["${name.replace(/"/g, "#quot;")}"]`);
+  return section("## Dependencies", [
+    `An arrow points from a service to another its declarations name: ${code("inherit")} (its row policy), ${code("writes")} (that service's model), ${code("affects")}, ${code("scope")} (a ${code("{ scope, of }")} access form) or ${code("anchor")} (a collection's anchor). Each service's page lists them.`,
+    [
+      "```mermaid",
+      "graph LR",
+      ...nodes,
+      ...edges.map(({ from, to, label }) => `  ${id(from)} -->|${label}| ${id(to)}`),
+      "```"
+    ]
+  ]);
+}
+
 // src/cli/schemaText.ts
 var NO_JSON_SCHEMA = "unknown (no JSON Schema)";
 var TARGET = "draft-07";
 var MAX_DEPTH = 8;
 var IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 var ROOT = "#";
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function jsonSchemaOf(schema, mode) {
@@ -235,7 +402,7 @@ function jsonSchemaOf(schema, mode) {
   }
   try {
     const json = schema["~standard"].jsonSchema[mode]({ target: TARGET });
-    return isRecord2(json) ? json : void 0;
+    return isRecord3(json) ? json : void 0;
   } catch {
     return void 0;
   }
@@ -247,8 +414,8 @@ function definitionOf(root, ref) {
   }
   const [, group = "", name = ""] = match;
   const definitions = root[group];
-  const found = isRecord2(definitions) ? definitions[decodeURIComponent(name)] : void 0;
-  return isRecord2(found) ? found : void 0;
+  const found = isRecord3(definitions) ? definitions[decodeURIComponent(name)] : void 0;
+  return isRecord3(found) ? found : void 0;
 }
 function literal(value) {
   return value === void 0 ? "undefined" : JSON.stringify(value);
@@ -287,13 +454,13 @@ function requiredOf(schema) {
   return new Set(Array.isArray(schema.required) ? schema.required.map(String) : []);
 }
 function objectText(schema, scope) {
-  const properties = isRecord2(schema.properties) ? schema.properties : {};
+  const properties = isRecord3(schema.properties) ? schema.properties : {};
   const required = requiredOf(schema);
   const members = Object.entries(properties).map(
     ([name, value]) => `${propertyName(name, !required.has(name))}: ${textOf(value, scope)}`
   );
   const extra = schema.additionalProperties;
-  if (isRecord2(extra)) {
+  if (isRecord3(extra)) {
     const value = textOf(extra, scope);
     if (members.length === 0) {
       return `Record<string, ${value}>`;
@@ -351,10 +518,10 @@ function refText(ref, scope) {
   return textOf(target, { ...scope, open: [...scope.open, ref] });
 }
 function textOf(schema, scope) {
-  if (schema === true || isRecord2(schema) && Object.keys(schema).length === 0) {
+  if (schema === true || isRecord3(schema) && Object.keys(schema).length === 0) {
     return "unknown";
   }
-  if (!isRecord2(schema) || scope.depth > MAX_DEPTH) {
+  if (!isRecord3(schema) || scope.depth > MAX_DEPTH) {
     return schema === false ? "never" : "unknown";
   }
   const inner = { ...scope, depth: scope.depth + 1 };
@@ -381,7 +548,7 @@ function textOf(schema, scope) {
   if (typeof type === "string") {
     return typeNameText(type, schema, inner);
   }
-  return isRecord2(schema.properties) ? objectText(schema, inner) : "unknown";
+  return isRecord3(schema.properties) ? objectText(schema, inner) : "unknown";
 }
 function schemaText(schema) {
   return textOf(schema, { root: schema, open: [ROOT], depth: 0 });
@@ -447,7 +614,7 @@ function schemaNotes(schema) {
 }
 function schemaFields(schema) {
   const properties = schema.properties;
-  if (schema.type !== "object" || !isRecord2(properties) || Object.keys(properties).length === 0) {
+  if (schema.type !== "object" || !isRecord3(properties) || Object.keys(properties).length === 0) {
     return void 0;
   }
   const required = requiredOf(schema);
@@ -456,7 +623,7 @@ function schemaFields(schema) {
     name,
     optional: !required.has(name),
     type: textOf(value, scope),
-    notes: isRecord2(value) ? schemaNotes(value) : ""
+    notes: isRecord3(value) ? schemaNotes(value) : ""
   }));
 }
 
@@ -547,6 +714,24 @@ function kindLine(method) {
   }
   return `A query that watches the ${code(method.watch.collection)} collection: a cached result is fetched again when the scope its input names changes.`;
 }
+function described(text) {
+  return text === void 0 ? [] : [paragraph(text)];
+}
+function callableBy(name, access) {
+  const method = access?.service?.methods.get(name);
+  if (method?.kinds === void 0) {
+    return [];
+  }
+  const anonymous = method.access === "public" ? ", or anonymously" : "";
+  return [`- Callable by: ${list(method.kinds)}${anonymous}`];
+}
+function methodFacts(service, name, method, access) {
+  return [
+    `- MCP tool (default name): ${code(defaultToolName(service, name))}`,
+    ...method.kind === "query" ? ["- MCP read-only hint: yes, as on every query's tool"] : [],
+    ...callableBy(name, access)
+  ];
+}
 function methodAccess(name, access) {
   const method = access?.service?.methods.get(name);
   if (method === void 0) {
@@ -557,11 +742,11 @@ function methodAccess(name, access) {
   ] : [];
   return [`Access: ${accessFormText(method.access)}.`, ...rowless];
 }
-function methodSection(name, method, access) {
-  const described = method.describe === void 0 ? [] : [paragraph(method.describe)];
+function methodSection(service, name, method, access) {
   return section(`### ${code(name)}`, [
-    ...described,
+    ...described(method.describe),
     kindLine(method),
+    methodFacts(service, name, method, access),
     ...methodAccess(name, access),
     ...inputBlocks(method),
     `Output: ${outputText(method.output)}.`
@@ -575,7 +760,7 @@ function methodsSection(contract, access) {
   return [
     "## Methods",
     "",
-    ...entries.flatMap(([name, method]) => methodSection(name, method, access))
+    ...entries.flatMap(([name, method]) => methodSection(contract.name, name, method, access))
   ];
 }
 function scopeText(scope) {
@@ -603,6 +788,7 @@ function collectionSection(name, collection, access) {
   const maxLimit = collection.maxLimit ?? DEFAULT_COLLECTION_MAX_LIMIT;
   const served = access?.service?.collections.get(name);
   return section(`### ${code(name)}`, [
+    ...described(collection.describe),
     optionTable([
       ["Scope", scopeText(collection.scope)],
       ["Item", code(collection.item)],
@@ -673,6 +859,7 @@ function streamSection(name, stream, access) {
   const scoped = isScopedStream(stream);
   const served = access?.service?.streams.get(name);
   return section(`### ${code(name)}`, [
+    ...described(stream.describe),
     optionTable([
       ["Item", code(typeOf(stream.item, "output"))],
       ["Scope", scoped ? `one feed per ${code(stream.scope ?? "")}` : "one global feed"],
@@ -700,6 +887,7 @@ function channelSection(name, channel, access) {
   const rate = channel.ratePerSecond ?? CHANNEL_DEFAULT_RATE;
   const served = access?.service?.channels.has(name) === true;
   return section(`### ${code(name)}`, [
+    ...described(channel.describe),
     optionTable([
       ["Payload", code(typeOf(channel.payload, "input"))],
       [
@@ -717,6 +905,7 @@ function channelSection(name, channel, access) {
 }
 function eventSection(name, event) {
   return section(`### ${code(name)}`, [
+    ...described(event.describe),
     optionTable([["Payload", code(typeOf(event.payload, "output"))]])
   ]);
 }
@@ -745,6 +934,10 @@ function accessSection(contract, access) {
         "Service-wide Admin",
         service.adminBypass ? "passes every check of the service" : `passes only the forms that name ${code("service")} (${code("adminBypass: false")})`
       ],
+      [
+        "Principal kinds",
+        service.kinds === void 0 ? void 0 : `${list(service.kinds)}: its methods, subscriptions and channels refuse every other kind`
+      ],
       ["Change topic", watchAccessText(service.watchAccess)],
       ["Field levels", fieldLevelsText(contract)]
     ]),
@@ -757,7 +950,9 @@ function renderService(contract, access) {
     "",
     `# ${contract.name}`,
     "",
+    ...described(contract.describe).flatMap((text) => [text, ""]),
     ...accessSection(contract, access),
+    ...access?.dependencies === void 0 ? [] : dependsOnSection(access.dependencies),
     ...entitySection(contract),
     ...projectionsSection(contract),
     ...methodsSection(contract, access),
@@ -787,10 +982,12 @@ function renderService(contract, access) {
 function fileOf(contract) {
   return `${contract.name.replace(/[^\w.-]/g, "-")}.md`;
 }
-function renderIndex(contracts) {
+function renderIndex(contracts, dependencies) {
   const count = (members) => String(Object.keys(members).length);
+  const hasDescribe = contracts.some((contract) => contract.describe !== void 0);
   const rows = contracts.map((contract) => [
     `[${contract.name}](${fileOf(contract)})`,
+    ...hasDescribe ? [contract.describe ?? ""] : [],
     count(contract.methods),
     count(contract.collections),
     count(contract.streams),
@@ -804,9 +1001,21 @@ function renderIndex(contracts) {
     "",
     "One page per service, generated from its contract by `quickdraw-docs`.",
     "",
-    ...table(["Service", "Methods", "Collections", "Streams", "Channels", "Events"], rows)
+    ...table(
+      [
+        "Service",
+        ...hasDescribe ? ["Description"] : [],
+        "Methods",
+        "Collections",
+        "Streams",
+        "Channels",
+        "Events"
+      ],
+      rows
+    ),
+    ...dependencies === void 0 ? [] : ["", ...dependencyGraph(dependencies)]
   ];
-  return `${lines.join("\n")}
+  return `${lines.join("\n").trimEnd()}
 `;
 }
 
@@ -815,7 +1024,8 @@ var USAGE = `Usage: quickdraw-docs <module> [--services <module>] [--out <dir>]
 
   <module>              a module exporting the app's contracts: each one, or a map of them
   --services <module>   a module exporting the services (each, or a list of them): the pages
-                        then also say who may call each method, from the services' access
+                        then also say who may call each method, from the services' access,
+                        and which services each depends on, with a graph on the index
   --out <dir>           where the pages go: one per service, plus README.md (default: docs/api)
   --check               write nothing; exit 1 when the pages on disk differ from the contracts
 `;
@@ -829,11 +1039,11 @@ var CONTRACT_KEYS = [
   "channels",
   "events"
 ];
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isContract(value) {
-  return isRecord3(value) && Object.isFrozen(value) && typeof value.name === "string" && "entity" in value && CONTRACT_KEYS.every((key) => isRecord3(value[key]));
+  return isRecord4(value) && Object.isFrozen(value) && typeof value.name === "string" && "entity" in value && CONTRACT_KEYS.every((key) => isRecord4(value[key]));
 }
 function contractsOf(exports) {
   const found = /* @__PURE__ */ new Map();
@@ -847,7 +1057,7 @@ function contractsOf(exports) {
   for (const value of Object.values(exports)) {
     if (isContract(value)) {
       add(value);
-    } else if (isRecord3(value)) {
+    } else if (isRecord4(value)) {
       Object.values(value).filter(isContract).forEach(add);
     }
   }
@@ -864,6 +1074,7 @@ function generateDocs(contracts, options = {}) {
       );
     }
   }
+  const dependencies = services === void 0 ? void 0 : dependenciesOf(contracts, services);
   const files = /* @__PURE__ */ new Map();
   for (const contract of contracts) {
     const file = fileOf(contract);
@@ -874,11 +1085,14 @@ function generateDocs(contracts, options = {}) {
       file,
       renderService(
         contract,
-        services === void 0 ? void 0 : { service: services.get(contract.name) }
+        services === void 0 ? void 0 : {
+          service: services.get(contract.name),
+          dependencies: dependencies?.get(contract.name)
+        }
       )
     );
   }
-  files.set(INDEX_FILE, renderIndex(contracts));
+  files.set(INDEX_FILE, renderIndex(contracts, dependencies));
   return files;
 }
 function readText(path) {