@suss/intent-ir 0.3.1 → 0.4.0

package/README.md

@@ -1,13 +1,13 @@
 # @suss/intent-ir
 
-The team-authored side of the loop: what the code was *meant* to do, in shapes that pair against the derived `BehavioralSummary` of what it *does*.
+The team-authored side of the loop: what the code was *meant* to do, in a form that pairs against the derived `BehavioralSummary` of what it *does*.
 
 ## What this package is
 
 Two citizens, discriminated by `kind`, both built on `@suss/ir-core` so intent and behaviour describe boundaries the same way:
 
 - **System intent** (`kind: boundary`): what one boundary should do, as named outcomes. The boundary is REST **or** function-call; each outcome is a `response` (status + body), a `returns` (a function/handler return value), or a `throws` (an error). The function-call form is what lets suss check its own non-HTTP surface.
-- **Outcome intent** (`kind: prd`): human `when` / `expect` scenarios, each with an optional `link` to a system-intent outcome (`<intent-name>.<outcome-id>`). A scenario with no `link` is a valid pending-link state: fully readable, not yet machine-linked.
+- **Outcome intent** (`kind: prd`): human `when` / `expect` scenarios, each with an optional `link` to a system-intent outcome (`<intent-name>.<outcome-id>`). A scenario with no `link` is a valid state to be in: it reads fully, and nothing has linked it to an outcome yet.
 
 ```ts
 import { IntentDocSchema, intentDocToSummary } from "@suss/intent-ir";
@@ -16,13 +16,13 @@ const doc = IntentDocSchema.parse(/* parsed YAML / JSON */);
 const summary = intentDocToSummary(doc); // normalised, checker-ready
 ```
 
-`schema.ts` is the authoring surface (friendly to write); `summary.ts` is the normalized shape the checker consumes (boundaries as `ir-core` `BoundaryBinding`s, bodies as `TypeShape`s, one flat outcome list) plus the transform between them. `source` provenance (`author` / `inferred` / `inferred, curated`) rides along for the inference path.
+`schema.ts` is the authoring surface (friendly to write); `summary.ts` is the normalized form the checker consumes (boundaries as `ir-core` `BoundaryBinding`s, bodies as `TypeShape`s, one flat outcome list) plus the transform between them. `source` provenance (`author` / `inferred` / `inferred, curated`) travels along with it for the inference path.
 
 The design is documented in [`docs/internal/proposals/intent-specs.md`](../../docs/internal/proposals/intent-specs.md).
 
-## Where it sits in suss
+## Where it fits in suss
 
-Peer to `@suss/behavioral-ir`; both build on `@suss/ir-core`. Readers (e.g. `@suss/contract-intent`) parse files into `IntentDoc` and call `intentDocToSummary`; the checker pairs the result against derived code summaries.
+It is a peer of `@suss/behavioral-ir`; both build on `@suss/ir-core`. Readers (e.g. `@suss/contract-intent`) parse files into `IntentDoc` and call `intentDocToSummary`; the checker pairs the result against derived code summaries.
 
 ## Status
 

package/dist/index.cjs

