@cowliss/cli 0.6.0 → 0.8.0

package/dist/guest/{journeys-BrcKEXz0.js → journeys-F8Yk8s1P.js}

@@ -4,21 +4,57 @@ import { z } from "zod";
 /** The public docs site, for the mail and the pages that point people at it. */
 const DOCS_URL = "https://docs.cowliss.com";
 /**
+* Stripe-style ID prefixes per resource type, so ids in logs, URLs, and
+* payloads are self-describing.
+*/
+const ID_PREFIXES = {
+	user: "usr_",
+	event: "evt_",
+	identifier: "idn_",
+	segment: "seg_",
+	/** The attribution unit: a readable `app_<slug>`, not a TypeID. */
+	app: "app_",
+	/** One inbound pipe into an app; a TypeID like everything else. */
+	source: "src_",
+	webhook: "whk_",
+	push: "psh_",
+	version: "ver_",
+	execution: "exe_",
+	delivery: "dlv_",
+	violation: "vio_",
+	quarantineEntry: "qtn_",
+	idempotencyKey: "idk_",
+	abuseEvent: "abu_",
+	suppression: "sup_",
+	senderDomain: "dom_",
+	journeyRun: "run_",
+	topup: "top_",
+	emailAddress: "eml_"
+};
+/**
 * Clerk ID prefix marking an organization-scoped subject. Ingestion API keys
 * must resolve to an org subject; user-scoped keys are rejected.
 */
 const CLERK_ORG_SUBJECT_PREFIX = "org_";
 /**
-* Fixed consent purposes for the prototype. Consent is a per-purpose map on
-* the profile, checked at send-step execution time.
-*
-* The two names describe what the recipient agreed to, not the pipe it
-* arrives on: "emails I did not ask for individually" and "my data leaving
-* for somewhere else". Naming them after the channel (`email`, `webhook`)
-* said nothing a recipient could consent to, and transactional mail already
-* bypasses the email purpose, so it was only ever marketing consent.
+* The marketing purpose by name, since it is the one every gate, the
+* unsubscribe route, and the developer's own toggle all reach for.
 */
