@toon-protocol/rig 4.5.0 → 4.7.0

package/dist/index.d.ts

@@ -1,7 +1,104 @@
-import { d as GitObjectType, e as PayoutPointer, P as Publisher, F as FeeRates, c as PublishReceipt, b as UnsignedEvent } from './publisher-Cf6tKnZ3.js';
-export { C as COMMENT_KIND, f as GitObject, G as GitObjectUpload, M as MAINTAINERS_TAG, g as MAX_OBJECT_SIZE, h as PAYOUT_TAG, i as PayoutChain, R as REPOSITORY_STATE_KIND, j as StatusKind, U as UploadReceipt, k as authorizedStatusAuthors, l as buildComment, m as buildIssue, n as buildPatch, o as buildRepoAnnouncement, p as buildRepoRefs, q as buildStatus, r as createGitBlob, s as createGitCommit, t as createGitTag, u as createGitTree, v as hashGitObject, w as isValidEvmPayoutAddress, x as parseMaintainers, y as parsePayout } from './publisher-Cf6tKnZ3.js';
+import { d as PayoutPointer, b as UnsignedEvent, e as GitObjectType, P as Publisher, F as FeeRates, c as PublishReceipt } from './publisher-DgbfziOm.js';
+export { C as COMMENT_KIND, f as CommentParent, g as CommentRoot, h as GitObject, G as GitObjectUpload, L as LEGACY_COMMENT_KIND, M as MAINTAINERS_TAG, i as MAX_ARWEAVE_TAGS_PER_EVENT, j as MAX_OBJECT_SIZE, k as PAYOUT_TAG, l as PayoutChain, R as REPOSITORY_STATE_KIND, m as StatusKind, U as UploadReceipt, n as authorizedStatusAuthors, o as buildComment, p as buildIssue, q as buildPatch, r as buildRepoRefs, s as buildStatus, t as commentBelongsToThread, u as createGitBlob, v as createGitCommit, w as createGitTag, x as createGitTree, y as hashGitObject, z as isValidEvmPayoutAddress, A as parseMaintainers, D as parsePayout } from './publisher-DgbfziOm.js';
 import '@toon-protocol/core/nip34';
 
+/**
+ * The kind:30617 repository announcement — build and amend (#154).
+ *
+ * A kind:30617 is NIP-33 replaceable: publishing a new one REPLACES the old
+ * one wholesale, so a republish that rebuilds the event from the handful of
+ * fields rig models destroys every tag rig does not model — another client's
+ * maintainer role tags (`M`/`m`/`o`), `clone`, `blossoms`, `t`, `alt`, or any
+ * tag invented after this file was written.
+ *
+ * This module owns the whole "next announcement" question so no caller has to
+ * think about it: give it the current announcement (or `null` for a repo's
+ * first) plus the fields you are editing, and it returns the next unsigned
+ * event. The known-tag set is explicit and small; **carrying a tag over
+ * verbatim is the default**, and unknown tags keep their original relative
+ * order. Same pattern as ngit's `is_known_tag_name` + `extra_tags`
+ * (`ngit:src/lib/repo_ref.rs`).
+ *
+ * Every kind:30617 rig publishes — first push, `rig maintainers`,
+ * `rig payout` — is built here.
+ */
+
+/** NIP-34 tag naming the relays a repo's events are published to. */
+declare const RELAYS_TAG = "relays";
+/** NIP-34 tag naming a web URL where the repo can be browsed. */
+declare const WEB_TAG = "web";
+/**
+ * The marker that makes an `["r", "<sha>", "euc"]` tag the repo's *earliest
+ * unique commit* — its fork-identity root — rather than any other `r` tag.
+ */
+declare const EARLIEST_UNIQUE_COMMIT_MARKER = "euc";
+/** The current announcement, as read off the relay. */
+interface ExistingAnnouncement {
+    tags: string[][];
+    /** kind:30617 content is conventionally empty, but it is preserved. */
+    content?: string;
+}
+/**
+ * The fields an amendment can change. **Omit a field to leave it exactly as
+ * the current announcement has it** — that, not deletion, is the default.
+ * Pass a value to rewrite it, and `null`/`[]` to remove it.
+ */
+interface AnnouncementEdits {
+    /** The `d` tag. Always written — an announcement is nothing without it. */
+    repoId: string;
+    name?: string;
+    description?: string;
+    /**
+     * Declared maintainer pubkeys (hex). Emitted as ONE multi-valued
+     * `["maintainers", …]` tag; duplicates and non-64-hex values are dropped,
+     * and an empty result emits no tag. The owner is an implicit maintainer.
+     */
+    maintainers?: readonly string[];
+    /** The `["payout", "<chain>", "<address>"]` pointer (rig#92). */
+    payout?: PayoutPointer | null;
+    /** Relay URLs, as ONE multi-valued `["relays", …]` tag. */
+    relays?: readonly string[] | null;
+    /** Web viewer URLs, as ONE multi-valued `["web", …]` tag. */
+    web?: readonly string[] | null;
+    /**
+     * The repo's earliest unique commit, emitted as `["r", "<sha>", "euc"]`.
+     * Omit to keep whatever the announcement already declares: a repo's fork
+     * identity must never change under its owner.
+     */
+    earliestUniqueCommit?: string | null;
+}
+/**
+ * The next kind:30617 for a repo: `current` with `edits` applied, and
+ * everything else — known-but-unedited tags AND tags rig has never heard of —
+ * carried over verbatim in place.
+ *
+ * An edited slot is rewritten where the current announcement first mentions
+ * it, so a republish moves nothing; repeated tags for one slot collapse into
+ * the single edited value. Slots the current announcement lacks are appended
+ * in {@link SLOTS} order. `d` always leads.
+ *
+ * @param current - The announcement being amended, or `null` for a repo's first.
+ * @param edits - The fields to change; omitted fields are left as they are.
+ */
+declare function amendRepoAnnouncement(current: ExistingAnnouncement | null, edits: AnnouncementEdits): UnsignedEvent;
+/**
+ * Build a repo's FIRST kind:30617 announcement — {@link amendRepoAnnouncement}
+ * with nothing to amend.
+ *
+ * @param repoId - Repository identifier (d tag)
+ * @param name - Human-readable repository name
+ * @param description - Repository description
+ * @param maintainers - Optional declared maintainer pubkeys (hex). Emitted as
+ *   a single `["maintainers", …]` tag when non-empty; duplicate and non-64-hex
+ *   values are dropped. The owner (the signer) is an implicit maintainer and
+ *   need not be listed — if passed it is emitted, which is harmless since the
+ *   owner is authorized regardless. See {@link MAINTAINERS_TAG}.
+ * @param payout - Optional declared payout pointer (rig#92). Emitted as a
+ *   single `["payout", "evm", <address>]` tag when given; omit (or pass
+ *   `null`) to leave the repo with no payout pointer. See {@link PAYOUT_TAG}.
+ */
+declare function buildRepoAnnouncement(repoId: string, name: string, description: string, maintainers?: string[], payout?: PayoutPointer | null): UnsignedEvent;
+
 /**
  * GitRepoReader — read a local repository via `execFile` git plumbing.
  *
@@ -133,6 +230,47 @@ declare class GitRepoReader {
      * trees) — used by push planning to report actionable oversize errors.
      */
     objectsBetweenWithPaths(want: string[], have: string[]): Promise<ObjectWithPath[]>;
