@suss/ir-core 0.33.0 → 0.34.0

package/dist/index.d.ts

@@ -1,22 +1,22 @@
 import { z } from 'zod';
-import { T as TypeShape, M as MessageBusSemantics, D as DeployableUnit, S as Semantics, B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, d as SourceLocationSchema, e as MessageBusTechnology } from './schemas-CIns0fqF.js';
-export { f as DeployableUnitSchema, E as EVERY_FIELD, F as FunctionCallSemantics, g as FunctionCallSemanticsSchema, G as GraphqlOperationSemantics, h as GraphqlOperationSemanticsSchema, i as GraphqlResolverSemantics, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, R as RestSemantics, l as RestSemanticsSchema, m as RuntimeConfigSemantics, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, p as StorageSemantics, q as StorageSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as methodsAgree, u as normalizePath, v as pathShape, w as routePathAdmits, x as routePathsMeet, y as storageContainerLabel, z as storageLabel, A as storageSystemLabel, H as typeDefinitionKey, I as withDefinitionsInlined } from './schemas-CIns0fqF.js';
+import { T as TypeShape, M as MessageBusSemantics, D as DeployableUnit, S as Semantics, B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, d as SourceLocationSchema, e as MessageBusTechnology } from './schemas-CghZNwSE.js';
+export { f as DeployableUnitSchema, E as EVERY_FIELD, F as FunctionCallSemantics, g as FunctionCallSemanticsSchema, G as GraphqlOperationSemantics, h as GraphqlOperationSemanticsSchema, i as GraphqlResolverSemantics, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, R as RestSemantics, l as RestSemanticsSchema, m as RuntimeConfigSemantics, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, p as StorageSemantics, q as StorageSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as isModuleName, u as methodsAgree, v as normalizePath, w as pathShape, x as routePathAdmits, y as routePathsMeet, z as storageContainerLabel, A as storageLabel, H as storageSystemLabel, I as typeDefinitionKey, J as withDefinitionsInlined } from './schemas-CghZNwSE.js';
 
 /**
  * The boundary-name syntax, parsed and printed in one place.
  *
- * A name in a summary means one of three things, told apart by the
- * braces alone: a literal (`orders-v1`), a pattern with deploy-time
- * holes (`{stage}-orders-v1`), or a reference saying where to go and
- * ask (`{location.bucket}`, `{ORDER_TABLE}`). A second parser can
- * disagree about which is which, and a second printer can spell a
- * value this one cannot read back, so everything that touches the
- * braces calls this module: `parseBoundaryName` and
- * `boundaryNameString` are the two directions, and the helpers below
- * are views over them. The package README tells the longer story,
- * including why REST route paths and message-bus channels stay apart.
- */
-/** One piece of a pattern: text the writer stated, or a hole. */
+ * A name in a summary is one of three things, and the braces alone tell
+ * them apart: a literal (`orders-v1`), a pattern with holes a deployment
+ * fills (`{stage}-orders-v1`), or a reference that says where to look
+ * the name up (`{location.bucket}`, `{ORDER_TABLE}`). A second parser
+ * could classify a string differently, and a second printer could write
+ * a string this parser cannot read back. So all code that reads or
+ * writes the braces goes through `parseBoundaryName` and
+ * `boundaryNameString`, and the other helpers here are built on those
+ * two. The package README has the longer explanation, including why
+ * REST route paths and message-bus channels are handled separately.
+ */
+/** One piece of a pattern: fixed text, or a hole. */
 type NamePart = {
     type: "text";
     text: string;
@@ -25,10 +25,10 @@ type NamePart = {
     label: string;
 };
 /**
- * What a name string means. A `reference` keeps its raw dot-separated
- * path, and `referenceOf` is the view that checks the parts are all
- * present, so a malformed spelling still classifies as a reference and
- * still pairs with nothing.
+ * A parsed boundary name. A `reference` keeps its raw dot-separated
+ * path, and `referenceOf` checks that every part is present. A
+ * malformed reference still classifies as a reference, so it still
+ * pairs with nothing.
  */
 type BoundaryName = {
     type: "literal";
@@ -40,97 +40,88 @@ type BoundaryName = {
     type: "reference";
     path: string[];
 };
-/** What a name string means. The exact inverse of `boundaryNameString`. */
+/** Parse a name string. The exact inverse of `boundaryNameString`. */
 declare function parseBoundaryName(name: string): BoundaryName;
-/** The one serializer. Everything a summary spells goes through here. */
+/** The name as a summary writes it. The exact inverse of `parseBoundaryName`. */
 declare function boundaryNameString(name: BoundaryName): string;
 /**
- * How a hole is spelled. A reader that assembles a pattern a part at a
- * time, the way the adapter's name reader does, mints each hole here
- * so the spelling cannot drift from the parse above.
+ * The string for one hole. Code that builds a pattern one part at a
+ * time calls this for each hole, so the result always parses back.
  */
 declare function patternHole(label: string): string;
 /**
- * The name a CloudFormation `Fn::Sub` value states. The array form
- * takes its template from the first element, and the variable map only
- * says where a substitution comes from, which does not change the name.
+ * The name pattern a CloudFormation `Fn::Sub` value produces, with each
+ * `${X}` turned into a hole. In the array form the template is the
+ * first element. The variable map only gives each substitution's
+ * source, which does not change the pattern.
  */
 declare function namePatternFromSub(value: unknown): string | null;
 /**
- * Whether a name says only that somebody else knows it. A wrapper that
- * takes its bucket as an argument states `{location.bucket}` and
- * nothing more, which says which parameter to ask rather than which
- * bucket. A name like that agrees with nothing until something grounds
- * it, since otherwise it would agree with every name there is.
+ * Whether a name is a reference, which gives where to look the name up
+ * and not the name itself. A wrapper that takes its bucket as an
+ * argument writes `{location.bucket}`. Such a name agrees with nothing
+ * until it is grounded, since otherwise it would agree with every name.
  */
 declare function namesNothing(name: string): boolean;
-/** Whether a name has anything a source left for deploy time to fill. */
+/** Whether a name has any hole left for the deployment to fill. */
 declare function hasNameHole(name: string): boolean;
 /**
- * The form two patterns are compared in: every hole reduced to the same
- * token, since the two sides pick their own name for the parameter.
+ * The name with every hole label blanked, for comparing two patterns.
+ * Each side chooses its own label for a parameter, so labels never
+ * decide a match.
  */
 declare function namePatternKey(name: string): string;
-/** How much of a name the writer stated rather than left for deploy time. */
+/** How many characters of fixed text a name has. A reference has none. */
 declare function fixedTextLength(name: string): number;
 /**
  * Whether two names are the same name. Two patterns agree when their
  * fixed parts line up, since a hole on one side meets a hole on the
- * other. A pattern and a concrete name agree when the fixed parts are
- * where the pattern says they are, which is what happens when one side
- * hardcoded what the other parameterized. A reference agrees with
- * nothing on either side.
+ * other. A pattern and a concrete name agree when the fixed text is
+ * where the pattern puts it. That happens when one side hardcoded what
+ * the other parameterized. A reference agrees with nothing.
  */
 declare function namesAgree(a: string, b: string): boolean;
-/** Where a reference says to go and ask. */
+/** A parsed reference: the value the code starts from, and the fields it reads inside it. */
 interface Reference {
     /**
-     * The value the code starts from: a parameter of the unit the
-     * reference was written in, or a variable the deployment sets. Which
-     * of those it is depends on the unit's inputs, so the reader that
-     * grounds a reference decides, not the string.
+     * A parameter of the unit the reference was written in, or a variable
+     * the deployment sets. The string does not record which. The grounding
+     * pass works that out from the unit's inputs.
      */
     root: string;
-    /** The fields to read inside it, outermost first. */
+    /** The fields read inside the root, outermost first. */
     fields: string[];
 }
 /**
- * How a reference is written. Null when a part of it is empty, since a
- * reference has to say what to ask about.
+ * The string for a reference, such as `{location.bucket}`. Null when
+ * any part is empty, since such a reference could never be settled.
  */
 declare function referenceName(reference: Reference): string | null;
 /**
- * The place a parsed reference says to ask, or null for a name that is
- * not a reference, or for a reference with a part missing, which says
- * nothing anybody could answer.
+ * The `Reference` in a parsed name. Null when the name is not a
+ * reference, or when a part of it is empty and nothing could settle it.
  */
 declare function referenceOf(name: BoundaryName): Reference | null;
-/**
- * The reference a name states, or null when the name states a name
- * rather than where to go and ask.
- */
+/** The `Reference` in a name string, or null when the name is a literal or a pattern. */
 declare function referenceFromName(name: string): Reference | null;
 
 /**
- * What the deployment running a piece of code fills its variables in
- * with.
+ * The values a deployment sets for the variables its code reads.
  *
  * A queue URL, a function name and a table name only exist once a stack
  * is deployed, so the source reaches them through a variable and the
- * template says what that variable is. Every protocol whose name has a
- * hole in it asks the same two questions here, and whoever knows which
- * deployment runs the code fills them in.
+ * template sets that variable. A protocol whose boundary name has a
+ * hole in it looks the hole up through this interface.
  *
- * The interface is declared next to the protocols because a protocol
- * has to ask without knowing what a summary is. `@suss/behavioral-ir`
- * works the values out from a set of summaries.
+ * The interface is declared in ir-core so a protocol can use it without
+ * depending on the summary types. `@suss/behavioral-ir` implements it
+ * from a set of summaries.
  */
 
 interface Deployment {
     /**
-     * Which variable a reference asks about, or null when what settles it
-     * is an argument a caller passes rather than anything the deployment
-     * says.
+     * The variable a reference points at. Null when a caller's argument
+     * settles the reference and the deployment has no say in it.
      */
     variableFor(reference: Reference): string | null;
     /**
@@ -140,11 +131,10 @@ interface Deployment {
      */
     setTo(reference: Reference): string | null;
     /**
-     * The declared resource this deployment wires that variable to, by
-     * the name the resource is declared under. A template that writes
-     * `!Ref ArchiveWorker` says which unit an invoke reaches without ever
-     * writing the deployed function's name, and that logical id is what
-     * the unit's own summary is keyed by.
+     * The logical id of the declared resource this deployment wires the
+     * variable to. A template that writes `!Ref ArchiveWorker` never gives
+     * the deployed function's name, but the unit's own summary is keyed by
+     * that logical id, so an invoke can still be matched to its unit.
      */
     pointsAt(reference: Reference): string | null;
 }
@@ -152,56 +142,49 @@ interface Deployment {
 declare const NOTHING_DEPLOYED: Deployment;
 
 /**
- * Comparing two TypeShapes structurally.
+ * Structural comparison of two TypeShapes.
  *
- * Both checkers do this. The behavioural checker compares a provider
- * body against a declared contract, and the intent checker compares a
- * code body against declared intent, and the two have to reach the same
- * verdict for the same pair. The comparison is here, next to the
- * TypeShape it works on, so neither checker owns it and the two cannot
- * drift apart.
+ * The behavioral checker compares a provider body against a declared
+ * contract, and the intent checker compares a code body against declared
+ * intent. The two have to reach the same verdict for the same pair, so
+ * the comparison is defined next to TypeShape and both checkers import
+ * it.
  *
- * The comparison is asymmetric, and the answer has three values rather
- * than two. `unknown` is what keeps a shape nobody can see into from
- * being reported as agreement.
+ * The comparison is asymmetric and has three results. `unknown` keeps a
+ * shape that cannot be inspected from being reported as a match.
  */
 
 /**
- * A comparison result with three values:
+ * The result of comparing two shapes:
  *   - "match": `actual` satisfies `declared`
- *   - "nomatch": there is a concrete, verifiable incompatibility
- *   - "unknown": uncertainty that would otherwise mask a mismatch
- *                (spreads, refs, unknown shapes)
+ *   - "nomatch": the shapes have a specific, checkable incompatibility
+ *   - "unknown": part of a shape cannot be inspected (a spread, a ref, an
+ *                unknown shape), and calling it a match could hide a mismatch
  */
 type MatchResult = "match" | "nomatch" | "unknown";
 /**
- * Compare an actual body against a declared body and say whether the
- * actual satisfies the declared.
+ * Whether an actual body satisfies a declared body.
  *
- * The two sides are not interchangeable. `actual` is the value that gets
+ * The arguments are not interchangeable. `actual` is the value that is
  * produced (a response body, a return value), and `declared` is the
- * contract it has to conform to. `unknown` is a soft signal, and the
- * caller decides whether to show it.
+ * contract it has to conform to. The caller decides whether to report
+ * an `"unknown"` result.
  */
 declare function bodyShapesMatch(actual: TypeShape, declared: TypeShape): MatchResult;
 
 /**
- * The contract a boundary protocol implements.
+ * The interface a boundary protocol implements.
  *
- * A protocol (REST, message-bus, one side of GraphQL) is a single
- * module in this directory. Its schema says what the identity fields
- * are, its behavior says how those fields key and agree, and the two
- * travel together so neither can be added without the other. Nothing
- * outside a protocol's own module decides how its boundaries behave.
+ * Each protocol (REST, message-bus, one side of GraphQL) is one module
+ * in this directory. Its schema lists the identity fields, and its
+ * behavior defines how those fields key and agree. The two are defined
+ * together, so neither can be added without the other.
  *
- * These definitions ship with ir-core rather than with the packs,
- * because a published summary has to mean the same thing to a reader
- * who never installed the pack that wrote it. If a pack needs a
- * protocol nobody has defined yet, add a module here.
- *
- * A protocol also says which of its words come from OpenTelemetry's
- * semantic conventions, in `semconv`. The README says why that
- * matters and where it stops.
+ * The definitions ship with ir-core and not with the packs, because a
+ * published summary has to mean the same thing to a reader who never
+ * installed the pack that wrote it. A pack that needs a new protocol
+ * adds a module here. Each protocol also maps its fields to
+ * OpenTelemetry attributes in `semconv`, as the package README explains.
  */
 
 /** One identity field written as an OpenTelemetry attribute. */
@@ -209,16 +192,16 @@ interface SemconvAttribute {
     /** The attribute name, as the semantic conventions spell it. */
     name: string;
     /**
-     * Values suss writes where the source named none. A span never says
-     * them, so the projection leaves the attribute off rather than
-     * emitting a string that could only ever mismatch.
+     * Values suss writes when the source gave none. A span never has
+     * them, so the projection leaves the attribute out instead of writing
+     * a value that could never match.
      */
     placeholderValues?: readonly string[];
 }
 /**
  * Which identity fields the semantic conventions have an attribute
- * for. A field is absent when they have no attribute for it, or when
- * our value is our own string rather than the one a span gets.
+ * for. A field is absent when the conventions have no attribute for it,
+ * or when suss writes its own value there instead of the one a span gets.
  */
 type SemconvMapping<S extends {
     name: string;
@@ -226,9 +209,9 @@ type SemconvMapping<S extends {
     readonly [K in Exclude<keyof S, "name">]?: SemconvAttribute;
 };
 /**
- * How one semantics variant keys its boundaries and pairs them up. Each
- * variant fills this in inside its own module, and nothing else in the
- * tree gets a say in how a boundary keys or agrees.
+ * How one protocol keys its boundaries and pairs them up. Each protocol
+ * implements this in its own module, and every rule for how its
+ * boundaries key or agree is defined there.
  */
 interface BoundaryBehavior<S extends {
     name: string;
@@ -244,8 +227,8 @@ interface BoundaryBehavior<S extends {
      */
     pairingKey?(semantics: S): string | null;
     /**
-     * Settles whatever `pairingKey` left out of the bucket. A variant that
-     * does not define it always agrees.
+     * Compares the fields `pairingKey` left out of the bucket. When a
+     * protocol does not define it, every pair in a bucket agrees.
      */
     sidesAgree?(a: S, b: S): boolean;
     /**
@@ -261,84 +244,81 @@ interface BoundaryBehavior<S extends {
     bucketsMeet?(a: S, b: S): boolean;
     /**
      * How narrowly this bucket states what it serves, compared
-     * lexicographically. When a consumer meets more than one bucket, the
-     * one ranking highest is the one it reaches, and an even contest is
-     * reported rather than paired.
+     * lexicographically. When a consumer meets more than one bucket, it
+     * reaches the one ranked highest, and a tie is reported instead of
+     * paired.
      */
     bucketRank?(semantics: S): readonly number[];
-    /** The line a reader sees for this boundary. Defaults to `identityKey`. */
+    /** The label a reader sees for this boundary. Defaults to `identityKey`. */
     displayLabel?(semantics: S): string | null;
     /**
-     * The semantics with any filesystem path it states rewritten, for
-     * the pass that makes a summary's paths project-relative. A
-     * protocol that states no path declares nothing here.
+     * The semantics with every filesystem path in it rewritten, for the
+     * pass that makes a summary's paths project-relative. A protocol
+     * without paths leaves this undefined.
      */
     rewritePaths?(semantics: S, rewrite: (path: string) => string): S;
     /**
-     * The first protocol whose `claims` returns true normalizes a
-     * hand-written suppression boundary, and a string nobody claims is
-     * compared byte for byte. A protocol whose keys are exact declares
-     * nothing here and stays verbatim.
+     * How a hand-written suppression boundary is normalized. The first
+     * protocol whose `claims` returns true normalizes the string, and a
+     * string no protocol claims is compared byte for byte. A protocol
+     * whose keys compare exactly leaves this undefined.
      */
     ruleBoundary?: {
         claims(raw: string): boolean;
         normalize(raw: string): string;
     };
     /**
-     * A protocol whose boundaries have no URL leaves this undefined, which
-     * is different from an "unknown" result: undefined means the question
-     * does not apply, and unknown means this declaration cannot settle it.
+     * Whether this boundary serves a request with the given method and
+     * path. A protocol whose boundaries have no URL leaves this undefined.
+     * Undefined means the question does not apply, and an `"unknown"`
+     * result means this declaration cannot settle it.
      */
     servesRequest?(semantics: S, method: string, path: string): MatchResult;
     /**
      * Whether every request this boundary takes falls inside a pattern
      * something else was registered for. Middleware registered for
      * `/v1/*` runs for `/v1/tenants/{id}` and not for `/health`, so
-     * composing it into a unit asks this first.
+     * composing middleware into a unit checks this first.
      *
      * A protocol whose boundaries no pattern addresses leaves this
      * undefined, and nothing registered with a pattern reaches them.
      */
     withinScope?(semantics: S, scope: string): boolean;
     /**
-     * The same boundary with a name the deployment fills in put in.
+     * The same boundary with the deployment's values filled into its name.
      *
      * A call written as `fetch(`${process.env.API_BASE}/orders`)` gets
      * part of its boundary from the source and part from whatever runs
-     * the code. Both parts have to be in before anybody can see that the
-     * two sides describe one boundary.
+     * the code. Both parts are needed before the two sides can be matched
+     * as one boundary.
      *
      * `deployment` is already scoped to the unit this boundary belongs
-     * to. A protocol hands over the reference its name states and gets
-     * back what fills it in, or null. Return null to leave it as it is,
-     * which is right whenever nothing needs filling in or nothing can
-     * fill it.
-     *
-     * A protocol whose names are settled in the source leaves this
-     * undefined.
+     * to. The protocol looks up the reference in its name through it.
+     * Return null to leave the semantics unchanged, when nothing needs
+     * filling in or nothing can fill it. A protocol whose names are fixed
+     * in the source leaves this undefined.
      */
     groundName?(semantics: S, deployment: Deployment): S | null;
     /**
-     * Where this boundary's name says to go and ask, when it says that
-     * rather than a name. A caller that has to explain why two sides did
-     * not meet reads it to say which input would settle them.
+     * The reference in this boundary's name, when the name is a
+     * reference. A caller explaining why two sides did not pair uses it
+     * to say which input would settle the name.
      *
-     * A protocol that defines `groundName` defines this too, and the
-     * same reference is what `groundName` hands over.
+     * A protocol that defines `groundName` defines this too, and
+     * `groundName` looks up the same reference.
      */
     nameReference?(semantics: S): Reference | null;
     /**
      * Whether a provider produces a status and a body that a consumer
-     * reads back. Every protocol has to state this, so that one added
-     * later says what it is instead of landing in the HTTP-style checks
-     * because nobody remembered to exclude it.
+     * reads back. It is required, so a new protocol cannot end up in the
+     * HTTP-style checks because nobody remembered to exclude it.
      */
     exchangesHttpResponses: boolean;
     /**
-     * Whether crossing this boundary leaves the process. A report about
-     * what a change means for somebody outside the code covers the ones
-     * that do; a call from one function in a project to another is a
-     * boundary as well, and a reader has the source diff for that.
+     * Whether crossing this boundary leaves the process. A report on what
+     * a change means for callers outside the code covers only these. A
+     * call between two functions in one project is a boundary too, and a
+     * reader has the source diff for it.
      */
     leavesTheProcess: boolean;
     /**
@@ -366,8 +346,8 @@ interface BoundarySemanticsDefinition<Z extends z.ZodType<{
     schema: Z;
     behavior: BoundaryBehavior<z.infer<Z>>;
     /**
-     * Every protocol declares this, empty included, so that adding one
-     * means deciding where its words come from.
+     * Required even when empty, so adding a protocol means deciding which
+     * of its fields are OpenTelemetry attributes.
      */
     semconv: SemconvMapping<z.infer<Z>>;
 }
@@ -383,7 +363,7 @@ type FnIdentityKey = `fn:${string}::${string}` & {
     readonly [IdentityKeyBrand]: "fn";
 };
 declare function fnIdentityKey(packageName: string, exportPath: readonly string[]): FnIdentityKey;
-/** `bus:technology subject`, with the technology closed off the schema. */
+/** `bus:technology subject`, where the technology is one the message-bus schema allows. */
 type BusIdentityKey = `bus:${MessageBusSemantics["messageBus"]} ${string}` & {
     readonly [IdentityKeyBrand]: "bus";
 };
@@ -402,6 +382,17 @@ type MetricIdentityKey = `metric:${string} ${string}` & {
     readonly [IdentityKeyBrand]: "metric";
 };
 declare function metricIdentityKey(metricSystem: string, metricType: string): MetricIdentityKey;
+/** `io:stream`, the key a write to one of the process's streams has. */
+type IoIdentityKey = `io:${string}` & {
+    readonly [IdentityKeyBrand]: "io";
+};
+declare function ioIdentityKey(target: string): IoIdentityKey;
+
+declare const IoSemanticsSchema: z.ZodObject<{
+    name: z.ZodLiteral<"io">;
+    target: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type IoSemantics = z.infer<typeof IoSemanticsSchema>;
 
 declare const MetricSemanticsSchema: z.ZodObject<{
     name: z.ZodLiteral<"metric">;
@@ -412,9 +403,9 @@ type MetricSemantics = z.infer<typeof MetricSemanticsSchema>;
 
 /**
  * `instanceName` is nullable here and required on the unit itself,
- * because only the provider always knows the name. A call that works
- * its callee out at run time still happened, and recording it with no
- * name says so without pairing it against everything.
+ * because only the provider always knows the name. A call that picks
+ * its callee at run time still happened. Recording it with a null name
+ * keeps the call without pairing it against every unit.
  */
 declare const UnitInvocationSemanticsSchema: z.ZodObject<{
     deploymentTarget: z.ZodEnum<{
@@ -432,31 +423,33 @@ type UnitInvocationSemantics = z.infer<typeof UnitInvocationSemanticsSchema>;
 /**
  * A boundary binding read as OpenTelemetry attributes.
  *
- * A summary says what a unit can reach and a span says what it did
- * reach. Joining the two means both sides spelling the boundary the
- * same way, so suss writes the value a span gets wherever the semantic
- * conventions have a word for it, and this projection puts those
- * values under the attributes a trace store already indexes.
+ * A summary records what a unit can reach and a span records what it
+ * did reach. Joining the two means both spell the boundary the same
+ * way. suss writes the value a span gets wherever the semantic
+ * conventions have a word for it, and this projection puts those values
+ * under the attribute names a trace store already indexes.
  *
- * Which fields those are is each protocol's own declaration, in its
- * module under `semantics/`. Nothing here knows about any protocol.
+ * Each protocol declares its own field-to-attribute mapping next to its
+ * definition, so this module has no protocol-specific code.
  */
 
 /**
- * The attributes a boundary states, by name. A field the source never
- * gave, a placeholder, and a field the conventions have no attribute
- * for are all left out, so every pair here compares byte for byte
- * against the same attribute on a span.
+ * The binding's OpenTelemetry attributes, keyed by attribute name.
+ *
+ * A field the source never gave is left out, and so is a placeholder
+ * value or a field the conventions have no attribute for. Every value
+ * returned compares byte for byte against the same attribute on a span.
  */
 declare function semconvAttributes(binding: BoundaryBinding): Record<string, string>;
 
 /**
- * What a pack says about itself, for everything that has to know a pack
- * exists without reading its patterns.
+ * What a pack declares about itself, for tools that list or suggest
+ * packs without loading their patterns.
  *
- * `suss init` suggests a pack when it sees the library in a project's
- * manifest, and the packages page lists every pack with a line about
- * what it reads. Both come from here, so nobody maintains a table.
+ * `suss init` suggests a pack when a project's manifest lists the
+ * library, and the packages page lists every pack with a line about
+ * what it reads. Both read these declarations, so there is no separate
+ * table to keep in step with the packs.
  */
 /** The manifest a dependency is declared in. */
 type Ecosystem = "npm" | "pypi" | "rubygems";
@@ -474,6 +467,18 @@ interface PackConfiguration {
     required: boolean;
     /** What the value is, in a sentence. */
     why: string;
+    /**
+     * What `suss init` writes to `file` when it sets a project up: the
+     * values a project the library's own generator made has. Absent when no
+     * value suits every project.
+     */
+    defaults?: Record<string, unknown>;
+    /**
+     * Reads the values from a file the project already has, so init can
+     * write them when there are no defaults. Null when the project does
+     * not say.
+     */
+    readFromProject?: (projectRoot: string) => Record<string, unknown> | null;
 }
 interface PackDeclaration {
     /**
@@ -507,23 +512,22 @@ interface PackDeclaration {
 }
 
 /**
- * Keys for a boundary binding, and whether two of them agree. Every
- * function here asks the binding's protocol and returns whatever it
- * says, so the rules themselves are in the protocol's own module under
- * `semantics/` and not in this file.
+ * Keys for a boundary binding, and whether two bindings agree. Each
+ * function looks up the binding's protocol and delegates to it, so the
+ * rules are defined with each protocol's semantics.
  *
- * The sharing is the point. The behavioural checker pairs code
- * summaries by these keys, and the intent checker pairs intent against
- * code by the same keys. If the two ever keyed differently, intent and
- * code would stop lining up, so the keying is here next to the binding
- * rather than in either checker.
+ * The behavioral checker pairs code summaries by these keys, and the
+ * intent checker pairs intent against code by the same keys. If the two
+ * keyed differently, intent and code would stop lining up, so the
+ * keying is defined next to the binding and neither checker has its
+ * own.
  */
 
 /**
- * Whether a binding is of one protocol, narrowed to that protocol's
- * own semantics when it is. A caller reaching through the binding to
- * compare the name by hand gets `string | undefined` and no narrowing,
- * so a name that no protocol uses compiles and quietly never matches.
+ * Whether a binding is of one protocol, narrowing its semantics to that
+ * protocol's type. `name` only accepts a protocol that exists. Comparing
+ * `binding?.semantics.name` by hand does not narrow, and a misspelled
+ * protocol name there compiles and never matches.
  */
 declare function bindingIs<N extends Semantics["name"]>(binding: BoundaryBinding | null | undefined, name: N): binding is BoundaryBinding & {
     semantics: Extract<Semantics, {
@@ -532,35 +536,34 @@ declare function bindingIs<N extends Semantics["name"]>(binding: BoundaryBinding
 };
 declare function boundaryKey(binding: BoundaryBinding): string | null;
 /**
- * The binding with any filesystem path its semantics state rewritten.
- * The CLI uses it to make a summary's paths project-relative, and each
- * protocol says for itself whether it states one.
+ * The binding with every filesystem path in its semantics rewritten.
+ * The CLI uses it to make a summary's paths project-relative. A binding
+ * whose protocol has no paths comes back unchanged.
  */
 declare function withRewrittenPaths(binding: BoundaryBinding, rewrite: (path: string) => string): BoundaryBinding;
 /**
- * The bucket a boundary pairs in, with any name the deployment fills in
- * put in first.
+ * The pairing key after the deployment's values are filled into the
+ * boundary's name.
  *
- * A consumer that gets its base URL from the runtime states a different
- * string from the provider it reaches, and the two are one boundary.
- * Every protocol that has such a name says how to fill it in, and one
- * whose names are settled in the source keys exactly as before.
+ * A consumer that gets its base URL at run time writes a different
+ * string from the provider it reaches, though the two are one boundary.
+ * A protocol whose names are fixed in the source gets the same key as
+ * `pairingKey` would give.
  */
 declare function groundedPairingKey(binding: BoundaryBinding, deployment: Deployment): string | null;
 /**
- * The same boundary, with whatever the deployment fills in put in.
+ * The same boundary, with the deployment's values filled into its name.
  *
- * Everything that reads a boundary's name for a person to see goes
- * through here first: the pairing pass, the drafter that writes an
- * intent document, and the intent checker that reads one back. A step
- * only one of them took would have the drafter write a name the
- * checker then argued with.
+ * The pairing pass, the drafter that writes an intent document and the
+ * intent checker that reads one back all ground a binding here before
+ * reading its name. If only one of them grounded it, the drafter could
+ * write a name the checker then disputes.
  */
 declare function groundBinding(binding: BoundaryBinding, deployment: Deployment): BoundaryBinding;
 /**
- * Where this boundary's name says to go and ask, or null when the
- * source stated a name outright. A report that has to say why two
- * sides did not meet reads it to say which input would settle them.
+ * The reference in this boundary's name, or null when the source gave
+ * the name outright. A report that explains why two sides did not pair
+ * uses it to say which input would settle the name.
  */
 declare function nameReference(binding: BoundaryBinding): Reference | null;
 declare function pairingKey(binding: BoundaryBinding): string | null;
@@ -574,9 +577,18 @@ declare function bucketRank(binding: BoundaryBinding): readonly number[];
 declare function boundaryLabel(binding: BoundaryBinding): string | null;
 declare function displayLabel(binding: BoundaryBinding): string;
 /**
- * A boundary string that no protocol claims keeps its case, because
- * message-bus keys are case-sensitive and uppercasing one would break
- * the rule without saying so.
+ * The boundary and the name a read took across it, as a report prints
+ * them: `runtime-config ACCOUNTS_REGION`. A boundary with no label of its
+ * own prints as its protocol, because the name already says what was
+ * read, and the recognizer the fallback label adds is a package name
+ * nobody reading the report can act on.
+ */
+declare function labelWithDetail(binding: BoundaryBinding, detail: string): string;
+/**
+ * A suppression rule's boundary string, normalized by the protocol that
+ * recognizes it. A string no protocol recognizes keeps its case,
+ * because message-bus keys are case-sensitive and uppercasing one would
+ * make the rule stop matching without any error.
  */
 declare function normalizeRuleBoundary(raw: string): string;
 declare function exchangesHttpResponses(binding: BoundaryBinding): boolean;
@@ -589,9 +601,11 @@ declare function leavesTheProcess(binding: BoundaryBinding): boolean;
 declare function canPair(binding: BoundaryBinding): boolean;
 declare function reportsUnpairedItself(binding: BoundaryBinding): boolean;
 /**
+ * Whether this binding serves a request with the given method and path.
+ *
  * Null means the protocol does not address its boundaries by method and
- * path at all, which a caller has to tell apart from an unknown answer:
- * unknown means it does, but this declaration cannot settle the question.
+ * path at all. A caller has to tell that apart from `"unknown"`, which
+ * means the protocol does, but this declaration cannot settle it.
  */
 declare function servesRequest(binding: BoundaryBinding, method: string, path: string): MatchResult | null;
 /**
@@ -602,64 +616,61 @@ declare function servesRequest(binding: BoundaryBinding, method: string, path: s
 declare function withinScope(binding: BoundaryBinding, scope: string): boolean;
 
 /**
- * How somebody spells a boundary they want to talk about, and whether
- * what they wrote picks out a given one.
+ * How a person writes a boundary they want to ask about, and whether
+ * what they wrote picks out a given boundary.
  *
- * The words get cut into tokens, the boundary does too, and a boundary
- * matches when it has every token somebody wrote. So
+ * The text and the boundary are both split into tokens, and a boundary
+ * matches when it has every token in the text. So
  * `aws.dynamodb:editions` matches the table and every index on it, and
  * adding `#by-publication` narrows it to the one index.
  *
- * `suss ask`, `suss check --at` and an intent document that says which
- * store a write reaches all read this, so the question and the
- * assertion are spelled and resolved the same way.
+ * `suss ask`, `suss check --at` and an intent document that gives the
+ * store a write reaches all match through these functions, so a
+ * question and an assertion resolve the same way.
  */
 
 /**
- * The name inside a fully-qualified cloud resource id, and anything
- * else unchanged.
+ * The name inside a fully qualified cloud resource id. Any other string
+ * comes back unchanged.
  *
  * `arn:aws:lambda:us-east-1:1234:function:prod-worker` and
- * `projects/p/locations/l/functions/prod-worker` say the same thing as
- * `prod-worker` plus an account and a region. Keeping the whole string
- * makes one deployment's spelling of a resource disagree with
- * another's, so every reader that meets one reduces it here and the two
- * sides compare the part they can both know. A Lambda ARN's trailing
- * alias or version comes off with the rest: the function is the
- * boundary whichever published copy a call reaches.
+ * `projects/p/locations/l/functions/prod-worker` are `prod-worker` plus
+ * an account and a region. Two deployments of one resource have
+ * different full ids, so readers reduce an id to its name here and the
+ * two sides compare the part they both know. A Lambda ARN's trailing
+ * alias or version is dropped too, since the function is the boundary
+ * whichever published version a call reaches.
  */
 declare function resourceNameIn(spelling: string): string;
 /**
- * The words in a boundary spelling. Separators between parts of a name
- * are cut, and the characters inside one part are left alone, so
- * `by-publication` stays one word and `{id}` and `:id` both come out as
- * `id`.
+ * The lowercase words in a boundary spelling. The text is split at the
+ * separators between parts of a name, and each part is kept whole, so
+ * `by-publication` stays one word and `{id}` and `:id` both become `id`.
  */
 declare function spellingTokens(text: string): string[];
-/** Every word this boundary can be asked about by. */
+/** Every word a person can use to ask about this boundary. */
 declare function bindingTokens(binding: BoundaryBinding): Set<string>;
 /**
- * Whether what somebody typed is the whole of this boundary's name
- * rather than part of it. `POST /articles` is exactly the collection
- * route and only part of `POST /articles/{slug}/comments`.
+ * Whether the typed text has every word of this boundary's label and
+ * nothing more. `POST /articles` matches the collection route exactly,
+ * and only partly matches `POST /articles/{slug}/comments`.
  */
 declare function namesBoundaryExactly(subject: string, binding: BoundaryBinding): boolean;
-/** Whether what somebody typed picks out this boundary. */
+/** Whether the typed text picks out this boundary: every word in it is one of the boundary's words. */
 declare function namesBoundary(subject: string, binding: BoundaryBinding): boolean;
 
 /**
- * Deciding when two message-bus channel strings mean the same thing.
+ * When two message-bus channel strings mean the same channel.
  *
- * A channel is a subject, optionally qualified by the bus that carries
- * it, written `${bus}#${subject}`. The two sides of a pairing rarely
- * know the same amount, so they pair on the subject and the buses have
- * to agree only when both sides know one. The package README works
- * through why, with examples.
+ * A channel is a subject, optionally qualified by the bus it travels
+ * on, written `${bus}#${subject}`. The two sides of a pairing rarely
+ * know the same amount, so they pair on the subject, and the buses have
+ * to match only when both sides know one. The package README explains
+ * why, with examples.
  *
- * Everything that writes or reads that string goes through
- * `formatChannel` and `parseChannel`, so the wire format has a single
- * author. A template reader that hand-writes the `#` would be a second
- * author, and the two would drift the first time either one changed.
+ * All code that writes or reads the string goes through `formatChannel`
+ * and `parseChannel`. A template reader that wrote the `#` by hand would
+ * drift from them the first time either one changed.
  */
 /** A channel string, written `${bus}#${subject}`, split into its two parts. */
 interface ParsedChannel {
@@ -669,31 +680,33 @@ interface ParsedChannel {
 declare function parseChannel(channel: string): ParsedChannel;
 declare const ChannelBrand: unique symbol;
 /**
- * `bus#subject`, or the bare subject when no source said the bus. The
- * unqualified form is legal, so fields keep the type string and the
- * mint is the whole win: a channel assembled by hand cannot claim the
- * brand, and the format has one spelling (#167).
+ * `bus#subject`, or the bare subject when no source gave the bus.
+ *
+ * Fields that store a channel stay typed as `string`, since a bare
+ * subject is legal there. The brand exists so that a `Channel` value
+ * can only come from `formatChannel` and never from a string built by
+ * hand (#167).
  */
 type Channel = string & {
     readonly [ChannelBrand]: "channel";
 };
 declare function formatChannel(bus: string | null, subject: string): Channel;
+/** A side that does not know its bus agrees with any bus. */
 declare function busesAgree(a: string | null, b: string | null): boolean;
 declare function channelsPair(a: string, b: string): boolean;
 
 /**
- * One convention for the source directory a deployable unit is built
- * from, one test for whether a file is inside it, and one reading of
- * the handler string that says which code the platform calls.
+ * The source directory a deployable unit is built from, and the handler
+ * string that says which code the platform calls.
  *
- * A deploy template gives a directory per unit, and a summary stores it
+ * A deploy template gives each unit a directory, and a summary stores it
  * as `metadata.codeScope.path`. Producers write that path and the
- * checker reads it back as a prefix test, so the two sides have to
- * agree on whether it ends in a slash. The test also has to stop at a
- * segment boundary, or `src/foo` would cover `src/foobar` and a handler
- * would pair with the wrong function. A CloudFormation template and a
- * Terraform configuration spell a handler the same way, so they read it
- * through the same function rather than through two of them.
+ * checker reads it back as a prefix test, so both sides normalize it
+ * through `codeScopePath` and agree on the trailing slash. The test
+ * stops at a segment boundary, or `src/foo` would cover `src/foobar` and
+ * a handler would pair with the wrong function. CloudFormation and
+ * Terraform write a handler the same way, so both read it through
+ * `parseHandler`.
  */
 /**
  * The canonical form of a code-scope directory: no leading `./`, no
@@ -706,8 +719,8 @@ declare function codeScopePath(raw: string): string;
  * at a segment boundary, so `src/foo` covers `src/foo/a.ts` and never
  * `src/foobar/a.ts`. A scope that is the project root covers every file.
  *
- * Both arguments go through `codeScopePath`, so a scope stored with a
- * trailing slash and one stored without it are read the same way.
+ * Both arguments are normalized with `codeScopePath`, so a trailing
+ * slash on either one makes no difference.
  */
 declare function fileInCodeScope(file: string, scope: string): boolean;
 interface ParsedHandler {
@@ -723,13 +736,12 @@ interface ParsedHandler {
 declare function parseHandler(handler: string): ParsedHandler | null;
 
 /**
- * The DispatchTable idiom: dispatch on a discriminated union through a
- * mapped-type Record, so a missing variant is a type error rather than a
- * runtime fall-through. It is decision #8 in design/docs-internal/style.md.
+ * Dispatch on a discriminated union through a mapped-type Record, so a
+ * table that misses a variant fails to compile. This is decision #8 in
+ * the internal style guide.
  *
- * It is here rather than in one package because the decision applies
- * repo-wide, and every package that walks an IR union needs it. Three
- * of them had written their own copy before this one existed.
+ * Every package that walks an IR union needs it, so it lives in ir-core
+ * and packages do not keep their own copies.
  */
 type DispatchTable<T extends {
     type: string;
@@ -743,17 +755,16 @@ declare function dispatchByType<T extends {
 }, R>(table: DispatchTable<T, R>, value: T): R;
 
 /**
- * The variables a deployment medium puts in a process's environment
+ * The variables a deployment platform puts in a process's environment
  * whatever its configuration says.
  *
- * Code reads them and nothing declares them, so a reader that left them
- * out would accuse every deployment of failing to supply `AWS_REGION`.
- * Two readers describe the same Lambda, a CloudFormation template and a
- * Terraform configuration, and a variable one of them knew about and
- * the other did not would be an error in one and not the other, so the
- * list is stated once here. A medium whose vendor documents a different
- * set per product, Cloud Run's `K_SERVICE` against a plain container's
- * nothing, states its own list in the pack that describes it.
+ * Code reads them and no template declares them, so without this list
+ * every deployment would be reported for failing to supply
+ * `AWS_REGION`. A CloudFormation template and a Terraform configuration
+ * can describe the same Lambda, and both use this one list so they
+ * agree on which variables are present. A platform whose vendor
+ * documents a different set per product, such as Cloud Run with its
+ * `K_SERVICE`, lists its variables in the pack that describes it.
  */
 
 /**
@@ -767,16 +778,17 @@ declare function dispatchByType<T extends {
 declare const PLATFORM_INJECTED_ENV_VARS: Record<DeployableUnit["deploymentTarget"], ReadonlyArray<string>>;
 
 /**
- * What a unit does at a boundary, in the words `suss ask` asks with.
+ * What a unit does at a boundary, in the words `suss ask` uses.
  *
- * `what writes postgresql:invoices` is the question and "this outcome
- * writes postgresql:invoices" is the assertion, so the report, the
- * question parser and an intent doc all have to spell the verbs the
- * same way. They are here rather than beside any one of them.
+ * A user asks `what writes postgresql:invoices`, and an intent doc
+ * asserts "this outcome writes postgresql:invoices". The report, the
+ * question parser and the intent reader all have to spell the verbs the
+ * same way, so the verbs are defined here once.
  *
- * `provides` is the unit's own boundary; `reads`, `writes` and
- * `invokes` are what a call site does at somebody else's. Calling a
- * deployed unit by name is one act, so it gets a verb of its own.
+ * `provides` is a boundary the unit serves. `reads`, `writes` and
+ * `invokes` are what a call site does at a boundary somebody else
+ * serves. Calling a deployed unit by name is its own act, so it gets
+ * its own verb.
  */
 
 declare const RelationSchema: z.ZodEnum<{
@@ -798,7 +810,7 @@ declare const EffectRelationSchema: z.ZodEnum<{
 type EffectRelation = z.infer<typeof EffectRelationSchema>;
 
 /**
- * pathPattern.ts: whether two route paths describe a request in common.
+ * Whether two route paths describe a request in common.
  *
  * A normalized path is text with holes in it. `{id}` is exactly one
  * segment, `{tenant?}` is zero or one, `{rest+}` is one or more and
@@ -811,32 +823,31 @@ type EffectRelation = z.infer<typeof EffectRelationSchema>;
  * segments, and walks the two segment lists with a reachability table
  * in which a hole absorbs as many segments as its range allows.
  */
-/** How many segments a hole takes, in the words the value domain uses. */
+/** How many segments a hole takes: exactly one, zero or one, one or more, or any number. */
 type HoleRange = "one" | "optional" | "many" | "any";
-/** How a hole taking `range` segments is spelled in a path. */
+/** The path text for a hole that takes `range` segments, such as `{rest+}`. */
 declare function rangedHole(name: string, range: HoleRange): string;
 /**
- * How a piece that is one of several texts is spelled in a path, or
- * null when an option would be read as something else, such as a set
- * boundary or the start of a query.
+ * The path text for a piece that matches any one of `options`, such as
+ * `(v1|v2)`. Null when an option would parse as something else, such as
+ * a set boundary or the start of a query.
  */
 declare function setPiece(options: readonly string[]): string | null;
 /** Negative when `a` ranks below `b`, positive above, zero when equal. */
 declare function compareRanks(a: readonly number[], b: readonly number[]): number;
 
 /**
- * The suppression pipeline, over the smallest finding both checkers share.
+ * Suppression rules and how they apply to findings from either checker.
  *
- * Behavioural `Finding` and intent `IntentFinding` both have `kind`,
- * `severity`, and an optional `suppressed`, which is all the pipeline
- * needs. The rule schema, first-match-wins matching, effect application,
- * and threshold counting are here so the two checkers share one
- * implementation without depending on each other. Only the matching of a
- * rule's discriminators differs, and a caller passes that in.
+ * Behavioral `Finding` and intent `IntentFinding` both have `kind`,
+ * `severity` and an optional `suppressed`, and the pipeline needs
+ * nothing else. The rule schema, first-match-wins matching, effect
+ * application and threshold counting are here so the two checkers share
+ * one implementation without depending on each other. Each checker
+ * passes in its own matcher for a rule's discriminators past `kind`.
  *
- * The module owns rules and matching, not file I/O. The CLI reads a
- * .sussignore file, checks each kind against the published enums, and
- * hands the parsed rules over.
+ * The CLI reads the `.sussignore` file, checks each kind against the
+ * published enums, and passes the parsed rules in.
  */
 
 declare const SuppressionRuleSchema: z.ZodObject<{
@@ -850,6 +861,7 @@ declare const SuppressionRuleSchema: z.ZodObject<{
         summary: z.ZodOptional<z.ZodString>;
         transitionId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    scenario: z.ZodOptional<z.ZodString>;
     scope: z.ZodDefault<z.ZodEnum<{
         narrow: "narrow";
         broad: "broad";
@@ -875,6 +887,7 @@ declare const SuppressionFileSchema: z.ZodObject<{
             summary: z.ZodOptional<z.ZodString>;
             transitionId: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        scenario: z.ZodOptional<z.ZodString>;
         scope: z.ZodDefault<z.ZodEnum<{
             narrow: "narrow";
             broad: "broad";
@@ -897,11 +910,11 @@ interface FindingSuppression {
     originalSeverity?: SuppressableSeverity | undefined;
 }
 /**
- * The structural base that both finding types satisfy. Behavioural
- * `Finding` and intent `IntentFinding` each declare these fields in
- * their own schemas, kept structurally identical, and the pipeline needs
- * nothing more. The `| undefined` unions match what zod infers for
- * `.optional()` fields under exactOptionalPropertyTypes.
+ * The fields both finding types share. Behavioral `Finding` and intent
+ * `IntentFinding` each declare these fields in their own schemas, and
+ * the two declarations have to stay structurally identical. The
+ * `| undefined` unions match what zod infers for `.optional()` fields
+ * under exactOptionalPropertyTypes.
  */
 interface SuppressibleFinding {
     kind: string;
@@ -909,10 +922,11 @@ interface SuppressibleFinding {
     suppressed?: FindingSuppression | undefined;
 }
 /**
- * Check that a narrow rule constrains something. A bare rule with only
- * a `reason` would suppress every finding in the codebase, which is
- * almost always a mistake. Broad-scope rules are allowed to match less
- * specifically, on purpose.
+ * An error message when a rule does not constrain enough, or null when
+ * it is valid. A rule with only a `reason` would suppress every finding
+ * in the codebase, which is almost always a mistake. A broad rule needs
+ * one constraint of any kind, and a narrow rule needs `kind` plus a
+ * boundary or transition id.
  */
 declare function validateRule(rule: SuppressionRule): string | null;
 
@@ -923,60 +937,69 @@ declare function validateRule(rule: SuppressionRule): string | null;
  */
 declare function ruleBoundaryMatchesKey(ruleBoundary: string, key: string | null): boolean;
 /**
- * Apply suppression rules to a list of findings. This works for either
- * finding type: `matches` decides whether a rule's discriminators past
- * `kind` (boundary, consumer, and so on) match a finding, and the kind
- * check itself is the same everywhere, so it happens here.
+ * Apply suppression rules to a list of findings of either type. This
+ * function checks `kind`, and `matches` checks the rest of a rule's
+ * discriminators (boundary, consumer, and so on) against a finding.
  *
- * Returns a new array. Findings with `effect: "hide"` are omitted from
- * the output entirely unless `keepHidden` is set. Findings with
- * `effect: "mark"` or `"downgrade"` are included with an added
- * `suppressed` field. First matching rule wins.
+ * Returns a new array. The first matching rule applies. A finding a
+ * `hide` rule matches is left out unless `keepHidden` is set. A finding
+ * a `mark` or `downgrade` rule matches is kept with a `suppressed` field
+ * added.
  */
 declare function applySuppressionsToFindings<T extends SuppressibleFinding>(findings: T[], rules: SuppressionRule[], matches: (rule: SuppressionRule, finding: T) => boolean, opts?: {
     keepHidden?: boolean;
 }): T[];
 /**
- * `hide` and `mark` findings are left out of the exit-code threshold,
- * and a `downgrade` finding counts at the severity it was downgraded
- * to. Callers use this to decide whether a finding contributes to
- * `hasErrors`-style gating.
+ * Whether a finding counts toward the exit-code threshold. A `hide` or
+ * `mark` finding does not count, and a `downgrade` finding counts at the
+ * severity it was downgraded to.
  */
 declare function countsForThreshold(finding: SuppressibleFinding): boolean;
 
 /**
- * urlPath.ts: the path part of a URL, however the URL was written.
+ * How a `test` unit is named. Every test pack names a test by its title
+ * path, the suite titles outermost first and then the test's own, and a
+ * PRD scenario's `coveredBy` entry is matched against that name, so the
+ * adapters that write it and the check that reads it share this one
+ * spelling.
+ */
+/** What joins the titles in a test unit's name, and the file and titles in a `coveredBy` entry. */
+declare const TEST_TITLE_SEPARATOR = " > ";
+declare function testUnitName(titles: readonly string[]): string;
+
+/**
+ * The path part of a URL, however the URL was written.
  *
- * Two sides of one boundary spell it differently. A provider says
- * `/orders`, because a route is mounted at a path. A consumer says
- * `http://backend.internal/orders`, because a call has to say which
- * host. They are the same boundary, and pairing them means reading the
- * path out of both.
+ * The two sides of one boundary spell a URL differently. A provider
+ * writes `/orders`, because a route is mounted at a path. A consumer
+ * writes `http://backend.internal/orders`, because a call has to give a
+ * host. Pairing them means reading the path out of both.
  *
- * The query and the fragment come off with the origin. Neither picks a
- * route: `/orders?page=2` reaches the same handler as `/orders`.
+ * The query and the fragment are removed along with the origin, because
+ * neither one picks a route: `/orders?page=2` reaches the same handler
+ * as `/orders`.
  */
 /**
  * The path a URL states, with any origin, query, and fragment removed.
  *
- * Text that states no origin comes back with only the query and the
+ * Text without an origin comes back with only the query and the
  * fragment removed, since a relative URL is already a path. A URL that
- * is nothing but an origin comes back as an empty string, which is what
- * a caller wanting a path should treat as "the root".
+ * is only an origin comes back as an empty string, and a caller should
+ * treat that as the root.
  */
 declare function pathAfterOrigin(text: string): string;
-/** Whether the text opens with an origin rather than with a path. */
+/** Whether the text starts with an origin (a scheme and host, or `//host`). */
 declare function statesAnOrigin(text: string): boolean;
 
 /**
  * @suss/ir-core: primitives shared across suss IRs.
  *
- * The schemas are the single source of truth, and the types come from
- * them. Each boundary protocol's schema and behavior are in one module
- * under `./semantics`, and everything else is in `./schemas`. The
- * boundary-binding constructors are here too, so that any package that
- * produces an IR object (pattern packs, contract readers, intent docs,
- * tests) can build a binding without depending on a specific IR.
+ * The zod schemas are the source of truth, and the types are derived
+ * from them. Each boundary protocol defines its schema and its pairing
+ * behavior together in one module. The boundary-binding constructors
+ * are here too, so any package that produces an IR object, such as a
+ * pattern pack or a contract reader, can build a binding without
+ * depending on a specific IR.
  */
 
 type ConfidenceSource = z.infer<typeof ConfidenceSourceSchema>;
@@ -1000,8 +1023,8 @@ declare function restBinding(opts: {
     declaredResponses?: number[];
 }): BoundaryBinding;
 /**
- * Build a function-call-semantics binding. Used by in-process packs
- * (React components, custom-hook boundaries, bare TS function exports).
+ * Build a function-call-semantics binding, for an in-process boundary
+ * such as a React component or an exported TypeScript function.
  */
 declare function functionCallBinding(opts: {
     transport: string;
@@ -1022,6 +1045,17 @@ declare function packageExportBinding(opts: {
     packageName: string;
     exportPath: string[];
 }): BoundaryBinding;
+/**
+ * Build a function-call binding for a public export of one of the
+ * modules a project lists in `suss.json`. Its key is
+ * `fn:<module>::<exportName>`, so an intent document or a PRD scenario
+ * can point at it by the module's name.
+ */
+declare function moduleExportBinding(opts: {
+    recognition: string;
+    module: string;
+    exportName: string;
+}): BoundaryBinding;
 /**
  * Build a graphql-resolver-semantics binding. Transport varies by
  * deployment: `"http"` for Apollo Server, `"aws-https"` for AppSync.
@@ -1044,20 +1078,20 @@ declare function graphqlOperationBinding(opts: {
     operationName?: string;
 }): BoundaryBinding;
 /**
- * Whether a binding is the consumer side of a GraphQL boundary,
- * settled by the protocol's own schema so callers do not compare the
- * semantics tag themselves.
+ * Whether a binding is the consumer side of a GraphQL boundary, checked
+ * against the protocol's own schema so callers do not compare the
+ * semantics tag by hand.
  */
 declare function isGraphqlOperationBinding(binding: BoundaryBinding | null | undefined): boolean;
 /**
- * Build a runtime-config binding for a runtime configuration channel
- * (env vars on a Lambda, ECS task, container, or k8s pod). Transport is
- * `"os"` because the OS hands env vars to the process at startup no
- * matter what the deployment medium is.
+ * Build a runtime-config binding, for the environment variables a
+ * deployed unit starts with. Transport is `"os"` because the operating
+ * system passes environment variables to the process at startup,
+ * whatever platform deployed it.
  *
- * A provider says which deployment it is. A recognizer standing at a
- * read in the code leaves both off, since nothing in the code says
- * which deployment will run it.
+ * A provider passes its deployment target and instance name. A
+ * recognizer at a read in the code leaves both out, since the code does
+ * not say which deployment runs it.
  */
 declare function runtimeConfigBinding(opts: {
     recognition: string;
@@ -1077,11 +1111,11 @@ declare function unitInvocationBinding(opts: {
     instanceName: string | null;
 }): BoundaryBinding;
 /**
- * Build a storage binding, the side of a store that both a schema
- * reader and a call site can spell. `transport` defaults to the store's
- * own name, which is right for a database whose product and wire
- * protocol are the same word; a store reached over an SDK passes its
- * wire instead, and one whose engine nobody settled has none to pass.
+ * Build a storage binding, which describes a store in terms both a
+ * schema reader and a call site can write. `transport` defaults to the
+ * storage system's name, which suits a database whose product and wire
+ * protocol share a name. A store reached through an SDK passes its wire
+ * protocol. With no storage system either, the transport is `"storage"`.
  */
 declare function storageBinding(opts: {
     recognition: string;
@@ -1114,5 +1148,15 @@ declare function metricBinding(opts: {
     /** Null when this source states a metric it could not name. */
     metricType: string | null;
 }): BoundaryBinding;
+/**
+ * Build an io binding, for a write to one of the process's own streams.
+ * The transport is `"in-process"` because the write is a call the
+ * program makes, and the runtime moves the bytes on from there.
+ */
+declare function ioBinding(opts: {
+    recognition: string;
+    /** Null when this source does not say which stream. */
+    target: string | null;
+}): BoundaryBinding;
 
-export { type BoundaryBehavior, type BoundaryBinding, BoundaryBindingSchema, type BoundaryName, type BoundarySemanticsDefinition, type BusIdentityKey, type Channel, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, DeployableUnit, type Deployment, type DispatchTable, type Ecosystem, type EffectRelation, EffectRelationSchema, type FindingSuppression, type FnIdentityKey, type GqlIdentityKey, type HoleRange, type MatchResult, MessageBusSemantics, MessageBusTechnology, type MetricIdentityKey, type MetricSemantics, MetricSemanticsSchema, NOTHING_DEPLOYED, type NamePart, PLATFORM_INJECTED_ENV_VARS, type PackConfiguration, type PackDeclaration, type ParsedChannel, type ParsedHandler, type Reference, type Relation, RelationSchema, Semantics, type SemconvAttribute, type SemconvMapping, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, type UnitIdentityKey, type UnitInvocationSemantics, UnitInvocationSemanticsSchema, applySuppressionsToFindings, bindingIs, bindingTokens, bodyShapesMatch, boundaryKey, boundaryLabel, boundaryNameString, bucketRank, bucketsMeet, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, compareRanks, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fixedTextLength, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, groundBinding, groundedPairingKey, hasNameHole, isGraphqlOperationBinding, leavesTheProcess, messageBusBinding, metricBinding, metricIdentityKey, namePatternFromSub, namePatternKey, nameReference, namesAgree, namesBoundary, namesBoundaryExactly, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseBoundaryName, parseChannel, parseHandler, pathAfterOrigin, patternHole, rangedHole, referenceFromName, referenceName, referenceOf, reportsUnpairedItself, resourceNameIn, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, semconvAttributes, servesRequest, setPiece, spansBuckets, spellingTokens, statesAnOrigin, storageBinding, unitIdentityKey, unitInvocationBinding, validateRule, withRewrittenPaths, withinScope };
+export { type BoundaryBehavior, type BoundaryBinding, BoundaryBindingSchema, type BoundaryName, type BoundarySemanticsDefinition, type BusIdentityKey, type Channel, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, DeployableUnit, type Deployment, type DispatchTable, type Ecosystem, type EffectRelation, EffectRelationSchema, type FindingSuppression, type FnIdentityKey, type GqlIdentityKey, type HoleRange, type IoIdentityKey, type IoSemantics, IoSemanticsSchema, type MatchResult, MessageBusSemantics, MessageBusTechnology, type MetricIdentityKey, type MetricSemantics, MetricSemanticsSchema, NOTHING_DEPLOYED, type NamePart, PLATFORM_INJECTED_ENV_VARS, type PackConfiguration, type PackDeclaration, type ParsedChannel, type ParsedHandler, type Reference, type Relation, RelationSchema, Semantics, type SemconvAttribute, type SemconvMapping, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TEST_TITLE_SEPARATOR, TypeShape, type UnitIdentityKey, type UnitInvocationSemantics, UnitInvocationSemanticsSchema, applySuppressionsToFindings, bindingIs, bindingTokens, bodyShapesMatch, boundaryKey, boundaryLabel, boundaryNameString, bucketRank, bucketsMeet, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, compareRanks, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fixedTextLength, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, groundBinding, groundedPairingKey, hasNameHole, ioBinding, ioIdentityKey, isGraphqlOperationBinding, labelWithDetail, leavesTheProcess, messageBusBinding, metricBinding, metricIdentityKey, moduleExportBinding, namePatternFromSub, namePatternKey, nameReference, namesAgree, namesBoundary, namesBoundaryExactly, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseBoundaryName, parseChannel, parseHandler, pathAfterOrigin, patternHole, rangedHole, referenceFromName, referenceName, referenceOf, reportsUnpairedItself, resourceNameIn, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, semconvAttributes, servesRequest, setPiece, spansBuckets, spellingTokens, statesAnOrigin, storageBinding, testUnitName, unitIdentityKey, unitInvocationBinding, validateRule, withRewrittenPaths, withinScope };