-const CONSENT_PURPOSES = ["emailMarketing", "dataProcessing"];
+const MARKETING = "marketing";
+/**
+* A legal journey `purpose` that is not a consent purpose: the send gates
+* pass it unconditionally, no profile's map stores it and no editor renders
+* it. What protects the channel itself (suppression, the SES gates, the
+* quota) still applies.
+*/
+const TRANSACTIONAL = "transactional";
+/**
+* The purposes a project may not declare, which are the same two that sit
+* outside the `marketing` umbrella: `marketing` is the umbrella itself and
+* `transactional` is the case consent does not govern. Everything a project
+* declares is a marketing-mail category and so sits under it.
+*/
+const RESERVED_PURPOSES = [MARKETING, TRANSACTIONAL];
 /**
 * The two classes of send, declared on the template rather than passed per
 * call so the class cannot drift between two sends of the same message.
@@ -56,6 +92,82 @@ const PUSH_LIMITS = {
 const COW_CONFIG_SCHEMA_PATH = "/schemas/cow.json";
 const COW_CONFIG_SCHEMA_URL = `${DOCS_URL}${COW_CONFIG_SCHEMA_PATH}`;
 
+//#endregion
+//#region ../../packages/shared/src/segment-definition.ts
+/**
+* A segment definition: a flat list of predicates over traits and event
+* history, combined with `all` or `any`. Deliberately flat — nested predicate groups are YAGNI for the
+* prototype, and a flat list keeps the pure evaluator a fold.
+*
+* A definition names no app (ADR 0022): the segment row's own `app_id` is
+* the one app it evaluates, so the events and the profiles it reads are
+* that app's and there is nothing to filter by here.
+*
+* Apart from `./segments` because a journey's trigger carries a definition
+* and the trigger schema is bundled into the wasm guest, where an edge to
+* `@cowliss/db` (which `./segments` has, for the row schema) is a hard
+* bundler failure. Nothing here imports anything but zod.
+*
+* The object is strict: a definition holding the retired `sourceId` or
+* `appId` key (both of which meant the app) fails loudly instead of parsing
+* as an unfiltered definition that evaluates over every app. There is deliberately no pipe
+* filter here — filtering by source is a later feature, and accepting one
+* now would make a stale `sourceId` parse as a filter on a pipe that does
+* not exist and silently match nothing.
+*/
+const SEGMENT_TRAIT_OPS = [
+	"eq",
+	"neq",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"exists",
+	"notExists",
+	"contains"
+];
+/** Operators that read no comparison value: presence of the key is the test. */
+const VALUELESS_TRAIT_OPS = ["exists", "notExists"];
+const predicateNameSchema = z.string().trim().min(1, "predicate name is required").max(200);
+const segmentPredicateSchema = z.discriminatedUnion("kind", [z.object({
+	kind: z.literal("trait"),
+	name: predicateNameSchema,
+	op: z.enum(SEGMENT_TRAIT_OPS),
+	/**
+	* Compared against the stored trait, which is `unknown` because
+	* identify accepts arbitrary JSON. The evaluator coerces both sides
+	* before comparing, so authors here (CLI, MCP, dashboard) get the
+	* form-field-friendly reading rather than strict JSON equality:
+	* numeric-looking strings are compared as numbers for eq/neq and for
+	* ordering ("150" matches 150, and orders like it), and "true"/"false"
+	* are compared as booleans for eq/neq, trimmed and case-insensitively
+	* (" TRUE " reads as true). Coercion needs both sides to agree on a
+	* type: "0" never equals false. The numeric net is as wide as
+	* `Number()`, so "0x64", "0b11" and "1e2" read as numbers too, which
+	* matters most for opaque ids: "007" is authored as the number 7.
+	*
+	* contains reads three ways. Against an array trait it is membership
+	* under that same equality, so "true" matches `[true]` and "1" matches
+	* `[1, 2]`. Against a string trait it is a plain substring search with
+	* no coercion, since substrings only mean something between strings.
+	* Against anything else it never matches. Ordering never coerces
+	* booleans.
+	*/
+	value: z.unknown().optional()
+}), z.object({
+	kind: z.literal("event"),
+	name: predicateNameSchema,
+	op: z.enum(["performed", "notPerformed"]),
+	/** How many matching events the predicate counts as "performed". */
+	atLeast: z.number().int().min(1).default(1),
+	/** Rolling window, relative to evaluation time; absent means all history. */
+	withinDays: z.number().int().min(1).optional()
+})]).refine((predicate) => predicate.kind !== "trait" || VALUELESS_TRAIT_OPS.includes(predicate.op) || predicate.value !== void 0, { message: "value is required unless op is exists or notExists" });
+const segmentDefinitionSchema = z.strictObject({
+	match: z.enum(["all", "any"]).default("all"),
+	predicates: z.array(segmentPredicateSchema).min(1, "at least one predicate is required")
+});
+
 //#endregion
 //#region ../../packages/shared/src/journeys-v2/manifest.ts
 /**
@@ -65,6 +177,34 @@ const COW_CONFIG_SCHEMA_URL = `${DOCS_URL}${COW_CONFIG_SCHEMA_PATH}`;
 * changed, and stores that entry on the version it creates.
 */
 /**
+* A duration as journey code writes it: an ms-style string ("2d") or
+* milliseconds. It lives here rather than with the guest protocol because a
+* manifest carries one too (a journey's enrollment cooldown) and `./guest`
+* already imports this module, so the other direction would be a cycle.
+*/
+const durationSchema = z.union([z.string().min(1), z.number().int().nonnegative()]);
+const DURATION_PATTERN = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w)$/;
+const DURATION_UNIT_MS = {
+	ms: 1,
+	s: 1e3,
+	m: 6e4,
+	h: 36e5,
+	d: 864e5,
+	w: 6048e5
+};
+/**
+* A duration in milliseconds. The simulator's virtual clock and the runner's
+* timers both need it, and neither may pull in Temporal's `msToNumber` (one
+* runs in the CLI, the other inside workflow code).
+*/
+function parseDuration(duration) {
+	if (typeof duration === "number") return duration;
+	const match = DURATION_PATTERN.exec(duration.trim());
+	if (!match) throw new Error(`Duration ${JSON.stringify(duration)} is not a duration: use milliseconds or an ms-style string like "1h" or "2d".`);
+	const unit = DURATION_UNIT_MS[match[2]];
+	return Math.round(Number(match[1]) * unit);
+}
+/**
 * A journey or template key: the file basename under `journeys/` or
 * `emails/`, kebab-case and unique across the project. Becomes part of the
 * Temporal workflow id and travels in the journey chain, so it stays short.
@@ -85,8 +225,8 @@ const journeyKeySchema = z.string().max(64).regex(JOURNEY_KEY_PATTERN, "key must
 */
 const tagsSchema = z.array(z.string().trim().min(1).max(50, "a tag must be at most 50 characters")).max(20, "a journey or template takes at most 20 tags").default([]).transform((tags) => [...new Set(tags)]);
 /**
-* A consent purpose key: camelCase, matching the fixed `emailMarketing` and
-* `dataProcessing`. Purposes are keys in the `consent` map a customer reads
+* A consent purpose key: camelCase, matching the reserved `marketing` and
+* `transactional`. Purposes are keys in the `consent` map a customer reads
 * on their own profile, which is why they are not the kebab-case of a
 * journey key.
 */
