@toon-protocol/rig 4.2.0 → 4.3.0

package/dist/index.d.ts

@@ -231,6 +231,12 @@ interface NostrFilter {
     '#a'?: string[];
     /** Event-reference tag filter (#278 tracker: statuses + comments). */
     '#e'?: string[];
+    /** Commit tag filter (#125 CI: results/progress/jobs for one commit). */
+    '#c'?: string[];
+    /** Addressee tag filter (#125 CI: a coordinator's inbox — 9843/9844/9840/29846). */
+    '#p'?: string[];
+    /** Only events at or after this unix time (#125 coordinator cursor resume). */
+    since?: number;
     limit?: number;
 }
 /**
@@ -1424,4 +1430,737 @@ interface FactoryJobExecution {
  */
 declare function executeFactoryJob(options: ExecuteFactoryJobOptions): Promise<FactoryJobExecution>;
 
-export { type BuildIncrementOfferOptions, type BuildNarrationOptions, type BuildResultEventOptions, type ClosureResult, type CollectRepoObjectsOptions, type CollectRepoObjectsResult, DEFAULT_CONCURRENCY, type DownloadOptions, type DownloadResult, type EncryptedArtifact, type EncryptedArtifactRef, type ExecuteFactoryJobOptions, type ExecutePushOptions, FACTORY_JOB_FEEDBACK_KIND, FACTORY_JOB_REQUEST_KIND, FACTORY_JOB_RESULT_KIND, type FactoryJobExecution, type FactoryJobHooks, type FactoryJobOutcome, type FactoryJobRequest, type FactoryJobWork, type FactoryMilestone, type FactoryTicket, FeeRates, type FetchLike, type FetchRemoteStateOptions, type FetchedObject, type GateCheck, type GateResult, type GatewayFetchOptions, type GitCommentRequest, GitError, type GitErrorEnvelope, type GitEstimateRequest, type GitEstimateResponse, type GitEventResponse, type GitFeeEstimate, type GitIssueRequest, GitObjectType, type GitPatchRequest, type GitPlannedObject, type GitPublishReceipt, type GitPushRequest, type GitPushResponse, type GitRef, type GitRefUpdate, type GitRepoAddr, GitRepoReader, type GitStatusRequest, type GitStatusValue, type GitUploadStep, type IncrementSpec, type JobDeliveryPort, type MissingObject, NonFastForwardError, type NostrEvent, type NostrFilter, ObjectIntegrityError, type ObjectStat, type ObjectWithPath, ObjectWriteMismatchError, type OfferedIncrement, type OversizeObject, OversizeObjectsError, PayoutPointer, type PlanPushOptions, type PlannedObject, PublishReceipt, Publisher, type PushFeeEstimate, type PushPlan, type PushResult, type ReadGitObject, type ReadObjectsResult, type RefUpdate, type RefUpdateKind, type RejectedRefUpdate, type RelayEvent, type RemoteState, type RepoRefs, type StatObjectsResult, UnsignedEvent, type UploadStepResult, type WebSocketFactory, type WebSocketLike, buildIncrementOfferEvent, buildNarrationEvent, buildQuoteEvent, buildResultEvent, collectRepoObjects, downloadGitObjects, executeFactoryJob, executePush, fetchRemoteState, fetchTxBytes, gatePassed, hexToNpub, isSafeRefname, missingObjectsMessage, npubToHex, ownerToHex, parseFactoryJobRequest, planFactoryJob, planPush, queryRelay, referencedShas, serializeEventReceipt, serializeFeeEstimate, serializePushPlan, serializePushResult, setHeadSymref, updateRef, verifyObjectBody, walkClosure, writeGitObject, writeGitObjects };
+/**
+ * NIP-C1 (Nostr CI) event builders + parsers — the wire layer of rig's
+ * relay-native CI (rig#125, slice 1). The spec is vendored at
+ * docs/specs/nip-c1.md; this module adopts it VERBATIM for kinds, tags,
+ * content, and ordering rules, so ngit tooling keeps reading rig's events and
+ * rig keeps reading ngit-ci's.
+ *
+ * Builders return UnsignedEvent (the Publisher signs — see ../publisher.ts,
+ * the same posture as ../nip34-events.ts). Parsers take a read-side
+ * NostrEvent and return `null` on ANY malformed shape: the relay is
+ * permissionless, so a consumer must never let a hand-crafted event smuggle a
+ * meaning the spec does not give it (an unknown `X` policy is NOT automatic
+ * service; a request naming another coordinator is NOT ours; a trigger whose
+ * `a` tags name two repo ids is NOT a run).
+ *
+ * rig's deliberate departures from the ngit reference, all within the spec:
+ *   - `["software","rig","<version>"]` on the Advertisement;
+ *   - Advertisement policy `M=maintainer-request`, `X=request-required`,
+ *     `B=out-of-band` (the coordinator is funded by its operator);
+ *   - logs/artifacts are TOON store gateway URLs, not Blossom (the tag
+ *     shapes are identical — only the URL host differs);
+ *   - PR context may carry `K`/`k` = 1617: `rig pr create` publishes NIP-34
+ *     patches, so a 1617 is the PR shape rig's own contributors produce.
+ */
+
+declare const CI_ADVERTISEMENT_KIND = 19843;
+declare const CI_SERVICE_REQUEST_KIND = 9843;
+declare const CI_SERVICE_STOP_KIND = 9844;
+declare const CI_SECRET_UPDATE_KIND = 29846;
+declare const CI_MANUAL_TRIGGER_KIND = 9840;
+declare const CI_JOB_RESULT_KIND = 9841;
+declare const CI_WORKFLOW_RESULT_KIND = 9842;
+declare const CI_WORKFLOW_PROGRESS_KIND = 39842;
+/** The one runner family rig supports (`W` tag / `R` prefix). */
+declare const CI_RUNNER_FAMILY = "act";
+/** The `software` tag name rig advertises under. */
+declare const CI_SOFTWARE = "rig";
+/** NIP-40 bound on Advertisement + Progress lifetime (seconds). */
+declare const CI_MAX_ADVERTISEMENT_TTL: number;
+declare const CI_MAX_PROGRESS_TTL: number;
+type CiConclusion = 'success' | 'failure' | 'neutral' | 'cancelled' | 'skipped' | 'timed_out' | 'startup_failure';
+declare function isCiConclusion(value: string): value is CiConclusion;
+type CiProgressStatus = 'queued' | 'in_progress' | 'concluded';
+/** Normalized trigger reasons rig runs (`schedule` is out of scope). */
+type CiTriggerReason = 'push' | 'pull_request' | 'manual';
+type CiAdmissionPolicy = 'operator-selected' | 'maintainer-request' | 'open';
+type CiExecutionPolicy = 'automatic' | 'request-required';
+type CiBillingPolicy = 'not-required' | 'out-of-band';
+/** Repo address string `30617:<owner-hex>:<repo-id>`. */
+type RepoAddress = string;
+declare function repoAddress(ownerPubkey: string, repoId: string): RepoAddress;
+declare function parseRepoAddress(a: string): {
+    ownerPubkey: string;
+    repoId: string;
+} | null;
+interface CiWorkflowRef {
+    /** Workflow file path, relative to the repo root (`w` tag). */
+    path: string;
+    /** SHA-256 (hex) of the workflow file content at the run's commit. */
+    sha256: string;
+}
+/**
+ * NIP-22 PR context of a `pull_request` run: the PR event as root (`E`/`K`/
+ * `P`) and the PR or PR-update event that supplied the commit as parent
+ * (`e`/`k`/`p`). `prKind`/`sourceKind` 1617 is rig's departure — see the
+ * module header.
+ */
+interface CiPrContext {
+    prEventId: string;
+    prAuthor: string;
+    prKind: 1617 | 1618;
+    sourceEventId: string;
+    sourceAuthor: string;
+    sourceKind: 1617 | 1618 | 1619;
+}
+interface CiTriggerContext {
+    /** The repo the run is for — the FIRST `a` tag. */
+    repoAddr: RepoAddress;
+    /** Further `a` tags: the same repo id under other maintainers' announcements. */
+    extraRepoAddrs?: string[];
+    /** The commit the workflow ran against — the FIRST `c` tag. */
+    commit: string;
+    /** Extra `c` tags: annotated tag object ids peeling to `commit`. */
+    tagObjectIds?: string[];
+    workflow: CiWorkflowRef;
+    reason: CiTriggerReason;
+    /** `r` tag — push runs (and optionally manual runs); never with `pr`. */
+    ref?: string;
+    pr?: CiPrContext;
+}
+/** The frozen request-provenance quote a run carries (`q … service-request|manual-trigger`). */
+type CiProvenance = {
+    kind: 'service-request';
+    eventId: string;
+    relayUrl: string;
+    pubkey: string;
+} | {
+    kind: 'manual-trigger';
+    eventId: string;
+    relayUrl: string;
+    pubkey: string;
+};
+/** The common + trigger-context tags (`a*`, `c*`, `w`, `o`, then `r` | `E K P e k p`). */
+declare function commonTriggerTags(trigger: CiTriggerContext): string[][];
+/**
+ * Parse the common + trigger-context tags. `defaultReason` supplies the
+ * reason when no `o` tag is present (Manual Triggers omit it and are always
+ * `manual`); without it a missing `o` is malformed.
+ */
+declare function parseCiTriggerContext(tags: string[][], opts?: {
+    defaultReason?: CiTriggerReason;
+}): CiTriggerContext | null;
+interface CiAdvertisementInput {
+    version: string;
+    /** Accepted `act` selectors (emitted as `R = act:<selector>`). */
+    selectors: string[];
+    admission: CiAdmissionPolicy;
+    execution: CiExecutionPolicy;
+    billing?: CiBillingPolicy;
+    secretsKey?: {
+        pubkey: string;
+        inboxRelays: string[];
+    };
+    /** NIP-40 expiration: > created_at, ≤ created_at + 30 min. */
+    expiresAt: number;
+}
+interface CiAdvertisement {
+    eventId: string;
+    pubkey: string;
+    createdAt: number;
+    version: string;
+    /** Supported runner families (`W`), case-folded + deduplicated. */
+    families: string[];
+    /** Accepted `<family>:<selector>` values (`R`), case-folded + deduplicated. */
+    selectors: string[];
+    admission: CiAdmissionPolicy;
+    execution: CiExecutionPolicy;
+    billing?: CiBillingPolicy;
+    secretsKey?: {
+        pubkey: string;
+        inboxRelays: string[];
+    };
+    expiresAt: number;
+}
+declare function buildCiAdvertisement(input: CiAdvertisementInput, createdAt?: number): UnsignedEvent;
+declare function parseCiAdvertisement(ev: NostrEvent): CiAdvertisement | null;
+interface ServiceControl {
+    kind: 'request' | 'stop';
+    eventId: string;
+    pubkey: string;
+    createdAt: number;
+    repoAddr: RepoAddress;
+    coordinatorPubkey: string;
+    relayHint?: string;
+}
+declare function buildCiServiceRequest(repoAddr: RepoAddress, coordinatorPubkey: string, relayHint?: string, createdAt?: number): UnsignedEvent;
+declare function buildCiServiceStop(repoAddr: RepoAddress, coordinatorPubkey: string, relayHint?: string, createdAt?: number): UnsignedEvent;
+declare function parseCiServiceControl(ev: NostrEvent): ServiceControl | null;
+/**
+ * NIP-C1 total order for controls (and secret updates): a greater
+ * `created_at` is later; at equal timestamps the lexicographically LOWER
+ * event id is later. Returns <0 when `a` is earlier than `b`.
+ */
+declare function controlOrder(a: {
+    createdAt: number;
+    eventId: string;
+}, b: {
+    createdAt: number;
+    eventId: string;
+}): number;
+interface SelectServiceRequestsOptions {
+    coordinatorPubkey: string;
+    /** When given, controls for other repo addresses are ignored. */
+    repoAddr?: RepoAddress;
+    /** Current owner ∪ maintainers (lowercase hex) — the accepted requesters. */
+    authorized: Set<string>;
+    /**
+     * Extra requester pubkeys the operator explicitly accepts (NIP-C1: "an
+     * operator MAY explicitly accept other requester pubkeys"). Their Requests
+     * count, but they stay non-maintainers: their Stops close only their own
+     * Requests, and runs they cause carry lower trust.
+     */
+    acceptedRequesters?: Set<string>;
+}
+interface SelectedServiceRequests {
+    /** The newest accepted, unstopped Request — service is eligible iff non-null. */
+    active: ServiceControl | null;
+    /** Every accepted Request still open, earliest first. */
+    open: ServiceControl[];
+}
+/**
+ * Reduce the Service Request / Stop history for one coordinator + repo
+ * perspective under the default policy (only current maintainers' Requests
+ * are accepted). A maintainer's Stop closes every earlier Request; any other
+ * author's Stop closes only that author's own earlier Requests — so a removed
+ * maintainer keeps the author-local effect but loses the repo-wide one.
+ */
+declare function selectServiceRequests(controls: ServiceControl[], opts: SelectServiceRequestsOptions): SelectedServiceRequests;
+interface CiManualTrigger {
+    eventId: string;
+    pubkey: string;
+    createdAt: number;
+    coordinatorPubkey: string;
+    trigger: Omit<CiTriggerContext, 'reason'>;
+}
+declare function buildCiManualTrigger(coordinatorPubkey: string, trigger: Omit<CiTriggerContext, 'reason'>, createdAt?: number): UnsignedEvent;
+/**
+ * Parse a Manual Trigger. With `coordinatorPubkey` given, a request addressed
+ * to any other coordinator is ignored (`null`). The ONLY lowercase `p` on a
+ * Manual Trigger is the coordinator — a second one is malformed.
+ */
+declare function parseCiManualTrigger(ev: NostrEvent, coordinatorPubkey?: string): CiManualTrigger | null;
+interface CiSecretUpdateArgs {
+    repoAddr: RepoAddress;
+    coordinatorPubkey: string;
+    advertisementId: string;
+    advertisementRelayHint?: string;
+    senderPubkey: string;
+    recipientPubkey: string;
+    ciphertext: string;
+    createdAt: number;
+}
+interface CiSecretUpdate {
+    eventId: string;
+    pubkey: string;
+    createdAt: number;
+    repoAddr: RepoAddress;
+    coordinatorPubkey: string;
+    advertisementId: string;
+    senderPubkey: string;
+    recipientPubkey: string;
+    ciphertext: string;
+}
+declare function buildCiSecretUpdate(args: CiSecretUpdateArgs): UnsignedEvent;
+declare function parseCiSecretUpdate(ev: NostrEvent): CiSecretUpdate | null;
+interface CiArtifact {
+    url: string;
+    filename: string;
+    name: string;
+}
+interface CiJobResultInput {
+    trigger: CiTriggerContext;
+    /** `39842:<coordinator>:<runId>` — the run's Workflow Progress address. */
+    progressAddress: string;
+    /** Relay the Progress event was published to (the `q` relay hint). */
+    relayUrl: string;
+    jobId: string;
+    name?: string;
+    conclusion: CiConclusion;
+    logsUrl: string;
+    logTail: string;
+    logOmittedBytes: number;
+    artifacts?: CiArtifact[];
+    queuedAt?: number;
+    startedAt?: number;
+    exitCode?: number;
+    runsOn?: string[];
+    /** MAY be carried on a Job Result (never a service-request by rig's coordinator). */
+    provenance?: CiProvenance;
+}
+interface CiJobResult {
+    eventId: string;
+    pubkey: string;
+    createdAt: number;
+    trigger: CiTriggerContext;
+    progressAddress: string;
+    jobId: string;
+    name?: string;
+    conclusion: CiConclusion;
+    logsUrl?: string;
+    logTail: string;
+    logOmittedBytes: number;
+    artifacts: CiArtifact[];
+    queuedAt?: number;
+    startedAt?: number;
+    exitCode?: number;
+    runsOn: string[];
+    provenance?: CiProvenance;
+}
+declare function buildCiJobResult(input: CiJobResultInput, createdAt?: number): UnsignedEvent;
+declare function parseCiJobResult(ev: NostrEvent): CiJobResult | null;
+/** A `q` quote of one Job Result (job id as the marker). */
+interface CiJobQuote {
+    eventId: string;
+    relayUrl: string;
+    pubkey: string;
+    jobId: string;
+}
+interface CiWorkflowResultInput {
+    trigger: CiTriggerContext;
+    runId: string;
+    conclusion: CiConclusion;
+    queuedAt?: number;
+    startedAt?: number;
+    provenance?: CiProvenance;
+    jobs: CiJobQuote[];
+}
+interface CiWorkflowResult {
+    eventId: string;
+    pubkey: string;
+    createdAt: number;
+    trigger: CiTriggerContext;
+    runId: string;
+    conclusion: CiConclusion;
+    queuedAt?: number;
+    startedAt?: number;
+    provenance?: CiProvenance;
+    jobs: CiJobQuote[];
+}
+declare function buildCiWorkflowResult(input: CiWorkflowResultInput, createdAt?: number): UnsignedEvent;
+declare function parseCiWorkflowResult(ev: NostrEvent): CiWorkflowResult | null;
+interface CiWorkflowProgressInput extends Omit<CiWorkflowResultInput, 'conclusion'> {
+    status: CiProgressStatus;
+    /** Required iff `status === 'concluded'`. */
+    conclusion?: CiConclusion;
+    /** Capacity rounds before start (queued only). */
+    queue?: number;
+    /** Job ids currently executing. */
+    inProgress?: string[];
+    /** NIP-40 expiration: > created_at, ≤ created_at + 30 min. */
+    expiresAt: number;
+}
+interface CiWorkflowProgress {
+    eventId: string;
+    pubkey: string;
+    createdAt: number;
+    trigger: CiTriggerContext;
+    runId: string;
+    status: CiProgressStatus;
+    conclusion?: CiConclusion;
+    queue?: number;
+    inProgress: string[];
+    queuedAt?: number;
+    startedAt?: number;
+    expiresAt: number;
+    provenance?: CiProvenance;
+    jobs: CiJobQuote[];
+}
+declare function buildCiWorkflowProgress(input: CiWorkflowProgressInput, createdAt?: number): UnsignedEvent;
+declare function parseCiWorkflowProgress(ev: NostrEvent): CiWorkflowProgress | null;
+
+/**
+ * Repository Secret Update payloads (rig#125): the NIP-44 v2 ciphertext a
+ * kind:29846 carries, its plaintext rules, and the per-name ordering that
+ * turns a stream of updates into the coordinator's secret inventory.
+ * docs/specs/nip-c1.md "Repository Secret Update" is the contract.
+ *
+ * The maintainer signs the OUTER event with their identity but encrypts
+ * with a FRESH per-submission sender key to the coordinator's advertised
+ * `secrets-key` (a short-lived transport key, never the coordinator's
+ * signing key). The plaintext repeats only two bindings — `author` and
+ * `created_at` — so captured ciphertext cannot be re-signed into another
+ * maintainer's authority or moved to a newer ordering position; the rest is
+ * authenticated by the outer signature and not duplicated.
+ *
+ * The inventory keeps a value-or-tombstone per name with the update's
+ * `(created_at, event id)` so that out-of-order or duplicate relay delivery
+ * can never resurrect an older value (a remove is an ordering tombstone).
+ * rig persists this inventory under the coordinator's state dir (slice 4);
+ * the bunker-sealed storage mode NIP-C1 defines is out of scope.
+ */
+declare const SECRET_NAME_RE: RegExp;
+/** Names a coordinator never injects into jobs (NIP-C1 reserved). */
+declare const RESERVED_SECRET_NAMES: readonly string[];
+declare const MAX_SECRET_NAMES = 100;
+declare const MAX_SECRET_VALUE_BYTES = 16384;
+declare const MAX_SECRET_PLAINTEXT_BYTES = 65535;
+declare const MAX_SECRET_CIPHERTEXT_BYTES: number;
+interface SecretUpdatePlaintext {
+    author: string;
+    created_at: number;
+    set: Record<string, string>;
+    remove: string[];
+}
+/**
+ * Validate the plaintext SHAPE + limits (not the outer bindings — see
+ * {@link validateSecretUpdate}). Throws on any violation; returns the
+ * narrowed value.
+ */
+declare function assertSecretUpdateShape(value: unknown): SecretUpdatePlaintext;
+/** Bind a decrypted plaintext to its outer event: author + created_at MUST match. */
+declare function validateSecretUpdate(plain: SecretUpdatePlaintext, outer: {
+    pubkey: string;
+    created_at: number;
+}): void;
+/** Encrypt one update (NIP-44 v2) from a fresh sender key to the advertised recipient. */
+declare function encryptSecretUpdate(plain: SecretUpdatePlaintext, senderSecretKey: Uint8Array, recipientPubkey: string): string;
+/**
+ * Decrypt + validate one update with the recipient (secrets-key) secret key
+ * and the event's `sender` pubkey. Bounds the ciphertext BEFORE decrypting
+ * (nostr-tools asks callers to) and the plaintext after.
+ */
+declare function decryptSecretUpdate(ciphertext: string, recipientSecretKey: Uint8Array, senderPubkey: string): SecretUpdatePlaintext;
+interface SecretInventoryEntry {
+    /** The value, or `null` for a remove tombstone. */
+    value: string | null;
+    /** Ordering position of the update that last touched this name. */
+    createdAt: number;
+    eventId: string;
+    /** The maintainer whose update supplied this entry. */
+    origin: string;
+}
+type SecretInventory = Record<string, SecretInventoryEntry>;
+/**
+ * Apply one accepted update to an inventory (immutably). Per name, the
+ * NIP-C1 total order decides: an update only replaces an entry it is LATER
+ * than, so replaying an old event — or a remove that arrived before the set
+ * it tombstones — never resurrects a stale value.
+ */
+declare function applySecretUpdate(inventory: SecretInventory, plain: SecretUpdatePlaintext, eventId: string): SecretInventory;
+/** The injectable name → value map (tombstones dropped). */
+declare function effectiveSecrets(inventory: SecretInventory): Record<string, string>;
+/** A fresh NIP-44 recipient (secrets-key) or sender keypair. */
+declare function generateSecretsKey(): {
+    secretKey: Uint8Array;
+    pubkey: string;
+};
+
+/**
+ * NIP-C1 trust levels (rig#125): how a run's results relate to the repo's
+ * maintainers, derived ONLY from Service Requests / Stops and the repo's
+ * declared maintainers — never from anything the coordinator asserts about
+ * itself. The relay is permissionless, so a stranger's coordinator can
+ * publish a green 9842 for anyone's commit; this is the consumer-side filter
+ * (the same posture as #287's authorized status authors) that lets
+ * `rig ci status --require-ci-trust` and rig-web tell whose CI they are
+ * looking at.
+ *
+ *   maintainer-directed      the run's frozen provenance quote names a
+ *                            maintainer: a manual trigger they signed, or a
+ *                            Service Request they signed that we have SEEN
+ *                            and that targets this run's publisher;
+ *   operationally-associated no qualifying quote, but at run time an
+ *                            accepted, unstopped maintainer Request stood for
+ *                            this publisher (it was authorized, just silent);
+ *   seen-in-network          the publisher is itself a maintainer, or SOME
+ *                            pubkey (not a maintainer) requested its service
+ *                            for this repo — e.g. a contributor running their
+ *                            own coordinator against a repo they don't own;
+ *   no-known-context         nothing ties the publisher to the repo.
+ */
+
+type CiTrustLevel = 'maintainer-directed' | 'operationally-associated' | 'seen-in-network' | 'no-known-context';
+/** Strongest first. */
+declare const CI_TRUST_ORDER: readonly CiTrustLevel[];
+declare function isCiTrustLevel(value: string): value is CiTrustLevel;
+interface DeriveTrustLevelArgs {
+    /** The run's 9842/39842 signer — the coordinator. */
+    publisherPubkey: string;
+    /** The run's frozen `q … service-request|manual-trigger` quote, if any. */
+    provenance?: CiProvenance;
+    /** Owner ∪ maintainers of the repo (hex, any case). */
+    authorized: Set<string>;
+    /** Every 9843/9844 seen for this repo address (any coordinator). */
+    controls: ServiceControl[];
+    /** The run's `created_at` — requests are evaluated as of this instant. */
+    runCreatedAt: number;
+}
+declare function deriveTrustLevel(args: DeriveTrustLevelArgs): CiTrustLevel;
+/** True when `level` is at least as strong as `required`. */
+declare function trustAtLeast(level: CiTrustLevel, required: CiTrustLevel): boolean;
+
+/**
+ * The Runner seam (rig#125) — the ONE new interface the relay-native CI
+ * layer introduces. The coordinator (./coordinator.ts) materializes a commit,
+ * picks a workflow, decides the secret set, and hands all of that to a
+ * Runner; the Runner executes the jobs and reports per-job conclusions, exit
+ * codes, timings, logs and artifact files. Nothing about relays, payments,
+ * or NIP-C1 events crosses this boundary in either direction.
+ *
+ * Two implementations exist today:
+ *
+ *   - {@link FakeRunner} (here): scripted outcomes for coordinator tests.
+ *   - `ActRunner` (./act-runner.ts): shells out to `act` against the host
+ *     Docker daemon — the first-slice "coordinator is its own runner" shape
+ *     ngit's reference coordinator also uses.
+ *
+ * A later TOON-lease runner (rent a workload from a TOON Network provider,
+ * blocked on TOON_Network Milestone 1) is a third class behind the SAME
+ * interface; that is the whole point of the seam.
+ */
+
+/** One artifact file a job produced (one entry per FILE, never an archive). */
+interface RunnerArtifact {
+    /** Absolute path of the file on the coordinator host. */
+    path: string;
+    /** The file's path within the artifact (mirrors upload-artifact). */
+    filename: string;
+    /** The artifact name grouping related files. */
+    name: string;
+}
+/** The outcome of one job within a run. */
+interface RunnerJobResult {
+    /** Job id as declared in the workflow file. */
+    jobId: string;
+    /** Human-readable job name, when the workflow declares one. */
+    name?: string;
+    conclusion: CiConclusion;
+    exitCode?: number;
+    /** Unix seconds. */
+    startedAt: number;
+    /** Unix seconds. */
+    finishedAt: number;
+    /** The job's complete log output. */
+    log: string;
+    artifacts: RunnerArtifact[];
+}
+/** The outcome of one workflow run. */
+interface RunnerRunResult {
+    /** Combined conclusion — the execution backend's own verdict, passed through. */
+    conclusion: CiConclusion;
+    jobs: RunnerJobResult[];
+    startedAt: number;
+    finishedAt: number;
+}
+/** Everything a Runner needs to execute one workflow once. */
+interface RunnerRequest {
+    /** A real git repository, checked out at `trigger.commit`. */
+    checkoutDir: string;
+    /** Workflow file path relative to `checkoutDir`, plus its content SHA-256. */
+    workflow: {
+        path: string;
+        sha256: string;
+    };
+    trigger: CiTriggerContext;
+    /** Secrets to inject; `{}` for runs the coordinator did not authorize secrets for. */
+    secrets: Record<string, string>;
+    /** Extra environment for the jobs. */
+    env?: Record<string, string>;
+    /** Wall-clock budget for the whole run; exceeding it concludes `timed_out`. */
+    timeoutMs: number;
+    /** Streaming log sink (per job). */
+    onLog?: (jobId: string, chunk: string) => void;
+    /** Cancels the run (concludes `cancelled`). */
+    signal?: AbortSignal;
+}
+/** Executes one workflow run. See the module header. */
+interface Runner {
+    /** Runner family, as advertised in the NIP-C1 `W` tag. */
+    readonly family: 'act';
+    /** Accepted selectors for the family (`R` = `act:<selector>`). */
+    readonly selectors: string[];
+    run(request: RunnerRequest): Promise<RunnerRunResult>;
+}
+type FakeRunnerScript = (request: RunnerRequest) => RunnerRunResult | Promise<RunnerRunResult>;
+/** The default script: one successful `build` job with a short log. */
+declare function defaultFakeRunResult(request: RunnerRequest): RunnerRunResult;
+/**
+ * A Runner that returns scripted outcomes and records every request, so a
+ * coordinator test can assert on what was asked (secrets, timeout, commit)
+ * and drive the publish sequence from a chosen result. Never touches Docker.
+ */
+declare class FakeRunner implements Runner {
+    private readonly script;
+    readonly family: "act";
+    readonly selectors: string[];
+    /** Every request, in call order. */
+    readonly requests: RunnerRequest[];
+    constructor(script?: FakeRunnerScript);
+    run(request: RunnerRequest): Promise<RunnerRunResult>;
+}
+
+/**
+ * Workflow discovery and trigger matching (rig#125).
+ *
+ * Workflows are GitHub-Actions-syntax files the coordinator reads out of a
+ * MATERIALIZED checkout (never from the relay, never from GitHub): first
+ * `.github/workflows/*.yml|yaml`, then `.ngit/act/workflows/*.yml|yaml` so
+ * repos already on ngit CI are served as-is. Each is identified on every
+ * NIP-C1 event by its path and the SHA-256 of its bytes (the `w` tag), so a
+ * consumer can verify exactly which file ran.
+ *
+ * Only the `on:` clause and the job list are interpreted here — enough to
+ * decide WHETHER a workflow runs for a push/pull-request trigger and which
+ * job ids to expect. Everything else in the file is act's business
+ * (./act-runner.ts). Parsing never throws: a malformed file comes back with
+ * `parseError` set so the coordinator can publish an honest
+ * `startup_failure` for it instead of silently skipping it.
+ */
+/** Where workflows live, in scan order (relative to the checkout root). */
+declare const WORKFLOW_DIRS: readonly [".github/workflows", ".ngit/act/workflows"];
+/** Branch/tag filters of a `push:` or `pull_request:` trigger. */
+interface RefFilters {
+    branches?: string[];
+    tags?: string[];
+}
+interface WorkflowTriggers {
+    push?: RefFilters;
+    pull_request?: RefFilters;
+    workflow_dispatch?: boolean;
+}
+interface WorkflowJob {
+    id: string;
+    name?: string;
+    runsOn?: string[];
+}
+interface DiscoveredWorkflow {
+    /** Path relative to the checkout root, forward slashes. */
+    path: string;
+    /** Lowercase hex SHA-256 of the file's exact bytes. */
+    sha256: string;
+    name?: string;
+    triggers: WorkflowTriggers;
+    jobs: WorkflowJob[];
+    /** Set when the file could not be understood; `triggers`/`jobs` are then empty. */
+    parseError?: string;
+}
+/** Lowercase hex SHA-256 of `bytes`. */
+declare function sha256Hex(bytes: Uint8Array | string): string;
+/**
+ * Parse one workflow file's bytes. Never throws — see the module header.
+ * YAML 1.1 loaders read the unquoted `on` key as boolean `true`; the `yaml`
+ * package (YAML 1.2) keeps it a string, but a file re-saved by such a loader
+ * carries a literal `true:` key, so both spellings are honoured.
+ */
+declare function parseWorkflow(path: string, content: string | Uint8Array): DiscoveredWorkflow;
+/**
+ * Every workflow file under {@link WORKFLOW_DIRS} in `checkoutDir`, in a
+ * stable order (directory order, then filename). Missing directories are
+ * simply empty.
+ */
+declare function discoverWorkflows(checkoutDir: string): Promise<DiscoveredWorkflow[]>;
+/**
+ * GitHub's `branches`/`tags` filter rule: patterns are applied in order, a
+ * `!` pattern excludes, and a name is included only if the LAST matching
+ * pattern was positive. A negation can never include on its own.
+ */
+declare function refMatchesPatterns(shortName: string, patterns: string[]): boolean;
+/**
+ * Does `wf` run for a push that moved `ref` (`refs/heads/...` or
+ * `refs/tags/...`)? Mirrors GitHub: no filters → every ref; a `branches`
+ * filter alone → only branches; a `tags` filter alone → only tags.
+ */
+declare function matchesPush(wf: DiscoveredWorkflow, ref: string): boolean;
+/**
+ * Does `wf` run for a pull request against `baseRef` (a `refs/heads/...` ref
+ * or a bare branch name)? With a `branches` filter and no known base the
+ * match cannot be proven, so the workflow does not run.
+ */
+declare function matchesPullRequest(wf: DiscoveredWorkflow, baseRef?: string): boolean;
+
+/**
+ * `rig ci status <commit>` — the FREE read side of relay-native CI (#125):
+ * every NIP-C1 run (kind:9842 Workflow Result / kind:39842 Workflow
+ * Progress) and job (kind:9841 Job Result) a relay holds for one commit of
+ * one repo, with each run's trust level derived from the repo's maintainers
+ * (kind:30617) and the Service Request / Stop history (kind:9843/9844).
+ *
+ * It is the one-command merge gate: exit 0 only when every COUNTED run has
+ * concluded green. A run counts when it is the latest attempt by its
+ * publisher for its workflow, survives `--workflow` and
+ * `--require-ci-trust`, and — since the relay is permissionless — a
+ * stranger's coordinator can never make a commit green under a trust
+ * requirement it does not meet. A commit with no concluded run is NOT green
+ * (exit 1, "no concluded run"), so a gate cannot pass by accident.
+ *
+ * Like the #278 tracker reads: no identity, no payment, reads may target
+ * several relays (merged by event id), and `--json` emits exactly one
+ * document.
+ */
+
+interface CiStatusJob {
+    jobId: string;
+    name?: string;
+    conclusion: CiConclusion;
+    logsUrl?: string;
+    artifacts: CiArtifact[];
+    exitCode?: number;
+    startedAt?: number;
+    eventId: string;
+    publisher: string;
+}
+interface CiStatusRun {
+    runId: string;
+    coordinator: string;
+    workflow: CiWorkflowRef;
+    reason: CiTriggerReason;
+    status: CiProgressStatus;
+    conclusion?: CiConclusion;
+    trust: CiTrustLevel;
+    createdAt: number;
+    startedAt?: number;
+    queuedAt?: number;
+    provenance?: CiProvenance;
+    jobs: CiStatusJob[];
+    /** Event id of the 9842 (concluded) or the latest 39842. */
+    eventId: string;
+}
+interface CiStatusSummary {
+    counted: number;
+    green: number;
+    red: number;
+    pending: number;
+}
+interface CiStatusReport {
+    command: 'ci status';
+    commit: string;
+    repo: {
+        owner: string;
+        repoId: string;
+    };
+    relays: string[];
+    requiredTrust: CiTrustLevel | null;
+    runs: CiStatusRun[];
+    summary: CiStatusSummary;
+    ok: boolean;
+    /** Why `ok` is false, for humans and logs. */
+    reason?: string;
+}
+interface AssembleStatusOptions {
+    commit: string;
+    ownerPubkey: string;
+    repoId: string;
+    /** Owner ∪ declared maintainers (lowercase hex). */
+    authorized: Set<string>;
+    events: NostrEvent[];
+    requireTrust?: CiTrustLevel;
+    workflow?: string;
+}
+/**
+ * Turn relay events into the run list + verdict. Runs are keyed by
+ * (publisher, runId): a 9842 marks the run concluded; otherwise the newest
+ * 39842 (by created_at) gives its status. Jobs attach by the 9841's quoted
+ * progress address. Per (publisher, workflow path) only the LATEST attempt
+ * (by created_at, ties → lowest id) counts.
+ */
+declare function assembleCiStatus(opts: AssembleStatusOptions): {
+    runs: CiStatusRun[];
+    summary: CiStatusSummary;
+    ok: boolean;
+    reason?: string;
+};
+
+export { type BuildIncrementOfferOptions, type BuildNarrationOptions, type BuildResultEventOptions, CI_ADVERTISEMENT_KIND, CI_JOB_RESULT_KIND, CI_MANUAL_TRIGGER_KIND, CI_MAX_ADVERTISEMENT_TTL, CI_MAX_PROGRESS_TTL, CI_RUNNER_FAMILY, CI_SECRET_UPDATE_KIND, CI_SERVICE_REQUEST_KIND, CI_SERVICE_STOP_KIND, CI_SOFTWARE, CI_TRUST_ORDER, CI_WORKFLOW_PROGRESS_KIND, CI_WORKFLOW_RESULT_KIND, type CiAdmissionPolicy, type CiAdvertisement, type CiAdvertisementInput, type CiArtifact, type CiBillingPolicy, type CiConclusion, type CiExecutionPolicy, type CiJobQuote, type CiJobResult, type CiJobResultInput, type CiManualTrigger, type CiPrContext, type CiProgressStatus, type CiProvenance, type CiSecretUpdate, type CiSecretUpdateArgs, type CiStatusJob, type CiStatusReport, type CiStatusRun, type CiStatusSummary, type CiTriggerContext, type CiTriggerReason, type CiTrustLevel, type CiWorkflowProgress, type CiWorkflowProgressInput, type CiWorkflowRef, type CiWorkflowResult, type CiWorkflowResultInput, type ClosureResult, type CollectRepoObjectsOptions, type CollectRepoObjectsResult, DEFAULT_CONCURRENCY, type DeriveTrustLevelArgs, type DiscoveredWorkflow, type DownloadOptions, type DownloadResult, type EncryptedArtifact, type EncryptedArtifactRef, type ExecuteFactoryJobOptions, type ExecutePushOptions, FACTORY_JOB_FEEDBACK_KIND, FACTORY_JOB_REQUEST_KIND, FACTORY_JOB_RESULT_KIND, type FactoryJobExecution, type FactoryJobHooks, type FactoryJobOutcome, type FactoryJobRequest, type FactoryJobWork, type FactoryMilestone, type FactoryTicket, FakeRunner, type FakeRunnerScript, FeeRates, type FetchLike, type FetchRemoteStateOptions, type FetchedObject, type GateCheck, type GateResult, type GatewayFetchOptions, type GitCommentRequest, GitError, type GitErrorEnvelope, type GitEstimateRequest, type GitEstimateResponse, type GitEventResponse, type GitFeeEstimate, type GitIssueRequest, GitObjectType, type GitPatchRequest, type GitPlannedObject, type GitPublishReceipt, type GitPushRequest, type GitPushResponse, type GitRef, type GitRefUpdate, type GitRepoAddr, GitRepoReader, type GitStatusRequest, type GitStatusValue, type GitUploadStep, type IncrementSpec, type JobDeliveryPort, MAX_SECRET_CIPHERTEXT_BYTES, MAX_SECRET_NAMES, MAX_SECRET_PLAINTEXT_BYTES, MAX_SECRET_VALUE_BYTES, type MissingObject, NonFastForwardError, type NostrEvent, type NostrFilter, ObjectIntegrityError, type ObjectStat, type ObjectWithPath, ObjectWriteMismatchError, type OfferedIncrement, type OversizeObject, OversizeObjectsError, PayoutPointer, type PlanPushOptions, type PlannedObject, PublishReceipt, Publisher, type PushFeeEstimate, type PushPlan, type PushResult, RESERVED_SECRET_NAMES, type ReadGitObject, type ReadObjectsResult, type RefFilters, type RefUpdate, type RefUpdateKind, type RejectedRefUpdate, type RelayEvent, type RemoteState, type RepoAddress, type RepoRefs, type Runner, type RunnerArtifact, type RunnerJobResult, type RunnerRequest, type RunnerRunResult, SECRET_NAME_RE, type SecretInventory, type SecretInventoryEntry, type SecretUpdatePlaintext, type SelectServiceRequestsOptions, type SelectedServiceRequests, type ServiceControl, type StatObjectsResult, UnsignedEvent, type UploadStepResult, WORKFLOW_DIRS, type WebSocketFactory, type WebSocketLike, type WorkflowJob, type WorkflowTriggers, applySecretUpdate, assembleCiStatus, assertSecretUpdateShape, buildCiAdvertisement, buildCiJobResult, buildCiManualTrigger, buildCiSecretUpdate, buildCiServiceRequest, buildCiServiceStop, buildCiWorkflowProgress, buildCiWorkflowResult, buildIncrementOfferEvent, buildNarrationEvent, buildQuoteEvent, buildResultEvent, collectRepoObjects, commonTriggerTags, controlOrder, decryptSecretUpdate, defaultFakeRunResult, deriveTrustLevel, discoverWorkflows, downloadGitObjects, effectiveSecrets, encryptSecretUpdate, executeFactoryJob, executePush, fetchRemoteState, fetchTxBytes, gatePassed, generateSecretsKey, hexToNpub, isCiConclusion, isCiTrustLevel, isSafeRefname, matchesPullRequest, matchesPush, missingObjectsMessage, npubToHex, ownerToHex, parseCiAdvertisement, parseCiJobResult, parseCiManualTrigger, parseCiSecretUpdate, parseCiServiceControl, parseCiTriggerContext, parseCiWorkflowProgress, parseCiWorkflowResult, parseFactoryJobRequest, parseRepoAddress, parseWorkflow, planFactoryJob, planPush, queryRelay, refMatchesPatterns, referencedShas, repoAddress, selectServiceRequests, serializeEventReceipt, serializeFeeEstimate, serializePushPlan, serializePushResult, setHeadSymref, sha256Hex, trustAtLeast, updateRef, validateSecretUpdate, verifyObjectBody, walkClosure, writeGitObject, writeGitObjects };