+    /**
+     * Run git and hand each stdout line to `visit` as it arrives, never holding
+     * the whole output in memory. Returning `false` from `visit` ends the walk:
+     * the child is killed and the promise resolves with what was seen.
+     *
+     * Every other git call here buffers into one `execFile` string, which is
+     * fine for bounded output. These object walks are not bounded — they grow
+     * with the size of the repository — so on a repo big enough to need the
+     * object-map cap they would be the thing that breaks (#162).
+     */
+    private streamLines;
+    /**
+     * Every object SHA in the local object database, in no particular order
+     * (`git cat-file --batch-all-objects --batch-check`, no bodies read).
+     *
+     * This is the honest answer to "what does this repository already have",
+     * which `rig fetch` needs to compute its delta. It deliberately does NOT
+     * consult the remote's kind:30618 `arweave` map: that map is capped (#162)
+     * and is a hint cache, never an index of local presence.
+     *
+     * Streamed, so the listing never has to fit in one buffer.
+     */
+    listAllObjectShas(): Promise<string[]>;
+    /**
+     * SHAs of every object reachable from `tips`, newest first: commits in
+     * reverse-chronological order, each commit immediately followed by the
+     * trees and blobs it is the first to reference
+     * (`git rev-list --objects --in-commit-order`).
+     *
+     * Used to rank the kind:30618 object map when it exceeds
+     * `MAX_ARWEAVE_TAGS_PER_EVENT` (#162): the entries most likely to be wanted
+     * by the next clone or fetch are the ones nearest the tips. Tips that do
+     * not resolve locally (a remote ref we never fetched) are dropped rather
+     * than failing the walk.
+     *
+     * `limit` stops the walk once that many SHAs have been seen — the ranking
+     * caller never needs more than the cap, and a full walk of a repository big
+     * enough to hit the cap is exactly the work worth not doing. The walk is
+     * streamed, so neither its output nor this array is ever bigger than that.
+     */
+    reachableObjectsNewestFirst(tips: string[], limit?: number): Promise<string[]>;
     /**
      * List every blob (file) reachable from a ref's root tree, recursively,
      * with the path it is served at (#368: the ar.io site manifest join key).
@@ -180,6 +318,19 @@ declare class GitRepoReader {
      * pairs for exactly the commits a format-patch series carries.
      */
     commitParents(shas: string[]): Promise<Map<string, string[]>>;
