@suss/recognize 0.33.1 → 0.34.1

package/dist/index.cjs

@@ -63,6 +63,7 @@ function opsIn(ctx) {
 // src/compile.ts
 var MAX_RECEIVER_HOPS = 8;
 function compile(chain, recognition) {
+  const receiverMethods = methodsWhoseReceiversAreAsked(chain);
   return (_call, ctx) => {
     const ops = opsIn(ctx);
     if (ops === null) {
@@ -83,6 +84,9 @@ function compile(chain, recognition) {
     if (methods === null) {
       return null;
     }
+    if (receiverMethods !== null) {
+      ops.readingReceivers?.(receiverMethods);
+    }
     for (const subject of subjectsOf(chain, ops)) {
       const method = operationOf(subject);
       const meaning = method === null ? null : listed(methods, method);
@@ -101,6 +105,14 @@ function compile(chain, recognition) {
     return null;
   };
 }
+function methodsWhoseReceiversAreAsked(chain) {
+  const start = linkIn(chain, "start");
+  const table = methodsIn(chain);
+  if (start === null || start.at.starts !== "receiver" || start.at.origin.origin !== "constructed" || linkIn(chain, "subject") !== null || table === null || table.ignoringCase) {
+    return null;
+  }
+  return new Set(Object.keys(table.table));
+}
 function linkIn(chain, asks) {
   const link = chain.links.find((candidate) => candidate.asks === asks);
   return link ?? null;
@@ -134,7 +146,23 @@ function listed(link, method) {
 }
 function subjectsOf(chain, ops) {
   const link = linkIn(chain, "subject");
-  return link === null ? [ops] : walk([ops], link.of);
+  if (link === null) {
+    return [ops];
+  }
+  announceArgumentReads(link.of, ops);
+  return walk([ops], link.of);
+}
+function announceArgumentReads(steps, ops) {
+  const first = steps[0];
+  if (first === void 0 || first.to !== "argument") {
+    return;
+  }
+  const at = first.at;
+  if (typeof at === "number") {
+    ops.readingArguments?.(at, at);
+    return;
+  }
+  ops.readingArguments?.(at.from);
 }
 var STEP = {
   receiver: (step, ops) => receiversOf(ops, step.method),
@@ -216,9 +244,24 @@ function accessEffect(matched, access) {
   const ending = chain.ending;
   const { input, kind, reached, unsettled } = access;
   const stated = { input, entry: reached.entry, kind };
-  const selector = namesFor(meaning.selector, subject, stated, unsettled);
-  const fields = namesFor(meaning.fields, subject, stated, unsettled);
-  return {
+  const listening = ops.statesSlots !== void 0;
+  const selectorRead = listening ? /* @__PURE__ */ new Map() : null;
+  const fieldsRead = listening ? /* @__PURE__ */ new Map() : null;
+  const selector = namesFor(
+    meaning.selector,
+    subject,
+    stated,
+    unsettled,
+    selectorRead
+  );
+  const fields = namesFor(
+    meaning.fields,
+    subject,
+    stated,
+    unsettled,
+    fieldsRead
+  );
+  const effect = {
     type: "interaction",
     binding: (0, import_behavioral_ir.storageBinding)({
       recognition,
@@ -237,6 +280,69 @@ function accessEffect(matched, access) {
       ...selector.length > 0 ? { selector } : {}
     }
   };
+  const slots = [
+    ...slotsRead("selector", selector, selectorRead),
+    ...slotsRead("field", fields, fieldsRead)
+  ];
+  if (slots.length > 0) {
+    ops.statesSlots?.(effect, slots);
+  }
+  return effect;
+}
+function slotsRead(slot, names, read) {
+  if (read === null) {
+    return [];
+  }
+  return [...new Set(names)].flatMap(
+    (name) => (read.get(name) ?? []).map((value) => ({ slot, name, value }))
+  );
+}
+function noteRead(read, name, value) {
+  const already = read.get(name);
+  if (already === void 0) {
+    read.set(name, [value]);
+    return;
+  }
+  if (!already.includes(value)) {
+    already.push(value);
+  }
+}
+function recording(value, read) {
+  return {
+    text: () => value.text(),
+    name: (unsettled) => value.name(unsettled),
+    ...value.names === void 0 ? {} : { names: (cap) => value.names?.(cap) ?? null },
+    flag: () => value.flag(),
+    entries: (unsettled) => value.entries(unsettled).map((entry) => {
+      if (entry.key !== null) {
+        noteRead(read, entry.key, entry.value);
+      }
+      return { key: entry.key, value: recording(entry.value, read) };
+    }),
+    items: () => value.items().map((item) => recording(item, read)),
+    property: (name) => {
+      const inside = value.property(name);
+      if (inside === null) {
+        return null;
+      }
+      noteRead(read, name, inside);
+      return recording(inside, read);
+    },
+    asArg: () => value.asArg(),
+    parts: () => value.parts(),
+    holes: () => value.holes(),
+    ...value.interpolated === void 0 ? {} : { interpolated: () => value.interpolated?.() ?? [] }
+  };
+}
+function watched(inputs, read) {
+  if (read === null) {
+    return inputs;
+  }
+  return {
+    ...inputs,
+    input: recording(inputs.input, read),
+    entry: inputs.entry === null ? null : recording(inputs.entry, read)
+  };
 }
 function reachedBy(chain, subject, unsettled) {
   const link = linkIn(chain, "containers");
@@ -315,7 +421,7 @@ var NOTHING_STATED = {
   parts: () => null,
   holes: () => []
 };
-function namesFor(says, subject, stated, unsettled) {
+function namesFor(says, subject, stated, unsettled, read = null) {
   if (says === void 0) {
     return [];
   }
@@ -324,7 +430,7 @@ function namesFor(says, subject, stated, unsettled) {
   }
   if (typeof says === "function") {
     const input2 = stated.input;
-    return input2 === null ? [] : [...says({ ...stated, input: input2 })];
+    return input2 === null ? [] : [...says(watched({ ...stated, input: input2 }, read))];
   }
   if ("selectorParam" in says) {
     return [...subject.parameterReadsAt?.(says.selectorParam) ?? []];
@@ -334,7 +440,7 @@ function namesFor(says, subject, stated, unsettled) {
     return namesAt(subject, pointed, unsettled);
   }
   const input = statedValue(subject, pointed.of) ?? NOTHING_STATED;
-  return [...pointed.by({ ...stated, input })];
+  return [...pointed.by(watched({ ...stated, input }, read))];
 }
 function namesAt(subject, pick, unsettled) {
   if (pick === void 0) {
@@ -375,20 +481,27 @@ function messageSend(matched) {
   }
   const messages = messagesIn(input, ending.messages);
   const sent = messages.length === 0 ? [NOTHING_STATED] : messages;
-  return sent.map((message) => ({
-    type: "interaction",
-    binding: (0, import_behavioral_ir.messageBusBinding)({
-      recognition,
-      messageBus: ending.wire,
-      channel: channelOf(message, input, ending)
-    }),
-    callee: ops.calleeText(),
-    interaction: {
-      class: "message-send",
-      ...bodyOf(message, ending),
-      ...routingKeyOf(message, ending)
+  const effects = [];
+  for (const message of sent) {
+    const channels = channelsOf({ message, input, ending });
+    for (const channel of channels) {
+      effects.push({
+        type: "interaction",
+        binding: (0, import_behavioral_ir.messageBusBinding)({
+          recognition,
+          messageBus: ending.wire,
+          channel
+        }),
+        callee: ops.calleeText(),
+        interaction: {
+          class: "message-send",
+          ...bodyOf(message, ending),
+          ...routingKeyOf(message, ending)
+        }
+      });
     }
-  }));
+  }
+  return effects;
 }
 function messagesIn(input, location) {
   if (location.each === "theInput") {
@@ -397,25 +510,47 @@ function messagesIn(input, location) {
   const collection = input.property(location.property);
   return collection === null ? [] : collection.items();
 }
-function channelOf(message, input, ending) {
-  const parts = [];
-  for (const part of ending.channel) {
-    const holder = part.on === "theInput" ? input : message;
-    const written = firstWritten(holder, part.property);
-    if (written === null) {
-      if (part.whenAbsent === void 0) {
-        return null;
-      }
-      parts.push(part.whenAbsent);
-      continue;
-    }
-    const stated = written.name(part.unsettled ?? ending.unsettledName);
-    if (stated === null || stated === "") {
-      return null;
+var CHANNEL_CAP = 16;
+function oneName(written, unsettled) {
+  const stated = written.name(unsettled);
+  return stated === null || stated === "" ? null : [stated];
+}
+function everyString(written, unsettled) {
+  const each = written.names?.(CHANNEL_CAP) ?? null;
+  if (each === null || each.length < 2 || each.includes("")) {
+    return oneName(written, unsettled);
+  }
+  return each;
+}
+function channelsOf(sending) {
+  const each = channelsRead(sending, "everyString");
+  return each.length > CHANNEL_CAP ? channelsRead(sending, "oneName") : each;
+}
+function channelsRead(sending, read) {
+  const separator = sending.ending.channelSeparator ?? "#";
+  let channels = null;
+  for (const part of sending.ending.channel) {
+    const values = partValues(part, sending, read);
+    if (values === null) {
+      return [null];
     }
-    parts.push(stated);
+    channels = channels === null ? values : crossed(channels, values, separator);
   }
-  return parts.join(ending.channelSeparator ?? "#");
+  return channels ?? [""];
+}
+function crossed(heads, values, separator) {
+  return heads.flatMap(
+    (head) => values.map((value) => `${head}${separator}${value}`)
+  );
+}
+function partValues(part, sending, read) {
+  const holder = part.on === "theInput" ? sending.input : sending.message;
+  const written = firstWritten(holder, part.property);
+  if (written === null) {
+    return part.whenAbsent === void 0 ? null : [part.whenAbsent];
+  }
+  const unsettled = part.unsettled ?? sending.ending.unsettledName;
+  return read === "everyString" ? everyString(written, unsettled) : oneName(written, unsettled);
 }
 function firstWritten(holder, properties) {
   for (const property of properties) {
@@ -498,28 +633,68 @@ function sqlAccess(matched) {
     namesInHoles(chain, stated.value),
     settledHoles(stated.value)
   );
-  const accesses = (0, import_sql.readSqlAccess)(statement, { dialect: ending.dialect });
-  return accesses.length === 0 ? null : accesses.map((access) => ({
-    type: "interaction",
-    binding: (0, import_behavioral_ir.storageBinding)({
-      recognition,
-      storageSystem: ending.system,
-      ...ending.transport === void 0 ? {} : { transport: ending.transport },
-      // A statement that qualifies its table says which namespace
-      // the access is in, and the pack's own scope is the fallback
-      // for a statement that leaves it out.
-      scope: access.qualifier[access.qualifier.length - 1] ?? ending.scope,
-      container: access.table
-    }),
-    callee: ops.calleeText(),
-    interaction: {
-      class: "storage-access",
-      kind: access.kind,
-      fields: access.fields,
-      ...access.selector.length > 0 ? { selector: access.selector } : {},
-      operation: method
+  const accesses = (0, import_sql.readSqlAccess)(statement, {
+    dialect: ending.dialect,
+    placeholders: ops.statesSlots !== void 0
+  });
+  if (accesses.length === 0) {
+    return null;
+  }
+  const values = placeholderValues(
+    stated,
+    subject,
+    matched.meaning.parameters
+  );
+  return accesses.map((access) => {
+    const effect = {
+      type: "interaction",
+      binding: (0, import_behavioral_ir.storageBinding)({
+        recognition,
+        storageSystem: ending.system,
+        ...ending.transport === void 0 ? {} : { transport: ending.transport },
+        // A statement that qualifies its table says which namespace
+        // the access is in, and the pack's own scope is the fallback
+        // for a statement that leaves it out.
+        scope: access.qualifier[access.qualifier.length - 1] ?? ending.scope,
+        container: access.table
+      }),
+      callee: ops.calleeText(),
+      interaction: {
+        class: "storage-access",
+        kind: access.kind,
+        fields: access.fields,
+        ...access.selector.length > 0 ? { selector: access.selector } : {},
+        operation: method
+      }
+    };
+    const slots = (access.placeholders ?? []).flatMap((one) => {
+      const value = placeholderValue(values, one.placeholder);
+      return value === null ? [] : [{ slot: SLOT_OF[one.clause], name: one.field, value }];
+    });
+    if (slots.length > 0) {
+      ops.statesSlots?.(effect, slots);
     }
-  }));
+    return effect;
+  });
+}
+var SLOT_OF = {
+  fields: "field",
+  selector: "selector"
+};
+function placeholderValues(stated, subject, says) {
+  const writesItsOwn = stated.parts.some((part) => /\$\d/.test(part));
+  if (stated.parts.length > 1 && !writesItsOwn) {
+    return { numbered: stated.value.interpolated?.() ?? [], named: null };
+  }
+  const picks = says === void 0 ? [] : Array.isArray(says) ? says : [says];
+  const given = picks.map((pick) => statedValue(subject, pick)).find((value) => value !== null);
+  return given === void 0 ? { numbered: [], named: null } : { numbered: given.items(), named: given };
+}
+function placeholderValue(values, placeholder) {
+  if (typeof placeholder === "number") {
+    return values.numbered[placeholder - 1] ?? null;
+  }
+  return values.named?.property(placeholder) ?? null;
 }
 function statementIn(subject, says) {
   const picks = Array.isArray(says) ? says : [says];
@@ -711,8 +886,8 @@ function describe(chain) {
   ];
   return {
     name: declaredName(chain.ending),
-    // A method table with a rule inside it is still a table, so that
-    // link stays counted as data and the rule is priced beside it.
+    // A method table with a rule inside still counts as a data link. The
+    // rule is counted on its own, as a function link.
     dataLinks: chain.links.length - links.length,
     functionLinks: written.map((rule) => rule.asks),
     astLinks: written.filter((rule) => rule.reachesAst).map((rule) => rule.asks),

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { ConstructedFrom, DeclaredBy, CallOps, InvocationRecognizer, PatternPack, UnsettledName, ReceiverOrigin, ProjectHelpers, PackDeclarations } from '@suss/extractor';
-export { CallOps, ConstructedFrom, DeclaredBy, DeclaredMatch, HelperDeclarations, HelperSink, HelperValue, OpsCarrier, PackDeclarations, PatternPack, ProjectHelper, ProjectHelpers, ReceiverOrigin, UnsettledName, ValueEntry, ValueOps } from '@suss/extractor';
-import { C as Chain, M as MethodMeaning, a as MessageSendMethod, b as MessageLocation, c as ChannelPart, S as SqlMethod, I as InterpolatesLink, d as CallStep, e as StorageMethod, A as ArgumentPick, L as LinkFunction, O as OneArgument, U as UnitInvokeMethod } from './chain-CVG6Jnr-.cjs';
-export { f as AccessKind, g as AccessPathLink, h as ArgumentsFrom, i as CallsLink, j as ContainerArgument, k as ContainerLink, l as ContainerRule, m as ContainersLink, E as Ending, F as FromReceiver, n as InputLink, o as InputRule, K as KindAsAsked, p as Link, q as ManyIn, r as MatchStart, s as MessageSendEnding, t as MethodsLink, u as OneMessage, v as ScopeLink, w as SelectorParamPick, x as SqlEnding, y as StartLink, z as StatedInputs, B as StatedRule, D as StorageEnding, G as SubjectLink, T as ToArgument, H as ToReceiver, J as UnitInvokeEnding } from './chain-CVG6Jnr-.cjs';
+export { CallOps, ClassOps, ConstructedFrom, DeclaredBy, DeclaredMatch, HelperDeclarations, HelperSink, HelperValue, OpsCarrier, PackDeclarations, PatternPack, ProjectHelper, ProjectHelpers, ReceiverOrigin, UnsettledName, ValueEntry, ValueOps } from '@suss/extractor';
+import { C as Chain, M as MethodMeaning, a as MessageSendMethod, b as MessageLocation, c as ChannelPart, S as SqlMethod, I as InterpolatesLink, d as CallStep, e as StorageMethod, A as ArgumentPick, L as LinkFunction, O as OneArgument, U as UnitInvokeMethod } from './chain-DYU9ZdzF.cjs';
+export { f as AccessKind, g as AccessPathLink, h as ArgumentsFrom, i as CallsLink, j as ContainerArgument, k as ContainerLink, l as ContainerRule, m as ContainersLink, E as Ending, F as FromReceiver, n as InputLink, o as InputRule, K as KindAsAsked, p as Link, q as ManyIn, r as MatchStart, s as MessageSendEnding, t as MethodsLink, u as OneMessage, v as ScopeLink, w as SelectorParamPick, x as SqlEnding, y as StartLink, z as StatedInputs, B as StatedRule, D as StorageEnding, G as SubjectLink, T as ToArgument, H as ToReceiver, J as UnitInvokeEnding } from './chain-DYU9ZdzF.cjs';
 import { Effect, MessageBusSemantics, DeployableUnit } from '@suss/behavioral-ir';
 
 /**
@@ -15,8 +15,8 @@ import { Effect, MessageBusSemantics, DeployableUnit } from '@suss/behavioral-ir
 
 /**
  * A receiver whose method one of these modules declared. Pass every
- * module that ships the same client, the way three packages all speak
- * one wire protocol.
+ * module that ships the same client, for example several packages that
+ * implement one wire protocol.
  */
 declare function declaredBy(...importedFrom: readonly string[]): DeclaredBy;
 /** A client made from one of these modules' exports. */
@@ -30,18 +30,18 @@ declare function constructedFrom(spec: {
 declare function opsIn(ctx: unknown): CallOps | null;
 
 /**
- * Turning a chain into the recognizer hook the adapters already call.
+ * Turns a chain into the recognizer hook the adapters already call.
  *
- * The links are guards, so the compiled hook checks the cheap one
- * first: looking a method up in a table costs nothing, while following
- * a receiver to the library that made it walks declarations. The chain
- * says which questions to ask, not the order to ask them in. A link
- * that changes what the receiver is, the way Prisma's model property
- * does, will need that order back, and the note here is where to start.
+ * Every link is a guard, and the compiled hook checks the cheapest one
+ * first. Looking a method up in a table costs nothing, while following
+ * a receiver to the library that made it walks declarations. So the
+ * hook ignores the order the pack declared its links in. A link that
+ * changes what the receiver is, as a Prisma model property would, needs
+ * declared order back, and that change goes here.
  *
  * A chain that states a subject asks its questions of a call next to
- * the one in hand, so the walk lives here. The README beside this file
- * says what each step reaches and why the walk is bounded.
+ * the one in hand, and the walk to that call is also here. DESIGN.md
+ * describes what each step reaches and why the walk is bounded.
  */
 
 /** A chain, as the hook the adapter dispatches to on every call. */
@@ -71,28 +71,27 @@ interface RanExample {
 /** How a pack's test compiles one line and runs the pack over it. */
 type RunOverCode = (code: string) => Effect[];
 /**
- * Every example a pack declares, run. A declaration with no example is
- * left out, which is what the pack health check catches separately.
+ * Runs every example a pack declares. A declaration with no example is
+ * skipped here; `examplesMissing` lists those, and the pack health
+ * check reports them.
  */
 declare function runExamples(pack: PatternPack, run: RunOverCode): RanExample[];
 /** The declarations a pack shipped without a line of code to run. */
 declare function examplesMissing(pack: PatternPack): string[];
 
 /**
- * messageSends.ts: a pack that recognizes a call putting a message on a
- * wire.
+ * A pack that recognizes a call putting a message on a wire.
  *
- * The AWS SDK shape is the one this was written against. An operation
- * is a command class and its arguments are one object, so the pack says
- * which command, where the message is inside it, and which of the
- * message's properties name the channel:
+ * It was written against the AWS SDK. There an operation is a command
+ * class and its arguments are one object, so the pack says which
+ * command, where the message is inside it, and which of the message's
+ * properties make up the channel:
  *
  *   client.send(new SendMessageCommand({ QueueUrl, MessageBody }))
  *   client.send(new PutEventsCommand({ Entries: [{ EventBusName, DetailType }] }))
  *
- * A library taking one message and a batch of them offers two commands,
- * so a pack writes two declarations. Which of the two a command is
- * belongs to the command rather than to a setting on one declaration.
+ * A library that sends one message and a batch through separate
+ * commands gets two declarations, one per command.
  */
 
 interface MessageSendsSpec {
@@ -102,19 +101,19 @@ interface MessageSendsSpec {
     messages: MessageLocation;
     /** The parts of the channel, joined in the order they are written. */
     channel: readonly ChannelPart[];
-    /** What joins the parts. Defaults to "#", which is what a bus and a subject use. */
+    /** What joins the parts. Defaults to "#", as used between a bus and a subject. */
     channelSeparator?: string;
     /** The property a message states its body on. */
     body?: string;
     /**
-     * The property whose literal value rides along as the routing key,
-     * scoping the message for a reader without joining the channel.
+     * The property whose literal value is recorded as the routing key. A
+     * reader can filter on it, and it stays out of the channel name.
      */
     routingKey?: string;
     /**
      * What a reader gives back for a channel nothing in the source
-     * settles. Defaults to keeping the reference, since a queue named
-     * only at deploy time is the common case rather than the exception.
+     * settles. Defaults to keeping the reference, because most queues get
+     * their name at deploy time.
      */
     unsettledName?: UnsettledName;
     /** How the pack pins down the client its calls are on. */
@@ -146,15 +145,15 @@ declare function messageSends(spec: MessageSendsSpec): MessageSends;
  */
 
 /**
- * One thing a pack matches, as whichever entry point built it hands it
- * over. `storageCalls` and `sqlStatements` both come out as this.
+ * One thing a pack matches, as an entry point returns it. `storageCalls`
+ * and `sqlStatements` both return this.
  */
 interface Match {
     readonly declared: Chain<MethodMeaning>;
 }
 /** What a pack says about itself, beyond the calls it matches. */
 interface PackSpec {
-    /** The languages the pack runs on, as the adapters name them. */
+    /** The languages the pack runs on, spelled as the adapters spell them. */
     languages: string[];
     /**
      * The name effects from this pack are recorded under, which is the
@@ -168,24 +167,23 @@ interface PackSpec {
      */
     version?: string;
     /**
-     * What the pack itself speaks, when that is not the wire its accesses
-     * record. An S3 access goes over the AWS SDK and says so on every
-     * effect, while the pack speaks S3.
+     * The pack's own protocol, when it differs from the wire its accesses
+     * record. An S3 pack records the AWS SDK as the wire on every effect,
+     * and its protocol is S3.
      */
     protocol?: string;
     /**
-     * Further modules whose presence makes a file worth reading, beyond
-     * the ones the chains match on. A helper a project reaches by a
-     * relative path gives the gate nothing; the library that helper
-     * imports gives it something.
+     * More modules that make a file worth reading, beyond the ones the
+     * chains match on. A helper imported by a relative path does not open
+     * the import gate, so the pack lists the library the helper imports.
      */
     requiresImport?: string[];
     /**
      * Recognizers written against the adapter directly, run alongside the
-     * declared chains. A pack migrating one call at a time keeps what is
-     * not declared yet here, and a pack that needs a shape the endings
-     * cannot say keeps it here for good. Health reporting counts these as
-     * function links, so the cost of staying here is visible.
+     * declared chains. A pack moving to chains one call at a time keeps
+     * the calls it has not declared yet here, and a call no ending can
+     * describe stays here for good. The pack health report counts these
+     * as function links, so a reader sees how many are left.
      */
     recognizers?: InvocationRecognizer[];
     /**
@@ -198,9 +196,10 @@ interface PackSpec {
 /** A pack, assembled from the calls it says it matches. */
 declare function pack(name: string, matches: readonly Match[], spec: PackSpec): PatternPack;
 /**
- * What a set of chains cost, for a pack that assembles itself. A pack
- * part way through the migration still has a hand-rolled walk beside
- * its declarations, and this is how the part that moved is priced.
+ * Describes a set of chains for the pack health report, for a pack that
+ * builds its `PatternPack` by hand. A pack partway through moving to
+ * declared chains keeps hand-written recognizers beside them, and this
+ * reports on the part that has moved.
  */
 declare function declarationsIn(matches: readonly Match[]): PackDeclarations;
 
@@ -208,13 +207,13 @@ declare function declarationsIn(matches: readonly Match[]): PackDeclarations;
  * The entry point for a pack whose calls hand the store a statement
  * written as SQL.
  *
- * A typed client says what it reached in its arguments, so the chain
- * asks the call. A raw statement says it in the text, so the chain
- * hands the text to `@suss/sql` and the parse settles the container,
- * the kind, the fields and the selector of every table the statement
- * touches. The links up to that point are the same ones every chain
- * states, which is why this is an ending rather than a grammar of its
- * own.
+ * With a typed client, the call's arguments show which table it
+ * reached. With a raw statement that information is in the SQL text,
+ * so the chain passes the text to `@suss/sql`. The parse gives the
+ * container, the kind, the fields and the selector of every table the
+ * statement touches. Every link before that point is one any other
+ * chain uses too, so SQL is a chain ending and needs no separate
+ * grammar.
  */
 
 /** What a pack says about the store its statements reach. */
@@ -255,10 +254,10 @@ declare function sqlStatements(spec: SqlStatementsSpec): SqlStatements;
  * The entry point for a pack that recognizes storage calls, and the
  * chain it builds.
  *
- * The entry point says what comes out rather than how, so a pack author
- * writes `storageCalls` and never meets an `Effect`. Each method on the
- * returned value adds one link and gives back a new chain, so a chain
- * is finished data by the time `pack` receives it.
+ * A pack author writes `storageCalls` and never builds an `Effect` by
+ * hand. Each method on the returned value adds one link and returns a
+ * new chain, so by the time `pack` receives a chain it is plain data
+ * that nothing changes afterwards.
  */
 
 /** What a pack says about the store its calls reach. */
@@ -271,8 +270,8 @@ interface StorageCallsSpec {
     scope?: string;
     /**
      * How the pack pins down the client its calls are on. A pack that
-     * matches a helper a project lists in its own config leaves this out,
-     * because the name that project gave is the whole of what it has.
+     * matches a helper listed in a project's own config leaves this out,
+     * because the helper's name is the only thing it has to match on.
      */
     client?: ReceiverOrigin;
     /**
@@ -294,9 +293,9 @@ interface StorageCalls {
         ignoringCase?: boolean;
     }): StorageCalls;
     /**
-     * What a bare call of the client itself does. A store hook is the
-     * case: `useAppStore((s) => s.bears)` reaches for no method, so the
-     * one meaning here is the whole answer.
+     * What a bare call of the client itself does. A store hook such as
+     * `useAppStore((s) => s.bears)` calls no method, so this meaning
+     * applies to every call.
      */
     calls(meaning: StorageMethod): StorageCalls;
     /**
@@ -336,13 +335,12 @@ interface StorageCalls {
 declare function storageCalls(spec: StorageCallsSpec): StorageCalls;
 
 /**
- * unitInvokes.ts: a pack that recognizes a call invoking one deployed
- * unit by name.
+ * A pack that recognizes a call invoking one deployed unit by name.
  *
- * The AWS SDK shape is the one this was written against, and it is the
- * same shape a send has: an operation is a command class and its
- * arguments are one object, so the pack says which command and which of
- * its properties says which unit the call reaches.
+ * It was written against the AWS SDK, where an invoke looks like a
+ * message send: an operation is a command class and its arguments are
+ * one object. The pack says which command, and which of its properties
+ * identifies the unit the call reaches.
  *
  *   client.send(new InvokeCommand({ FunctionName, Payload }))
  */