@usine/core 0.3.0 → 0.5.0

package/dist/event.d.ts

@@ -1,11 +1,8 @@
 import { Schema } from "effect";
-/** Identity of one recorded fact; repeated sightings are matched through its dedup key. */
+/** The ID of an Event; duplicates are detected by `DedupKey`, not by ID. */
 export declare const EventId: Schema.brand<Schema.NonEmptyString, "EventId">;
 export type EventId = typeof EventId.Type;
-/**
- * Idempotency key the engine derives from watched state, timestamps excluded.
- * The same state is the same Event forever, so a loop file never sets it (ADR 0002).
- */
+/** The idempotency key that the engine derives from the watched state, excluding timestamps (ADR 0002). */
 export declare const DedupKey: Schema.brand<Schema.NonEmptyString, "DedupKey">;
 export type DedupKey = typeof DedupKey.Type;
 declare const Event_base: Schema.Class<Event, Schema.Struct<{
@@ -15,9 +12,8 @@ declare const Event_base: Schema.Class<Event, Schema.Struct<{
     readonly receivedAt: Schema.DateTimeUtc;
 }>, {}>;
 /**
- * One deduplicated fact the engine may react to: a trigger match or an operator
- * approval. Trigger payloads retain the snapshot that selection expressions
- * and prompt interpolation use; retries keep that recorded snapshot.
+ * A trigger match or operator approval. A trigger payload is the snapshot used by selection
+ * expressions and prompt interpolation, and retries reuse it.
  */
 export declare class Event extends Event_base {
 }

package/dist/event.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,2FAA2F;AAC3F,eAAO,MAAM,OAAO,gDAAsD,CAAC;AAE3E,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,QAAQ,iDAAuD,CAAC;AAE7E,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAC;;;;;;;AAE5C;;;;GAIG;AACH,qBAAa,KAAM,SAAQ,UAKzB;CAAG"}
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,4EAA4E;AAC5E,eAAO,MAAM,OAAO,gDAAsD,CAAC;AAE3E,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC;AAE1C,2GAA2G;AAC3G,eAAO,MAAM,QAAQ,iDAAuD,CAAC;AAE7E,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAC;;;;;;;AAE5C;;;GAGG;AACH,qBAAa,KAAM,SAAQ,UAKzB;CAAG"}

package/dist/event.js

@@ -1,15 +1,11 @@
 import { Schema } from "effect";
-/** Identity of one recorded fact; repeated sightings are matched through its dedup key. */
+/** The ID of an Event; duplicates are detected by `DedupKey`, not by ID. */
 export const EventId = Schema.NonEmptyString.pipe(Schema.brand("EventId"));
-/**
- * Idempotency key the engine derives from watched state, timestamps excluded.
- * The same state is the same Event forever, so a loop file never sets it (ADR 0002).
- */
+/** The idempotency key that the engine derives from the watched state, excluding timestamps (ADR 0002). */
 export const DedupKey = Schema.NonEmptyString.pipe(Schema.brand("DedupKey"));
 /**
- * One deduplicated fact the engine may react to: a trigger match or an operator
- * approval. Trigger payloads retain the snapshot that selection expressions
- * and prompt interpolation use; retries keep that recorded snapshot.
+ * A trigger match or operator approval. A trigger payload is the snapshot used by selection
+ * expressions and prompt interpolation, and retries reuse it.
  */
 export class Event extends Schema.Class("Event")({
     id: EventId,

package/dist/event.js.map

@@ -1 +1 @@
-{"version":3,"file":"event.js","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,2FAA2F;AAC3F,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;AAI3E;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;AAI7E;;;;GAIG;AACH,MAAM,OAAO,KAAM,SAAQ,MAAM,CAAC,KAAK,CAAQ,OAAO,CAAC,CAAC;IACtD,EAAE,EAAE,OAAO;IACX,QAAQ,EAAE,QAAQ;IAClB,OAAO,EAAE,MAAM,CAAC,IAAI;IACpB,UAAU,EAAE,MAAM,CAAC,WAAW;CAC/B,CAAC;CAAG"}
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;AAI3E,2GAA2G;AAC3G,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;AAI7E;;;GAGG;AACH,MAAM,OAAO,KAAM,SAAQ,MAAM,CAAC,KAAK,CAAQ,OAAO,CAAC,CAAC;IACtD,EAAE,EAAE,OAAO;IACX,QAAQ,EAAE,QAAQ;IAClB,OAAO,EAAE,MAAM,CAAC,IAAI;IACpB,UAAU,EAAE,MAAM,CAAC,WAAW;CAC/B,CAAC;CAAG"}

package/dist/instance.d.ts

@@ -1,5 +1,11 @@
 import { Schema } from "effect";
-/** Root folder containing the factory's `usine.yaml`, Loop files, and Agent roster; the caller resolves its location. */
+/** The folder with `usine.yaml`, Loop files, and Agent files. */
 export declare const InstanceDirectory: Schema.brand<Schema.NonEmptyString, "InstanceDirectory">;
 export type InstanceDirectory = typeof InstanceDirectory.Type;
+/**
+ * The UUID of one instance folder, which tells apart instances that share a GitHub App. It
+ * stays the same across restarts of the instance.
+ */
+export declare const InstanceId: Schema.brand<Schema.String, "InstanceId">;
+export type InstanceId = typeof InstanceId.Type;
 //# sourceMappingURL=instance.d.ts.map

package/dist/instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,yHAAyH;AACzH,eAAO,MAAM,iBAAiB,0DAAgE,CAAC;AAC/F,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAC"}
+{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,0DAAgE,CAAC;AAC/F,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,UAAU,2CAAwE,CAAC;AAChG,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAC"}

package/dist/instance.js

@@ -1,4 +1,9 @@
 import { Schema } from "effect";
-/** Root folder containing the factory's `usine.yaml`, Loop files, and Agent roster; the caller resolves its location. */
+/** The folder with `usine.yaml`, Loop files, and Agent files. */
 export const InstanceDirectory = Schema.NonEmptyString.pipe(Schema.brand("InstanceDirectory"));
+/**
+ * The UUID of one instance folder, which tells apart instances that share a GitHub App. It
+ * stays the same across restarts of the instance.
+ */
+export const InstanceId = Schema.String.check(Schema.isUUID()).pipe(Schema.brand("InstanceId"));
 //# sourceMappingURL=instance.js.map

package/dist/instance.js.map

@@ -1 +1 @@
-{"version":3,"file":"instance.js","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,yHAAyH;AACzH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"instance.js","sourceRoot":"","sources":["../src/instance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,iEAAiE;AACjE,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC;AAG/F;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC"}

package/dist/item.d.ts

@@ -1,8 +1,7 @@
 import { Schema } from "effect";
-/** Identity of the issue or pull request a loop acts on. Many content-distinct Events can concern one Item. */
+/** The ID of an issue or pull request; several Events can have the same Item. */
 export declare const ItemKey: Schema.brand<Schema.NonEmptyString, "ItemKey">;
 export type ItemKey = typeof ItemKey.Type;
-/** The issue or pull request number within its repository. */
 export declare const ItemNumber: Schema.brand<Schema.Int, "ItemNumber">;
 export type ItemNumber = typeof ItemNumber.Type;
 //# sourceMappingURL=item.d.ts.map

package/dist/item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"item.d.ts","sourceRoot":"","sources":["../src/item.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,+GAA+G;AAC/G,eAAO,MAAM,OAAO,gDAAsD,CAAC;AAE3E,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC;AAE1C,8DAA8D;AAC9D,eAAO,MAAM,UAAU,wCAEtB,CAAC;AACF,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAC"}
+{"version":3,"file":"item.d.ts","sourceRoot":"","sources":["../src/item.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,iFAAiF;AACjF,eAAO,MAAM,OAAO,gDAAsD,CAAC;AAE3E,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC;AAE1C,eAAO,MAAM,UAAU,wCAEtB,CAAC;AACF,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAC"}

package/dist/item.js

@@ -1,6 +1,5 @@
 import { Schema } from "effect";
-/** Identity of the issue or pull request a loop acts on. Many content-distinct Events can concern one Item. */
+/** The ID of an issue or pull request; several Events can have the same Item. */
 export const ItemKey = Schema.NonEmptyString.pipe(Schema.brand("ItemKey"));
-/** The issue or pull request number within its repository. */
 export const ItemNumber = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)).pipe(Schema.brand("ItemNumber"));
 //# sourceMappingURL=item.js.map

package/dist/item.js.map

@@ -1 +1 @@
-{"version":3,"file":"item.js","sourceRoot":"","sources":["../src/item.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,+GAA+G;AAC/G,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;AAI3E,8DAA8D;AAC9D,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC/E,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAC3B,CAAC"}
+{"version":3,"file":"item.js","sourceRoot":"","sources":["../src/item.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,iFAAiF;AACjF,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;AAI3E,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC/E,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAC3B,CAAC"}

package/dist/loop.d.ts

@@ -1,9 +1,17 @@
 import { Schema } from "effect";
-/** The loop file's name. Renaming the file retires one loop and creates another (ADR 0001). */
+/** The Loop file name. Renaming the file creates a new Loop and retires the old one (ADR 0001). */
 export declare const LoopName: Schema.brand<Schema.NonEmptyString, "LoopName">;
 export type LoopName = typeof LoopName.Type;
-/** Whether a loop parks new runs until an approval Event arrives. The default is `none`. */
+/** The approval modes; with `required`, new Runs wait for an approval Event. */
 export declare const APPROVAL_REQUIREMENTS: readonly ["none", "required"];
 export declare const ApprovalRequirement: Schema.Literals<readonly ["none", "required"]>;
 export type ApprovalRequirement = typeof ApprovalRequirement.Type;
+/**
+ * The repository access modes. With `write`, Attempts can push and merge. With `read`, they can
+ * read code and post reviews and comments but can't push; a Worker kind that can't issue such a
+ * token rejects the Attempt (ADR 0011).
+ */
+export declare const LOOP_PERMISSIONS: readonly ["write", "read"];
+export declare const LoopPermissions: Schema.Literals<readonly ["write", "read"]>;
+export type LoopPermissions = typeof LoopPermissions.Type;
 //# sourceMappingURL=loop.d.ts.map

package/dist/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,iDAAuD,CAAC;AAE7E,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAC;AAE5C,4FAA4F;AAC5F,eAAO,MAAM,qBAAqB,YAAI,MAAM,EAAE,UAAU,CAAU,CAAC;AACnE,eAAO,MAAM,mBAAmB,gDAAyC,CAAC;AAC1E,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAC"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,mGAAmG;AACnG,eAAO,MAAM,QAAQ,iDAAuD,CAAC;AAE7E,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAC;AAE5C,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,YAAI,MAAM,EAAE,UAAU,CAAU,CAAC;AACnE,eAAO,MAAM,mBAAmB,gDAAyC,CAAC;AAC1E,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,YAAI,OAAO,EAAE,MAAM,CAAU,CAAC;AAC3D,eAAO,MAAM,eAAe,6CAAoC,CAAC;AACjE,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAC"}

package/dist/loop.js

@@ -1,7 +1,14 @@
 import { Schema } from "effect";
-/** The loop file's name. Renaming the file retires one loop and creates another (ADR 0001). */
+/** The Loop file name. Renaming the file creates a new Loop and retires the old one (ADR 0001). */
 export const LoopName = Schema.NonEmptyString.pipe(Schema.brand("LoopName"));
-/** Whether a loop parks new runs until an approval Event arrives. The default is `none`. */
+/** The approval modes; with `required`, new Runs wait for an approval Event. */
 export const APPROVAL_REQUIREMENTS = ["none", "required"];
 export const ApprovalRequirement = Schema.Literals(APPROVAL_REQUIREMENTS);
+/**
+ * The repository access modes. With `write`, Attempts can push and merge. With `read`, they can
+ * read code and post reviews and comments but can't push; a Worker kind that can't issue such a
+ * token rejects the Attempt (ADR 0011).
+ */
+export const LOOP_PERMISSIONS = ["write", "read"];
+export const LoopPermissions = Schema.Literals(LOOP_PERMISSIONS);
 //# sourceMappingURL=loop.js.map

package/dist/loop.js.map

@@ -1 +1 @@
-{"version":3,"file":"loop.js","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,+FAA+F;AAC/F,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;AAI7E,4FAA4F;AAC5F,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,MAAM,EAAE,UAAU,CAAU,CAAC;AACnE,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC"}
+{"version":3,"file":"loop.js","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,mGAAmG;AACnG,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;AAI7E,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,MAAM,EAAE,UAAU,CAAU,CAAC;AACnE,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC;AAG1E;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,CAAU,CAAC;AAC3D,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC"}

package/dist/operator.d.ts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+/**
+ * The operator's GitHub login from `usine.yaml`. The web UI acts as this login, and only this
+ * login can answer an Ask (ADR 0017).
+ */
+export declare const OperatorLogin: Schema.brand<Schema.String, "OperatorLogin">;
+export type OperatorLogin = typeof OperatorLogin.Type;
+//# sourceMappingURL=operator.d.ts.map

package/dist/operator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.d.ts","sourceRoot":"","sources":["../src/operator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC;;;GAGG;AACH,eAAO,MAAM,aAAa,8CAIW,CAAC;AAEtC,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAC"}

package/dist/operator.js

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+/**
+ * The operator's GitHub login from `usine.yaml`. The web UI acts as this login, and only this
+ * login can answer an Ask (ADR 0017).
+ */
+export const OperatorLogin = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/u, {
+    message: "Expected a GitHub login",
+})).pipe(Schema.brand("OperatorLogin"));
+//# sourceMappingURL=operator.js.map

package/dist/operator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.js","sourceRoot":"","sources":["../src/operator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAC9C,MAAM,CAAC,SAAS,CAAC,kDAAkD,EAAE;IACnE,OAAO,EAAE,yBAAyB;CACnC,CAAC,CACH,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC"}

package/dist/repository.d.ts

@@ -1,21 +1,19 @@
 import { Schema } from "effect";
-/**
- * Full `owner/name` of a GitHub repository, in the casing the operator wrote.
- * Compare through `canonicalRepositoryName`, since GitHub ignores case.
- */
+/** A GitHub `owner/name` in the casing from config; compare with `canonicalRepositoryName`. */
 export declare const RepositoryName: Schema.brand<Schema.String, "RepositoryName">;
 export type RepositoryName = typeof RepositoryName.Type;
-/** The branch, tag, commit, or `HEAD` a Worker fetches when preparing an Attempt; named refs resolve at preparation time. */
+/** The branch, tag, commit, or `HEAD` to check out for an Attempt, resolved when the Attempt is prepared. */
 export declare const RepositoryRevision: Schema.brand<Schema.String, "RepositoryRevision">;
 export type RepositoryRevision = typeof RepositoryRevision.Type;
-/** An exact Git commit recorded for a checkout or produced by an Attempt, unchanged when branch names move. */
+/** A full SHA-1 or SHA-256 commit ID in lowercase hex. */
 export declare const CommitSha: Schema.brand<Schema.String, "CommitSha">;
 export type CommitSha = typeof CommitSha.Type;
-/** Splits a repository name into its `owner` and `name`. */
+/** Returns `value` with every character outside `[A-Za-z0-9_.-]` replaced by `_`, for a path or ref segment. */
+export declare const safeSegment: (value: string) => string;
 export declare const splitRepositoryName: (repository: RepositoryName) => {
     readonly owner: string;
     readonly name: string;
 };
-/** Lowercases a repository name for comparison, since GitHub ignores case. */
+/** Returns the comparison key for a repository name; GitHub names are case-insensitive. */
 export declare const canonicalRepositoryName: (repository: RepositoryName) => string;
 //# sourceMappingURL=repository.d.ts.map

package/dist/repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../src/repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC;;;GAGG;AACH,eAAO,MAAM,cAAc,+CAIW,CAAC;AAEvC,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC;AAExD,6HAA6H;AAC7H,eAAO,MAAM,kBAAkB,mDAIW,CAAC;AAC3C,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAC;AAEhE,+GAA+G;AAC/G,eAAO,MAAM,SAAS,0CAIW,CAAC;AAClC,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAC;AAE9C,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,eAAgB,cAAc;aAG1D,KAAK;aACL,IAAI;CAEP,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,eAAgB,cAAc,KAAG,MAC3C,CAAC"}
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../src/repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,+FAA+F;AAC/F,eAAO,MAAM,cAAc,+CAIW,CAAC;AAEvC,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC;AAExD,6GAA6G;AAC7G,eAAO,MAAM,kBAAkB,mDAIW,CAAC;AAC3C,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAC;AAEhE,0DAA0D;AAC1D,eAAO,MAAM,SAAS,0CAIW,CAAC;AAClC,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAC;AAE9C,gHAAgH;AAChH,eAAO,MAAM,WAAW,UAAW,MAAM,KAAG,MAAoD,CAAC;AAEjG,eAAO,MAAM,mBAAmB,eAAgB,cAAc;aAG1D,KAAK;aACL,IAAI;CAEP,CAAC;AAEF,2FAA2F;AAC3F,eAAO,MAAM,uBAAuB,eAAgB,cAAc,KAAG,MAC3C,CAAC"}

package/dist/repository.js

@@ -1,20 +1,18 @@
 import { Schema } from "effect";
-/**
- * Full `owner/name` of a GitHub repository, in the casing the operator wrote.
- * Compare through `canonicalRepositoryName`, since GitHub ignores case.
- */
+/** A GitHub `owner/name` in the casing from config; compare with `canonicalRepositoryName`. */
 export const RepositoryName = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u, {
     message: "Expected a full GitHub repo name (owner/name)",
 })).pipe(Schema.brand("RepositoryName"));
-/** The branch, tag, commit, or `HEAD` a Worker fetches when preparing an Attempt; named refs resolve at preparation time. */
+/** The branch, tag, commit, or `HEAD` to check out for an Attempt, resolved when the Attempt is prepared. */
 export const RepositoryRevision = Schema.String.check(Schema.isPattern(/^[^\s-]\S*$/u, {
-    message: "Expected a git revision without whitespace or a leading dash",
+    message: "Expected a Git revision without whitespace or a leading dash",
 })).pipe(Schema.brand("RepositoryRevision"));
-/** An exact Git commit recorded for a checkout or produced by an Attempt, unchanged when branch names move. */
+/** A full SHA-1 or SHA-256 commit ID in lowercase hex. */
 export const CommitSha = Schema.String.check(Schema.isPattern(/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/u, {
-    message: "Expected a 40- or 64-character lowercase git object id",
+    message: "Expected a 40- or 64-character lowercase Git object ID",
 })).pipe(Schema.brand("CommitSha"));
-/** Splits a repository name into its `owner` and `name`. */
+/** Returns `value` with every character outside `[A-Za-z0-9_.-]` replaced by `_`, for a path or ref segment. */
+export const safeSegment = (value) => value.replaceAll(/[^A-Za-z0-9_.-]/gu, "_");
 export const splitRepositoryName = (repository) => {
     const separator = repository.indexOf("/");
     return {
@@ -22,6 +20,6 @@ export const splitRepositoryName = (repository) => {
         name: repository.slice(separator + 1),
     };
 };
-/** Lowercases a repository name for comparison, since GitHub ignores case. */
+/** Returns the comparison key for a repository name; GitHub names are case-insensitive. */
 export const canonicalRepositoryName = (repository) => repository.toLowerCase();
 //# sourceMappingURL=repository.js.map

package/dist/repository.js.map

@@ -1 +1 @@
-{"version":3,"file":"repository.js","sourceRoot":"","sources":["../src/repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAC/C,MAAM,CAAC,SAAS,CAAC,qCAAqC,EAAE;IACtD,OAAO,EAAE,+CAA+C;CACzD,CAAC,CACH,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAIvC,6HAA6H;AAC7H,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CACnD,MAAM,CAAC,SAAS,CAAC,cAAc,EAAE;IAC/B,OAAO,EAAE,8DAA8D;CACxE,CAAC,CACH,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC;AAG3C,+GAA+G;AAC/G,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAC1C,MAAM,CAAC,SAAS,CAAC,kCAAkC,EAAE;IACnD,OAAO,EAAE,wDAAwD;CAClE,CAAC,CACH,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;AAGlC,4DAA4D;AAC5D,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,UAA0B,EAAE,EAAE;IAChE,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1C,OAAO;QACL,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC;QACrC,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;KAC7B,CAAC;AACb,CAAC,CAAC;AAEF,8EAA8E;AAC9E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,UAA0B,EAAU,EAAE,CAC5E,UAAU,CAAC,WAAW,EAAE,CAAC"}
+{"version":3,"file":"repository.js","sourceRoot":"","sources":["../src/repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,+FAA+F;AAC/F,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAC/C,MAAM,CAAC,SAAS,CAAC,qCAAqC,EAAE;IACtD,OAAO,EAAE,+CAA+C;CACzD,CAAC,CACH,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAIvC,6GAA6G;AAC7G,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CACnD,MAAM,CAAC,SAAS,CAAC,cAAc,EAAE;IAC/B,OAAO,EAAE,8DAA8D;CACxE,CAAC,CACH,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC;AAG3C,0DAA0D;AAC1D,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAC1C,MAAM,CAAC,SAAS,CAAC,kCAAkC,EAAE;IACnD,OAAO,EAAE,wDAAwD;CAClE,CAAC,CACH,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;AAGlC,gHAAgH;AAChH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;AAEjG,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,UAA0B,EAAE,EAAE;IAChE,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1C,OAAO;QACL,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC;QACrC,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;KAC7B,CAAC;AACb,CAAC,CAAC;AAEF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,UAA0B,EAAU,EAAE,CAC5E,UAAU,CAAC,WAAW,EAAE,CAAC"}

package/dist/run/again.d.ts

@@ -0,0 +1,13 @@
+import { Schema } from "effect";
+declare const RunAgain_base: Schema.Class<RunAgain, Schema.Struct<{
+    readonly from: Schema.brand<Schema.NonEmptyString, "RunId">;
+    readonly requestedBy: Schema.OptionFromNullOr<Schema.brand<Schema.String, "OperatorLogin">>;
+}>, {}>;
+/**
+ * The origin of a Run created by running a succeeded or canceled Run again (ADR 0002).
+ * `requestedBy` is the operator login from `usine.yaml`, or `None` if none is configured.
+ */
+export declare class RunAgain extends RunAgain_base {
+}
+export {};
+//# sourceMappingURL=again.d.ts.map

package/dist/run/again.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"again.d.ts","sourceRoot":"","sources":["../../src/run/again.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;;;;;AAKhC;;;GAGG;AACH,qBAAa,QAAS,SAAQ,aAK7B;CAAG"}

package/dist/run/again.js

@@ -0,0 +1,14 @@
+import { Schema } from "effect";
+import { closedStruct } from "../closed-struct.js";
+import { OperatorLogin } from "../operator.js";
+import { RunId } from "./run.js";
+/**
+ * The origin of a Run created by running a succeeded or canceled Run again (ADR 0002).
+ * `requestedBy` is the operator login from `usine.yaml`, or `None` if none is configured.
+ */
+export class RunAgain extends Schema.Class("RunAgain")(closedStruct({
+    from: RunId,
+    requestedBy: Schema.OptionFromNullOr(OperatorLogin),
+})) {
+}
+//# sourceMappingURL=again.js.map

package/dist/run/again.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"again.js","sourceRoot":"","sources":["../../src/run/again.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEjC;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,MAAM,CAAC,KAAK,CAAW,UAAU,CAAC,CAC9D,YAAY,CAAC;IACX,IAAI,EAAE,KAAK;IACX,WAAW,EAAE,MAAM,CAAC,gBAAgB,CAAC,aAAa,CAAC;CACpD,CAAC,CACH;CAAG"}

package/dist/run/approval.d.ts

@@ -0,0 +1,27 @@
+import { Schema } from "effect";
+/** The approval channels: `ui` for the web UI's Approve action and `github-ask` for a 👍 on the GitHub Ask (ADR 0017). */
+export declare const APPROVAL_CHANNELS: readonly ["ui", "github-ask"];
+export declare const ApprovalChannel: Schema.Literals<readonly ["ui", "github-ask"]>;
+export type ApprovalChannel = typeof ApprovalChannel.Type;
+declare const ApprovalSource_base: Schema.Class<ApprovalSource, Schema.Struct<{
+    readonly channel: Schema.Literals<readonly ["ui", "github-ask"]>;
+    readonly approver: Schema.OptionFromNullOr<Schema.brand<Schema.String, "OperatorLogin">>;
+}>, {}>;
+/**
+ * The approver and channel, recorded when the approval takes effect. A `ui` approval has no
+ * `approver` if `usine.yaml` sets no operator login; a `github-ask` approval always has one.
+ */
+export declare class ApprovalSource extends ApprovalSource_base {
+}
+declare const RunApproval_base: Schema.Class<RunApproval, Schema.Struct<{
+    readonly approvedAt: Schema.DateTimeUtc;
+    readonly source: Schema.Option<typeof ApprovalSource>;
+}>, {}>;
+/**
+ * A Run's approval. `approvedAt` is when the approval Event arrived, and `source` is `None` for
+ * older records.
+ */
+export declare class RunApproval extends RunApproval_base {
+}
+export {};
+//# sourceMappingURL=approval.d.ts.map

package/dist/run/approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../../src/run/approval.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIxC,0HAA0H;AAC1H,eAAO,MAAM,iBAAiB,YAAI,IAAI,EAAE,YAAY,CAAU,CAAC;AAC/D,eAAO,MAAM,eAAe,gDAAqC,CAAC;AAClE,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAC;;;;;AAE1D;;;GAGG;AACH,qBAAa,cAAe,SAAQ,mBAUnC;CAAG;;;;;AAEJ;;;GAGG;AACH,qBAAa,WAAY,SAAQ,gBAG/B;CAAG"}

package/dist/run/approval.js

@@ -0,0 +1,25 @@
+import { Option, Schema } from "effect";
+import { closedStruct } from "../closed-struct.js";
+import { OperatorLogin } from "../operator.js";
+/** The approval channels: `ui` for the web UI's Approve action and `github-ask` for a 👍 on the GitHub Ask (ADR 0017). */
+export const APPROVAL_CHANNELS = ["ui", "github-ask"];
+export const ApprovalChannel = Schema.Literals(APPROVAL_CHANNELS);
+/**
+ * The approver and channel, recorded when the approval takes effect. A `ui` approval has no
+ * `approver` if `usine.yaml` sets no operator login; a `github-ask` approval always has one.
+ */
+export class ApprovalSource extends Schema.Class("ApprovalSource")(closedStruct({
+    channel: ApprovalChannel,
+    approver: Schema.OptionFromNullOr(OperatorLogin),
+}).check(Schema.makeFilter(({ channel, approver }) => channel !== "github-ask" || Option.isSome(approver), { message: "Expected an approver for a GitHub ask approval" }))) {
+}
+/**
+ * A Run's approval. `approvedAt` is when the approval Event arrived, and `source` is `None` for
+ * older records.
+ */
+export class RunApproval extends Schema.Class("RunApproval")({
+    approvedAt: Schema.DateTimeUtc,
+    source: Schema.Option(ApprovalSource),
+}) {
+}
+//# sourceMappingURL=approval.js.map

package/dist/run/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../../src/run/approval.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,0HAA0H;AAC1H,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,YAAY,CAAU,CAAC;AAC/D,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;AAGlE;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,MAAM,CAAC,KAAK,CAAiB,gBAAgB,CAAC,CAChF,YAAY,CAAC;IACX,OAAO,EAAE,eAAe;IACxB,QAAQ,EAAE,MAAM,CAAC,gBAAgB,CAAC,aAAa,CAAC;CACjD,CAAC,CAAC,KAAK,CACN,MAAM,CAAC,UAAU,CACf,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,OAAO,KAAK,YAAY,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAC9E,EAAE,OAAO,EAAE,gDAAgD,EAAE,CAC9D,CACF,CACF;CAAG;AAEJ;;;GAGG;AACH,MAAM,OAAO,WAAY,SAAQ,MAAM,CAAC,KAAK,CAAc,aAAa,CAAC,CAAC;IACxE,UAAU,EAAE,MAAM,CAAC,WAAW;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC;CACtC,CAAC;CAAG"}

package/dist/run/run.d.ts

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-/** Identity of the work owed to one Event, retained across retries of its Step. */
+/** The ID of a Run, unchanged across retries of its Step. */
 export declare const RunId: Schema.brand<Schema.NonEmptyString, "RunId">;
 export type RunId = typeof RunId.Type;
 declare const Run_base: Schema.Class<Run, Schema.Struct<{
@@ -9,7 +9,7 @@ declare const Run_base: Schema.Class<Run, Schema.Struct<{
     readonly state: Schema.Union<readonly [typeof import("./state.ts").Pending, typeof import("./state.ts").Waiting, typeof import("./state.ts").Queued, typeof import("./state.ts").Running, typeof import("./state.ts").Succeeded, typeof import("./state.ts").Failed, typeof import("./state.ts").Canceled]>;
     readonly openedAt: Schema.DateTimeUtc;
 }>, {}>;
-/** The work a loop owes one Event. At most one open Run exists per dedup key; the engine's ledger enforces it (ADR 0002). */
+/** The work a Loop does for one Event. The engine allows at most one open Run per dedup key (ADR 0002). */
 export declare class Run extends Run_base {
 }
 export {};

package/dist/run/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKhC,mFAAmF;AACnF,eAAO,MAAM,KAAK,8CAAoD,CAAC;AAEvE,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC;;;;;;;;AAEtC,6HAA6H;AAC7H,qBAAa,GAAI,SAAQ,QAMvB;CAAG"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKhC,6DAA6D;AAC7D,eAAO,MAAM,KAAK,8CAAoD,CAAC;AAEvE,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC;;;;;;;;AAEtC,2GAA2G;AAC3G,qBAAa,GAAI,SAAQ,QAMvB;CAAG"}

package/dist/run/run.js

@@ -2,9 +2,9 @@ import { Schema } from "effect";
 import { EventId } from "../event.js";
 import { LoopName } from "../loop.js";
 import { RunState } from "./state.js";
-/** Identity of the work owed to one Event, retained across retries of its Step. */
+/** The ID of a Run, unchanged across retries of its Step. */
 export const RunId = Schema.NonEmptyString.pipe(Schema.brand("RunId"));
-/** The work a loop owes one Event. At most one open Run exists per dedup key; the engine's ledger enforces it (ADR 0002). */
+/** The work a Loop does for one Event. The engine allows at most one open Run per dedup key (ADR 0002). */
 export class Run extends Schema.Class("Run")({
     id: RunId,
     eventId: EventId,

package/dist/run/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,mFAAmF;AACnF,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;AAIvE,6HAA6H;AAC7H,MAAM,OAAO,GAAI,SAAQ,MAAM,CAAC,KAAK,CAAM,KAAK,CAAC,CAAC;IAChD,EAAE,EAAE,KAAK;IACT,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,QAAQ;IACd,KAAK,EAAE,QAAQ;IACf,QAAQ,EAAE,MAAM,CAAC,WAAW;CAC7B,CAAC;CAAG"}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,6DAA6D;AAC7D,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;AAIvE,2GAA2G;AAC3G,MAAM,OAAO,GAAI,SAAQ,MAAM,CAAC,KAAK,CAAM,KAAK,CAAC,CAAC;IAChD,EAAE,EAAE,KAAK;IACT,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,QAAQ;IACd,KAAK,EAAE,QAAQ;IACf,QAAQ,EAAE,MAAM,CAAC,WAAW;CAC7B,CAAC;CAAG"}

package/dist/run/state.d.ts

@@ -13,102 +13,93 @@ declare const OperatorCanceled_base: Schema.Class<OperatorCanceled, Schema.Tagge
  *   pending | waiting | queued           ──► canceled   (supersede, revoke: a started
  *                                                        attempt always finishes, ADR 0007)
  *
- * Each transition accepts only the states it is legal on, so an illegal
- * transition fails to compile. Construct states through the transitions or by
- * decoding a stored row with `RunState`.
+ * Each transition accepts only its legal source states, so an illegal transition is a type
+ * error. States come from the transitions or from decoding a stored row with `RunState`.
  */
-/** The operator closed the run by hand. */
 export declare class OperatorCanceled extends OperatorCanceled_base {
 }
 declare const Superseded_base: Schema.Class<Superseded, Schema.TaggedStruct<"Superseded", {
     readonly by: Schema.brand<Schema.NonEmptyString, "EventId">;
 }>, {}>;
-/** A newer Event for the same Item took the run's place before any attempt started. */
+/** Cancellation because a newer Event for the same Item arrived before any Attempt started. */
 export declare class Superseded extends Superseded_base {
 }
 declare const Revoked_base: Schema.Class<Revoked, Schema.TaggedStruct<"Revoked", {}>, {}>;
-/** The run's Item stopped matching its loop's trigger before any attempt started. */
+/** Cancellation because the Item stopped matching the Loop's trigger before any Attempt started. */
 export declare class Revoked extends Revoked_base {
 }
 export declare const CancelReason: Schema.Union<readonly [typeof OperatorCanceled, typeof Superseded, typeof Revoked]>;
 export type CancelReason = typeof CancelReason.Type;
 declare const Pending_base: Schema.Class<Pending, Schema.TaggedStruct<"Pending", {}>, {}>;
-/** Just created: no attempt started and no approval gate passed. */
+/** A new Run with no Attempt started and no approval gate passed. */
 export declare class Pending extends Pending_base {
 }
 declare const Waiting_base: Schema.Class<Waiting, Schema.TaggedStruct<"Waiting", {}>, {}>;
-/** Parked on the loop's approval gate. The approval it waits for is an Event like any other fact. */
+/** A Run waiting for its Loop's approval Event. */
 export declare class Waiting extends Waiting_base {
 }
 declare const Queued_base: Schema.Class<Queued, Schema.TaggedStruct<"Queued", {}>, {}>;
-/** Approved and waiting for a worker slot. */
+/** An approved Run waiting for a Worker slot. */
 export declare class Queued extends Queued_base {
 }
 declare const Running_base: Schema.Class<Running, Schema.TaggedStruct<"Running", {}>, {}>;
-/** An attempt is executing on a worker. */
+/** A Run with an Attempt running on a Worker. */
 export declare class Running extends Running_base {
 }
 declare const Succeeded_base: Schema.Class<Succeeded, Schema.TaggedStruct<"Succeeded", {}>, {}>;
-/** The step finished and its result is stored. */
+/** A Run whose Step finished with a stored result. */
 export declare class Succeeded extends Succeeded_base {
 }
 declare const Failed_base: Schema.Class<Failed, Schema.TaggedStruct<"Failed", {}>, {}>;
-/** The last attempt failed and no auto-retry applies. The failure is on the Attempt, and `retry` reopens the run. */
+/** A Run whose last Attempt failed without an auto-retry; the failure is stored on the Attempt. */
 export declare class Failed extends Failed_base {
 }
 declare const Canceled_base: Schema.Class<Canceled, Schema.TaggedStruct<"Canceled", {
     readonly reason: Schema.Union<readonly [typeof OperatorCanceled, typeof Superseded, typeof Revoked]>;
 }>, {}>;
-/** Canceled, with the reason recorded. */
 export declare class Canceled extends Canceled_base {
 }
-/** Runs that still owe work, including those waiting for approval or a Worker. */
+/** The states of a Run that isn't closed. */
 export declare const Open: Schema.Union<readonly [typeof Pending, typeof Waiting, typeof Queued, typeof Running]>;
 export type Open = typeof Open.Type;
-/** A Run's progress from creation through approval and execution to a recorded outcome. */
 export declare const RunState: Schema.Union<readonly [typeof Pending, typeof Waiting, typeof Queued, typeof Running, typeof Succeeded, typeof Failed, typeof Canceled]>;
 export type RunState = typeof RunState.Type;
-/** The states with no attempt started: what `supersede` and `revoke` accept. */
+/** The states before any Attempt starts, accepted by `supersede` and `revoke`. */
 export declare const Unstarted: Schema.Union<readonly [typeof Pending, typeof Waiting, typeof Queued]>;
 export type Unstarted = typeof Unstarted.Type;
-/** The states an attempt can start from: the gate is passed or absent. */
+/** The states from which an Attempt can start. */
 export declare const Startable: Schema.Union<readonly [typeof Pending, typeof Queued]>;
 export type Startable = typeof Startable.Type;
 export declare const isOpen: <I>(input: I) => input is I & (Pending | Queued | Running | Waiting);
 export declare const isUnstarted: <I>(input: I) => input is I & (Pending | Queued | Waiting);
 export declare const isStartable: <I>(input: I) => input is I & (Pending | Queued);
-/** The operator actions permitted by a Run's lifecycle state. Command handlers still apply the typed transitions. */
+/** Returns the operator actions allowed in `state`. */
 export declare const operatorActions: (state: RunState) => {
     canApprove: boolean;
     canRetry: boolean;
+    canResolveFailure: boolean;
     canCancel: boolean;
+    canRunAgain: boolean;
 };
-/** The open states as `_tag` literals, for queries that filter stored rows. */
+/** The `_tag` values of `Open`, for SQL filters. */
 export declare const OPEN_STATE_TAGS: readonly ["Pending", "Waiting", "Queued", "Running"];
-/** Every state as a `_tag` literal, for read models that project stored rows. */
+/** The `_tag` values of `RunState`. */
 export declare const STATE_TAGS: readonly ["Pending", "Waiting", "Queued", "Running", "Succeeded", "Failed", "Canceled"];
-/** The unstarted states as `_tag` literals, for queries that filter stored rows. */
+/** The `_tag` values of `Unstarted`, for SQL filters. */
 export declare const UNSTARTED_STATE_TAGS: readonly ["Pending", "Waiting", "Queued"];
-/** Parks a pending run on its loop's approval gate. */
 export declare const awaitApproval: (_state: Pending) => Waiting;
-/** Returns the approved state; the Run still waits for a Worker slot before execution. */
 export declare const approve: (_state: Waiting) => Queued;
-/** Returns the running state for a first Attempt after any required approval has been granted. */
 export declare const start: (_state: Startable) => Running;
-/** Closes the run after a successful attempt. */
 export declare const succeed: (_state: Running) => Succeeded;
-/** Closes the run after a failed attempt when no auto-retry applies; `shouldAutoRetry` decides that. */
+/** Returns `Failed`. Callers use it only if `shouldAutoRetry` returns `false`. */
 export declare const fail: (_state: Running) => Failed;
-/** Returns the reopened state for operator retry; attempt N+1 belongs to the same Run and Step. */
 export declare const retry: (_state: Failed) => Running;
-/** Cancels from any open state. */
 export declare const cancelByOperator: (_state: Open) => Canceled;
 /**
- * Cancels an unstarted run because a newer Event for the same Item replaced it.
- * A running attempt always finishes and the newer state is judged when it ends (ADR 0007).
+ * Returns `Canceled` for a Run replaced by the newer Event `by`. A running Run isn't
+ * superseded; the engine evaluates the newer Event after its Attempt ends (ADR 0007).
  */
 export declare const supersede: (_state: Unstarted, by: EventId) => Canceled;
-/** Cancels an unstarted run because its Item stopped matching the loop's trigger. */
 export declare const revoke: (_state: Unstarted) => Canceled;
 export {};
 //# sourceMappingURL=state.d.ts.map

package/dist/run/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/run/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;;AAEtC;;;;;;;;;;;;;;;GAeG;AAEH,2CAA2C;AAC3C,qBAAa,gBAAiB,SAAQ,qBAEb;CAAG;;;;AAE5B,uFAAuF;AACvF,qBAAa,UAAW,SAAQ,eAG/B;CAAG;;AAEJ,qFAAqF;AACrF,qBAAa,OAAQ,SAAQ,YAAkE;CAAG;AAElG,eAAO,MAAM,YAAY,qFAAwD,CAAC;AAClF,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAC;;AAEpD,oEAAoE;AACpE,qBAAa,OAAQ,SAAQ,YAA8D;CAAG;;AAE9F,qGAAqG;AACrG,qBAAa,OAAQ,SAAQ,YAA8D;CAAG;;AAE9F,8CAA8C;AAC9C,qBAAa,MAAO,SAAQ,WAA2D;CAAG;;AAE1F,2CAA2C;AAC3C,qBAAa,OAAQ,SAAQ,YAA8D;CAAG;;AAE9F,kDAAkD;AAClD,qBAAa,SAAU,SAAQ,cAG9B;CAAG;;AAEJ,qHAAqH;AACrH,qBAAa,MAAO,SAAQ,WAA2D;CAAG;;;;AAE1F,0CAA0C;AAC1C,qBAAa,QAAS,SAAQ,aAE5B;CAAG;AAEL,kFAAkF;AAClF,eAAO,MAAM,IAAI,wFAAoD,CAAC;AACtE,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAC;AAEpC,2FAA2F;AAC3F,eAAO,MAAM,QAAQ,0IAA+D,CAAC;AACrF,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAC;AAE5C,gFAAgF;AAChF,eAAO,MAAM,SAAS,wEAA2C,CAAC;AAClE,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAC;AAE9C,0EAA0E;AAC1E,eAAO,MAAM,SAAS,wDAAkC,CAAC;AACzD,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAC;AAE9C,eAAO,MAAM,MAAM,sEAAkB,CAAC;AACtC,eAAO,MAAM,WAAW,4DAAuB,CAAC;AAChD,eAAO,MAAM,WAAW,kDAAuB,CAAC;AAEhD,qHAAqH;AACrH,eAAO,MAAM,eAAe,UAAW,QAAQ;IAC7C,UAAU;IACV,QAAQ;IACR,SAAS;CACT,CAAC;AAcH,+EAA+E;AAC/E,eAAO,MAAM,eAAe,sDAA4D,CAAC;AAEzF,iFAAiF;AACjF,eAAO,MAAM,UAAU,yFAQtB,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,2CAAsD,CAAC;AAExF,uDAAuD;AACvD,eAAO,MAAM,aAAa,WAAY,OAAO,KAAG,OAAwB,CAAC;AAEzE,0FAA0F;AAC1F,eAAO,MAAM,OAAO,WAAY,OAAO,KAAG,MAAsB,CAAC;AAEjE,kGAAkG;AAClG,eAAO,MAAM,KAAK,WAAY,SAAS,KAAG,OAAwB,CAAC;AAEnE,iDAAiD;AACjD,eAAO,MAAM,OAAO,WAAY,OAAO,KAAG,SAA4B,CAAC;AAEvE,wGAAwG;AACxG,eAAO,MAAM,IAAI,WAAY,OAAO,KAAG,MAAsB,CAAC;AAE9D,mGAAmG;AACnG,eAAO,MAAM,KAAK,WAAY,MAAM,KAAG,OAAwB,CAAC;AAEhE,mCAAmC;AACnC,eAAO,MAAM,gBAAgB,WAAY,IAAI,KAAG,QACE,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,SAAS,WAAY,SAAS,MAAM,OAAO,KAAG,QACT,CAAC;AAEnD,qFAAqF;AACrF,eAAO,MAAM,MAAM,WAAY,SAAS,KAAG,QAAmD,CAAC"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/run/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;;AAEtC;;;;;;;;;;;;;;GAcG;AAEH,qBAAa,gBAAiB,SAAQ,qBAEb;CAAG;;;;AAE5B,+FAA+F;AAC/F,qBAAa,UAAW,SAAQ,eAG/B;CAAG;;AAEJ,oGAAoG;AACpG,qBAAa,OAAQ,SAAQ,YAAkE;CAAG;AAElG,eAAO,MAAM,YAAY,qFAAwD,CAAC;AAClF,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAC;;AAEpD,qEAAqE;AACrE,qBAAa,OAAQ,SAAQ,YAA8D;CAAG;;AAE9F,mDAAmD;AACnD,qBAAa,OAAQ,SAAQ,YAA8D;CAAG;;AAE9F,iDAAiD;AACjD,qBAAa,MAAO,SAAQ,WAA2D;CAAG;;AAE1F,iDAAiD;AACjD,qBAAa,OAAQ,SAAQ,YAA8D;CAAG;;AAE9F,sDAAsD;AACtD,qBAAa,SAAU,SAAQ,cAG9B;CAAG;;AAEJ,mGAAmG;AACnG,qBAAa,MAAO,SAAQ,WAA2D;CAAG;;;;AAE1F,qBAAa,QAAS,SAAQ,aAE5B;CAAG;AAEL,6CAA6C;AAC7C,eAAO,MAAM,IAAI,wFAAoD,CAAC;AACtE,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAC;AAEpC,eAAO,MAAM,QAAQ,0IAA+D,CAAC;AACrF,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAC;AAE5C,kFAAkF;AAClF,eAAO,MAAM,SAAS,wEAA2C,CAAC;AAClE,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAC;AAE9C,kDAAkD;AAClD,eAAO,MAAM,SAAS,wDAAkC,CAAC;AACzD,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAC;AAE9C,eAAO,MAAM,MAAM,sEAAkB,CAAC;AACtC,eAAO,MAAM,WAAW,4DAAuB,CAAC;AAChD,eAAO,MAAM,WAAW,kDAAuB,CAAC;AAEhD,uDAAuD;AACvD,eAAO,MAAM,eAAe,UAAW,QAAQ;IAC7C,UAAU;IACV,QAAQ;IACR,iBAAiB;IACjB,SAAS;IACT,WAAW;CACX,CAAC;AAUH,oDAAoD;AACpD,eAAO,MAAM,eAAe,sDAA4D,CAAC;AAEzF,uCAAuC;AACvC,eAAO,MAAM,UAAU,yFAQtB,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,2CAAsD,CAAC;AAExF,eAAO,MAAM,aAAa,WAAY,OAAO,KAAG,OAAwB,CAAC;AAEzE,eAAO,MAAM,OAAO,WAAY,OAAO,KAAG,MAAsB,CAAC;AAEjE,eAAO,MAAM,KAAK,WAAY,SAAS,KAAG,OAAwB,CAAC;AAEnE,eAAO,MAAM,OAAO,WAAY,OAAO,KAAG,SAA4B,CAAC;AAEvE,kFAAkF;AAClF,eAAO,MAAM,IAAI,WAAY,OAAO,KAAG,MAAsB,CAAC;AAE9D,eAAO,MAAM,KAAK,WAAY,MAAM,KAAG,OAAwB,CAAC;AAEhE,eAAO,MAAM,gBAAgB,WAAY,IAAI,KAAG,QACE,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,SAAS,WAAY,SAAS,MAAM,OAAO,KAAG,QACT,CAAC;AAEnD,eAAO,MAAM,MAAM,WAAY,SAAS,KAAG,QAAmD,CAAC"}