@@ -47,7 +47,7 @@ var IntentFindingKindSchema = import_zod.z.enum([
   // code produces a REST status the intent doesn't declare
   "unkeyableBoundary",
   // intent boundary can't be keyed, so it can't be checked
-  // Outcome intent (kind: prd) — scenario link coverage against system
+  // Outcome intent (kind: prd), scenario link coverage against system
   // intent. These concretise the proposal's "scenario not linked /
   // dangling / ambiguous" set (docs/internal/proposals/intent-specs.md);
   // the proposal deferred concrete names to implementation time.
@@ -76,7 +76,7 @@ var IntentFindingSchema = import_zod.z.object({
   kind: IntentFindingKindSchema,
   severity: IntentFindingSeveritySchema,
   /**
-   * Human-readable boundary label — e.g. `GET /users/:id` or
+   * Human-readable boundary label: e.g. `GET /users/:id` or
    * `fn:@suss/cli::contract`. The key the intent and code were paired on.
    */
   boundary: import_zod.z.string(),
@@ -88,11 +88,11 @@ var IntentFindingSchema = import_zod.z.object({
    */
   code: import_zod.z.string().optional(),
   /**
-   * PRD-scenario extension — present only on outcome-intent findings
+   * PRD-scenario extension: present only on outcome-intent findings
    * (unlinkedScenario / danglingScenarioLink / ambiguousScenarioLink).
    * Identifies the scenario (by its optional title) and the qualified
    * outcome ref (`<intent-name>.<outcome-id>`) that failed to resolve.
-   * The peer / boundary findings leave it unset — this is the "intent
+   * The peer / boundary findings leave it unset. This is the "intent
    * finding extension" decision 2 of the proposal anticipated.
    */
   scenario: import_zod.z.object({
@@ -201,11 +201,11 @@ var PrdScenarioSchema = import_zod2.z.object({
    * (`<intent-name>.<outcome-id>`). A scenario without `link` is a
    * valid pending-link state: fully human-readable, not yet machine-
    * linked. The link is filled in later by a facilitator (a person, a
-   * platform, or an LLM at authoring time) — never required to author.
+   * platform, or an LLM at authoring time), never required to author.
    *
    * (The human-readable parts are `when` / `expect`; the field is named
    * `link`, not `then`, because a data object with a `then` property is
-   * treated as a thenable by Promise resolution — a latent footgun.)
+   * treated as a thenable by Promise resolution, a latent footgun.)
    */
   link: import_zod2.z.union([import_zod2.z.string().min(1), import_zod2.z.array(import_zod2.z.string().min(1)).min(1)]).optional()
 });

package/dist/index.d.cts

@@ -117,20 +117,20 @@ declare const BoundarySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 declare const BoundaryTransitionSchema: z.ZodObject<{
     id: z.ZodString;
     when: z.ZodString;
-    response: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+    response: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
         status: z.ZodNumber;
         body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
             properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>>>;
             required: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>]>>;
     }, z.core.$strip>>>;
-    returns: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+    returns: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
         body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
             properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>>>;
             required: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>]>>;
     }, z.core.$strip>>>;
-    throws: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+    throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
         errorType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
@@ -160,20 +160,20 @@ declare const BoundaryIntentSchema: z.ZodObject<{
     transitions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         when: z.ZodString;
-        response: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+        response: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             status: z.ZodNumber;
             body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
                 properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>>>;
                 required: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>]>>;
         }, z.core.$strip>>>;
-        returns: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+        returns: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
                 properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>>>;
                 required: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>]>>;
         }, z.core.$strip>>>;
-        throws: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+        throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             errorType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
@@ -227,20 +227,20 @@ declare const IntentDocSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     transitions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         when: z.ZodString;
-        response: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+        response: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             status: z.ZodNumber;
             body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
                 properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>>>;
                 required: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>]>>;
         }, z.core.$strip>>>;
-        returns: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+        returns: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
                 properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>>>;
                 required: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>]>>;
         }, z.core.$strip>>>;
-        throws: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+        throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             errorType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
@@ -279,7 +279,7 @@ declare const PrimitiveTypeName: z.ZodEnum<{
 }>;
 type PrimitiveTypeName = z.infer<typeof PrimitiveTypeName>;
 
-/** How a boundary outcome resolves — the cross-kind unification. */
+/** How a boundary outcome resolves, the cross-kind unification. */
 type IntentOutcomeKind = "response" | "return" | "throw";
 interface IntentOutcome {
     /** Author-declared id PRD scenarios reference. */

package/dist/index.d.ts

@@ -117,20 +117,20 @@ declare const BoundarySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 declare const BoundaryTransitionSchema: z.ZodObject<{
     id: z.ZodString;
     when: z.ZodString;
-    response: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+    response: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
         status: z.ZodNumber;
         body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
             properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>>>;
             required: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>]>>;
     }, z.core.$strip>>>;
-    returns: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+    returns: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
         body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
             properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>>>;
             required: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>]>>;
     }, z.core.$strip>>>;
-    throws: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+    throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
         errorType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