+    /**
+     * SHAs of the repo's ROOT commits — the parentless commits a history starts
+     * from — via `git rev-list --max-parents=0`.
+     *
+     * The repo's *earliest unique commit* (NIP-34's `euc` fork-identity tag) is
+     * chosen from these; the choosing rule lives in `repo-announcement.ts`.
+     *
+     * @param rev - Consider only roots reachable from this revision. Omit for
+     *   every root in the repository (`--all`).
+     * @returns The roots in `rev-list` order, or `[]` when the revision does not
+     *   resolve — an unborn `HEAD` in a repo with no commits is not an error.
+     */
+    rootCommits(rev?: string): Promise<string[]>;
     /**
      * Resolve a ref/revision to a full SHA via `git rev-parse --verify`.
      * Throws {@link GitError} when the name doesn't resolve.
@@ -192,8 +343,9 @@ declare class GitRepoReader {
  * `rig push` (epic #222, ticket #225).
  *
  * Queries relay(s) over NIP-01 WebSocket for the repository's NIP-34 state:
- *   - kind:30618 (repository state): `r` tags → ref map, `HEAD` symref,
- *     `arweave` tags → git SHA → Arweave txId hints.
+ *   - kind:30618 (repository state): ref tags → ref map (both the NIP-34
+ *     shape and rig's legacy `r` shape — see `./nip34-refs.ts`), `HEAD`
+ *     symref, `arweave` tags → git SHA → Arweave txId hints.
  *   - kind:30617 (repository announcement): presence = the repo exists on
  *     TOON (first-push detection) + name/description/relays metadata.
  *
@@ -231,6 +383,12 @@ interface NostrFilter {
     '#a'?: string[];
     /** Event-reference tag filter (#278 tracker: statuses + comments). */
     '#e'?: string[];