@@ -101,22 +241,22 @@ const CONSENT_PURPOSE_KEY_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
 const consentPurposeKeySchema = z.string().max(50, "a purpose key must be at most 50 characters").regex(CONSENT_PURPOSE_KEY_PATTERN, "a consent purpose key must be camelCase (a letter first, then letters and digits)");
 /**
 * One purpose a project declares in `cow.json` (spec: Decisions). A declared
-* purpose is marketing-class and sits under the `emailMarketing` umbrella,
-* so `denied` is the only default it may carry: the purpose is absent on
-* every profile that already exists, and a granted default would answer for
-* all of them at once.
+* purpose is marketing-class and sits under the `marketing` umbrella, so
+* `denied` is the only default it may carry: the purpose is absent on every
+* profile that already exists, and a granted default would answer for all of
+* them at once.
 *
 * The field stays required rather than disappearing, so every `cow.json` and
-* every stored manifest written before this still parses, and the column
-* behind it still holds `granted` for the seeded `dataProcessing` row: this
-* is a refusal at declaration time, not a narrower storage shape.
+* every stored manifest written before this still parses: this is a refusal
+* at declaration time, not a narrower storage shape.
 *
-* The two fixed purposes cannot be declared. They are seeded for every org
-* and owned by no project, so a project redeclaring one would be renaming
-* the master switch every other project's journeys hang off.
+* Neither reserved purpose can be declared: `marketing` is the master switch
+* every other project's journeys hang off, and `transactional` is not a
+* consent purpose at all, so declaring it would promise a switch that no
+* send ever reads.
 */
 const declaredPurposeSchema = z.strictObject({
-	key: consentPurposeKeySchema.refine((key) => !CONSENT_PURPOSES.includes(key), `${CONSENT_PURPOSES.join(" and ")} are fixed purposes and cannot be declared`),
+	key: consentPurposeKeySchema.refine((key) => !RESERVED_PURPOSES.includes(key), `${RESERVED_PURPOSES.join(" and ")} are reserved purposes and cannot be declared`),
 	/** What the dashboard and the account modal render beside the switch. */
 	label: z.string().trim().min(1).max(50, "a purpose label must be at most 50 characters"),
 	/** What the purpose means for a profile whose map does not answer it. */
@@ -137,19 +277,27 @@ const purposesSchema = z.array(declaredPurposeSchema).max(20, "a project declare
 const onePatternSchema = z.string().min(1).max(200, "a pattern must be at most 200 characters");
 const patternSchema = z.union([onePatternSchema, z.array(onePatternSchema).min(1).max(20, "a matcher takes at most 20 patterns")]);
 /**
-* What starts a journey: an event (optionally narrowed to an app id or a
-* list of them) or a segment entry. The registry DTO in `../journeys`
-* reuses it.
+* What starts a journey: an event, or entry into the segment the trigger
+* itself describes. The registry DTO in `../journeys` reuses it.
+*
+* No trigger names an app (ADR 0022): a repository is one app, the journey
+* row carries its `app_id`, and the runtime compares that with the event's.
+* An `appId` here would be a second way to say it, and the way to leak.
+*
+* A segment trigger carries the predicate list, not a name: the push
+* materializes one segment row per journey that inlines a definition, owned
+* by the journey and named after its key, so the segment exists because the
+* journey exists and there is no order to get wrong (ADR 0016). The
+* definition is data — validated here, carried on the version, never
+* compiled and never executed.
 *
-* Both members are strict, so a journey holding the retired `source` key
-* fails to compile instead of silently triggering on every app.
-* There is deliberately no pipe filter: a trigger narrows by the app the
-* write is attributed to, the same token a segment definition names.
+* Both members are strict, so a journey holding the retired `source` or
+* `appId` key, or the retired `{ segment: "name" }` form, fails to build
+* instead of silently triggering on every app or on nothing. There is
+* deliberately no pipe filter and no app filter: the journey's own app is
+* the only narrowing there is.
 */
-const triggerSchema = z.union([z.strictObject({
-	event: patternSchema,
-	appId: patternSchema.optional()
-}), z.strictObject({ segment: z.string().min(1) })]);
+const triggerSchema = z.union([z.strictObject({ event: patternSchema }), z.strictObject({ segment: segmentDefinitionSchema })]);
 /**
 * The address half of a from-header: a local part, an `@`, and a dotted
 * domain. Deliberately narrower than RFC 5322 (no quoted local parts, no
@@ -252,10 +400,35 @@ const manifestJourneySchema = z.object({
 	*/
 	purpose: consentPurposeKeySchema,
 	/**
+	* How often one recipient may enter. Enrollment derives from the purpose
+	* (ADR 0015), so the only thing an author writes is how long after a
+	* completed run the journey re-opens: absent means once, ever. Refused on
+	* a transactional journey, which enrolls on every trigger — see
+	* `manifestSchema` below, where the cross-field check lives (a refinement
+	* on this object would break the `.pick()` the guest SDK and the guest
+	* protocol both take of it).
+	*/
+	enrollment: z.strictObject({ cooldown: durationSchema.refine((value) => {
+		try {
+			parseDuration(value);
+			return true;
+		} catch {
+			return false;
+		}
+	}, "a cooldown must be milliseconds or an ms-style string like \"7d\"") }).optional(),
+	/**
+	* The author's own sentence about what this journey does, shown wherever
+	* the journey is read. Capped like a segment's description; absent when
+	* the author wrote none.
+	*/
+	description: z.string().trim().max(500, `description must be at most ${500} characters`).optional(),
+	/**
 	* The address every `send.email` in this journey goes out as, unless the
-	* call names its own. Optional everywhere: an omitted one is the
-	* organization's shared fallback address, which is what makes day-one
-	* sending zero-config (ADR 0014).
+	* call names its own. Required of the author (`defineJourney` types it so,
+	* and `cow build` refuses a journey without it), and still optional here:
+	* releases pushed before ADR 0014 was amended carry none, and this schema
+	* parses stored manifests as well as new ones. A push with no `from` is
+	* refused by the domain gate, which says what to do about it.
 	*/
 	from: fromSchema.optional(),
 	spine: z.array(spineEntrySchema),
@@ -268,6 +441,13 @@ const manifestTemplateSchema = z.object({
 	sendClass: z.enum(SEND_CLASSES),
 	/** True asks the host to mint a signed `verifyUrl` prop at send time. */
 	verifyLink: z.boolean(),
+	/**
+	* True asks the host to mint a signed `unsubscribeUrl` prop at send time,
+	* for the author's own footer link. Default false: a marketing send whose
+	* HTML carries no unsubscribe link at all still gets one, appended as a
+	* platform footer, so the link is never the author's to forget.
+	*/
+	unsubscribeLink: z.boolean().default(false),
 	/** JSON Schema of the template's `props`, converted by `cow build`. */
 	propsSchema: z.record(z.string(), z.unknown()),
 	bundle: digestSchema
@@ -318,6 +498,15 @@ const manifestSchema = z.object({
 	uniqueKeys(manifest.journeys, ctx, "journeys");
 	uniqueKeys(manifest.templates, ctx, "templates");
 	uniqueKeys(manifest.purposes ?? [], ctx, "purposes");
+	for (const [index, journey] of manifest.journeys.entries()) if (journey.enrollment && journey.purpose === "transactional") ctx.addIssue({
+		code: "custom",
+		message: `journey "${journey.key}": a transactional journey enrolls on every trigger, so it takes no enrollment cooldown`,
+		path: [
+			"journeys",
+			index,
+			"enrollment"
+		]
+	});
 });
 /**
 * One entry of a stored manifest: what a version is a snapshot of. Journeys
@@ -330,30 +519,56 @@ const versionManifestSchema = z.union([manifestJourneySchema, manifestTemplateSc
 //#endregion
 //#region ../../packages/shared/src/journeys-v2/config.ts
 /**
-* A project's name: what `cow init` asked for, and what the `projects` row
-* stores. Lives here rather than beside the release DTOs because `cow.json`
-* is the file a developer types it into; `createProjectBodySchema` reuses it.
+* An app id as `cow.json` carries it: the readable `app_<slug>`
+* `appIdFromName` derives, which is the one id a developer types by hand.
+*
+* It lives here rather than beside the app DTOs in ../apps because that
+* module imports the Drizzle schema, which neither the wasmtime guest nor
+* the Temporal workflow isolate can carry, and because `cow.json` is the
+* file a developer types it into. Everything that names an app on the wire
+* reuses it.
+*/
+const appIdSchema = z.string().trim().max(200).regex(new RegExp(`^${ID_PREFIXES.app}[a-z0-9]+(-[a-z0-9]+)*$`), "an app id looks like \"app_website\"");
+/**
+* A source id: the one inbound pipe an ingestion or send call names. It
+* lives beside `appIdSchema` for the same two reasons — the sources module
+* imports the Drizzle schema, and both are ids that travel on the wire — and
+* it has the same shape, so a bare `src_` is refused here rather than at the
+* database.
+*
+* The prefixes above and here are interpolated raw; `journeys-v2.test.ts`
+* asserts they are plain `<word>_` literals, so none of them can quietly
+* change what these patterns match.
 */
-const projectNameSchema = z.string().trim().min(1).max(200);
+const sourceIdSchema = z.string().trim().max(200).regex(new RegExp(`^${ID_PREFIXES.source}[a-z0-9_]+$`), "a source id looks like \"src_01j8x…\"");
 /**
-* `cow.json` (spec: Project layout): the org, and which of its projects this
-* directory is. Auth never lives in the project. Strict, so a typo'd key
-* is a build error rather than a silently ignored setting.
+* A Clerk organization id, as `cow.json` spells it. Exported beside
+* `appIdSchema` because the push body carries the org the file names so the
+* server can refuse a push aimed at another one (ADR 0022).
+*/
+const orgIdSchema = z.string().trim().max(200).startsWith(CLERK_ORG_SUBJECT_PREFIX, "orgId must be a Clerk org id");
+/**
+* `cow.json` (spec: Project layout): the org, and which of its apps this
+* repository pushes to. Auth never lives in the file. Strict, so a typo'd
+* key is a build error rather than a silently ignored setting — which is
+* also what turns the retired `project` key into a refusal (`cow build`
+* says what to rename it to).
 */
 const cowConfigSchema = z.strictObject({
 	$schema: z.url().optional(),
-	orgId: z.string().startsWith(CLERK_ORG_SUBJECT_PREFIX, "orgId must be a Clerk org id"),
+	orgId: orgIdSchema,
 	/**
-	* Which project of the org this directory pushes to. One org can hold
-	* several, one per repo, each with its own release sequence and its own
-	* slice of the deployed journeys, so every project says which it is.
+	* Which app of the org this repository pushes to (ADR 0022). The app is
+	* the push unit: it owns the journey and template keys, and `cow
+	* status`, `cow enable --all` and `cow pull` all resolve against it. One
+	* repository is one app, so no journey file names one.
 	*/
-	project: projectNameSchema,
+	appId: appIdSchema,
 	/**
-	* The consent purposes this project declares. They are org-wide, so two
-	* projects declaring one key must agree on its label and default or the
-	* deploy is refused; a deploy adds and updates them and never deletes
-	* one, because profiles hold answers against them.
+	* The consent purposes this repository declares. They are org-wide, so
+	* two apps declaring one key must agree on its label and default or the
+	* push is refused; a push adds and updates them and never deletes one,
+	* because profiles hold answers against them.
 	*/
 	purposes: purposesSchema.optional(),
 	/** Overrides the API the CLI talks to; the hosted product needs none. */
@@ -366,7 +581,7 @@ const cowConfigSchema = z.strictObject({
 	webUrl: z.url().optional()
 }).meta({
 	title: "cow.json",
-	description: "A cow project: the organization and the project it pushes to."
+	description: "A cow project: the organization and the app it pushes to."
 });
 
 //#endregion
@@ -377,8 +592,6 @@ const cowConfigSchema = z.strictObject({
 * a guest returns with these schemas before anything acts on it; the guest
 * SDK and the Node simulator produce and consume the same shapes.
 */
-/** A duration as journey code writes it: an ms-style string ("2d") or milliseconds. */
-const durationSchema = z.union([z.string().min(1), z.number().int().nonnegative()]);
 /** The event a journey runs for, or waits on: name, properties, and when. */
 const guestEventSchema = z.object({
 	name: z.string().min(1),
@@ -418,8 +631,9 @@ const commandSchema = z.discriminatedUnion("name", [
 			/**
 			* The address this mail leaves as. The guest SDK fills in the
 			* journey's own whenever the call does not name one, so the host has
-			* one resolution path and never reads the manifest to find it;
-			* absent on both is the organization's shared fallback address.
+			* one resolution path and never reads the manifest to find it. A
+			* journey must name one, so absent on both is a release pushed before
+			* that was true, and the `domain` gate refuses it.
 			*/
 			from: fromSchema.optional(),
 			/** Where a reply to this one mail goes, instead of the from-address. */
@@ -563,11 +777,14 @@ const manifestInputSchema = z.object({ kind: z.literal("manifest") });
 const manifestOutputSchema = z.discriminatedUnion("kind", [manifestJourneySchema.pick({
 	trigger: true,
 	purpose: true,
+	enrollment: true,
+	description: true,
 	from: true,
 	tags: true
 }).extend({ kind: z.literal("journey") }), manifestTemplateSchema.pick({
 	sendClass: true,
 	verifyLink: true,
+	unsubscribeLink: true,
 	propsSchema: true,
 	tags: true
 }).extend({ kind: z.literal("template") })]);
@@ -683,6 +900,8 @@ var CapabilityError = class extends Error {
 const journeyConfigSchema = manifestJourneySchema.pick({
 	trigger: true,
 	purpose: true,
+	enrollment: true,
+	description: true,
 	from: true,
 	tags: true
 });
@@ -690,16 +909,25 @@ const journeyConfigSchema = manifestJourneySchema.pick({
 * Author a journey. Throws at definition time on an invalid config.
 *
 * There is no environment gate here: an organization has one data space, and
-* a journey runs wherever it is enabled and nowhere else (ADR 0011, ADR 0013).
+* a journey runs wherever it is on and nowhere else (ADR 0011, ADR 0013).
+*
+* There is no app gate either. A journey belongs to the one app `cow.json`
+* names, so it only ever sees that app's events, profiles and segments
+* (ADR 0022); a trigger naming an app is refused rather than honoured.
 */
 function defineJourney(input) {
+	const config = journeyConfigSchema.parse({
+		trigger: input.trigger,
+		purpose: input.purpose,
+		enrollment: input.enrollment,
+		description: input.description,
+		from: input.from,
+		tags: input.tags
+	});
+	if (config.from === void 0) throw new Error("defineJourney needs a \"from\": the address this journey sends as, on a domain your organization verified. Add and verify it on the Domains page (Settings, Domains). For example from: \"Billing <billing@your-domain.com>\".");
 	return {
-		...journeyConfigSchema.parse({
-			trigger: input.trigger,
-			purpose: input.purpose,
-			from: input.from,
-			tags: input.tags
-		}),
+		...config,
+		from: config.from,
 		run: input.run
 	};
 }

package/dist/guest/journeys.d.ts

@@ -1,4 +1,4 @@
-import { n as Duration, r as GuestEvent, t as Trigger } from "./index-CXcCEcAg.js";
+import { i as GuestEvent, n as Trigger, r as TriggerInput, t as Duration } from "./index-EqBCZnpq.js";
 //#region src/guest/journeys.d.ts
 /** The event a journey runs for, or the one a `waitForEvent` resolved with. */
 type Event = GuestEvent;
@@ -32,10 +32,10 @@ declare class CapabilityError extends Error {
   constructor(code: string, message: string);
 }
 /**
- * The project's templates, keyed by template key. `cow build` writes the
+ * The repository's templates, keyed by template key. `cow build` writes the
  * real interface into `.cow/types.d.ts` and TypeScript merges it into this
  * one, which is what types `api.send.email`. Empty here on purpose: a
- * project that has not built yet still compiles, with string keys.
+ * repository that has not built yet still compiles, with string keys.
  */
 interface CowTemplates {}
 type TemplateKey = keyof CowTemplates extends never ? string : keyof CowTemplates;
@@ -121,22 +121,41 @@ type Api = {
 type JourneyConfig = {
   trigger: Trigger;
   /**
-   * A fixed purpose (`emailMarketing`, `dataProcessing`) or one this
-   * project declares in `cow.json`. The key's shape is checked here; that
-   * the org declares it is checked when the release is deployed.
+   * Why this journey contacts someone: `marketing`, `transactional`, or a
+   * purpose this repository declares in `cow.json`. The key's shape is
+   * checked here; that the org declares it is checked when the push lands.
    */
   purpose: string;
+  /**
+   * How often one recipient may enter this journey. A marketing journey
+   * enrolls each recipient once, ever; give it a `cooldown` and it re-opens
+   * that long after their last completed run. A transactional journey
+   * enrolls on every trigger — three orders are three receipts — so it
+   * takes no cooldown and `cow build` refuses one.
+   *
+   * History counts: adding a cooldown to a journey that has been running
+   * for months measures from runs that already completed.
+   */
+  enrollment?: {
+    cooldown: Duration;
+  };
+  /**
+   * One plain sentence saying what this journey does for the person who
+   * gets it. Shown wherever the journey is read. Optional; at most 500
+   * characters.
+   */
+  description?: string;
   /**
    * The address every `api.send.email` in this journey goes out as:
    * `"billing@acme.com"` or `"Billing <billing@acme.com>"`. A single send
    * can override it.
    *
-   * Optional: leave it out and Cowliss sends from the address it gives your
-   * organization, with nothing to set up. Named here rather than in a
-   * settings page, so the address a journey sends from is readable in the
-   * journey's own source.
+   * Required, on a domain your organization has verified: there is no
+   * address Cowliss lends you. Named here rather than in a settings page,
+   * so the address a journey sends from is readable in the journey's own
+   * source.
    */
-  from?: string;
+  from: string;
   /** The author's labels; the dashboard's only grouping. Defaults to none. */
   tags: string[];
 };
@@ -147,11 +166,22 @@ type Journey = JourneyConfig & {
  * Author a journey. Throws at definition time on an invalid config.
  *
  * There is no environment gate here: an organization has one data space, and
- * a journey runs wherever it is enabled and nowhere else (ADR 0011, ADR 0013).
+ * a journey runs wherever it is on and nowhere else (ADR 0011, ADR 0013).
+ *
+ * There is no app gate either. A journey belongs to the one app `cow.json`
+ * names, so it only ever sees that app's events, profiles and segments
+ * (ADR 0022); a trigger naming an app is refused rather than honoured.
  */
-declare function defineJourney(input: Omit<JourneyConfig, "tags"> & {
+declare function defineJourney(input: Omit<JourneyConfig, "tags" | "trigger"> & {
+  /**
+   * What starts it: `{ event }`, one event-name pattern or a list of
+   * them, or `{ segment }` carrying the predicate list of the segment
+   * this journey enrolls from. Written form, so a predicate can leave
+   * `match` and `atLeast` out. No app: the repository's app is the scope.
+   */
+  trigger: TriggerInput;
   tags?: string[];
   run: (event: Event, api: Api) => Promise<void>;
 }): Journey;
 //#endregion
-export { Api, CapabilityError, CowTemplates, type Duration, EmailSendResult, Event, Journey, JourneyConfig, Profile, type Trigger, defineJourney };
+export { Api, CapabilityError, CowTemplates, type Duration, EmailSendResult, Event, Journey, JourneyConfig, Profile, type Trigger, type TriggerInput, defineJourney };

package/dist/guest/journeys.js

@@ -1,3 +1,3 @@
-import { n as defineJourney, t as CapabilityError } from "./journeys-BrcKEXz0.js";
+import { n as defineJourney, t as CapabilityError } from "./journeys-F8Yk8s1P.js";
 
 export { CapabilityError, defineJourney };

package/dist/guest/wasi.js

@@ -1,4 +1,4 @@
-import { t as runGuest } from "./driver-DBt5l1Z5.js";
+import { t as runGuest } from "./driver-BXuYP007.js";
 
 //#region src/guest/wasi.ts
 const STDIN = 0;