@@ -160,20 +160,20 @@ declare const BoundaryIntentSchema: z.ZodObject<{
     transitions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         when: z.ZodString;
-        response: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+        response: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             status: z.ZodNumber;
             body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
                 properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>>>;
                 required: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>]>>;
         }, z.core.$strip>>>;
-        returns: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+        returns: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
                 properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>>>;
                 required: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>]>>;
         }, z.core.$strip>>>;
-        throws: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+        throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             errorType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
@@ -227,20 +227,20 @@ declare const IntentDocSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     transitions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         when: z.ZodString;
-        response: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+        response: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             status: z.ZodNumber;
             body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
                 properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>>>;
                 required: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>]>>;
         }, z.core.$strip>>>;
-        returns: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+        returns: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
                 properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>>>;
                 required: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>]>>;
         }, z.core.$strip>>>;
-        throws: z.ZodOptional<z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodObject<{
+        throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             errorType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
@@ -279,7 +279,7 @@ declare const PrimitiveTypeName: z.ZodEnum<{
 }>;
 type PrimitiveTypeName = z.infer<typeof PrimitiveTypeName>;
 
-/** How a boundary outcome resolves — the cross-kind unification. */
+/** How a boundary outcome resolves, the cross-kind unification. */
 type IntentOutcomeKind = "response" | "return" | "throw";
 interface IntentOutcome {
     /** Author-declared id PRD scenarios reference. */

package/dist/index.js

@@ -12,7 +12,7 @@ var IntentFindingKindSchema = z.enum([
   // code produces a REST status the intent doesn't declare
   "unkeyableBoundary",
   // intent boundary can't be keyed, so it can't be checked
-  // Outcome intent (kind: prd) — scenario link coverage against system
+  // Outcome intent (kind: prd), scenario link coverage against system
   // intent. These concretise the proposal's "scenario not linked /
   // dangling / ambiguous" set (docs/internal/proposals/intent-specs.md);
   // the proposal deferred concrete names to implementation time.
@@ -41,7 +41,7 @@ var IntentFindingSchema = z.object({
   kind: IntentFindingKindSchema,
   severity: IntentFindingSeveritySchema,
   /**
-   * Human-readable boundary label — e.g. `GET /users/:id` or
+   * Human-readable boundary label: e.g. `GET /users/:id` or
    * `fn:@suss/cli::contract`. The key the intent and code were paired on.
    */
   boundary: z.string(),
@@ -53,11 +53,11 @@ var IntentFindingSchema = z.object({
    */
   code: z.string().optional(),
   /**
-   * PRD-scenario extension — present only on outcome-intent findings
+   * PRD-scenario extension: present only on outcome-intent findings
    * (unlinkedScenario / danglingScenarioLink / ambiguousScenarioLink).
    * Identifies the scenario (by its optional title) and the qualified
    * outcome ref (`<intent-name>.<outcome-id>`) that failed to resolve.
-   * The peer / boundary findings leave it unset — this is the "intent
+   * The peer / boundary findings leave it unset. This is the "intent
    * finding extension" decision 2 of the proposal anticipated.
    */
   scenario: z.object({
@@ -166,11 +166,11 @@ var PrdScenarioSchema = z2.object({
    * (`<intent-name>.<outcome-id>`). A scenario without `link` is a
    * valid pending-link state: fully human-readable, not yet machine-
    * linked. The link is filled in later by a facilitator (a person, a
-   * platform, or an LLM at authoring time) — never required to author.
+   * platform, or an LLM at authoring time), never required to author.
    *
    * (The human-readable parts are `when` / `expect`; the field is named
    * `link`, not `then`, because a data object with a `then` property is
-   * treated as a thenable by Promise resolution — a latent footgun.)
+   * treated as a thenable by Promise resolution, a latent footgun.)
    */
   link: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]).optional()
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/intent-ir",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Intent IR for suss — the team-authored side of the loop. PRD (outcome) intent and system intent, in shapes that pair against derived behavioral summaries.",
   "keywords": [
@@ -47,7 +47,7 @@
     "zod": "^4.0.0"
   },
   "dependencies": {
-    "@suss/ir-core": "0.3.1"
+    "@suss/ir-core": "0.4.0"
   },
   "devDependencies": {
     "tsup": "*",