+    /**
+     * NIP-22 UPPERCASE root-scope reference — distinct from `#e` and matched
+     * case-sensitively (#159: kind:1111 comments hang off their thread root's
+     * `E` tag, while `e` names the immediate parent).
+     */
+    '#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). */
@@ -266,8 +424,10 @@ interface FetchRemoteStateOptions {
     timeoutMs?: number;
     /**
      * Git-SHA → Arweave txId resolver used by {@link RemoteState.resolveMissing}.
-     * Defaults to the shared GraphQL resolver from @toon-protocol/arweave;
-     * injectable for tests.
+     * Defaults to the shared GraphQL resolver from @toon-protocol/arweave,
+     * which asks `arweave.net` — so every command that takes a gateway passes
+     * one bound to it instead (`../git-sha-resolver.ts`, #183). Injectable for
+     * tests.
      */
     resolveSha?: (sha: string, repo: string) => Promise<string | null>;
     /** WebSocket constructor override (defaults to the global WebSocket). */
@@ -281,7 +441,12 @@ interface RemoteState {
     refs: Map<string, string>;
     /** HEAD symref target (e.g. `refs/heads/main`), or null if unset. */
     headSymref: string | null;
-    /** Git SHA → Arweave txId hints from the latest kind:30618 `arweave` tags. */
+    /**
+     * Git SHA → Arweave txId hints from the latest kind:30618 `arweave` tags,
+     * capped at `MAX_ARWEAVE_TAGS_PER_EVENT` (#162). A HINT MAP, not an index:
+     * a SHA missing from it is resolved via {@link RemoteState.resolveMissing},
+     * never assumed absent from Arweave.
+     */
     shaToTxId: Map<string, string>;
     /** The latest kind:30618 event, or null if the repo has no state yet. */
     refsEvent: NostrEvent | null;
@@ -594,6 +759,14 @@ declare function ownerToHex(owner: string): string;
  * `r` tags are the full new ref state. On a first push it publishes the
  * kind:30617 announcement before the refs event.
  *
+ * That merge is bounded at `MAX_ARWEAVE_TAGS_PER_EVENT` (#162): an unbounded
+ * map eventually produces an event relays reject. Over the cap, entries are
+ * kept in priority order (this push's objects, then objects reachable from
+ * the new tips newest-first); under it, the published map is byte-identical
+ * to what earlier releases published. A dropped entry is a cache miss, never
+ * a lost object — it is still on Arweave under its `Git-SHA` / `Repo` tags
+ * and still resolves through the GraphQL resolver.
+ *
  * Resume safety: uploads are content-addressed (Git-SHA-tagged), so re-running
  * `executePush` after a crash is safe — it consults the merged
  * remote + planned sha→txId map before paying for any upload, and a re-plan
@@ -731,10 +904,18 @@ interface PushPlan {
     knownShaToTxId: Map<string, string>;
     /** True when no kind:30617 exists yet — executePush announces first. */
     announceNeeded: boolean;
-    /** Announcement metadata used when {@link announceNeeded}. */
+    /**
+     * Announcement metadata used when {@link announceNeeded}. `web` and
+     * `earliestUniqueCommit` are the NIP-34 conformance tags (#158); the
+     * `relays` tag comes from the relay list `executePush` publishes to.
+     */
     announcement: {
         name: string;
         description: string;
+        /** The repo's rig-web viewer URL (`repoWebUrl`), when one is known. */
+        web?: string;
+        /** The repo's `["r", "<sha>", "euc"]` fork identity, from local git. */
+        earliestUniqueCommit?: string;
     };
     estimate: PushFeeEstimate;
 }
@@ -753,10 +934,15 @@ interface PlanPushOptions {
     refs?: string[];
     /** Allow non-fast-forward updates (default false → hard error). */
     force?: boolean;
-    /** Repo name/description for the first-push announcement. */
+    /**
+     * Repo metadata for the first-push announcement. `web` is the repo's
+     * rig-web viewer URL (`repoWebUrl` — the CLI supplies it once a relay is
+     * resolved); the `euc` is computed here from `repoReader`.
+     */
     announcement?: {
         name?: string;
         description?: string;
+        web?: string;
     };
     /**
      * Async resolver for SHAs the remote's `arweave` tags don't cover —
@@ -790,8 +976,11 @@ interface PushResult {
     /** kind:30618 (cumulative refs + arweave map) receipt. */
     refsReceipt: PublishReceipt;
     /**
-     * The full sha→txId map published in the refs event: remote hints +
-     * resolver finds + this push's uploads.
+     * The sha→txId map actually published in the refs event: remote hints +
+     * resolver finds + this push's uploads, bounded to
+     * `MAX_ARWEAVE_TAGS_PER_EVENT` in priority order (#162). Entries dropped by
+     * the cap are still on Arweave and still resolve through the GraphQL
+     * `Git-SHA` resolver.
      */
     arweaveMap: Map<string, string>;
     /** Total fees actually paid (uploads + events), smallest asset unit. */
@@ -865,10 +1054,15 @@ interface GitEstimateRequest {
      * (forward-compat); defaults to the daemon's config-seeded relay.
      */
     relayUrls?: string[];
-    /** Repo name/description for the first-push kind:30617 announcement. */
+    /**
+     * Repo metadata for the first-push kind:30617 announcement. `web` is the
+     * repo's rig-web viewer URL for the NIP-34 `web` tag (#158); a daemon that
+     * predates it simply ignores the field.
+     */
     announcement?: {
         name?: string;
         description?: string;
+        web?: string;
     };
 }
 /** Pre-push fee table (all fees in base/micro units, decimal strings). */
@@ -903,9 +1097,16 @@ interface GitEstimateResponse {
     knownShaToTxId: Record<string, string>;
     /** True when no kind:30617 exists yet — the push announces first. */
     announceNeeded: boolean;
+    /**
+     * What the first announcement will carry. `web` and `earliestUniqueCommit`
+     * are the NIP-34 conformance tags (#158) and are absent when the planner
+     * could not derive them (no relay resolved, or a repo with no commits).
+     */
     announcement: {
         name: string;
         description: string;
+        web?: string;
+        earliestUniqueCommit?: string;
     };
     estimate: GitFeeEstimate;
 }
@@ -964,20 +1165,32 @@ interface GitIssueRequest {
     /** Labels (`t` tags). */
     labels?: string[];
 }
-/** `POST /git/comment` — publish a kind:1622 comment on an issue/patch. PAID. */
+/**
+ * `POST /git/comment` — publish a NIP-22 kind:1111 comment on an issue or
+ * patch. PAID.
+ *
+ * The root is the issue/patch being discussed, NEVER the repository: it
+ * becomes the comment's uppercase `E`/`K`/`P` scope. `parentComment` makes
+ * the comment a nested reply (lowercase `e`/`k`/`p`, `k` = 1111); omitted,
+ * the parent is the root itself. Legacy kind:1622 is never published (#159).
+ */
 interface GitCommentRequest {
     repoAddr: GitRepoAddr;
-    /** Event id of the issue or patch being commented on. */
+    /** Event id of the issue or patch the thread hangs off (uppercase `E`). */
     rootEventId: string;
+    /** Kind of that root event, e.g. 1621 or 1617 (uppercase `K`). */
+    rootKind: number;
+    /** Pubkey of the root event's author (uppercase `P`). */
+    rootAuthorPubkey: string;
     /** Comment body (Markdown content). */
     body: string;
-    /**
-     * Pubkey of the TARGET event's author (NIP-34 `p` threading tag — not the
-     * comment author). Defaults to the repo owner.
-     */
-    parentAuthorPubkey?: string;
-    /** `e`-tag marker (default 'root': commenting directly on the issue/patch). */
-    marker?: 'root' | 'reply';
+    /** The kind:1111 comment being replied to — omit for a top-level comment. */
+    parentComment?: {
+        /** Event id of that comment (lowercase `e`). */
+        eventId: string;
+        /** Pubkey of its author (lowercase `p`). */
+        authorPubkey: string;
+    };
 }
 /**
  * `POST /git/patch` — publish a kind:1617 patch. Supply EXACTLY ONE of
@@ -1463,6 +1676,13 @@ 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;
+/**
+ * rig's NIP-C1 EXTENSION kind (ADR-0002, docs/specs/nip-c1-live-log-tail.md):
+ * the live log tail of a run in flight. Not in the vendored spec — the number
+ * is rig's choice, offered upstream to ngit-ci, and renumbering it is a deploy
+ * rather than a migration because the event holds no durable data.
+ */
+declare const CI_LIVE_LOG_TAIL_KIND = 39841;
 /** The one runner family rig supports (`W` tag / `R` prefix). */
 declare const CI_RUNNER_FAMILY = "act";
 /** The `software` tag name rig advertises under. */
@@ -1470,6 +1690,35 @@ 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;
+/** The same NIP-40 bound on a Live Log Tail (seconds). */
+declare const CI_MAX_LIVE_LOG_TAIL_TTL: number;
+/**
+ * How often a run in flight republishes its tail. Fixed — a fixed interval is
+ * what makes the worst case budgetable — and expressed in milliseconds because
+ * both consumers (the coordinator's scheduler seam and `estimateRunCost`'s run
+ * timeout) work in milliseconds.
+ */
+declare const CI_LIVE_LOG_TAIL_INTERVAL_MS = 10000;
+/**
+ * Bytes of tail one live job gets by default: deliberately far more than the
+ * 4 KiB that rides in a Job Result, because the relay fee ignores event size
+ * and the difference between one screen and several is the difference between
+ * "is it alive" and "what is it doing".
+ */
+declare const CI_LIVE_LOG_TAIL_JOB_BYTES: number;
+/**
+ * Ceiling on the tail bytes ONE event may carry, so a run with many live jobs
+ * stays relay-safe. Beyond it the budget is divided evenly — see
+ * {@link liveLogTailBudget}.
+ */
+declare const CI_LIVE_LOG_TAIL_MAX_BYTES: number;
+/**
+ * The distinguished key naming the runner channel in a coordinator's per-job
+ * buffers. It is not a job id and can never collide with one (a workflow job id
+ * matches `[A-Za-z_][A-Za-z0-9_-]*`), and it never appears in the wire event's
+ * `jobs` array — the runner channel has its own `runner` slot.
+ */
+declare const CI_RUNNER_CHANNEL_KEY = "~runner";
 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';
@@ -1770,6 +2019,76 @@ interface CiWorkflowProgress {
 }
 declare function buildCiWorkflowProgress(input: CiWorkflowProgressInput, createdAt?: number): UnsignedEvent;
 declare function parseCiWorkflowProgress(ev: NostrEvent): CiWorkflowProgress | null;
+/** One unfinished job's recent output. */
+interface CiLiveLogTailJob {
+    /** Job id as declared in the workflow file. */
+    job: string;
+    /** The most recent output, sliced from the END of the redacted log. */
+    tail: string;
+    /** Bytes of that job's output preceding `tail`. */
+    omitted: number;
+}
+/** The runner channel: the runner's own account of the run, never a job. */
+interface CiLiveLogTailChannel {
+    tail: string;
+    omitted: number;
+}
+interface CiLiveLogTailInput {
+    trigger: CiTriggerContext;
+    /** The run's Workflow Progress `d`. */
+    runId: string;
+    /** Every unfinished job; a job drops out once its Job Result is published. */
+    jobs: CiLiveLogTailJob[];
+    runner?: CiLiveLogTailChannel;
+    /** NIP-40 expiration: > created_at, ≤ created_at + 30 min. */
+    expiresAt: number;
+}
+interface CiLiveLogTail {
+    eventId: string;
+    pubkey: string;
+    createdAt: number;
+    trigger: CiTriggerContext;
+    runId: string;
+    jobs: CiLiveLogTailJob[];
+    runner?: CiLiveLogTailChannel;
+    expiresAt: number;
+}
+/**
+ * Bytes of tail each live entry gets when `entries` of them share one event:
+ * the per-job default until that many entries would breach the per-event
+ * ceiling, then the ceiling divided evenly. Entries are unfinished jobs PLUS
+ * the runner channel when it has output — everything that occupies bytes in
+ * the event.
+ */
+declare function liveLogTailBudget(entries: number): number;
+/**
+ * Worst-case number of Live Log Tail events a run of at most `runTimeoutMs`
+ * can publish: one per cadence tick plus the closing replacement. This is what
+ * the coordinator must be able to afford BEFORE it starts the run — there is
+ * no best-effort mode, because a stream that silently stops is
+ * indistinguishable to a viewer from a stalled job.
+ */
+declare function liveLogTailEventBudget(runTimeoutMs: number): number;
+/**
+ * Take the last `maxBytes` UTF-8 bytes of `text`, reporting how many bytes
+ * precede them. The slice never splits a multi-byte character, and `omitted`
+ * counts BYTES (what a reader comparing against the job log's size needs), not
+ * characters. Callers slice REDACTED output — never the reverse (ADR-0002).
+ */
+declare function sliceLogTail(text: string, maxBytes: number): {
+    tail: string;
+    omitted: number;
+};
+declare function buildCiLiveLogTail(input: CiLiveLogTailInput, createdAt?: number): UnsignedEvent;
+/**
+ * Parse a Live Log Tail. Unknown fields — anywhere in the content, and unknown
+ * tags — are ignored, so a later rig may add to the shape without breaking a
+ * client; anything the shape does NOT allow (bad JSON, a jobs entry without a
+ * job id, a duplicated job, a runner channel smuggled in as a job, an
+ * expiration beyond the 30-minute bound) is `null` rather than a throw or a
+ * half-populated result.
+ */
+declare function parseCiLiveLogTail(ev: NostrEvent): CiLiveLogTail | null;
 
 /**
  * Repository Secret Update payloads (rig#125): the NIP-44 v2 ciphertext a
@@ -1961,7 +2280,12 @@ interface RunnerRequest {
     env?: Record<string, string>;
     /** Wall-clock budget for the whole run; exceeding it concludes `timed_out`. */
     timeoutMs: number;
-    /** Streaming log sink (per job). */
+    /**
+     * Streaming log sink, called with a job id as output is produced. Output
+     * the runner attributes to no job — its own account of executing the run —
+     * goes to the RUNNER CHANNEL: the reserved key `CI_RUNNER_CHANNEL_KEY`
+     * exported by ./nip-c1-events.ts, which no workflow job id can equal.
+     */
     onLog?: (jobId: string, chunk: string) => void;
     /** Cancels the run (concludes `cancelled`). */
     signal?: AbortSignal;
@@ -2177,4 +2501,135 @@ declare function assembleCiStatus(opts: AssembleStatusOptions): {
     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 };
+/**
+ * Real wire capture from wss://relay.ngit.dev (2026-09-17T16:00:01Z).
+ *
+ * A kind:30617 repository announcement for ngit's `wyrd` repo. It carries a
+ * `clone` tag and the unmerged role tags from nips PR #2324 (`M` — lead
+ * maintainer, `m` — maintainer), alongside the conformant `relays`, `web`
+ * and `["r", <sha>, "euc"]` earliest-unique-commit tags described in
+ * rig#153's Implementation Decisions. Committed byte-for-byte as received —
+ * no edited tags, no re-serialization — so its id and signature verify (see
+ * `ngit-fixtures.test.ts`).
+ *
+ * No live event combining `M`, `m` AND `o` together with `clone` was found
+ * on relay.ngit.dev at capture time (a relay-wide scan of 597 kind:30617
+ * events found exactly one `o`-tagged announcement, and it carried no `M`).
+ * This fixture is the richest real combination available: `M` + `m` + `clone`.
+ *
+ * Captured with `scripts/capture-ngit-fixtures.mjs` (repo root); see that
+ * file for the exact filter and how to re-run the capture.
+ */
+
+declare const NGIT_ANNOUNCEMENT_WYRD_RELAY = "wss://relay.ngit.dev";
+declare const NGIT_ANNOUNCEMENT_WYRD_CAPTURED_AT = "2026-09-17T16:00:01Z";
+declare const NGIT_ANNOUNCEMENT_WYRD_EVENT_ID = "5df470edc9067955e707def26b57dbf3c61920ede9c6792ab592d435729192b0";
+/** kind:30617 announcement for `wyrd`, as served by relay.ngit.dev. */
+declare const NGIT_ANNOUNCEMENT_WYRD: NostrEvent;
+
+/**
+ * Real wire capture from wss://relay.ngit.dev (2026-09-17T16:00:01Z).
+ *
+ * The kind:30618 repository state event for ngit's own `ngit` repo
+ * (author a008def15796fba9a0d6fab04e8fd57089285d9fd505da5a83fe8aad57a3564d,
+ * npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr — the
+ * canonical repo ngit's cli/git plugin ships from). It carries `HEAD` and
+ * NIP-34 ref-shape tags for `refs/heads/*` and `refs/tags/*`, INCLUDING
+ * peeled `^{}` entries for annotated tags (e.g. `refs/tags/v3.0.0^{}`) —
+ * exactly the shape rig#153's dual-read work must parse without treating
+ * peeled entries as ordinary refs. Committed byte-for-byte as received — no
+ * edited tags, no re-serialization, tag order preserved — so its id and
+ * signature verify (see `ngit-fixtures.test.ts`).
+ *
+ * Captured with `scripts/capture-ngit-fixtures.mjs` (repo root); see that
+ * file for the exact filter and how to re-run the capture.
+ */
+
+declare const NGIT_STATE_NGIT_RELAY = "wss://relay.ngit.dev";
+declare const NGIT_STATE_NGIT_CAPTURED_AT = "2026-09-17T16:00:01Z";
+declare const NGIT_STATE_NGIT_EVENT_ID = "17fdde63cbc0289e933e6ed232e354cce6713d89e10a793f6d6f9d8ad274ee14";
+/** kind:30618 repository state for ngit's own `ngit` repo. */
+declare const NGIT_STATE_NGIT: NostrEvent;
+
+/**
+ * Real wire capture from wss://relay.ngit.dev (2026-09-17T16:00:01Z).
+ *
+ * A kind:1621 issue on the `HydrusUI` repo (author
+ * 43d7f07d10b9e662745e10b2fc201a74dc178a308c31409350d06b04477816e1) and its
+ * full kind:1111 NIP-22 comment thread: five comments, including one
+ * NESTED reply. Four of the five comments (`e`/`k`/`p`) point straight at
+ * the root issue; `NGIT_COMMENT_THREAD_NESTED_REPLY` instead points its
+ * lowercase `e`/`k`/`p` at another comment
+ * (`NGIT_COMMENT_THREAD_NESTED_REPLY_PARENT_ID`), while its uppercase
+ * `E`/`K`/`P` still name the root issue — the shape rig#153's comment
+ * builder and readers must produce and accept. Committed byte-for-byte as
+ * received — no edited tags, no re-serialization, tag order preserved — so
+ * every event's id and signature verify (see `ngit-fixtures.test.ts`).
+ *
+ * Captured with `scripts/capture-ngit-fixtures.mjs` (repo root); see that
+ * file for the exact filter and how to re-run the capture.
+ */
+
+declare const NGIT_COMMENT_THREAD_RELAY = "wss://relay.ngit.dev";
+declare const NGIT_COMMENT_THREAD_CAPTURED_AT = "2026-09-17T16:00:01Z";
+declare const NGIT_COMMENT_THREAD_ROOT_EVENT_ID = "3bb49002757fe697f328a2825fdd00f48a8c376238db65b18906d52864692e2a";
+declare const NGIT_COMMENT_THREAD_COMMENT_EVENT_IDS: string[];
+/** The one comment in the thread whose parent is another comment, not the root issue. */
+declare const NGIT_COMMENT_THREAD_NESTED_REPLY_ID = "952c1fe0a2e88c3c716b56aa2f695349a77220a211779de30e97b115ba94e084";
+declare const NGIT_COMMENT_THREAD_NESTED_REPLY_PARENT_ID = "6f815f058c6f627eab6f5324f06cda29163e0232f410abf8eff22de250e188c1";
+/** kind:1621 issue "Bug: Thumbnail Healing / Transfer" on HydrusUI. */
+declare const NGIT_COMMENT_THREAD_ROOT: NostrEvent;
+/** All five kind:1111 comments on the thread, oldest first. */
+declare const NGIT_COMMENT_THREAD_COMMENTS: NostrEvent[];
+
+/**
+ * Real wire capture from wss://relay.ngit.dev (2026-09-17T16:00:01Z).
+ *
+ * A kind:1631 ("applied"/merged) status event on ngit's own `ngit` repo, in
+ * NIP-10 marker form: `["e", <target-id>, "", "root"]` plus the repo's `a`
+ * coordinate tag — exactly the shape rig#153's status builder must produce
+ * and its readers must resolve, instead of today's bare `["e", <id>]`. Its
+ * target, {@link NGIT_STATUS_NGIT_TARGET}, is the kind:1618 pull request the
+ * status applies to (a `branch-name` tag rides along on it, relevant to a
+ * neighbouring rig#153 ticket). Committed byte-for-byte as received — no
+ * edited tags, no re-serialization, tag order preserved — so both events'
+ * ids and signatures verify (see `ngit-fixtures.test.ts`).
+ *
+ * Captured with `scripts/capture-ngit-fixtures.mjs` (repo root); see that
+ * file for the exact filter and how to re-run the capture.
+ */
+
+declare const NGIT_STATUS_NGIT_RELAY = "wss://relay.ngit.dev";
+declare const NGIT_STATUS_NGIT_CAPTURED_AT = "2026-09-17T16:00:01Z";
+declare const NGIT_STATUS_NGIT_EVENT_ID = "7fa92c2970493b77974848db0c225e0c37fb6694eabed67387224a4711093b2f";
+declare const NGIT_STATUS_NGIT_TARGET_EVENT_ID = "fabe42e7c41d4e43e3dcc78db20c3859a7696eb6bc655aed852741e074951c48";
+/** kind:1631 status ("applied") in NIP-10 marker form, targeting the PR below. */
+declare const NGIT_STATUS_NGIT: NostrEvent;
+/** kind:1618 pull request that {@link NGIT_STATUS_NGIT} targets. */
+declare const NGIT_STATUS_NGIT_TARGET: NostrEvent;
+
+/**
+ * Real NIP-34 wire fixtures captured from `wss://relay.ngit.dev` (rig#155,
+ * spec rig#153). Conformance is tested against what the incumbent (ngit)
+ * actually publishes, not against our reading of the NIP.
+ *
+ * Every event here is committed exactly as the relay sent it — no edited
+ * tags, no re-serialization — so `ngit-fixtures.test.ts` can verify each
+ * one's id and signature. `@toon-protocol/rig` imports these fixtures from
+ * this module and re-exports them from its package index.
+ * `@toon-protocol/rig-web` tests use a self-contained COPY of this same
+ * captured data instead of importing this package directly
+ * (`packages/rig-web/src/web/__fixtures__/ngit-wire.ts`) — rig-web's
+ * typecheck gate runs before `@toon-protocol/rig` is built, so an import
+ * resolved through its built `dist/` would fail there even though it can
+ * look fine locally with a stale `dist/`. See that file's header for the
+ * full rationale.
+ *
+ * Re-capture with `scripts/capture-ngit-fixtures.mjs` (repo root); update
+ * BOTH this package's fixtures and rig-web's copy from the same capture.
+ */
+
+/** Every captured event, flattened — for the id/signature verification test. */
+declare const ALL_NGIT_FIXTURE_EVENTS: NostrEvent[];
+
+export { ALL_NGIT_FIXTURE_EVENTS, type AnnouncementEdits, type BuildIncrementOfferOptions, type BuildNarrationOptions, type BuildResultEventOptions, CI_ADVERTISEMENT_KIND, CI_JOB_RESULT_KIND, CI_LIVE_LOG_TAIL_INTERVAL_MS, CI_LIVE_LOG_TAIL_JOB_BYTES, CI_LIVE_LOG_TAIL_KIND, CI_LIVE_LOG_TAIL_MAX_BYTES, CI_MANUAL_TRIGGER_KIND, CI_MAX_ADVERTISEMENT_TTL, CI_MAX_LIVE_LOG_TAIL_TTL, CI_MAX_PROGRESS_TTL, CI_RUNNER_CHANNEL_KEY, 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 CiLiveLogTail, type CiLiveLogTailChannel, type CiLiveLogTailInput, type CiLiveLogTailJob, 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, EARLIEST_UNIQUE_COMMIT_MARKER, type EncryptedArtifact, type EncryptedArtifactRef, type ExecuteFactoryJobOptions, type ExecutePushOptions, type ExistingAnnouncement, 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, NGIT_ANNOUNCEMENT_WYRD, NGIT_ANNOUNCEMENT_WYRD_CAPTURED_AT, NGIT_ANNOUNCEMENT_WYRD_EVENT_ID, NGIT_ANNOUNCEMENT_WYRD_RELAY, NGIT_COMMENT_THREAD_CAPTURED_AT, NGIT_COMMENT_THREAD_COMMENTS, NGIT_COMMENT_THREAD_COMMENT_EVENT_IDS, NGIT_COMMENT_THREAD_NESTED_REPLY_ID, NGIT_COMMENT_THREAD_NESTED_REPLY_PARENT_ID, NGIT_COMMENT_THREAD_RELAY, NGIT_COMMENT_THREAD_ROOT, NGIT_COMMENT_THREAD_ROOT_EVENT_ID, NGIT_STATE_NGIT, NGIT_STATE_NGIT_CAPTURED_AT, NGIT_STATE_NGIT_EVENT_ID, NGIT_STATE_NGIT_RELAY, NGIT_STATUS_NGIT, NGIT_STATUS_NGIT_CAPTURED_AT, NGIT_STATUS_NGIT_EVENT_ID, NGIT_STATUS_NGIT_RELAY, NGIT_STATUS_NGIT_TARGET, NGIT_STATUS_NGIT_TARGET_EVENT_ID, 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, RELAYS_TAG, 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, WEB_TAG, WORKFLOW_DIRS, type WebSocketFactory, type WebSocketLike, type WorkflowJob, type WorkflowTriggers, amendRepoAnnouncement, applySecretUpdate, assembleCiStatus, assertSecretUpdateShape, buildCiAdvertisement, buildCiJobResult, buildCiLiveLogTail, buildCiManualTrigger, buildCiSecretUpdate, buildCiServiceRequest, buildCiServiceStop, buildCiWorkflowProgress, buildCiWorkflowResult, buildIncrementOfferEvent, buildNarrationEvent, buildQuoteEvent, buildRepoAnnouncement, buildResultEvent, collectRepoObjects, commonTriggerTags, controlOrder, decryptSecretUpdate, defaultFakeRunResult, deriveTrustLevel, discoverWorkflows, downloadGitObjects, effectiveSecrets, encryptSecretUpdate, executeFactoryJob, executePush, fetchRemoteState, fetchTxBytes, gatePassed, generateSecretsKey, hexToNpub, isCiConclusion, isCiTrustLevel, isSafeRefname, liveLogTailBudget, liveLogTailEventBudget, matchesPullRequest, matchesPush, missingObjectsMessage, npubToHex, ownerToHex, parseCiAdvertisement, parseCiJobResult, parseCiLiveLogTail, parseCiManualTrigger, parseCiSecretUpdate, parseCiServiceControl, parseCiTriggerContext, parseCiWorkflowProgress, parseCiWorkflowResult, parseFactoryJobRequest, parseRepoAddress, parseWorkflow, planFactoryJob, planPush, queryRelay, refMatchesPatterns, referencedShas, repoAddress, selectServiceRequests, serializeEventReceipt, serializeFeeEstimate, serializePushPlan, serializePushResult, setHeadSymref, sha256Hex, sliceLogTail, trustAtLeast, updateRef, validateSecretUpdate, verifyObjectBody, walkClosure, writeGitObject, writeGitObjects };