@agent-arc-status/reference 0.3.0

package/dist/parse.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Parsing helpers for arc.status events.
+ *
+ * These wrap `JSON.parse` with structural validation. They never throw on
+ * malformed input; they return a `ValidationResult`.
+ */
+import { type ValidationResult } from "./validate.js";
+/**
+ * Parse a single JSON string or buffer into a validated event.
+ */
+export declare function parse(input: string | Buffer): ValidationResult;
+export interface JsonlParseResult {
+    /** Validated events in order of appearance. */
+    events: import("./types.js").ArcStatusEvent[];
+    /** Per-line errors keyed by 0-indexed line number. */
+    errors: Array<{
+        line: number;
+        issues: import("./validate.js").ValidationIssue[];
+    }>;
+}
+/**
+ * Parse a JSON Lines stream of events. Empty lines are skipped.
+ *
+ * Does not throw. Lines that fail to parse or validate are reported in
+ * `errors`; valid lines are returned in `events`. Callers decide whether
+ * to treat any error as fatal.
+ */
+export declare function parseJsonl(input: string | Buffer): JsonlParseResult;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAY,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEhE;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,gBAAgB,CAmB9D;AAED,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,MAAM,EAAE,OAAO,YAAY,EAAE,cAAc,EAAE,CAAC;IAC9C,sDAAsD;IACtD,MAAM,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,OAAO,eAAe,EAAE,eAAe,EAAE,CAAC;KACnD,CAAC,CAAC;CACJ;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,gBAAgB,CAmBnE"}

package/dist/parse.js

@@ -0,0 +1,56 @@
+/**
+ * Parsing helpers for arc.status events.
+ *
+ * These wrap `JSON.parse` with structural validation. They never throw on
+ * malformed input; they return a `ValidationResult`.
+ */
+import { validate } from "./validate.js";
+/**
+ * Parse a single JSON string or buffer into a validated event.
+ */
+export function parse(input) {
+    const text = typeof input === "string" ? input : input.toString("utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            issues: [
+                {
+                    path: "",
+                    message: `not valid JSON: ${err.message}`,
+                },
+            ],
+        };
+    }
+    return validate(parsed);
+}
+/**
+ * Parse a JSON Lines stream of events. Empty lines are skipped.
+ *
+ * Does not throw. Lines that fail to parse or validate are reported in
+ * `errors`; valid lines are returned in `events`. Callers decide whether
+ * to treat any error as fatal.
+ */
+export function parseJsonl(input) {
+    const text = typeof input === "string" ? input : input.toString("utf8");
+    const lines = text.split(/\r?\n/);
+    const events = [];
+    const errors = [];
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        if (raw === undefined || raw.trim() === "")
+            continue;
+        const result = parse(raw);
+        if (result.ok) {
+            events.push(result.event);
+        }
+        else {
+            errors.push({ line: i, issues: result.issues });
+        }
+    }
+    return { events, errors };
+}
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAyB,MAAM,eAAe,CAAC;AAEhE;;GAEG;AACH,MAAM,UAAU,KAAK,CAAC,KAAsB;IAC1C,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAExE,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE;gBACN;oBACE,IAAI,EAAE,EAAE;oBACR,OAAO,EAAE,mBAAoB,GAAa,CAAC,OAAO,EAAE;iBACrD;aACF;SACF,CAAC;IACJ,CAAC;IAED,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC1B,CAAC;AAYD;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC/C,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAElC,MAAM,MAAM,GAA0C,EAAE,CAAC;IACzD,MAAM,MAAM,GAA+B,EAAE,CAAC;IAE9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACrB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,SAAS;QACrD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC"}

package/dist/render.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Renderers turn arc.status events into human-facing strings for a given
+ * surface (terminal, Slack, Telegram, etc.).
+ *
+ * Rendering is intentionally a consumer concern (see spec §1.3 design
+ * principle 5: "Receiver renders"). These helpers are provided so common
+ * cases work in one line; complex surfaces should write their own.
+ */
+import type { ArcStatusEvent } from "./types.js";
+export interface RenderOptions {
+    /** Include a leading symbol per phase. Default: true. */
+    symbol?: boolean;
+    /** Include the phase label in CAPS. Default: false. */
+    phaseLabel?: boolean;
+    /** Include `step/total` if both are present on the event. Default: true. */
+    step?: boolean;
+    /** Include `eta_minutes` if present. Default: true. */
+    eta?: boolean;
+    /** Append the body, if present. Default: false. */
+    body?: boolean;
+    /** Truncate the body to N characters when included. Default: 240. */
+    bodyMax?: number;
+}
+/**
+ * Render an event to a single human-readable line, with optional body block.
+ *
+ * Examples:
+ *   "▶ build Pulsefeed v0.1"
+ *   "✓ [6/11] receiver booted (ETA 25m)"
+ *   "· still working: hyperparameter sweep (run 4/12)"
+ *   "■ v0.1 complete, 43 tests, deployed"
+ *   "⛔ need finance sign-off on plan-B reclassification"
+ */
+export declare function render(event: ArcStatusEvent, options?: RenderOptions): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,YAAY,CAAC;AAkBjE,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uDAAuD;IACvD,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,mDAAmD;IACnD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAuC7E"}

package/dist/render.js

@@ -0,0 +1,83 @@
+/**
+ * Renderers turn arc.status events into human-facing strings for a given
+ * surface (terminal, Slack, Telegram, etc.).
+ *
+ * Rendering is intentionally a consumer concern (see spec §1.3 design
+ * principle 5: "Receiver renders"). These helpers are provided so common
+ * cases work in one line; complex surfaces should write their own.
+ */
+const PHASE_SYMBOLS = {
+    started: "▶",
+    milestone: "✓",
+    heartbeat: "·",
+    done: "■",
+    blocked: "⛔",
+};
+const PHASE_LABELS = {
+    started: "STARTED",
+    milestone: "MILESTONE",
+    heartbeat: "HEARTBEAT",
+    done: "DONE",
+    blocked: "BLOCKED",
+};
+const DEFAULTS = {
+    symbol: true,
+    phaseLabel: false,
+    step: true,
+    eta: true,
+    body: false,
+    bodyMax: 240,
+};
+/**
+ * Render an event to a single human-readable line, with optional body block.
+ *
+ * Examples:
+ *   "▶ build Pulsefeed v0.1"
+ *   "✓ [6/11] receiver booted (ETA 25m)"
+ *   "· still working: hyperparameter sweep (run 4/12)"
+ *   "■ v0.1 complete, 43 tests, deployed"
+ *   "⛔ need finance sign-off on plan-B reclassification"
+ */
+export function render(event, options) {
+    const opts = { ...DEFAULTS, ...options };
+    const parts = [];
+    if (opts.symbol) {
+        parts.push(PHASE_SYMBOLS[event.phase]);
+    }
+    if (opts.phaseLabel) {
+        parts.push(PHASE_LABELS[event.phase]);
+    }
+    if (opts.step &&
+        typeof event.step === "number" &&
+        typeof event.total === "number") {
+        parts.push(`[${event.step}/${event.total}]`);
+    }
+    parts.push(event.title);
+    if (opts.eta && typeof event.eta_minutes === "number") {
+        parts.push(`(ETA ${formatMinutes(event.eta_minutes)})`);
+    }
+    let line = parts.join(" ");
+    if (opts.body && event.body) {
+        const max = Math.max(1, opts.bodyMax);
+        const body = event.body.length > max
+            ? event.body.slice(0, max - 1) + "…"
+            : event.body;
+        line += "\n" + body;
+    }
+    return line;
+}
+function formatMinutes(minutes) {
+    if (minutes < 1)
+        return "<1m";
+    // Round to whole minutes first, then split into h/m, so a value like 119.6
+    // becomes 2h rather than the malformed "1h60m".
+    const total = Math.round(minutes);
+    if (total < 60)
+        return `${total}m`;
+    const h = Math.floor(total / 60);
+    const m = total - h * 60;
+    if (m === 0)
+        return `${h}h`;
+    return `${h}h${m}m`;
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}

package/dist/state.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Fold an ordered event stream into the current state of an arc: the cheap
+ * "what is true now?" reduction that design-rationale.md promises the reference
+ * implementation provides. Append-only events compose with any transport; this
+ * reconstructs current state for consumers that want a snapshot rather than a
+ * timeline. Pure, zero dependencies.
+ */
+import type { ArcStatusEvent, ArcStatusPhase } from "./types.js";
+export interface ArcMilestone {
+    title: string;
+    sent_at: string;
+    step?: number;
+    total?: number;
+}
+export interface ArcState {
+    arc_id: string;
+    /** Objective, taken from the `started` event (falls back to the first event). */
+    title: string;
+    /** Phase of the most recent event. */
+    phase: ArcStatusPhase;
+    /** Derived lifecycle status. `blocked` clears once a later non-blocked event arrives. */
+    status: "active" | "blocked" | "done";
+    /** Latest `step`/`total`/`eta_minutes` seen on any event, if present. */
+    step?: number;
+    total?: number;
+    eta_minutes?: number;
+    startedAt: string;
+    lastEventAt: string;
+    eventCount: number;
+    milestones: ArcMilestone[];
+    /** The current blocker if the most recent event is `blocked`, else null. */
+    blocked: {
+        title: string;
+        body?: string;
+        sent_at: string;
+    } | null;
+}
+/**
+ * Reduce an ordered sequence of events for a single arc into current state.
+ * Returns null for an empty sequence. Does not validate the sequence; pass a
+ * sequence you trust (or run `validateSequence` first).
+ */
+export declare function reduceArc(events: ArcStatusEvent[]): ArcState | null;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,KAAK,EAAE,cAAc,CAAC;IACtB,yFAAyF;IACzF,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IACtC,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACnE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,QAAQ,GAAG,IAAI,CAoDnE"}

package/dist/state.js

@@ -0,0 +1,62 @@
+/**
+ * Fold an ordered event stream into the current state of an arc: the cheap
+ * "what is true now?" reduction that design-rationale.md promises the reference
+ * implementation provides. Append-only events compose with any transport; this
+ * reconstructs current state for consumers that want a snapshot rather than a
+ * timeline. Pure, zero dependencies.
+ */
+/**
+ * Reduce an ordered sequence of events for a single arc into current state.
+ * Returns null for an empty sequence. Does not validate the sequence; pass a
+ * sequence you trust (or run `validateSequence` first).
+ */
+export function reduceArc(events) {
+    if (events.length === 0)
+        return null;
+    const first = events[0];
+    const last = events[events.length - 1];
+    const started = events.find((e) => e.phase === "started");
+    const milestones = [];
+    let step;
+    let total;
+    let eta_minutes;
+    for (const e of events) {
+        if (e.phase === "milestone") {
+            milestones.push({
+                title: e.title,
+                sent_at: e.sent_at,
+                step: e.step,
+                total: e.total,
+            });
+        }
+        if (typeof e.step === "number")
+            step = e.step;
+        if (typeof e.total === "number")
+            total = e.total;
+        if (typeof e.eta_minutes === "number")
+            eta_minutes = e.eta_minutes;
+    }
+    const status = last.phase === "done"
+        ? "done"
+        : last.phase === "blocked"
+            ? "blocked"
+            : "active";
+    const blocked = last.phase === "blocked"
+        ? { title: last.title, body: last.body, sent_at: last.sent_at }
+        : null;
+    return {
+        arc_id: first.arc_id,
+        title: started?.title ?? first.title,
+        phase: last.phase,
+        status,
+        step,
+        total,
+        eta_minutes,
+        startedAt: started?.sent_at ?? first.sent_at,
+        lastEventAt: last.sent_at,
+        eventCount: events.length,
+        milestones,
+        blocked,
+    };
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA+BH;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,MAAwB;IAChD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAErC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;IACzB,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;IACxC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;IAE1D,MAAM,UAAU,GAAmB,EAAE,CAAC;IACtC,IAAI,IAAwB,CAAC;IAC7B,IAAI,KAAyB,CAAC;IAC9B,IAAI,WAA+B,CAAC;IAEpC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAC5B,UAAU,CAAC,IAAI,CAAC;gBACd,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,KAAK,EAAE,CAAC,CAAC,KAAK;aACf,CAAC,CAAC;QACL,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;YAAE,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;QAC9C,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;YAAE,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QACjD,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ;YAAE,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC;IACrE,CAAC;IAED,MAAM,MAAM,GACV,IAAI,CAAC,KAAK,KAAK,MAAM;QACnB,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS;YACxB,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,QAAQ,CAAC;IAEjB,MAAM,OAAO,GACX,IAAI,CAAC,KAAK,KAAK,SAAS;QACtB,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE;QAC/D,CAAC,CAAC,IAAI,CAAC;IAEX,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,CAAC,KAAK;QACpC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM;QACN,IAAI;QACJ,KAAK;QACL,WAAW;QACX,SAAS,EAAE,OAAO,EAAE,OAAO,IAAI,KAAK,CAAC,OAAO;QAC5C,WAAW,EAAE,IAAI,CAAC,OAAO;QACzB,UAAU,EAAE,MAAM,CAAC,MAAM;QACzB,UAAU;QACV,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Agent Arc Status Protocol v0.2: TypeScript types.
+ *
+ * These mirror the JSON Schema in `spec/schema.json`. They are the
+ * authoritative type-level representation of a conformant event.
+ */
+export declare const ARC_STATUS_PHASES: readonly ["started", "milestone", "heartbeat", "done", "blocked"];
+export type ArcStatusPhase = (typeof ARC_STATUS_PHASES)[number];
+export interface ArcStatusEvent {
+    /** Stable identifier for the arc. All events in one arc share this value. */
+    arc_id: string;
+    /** Lifecycle position of the arc at the moment of emission. */
+    phase: ArcStatusPhase;
+    /** Short human-readable label for this event. */
+    title: string;
+    /** Longer freeform body, optionally containing markdown. */
+    body?: string;
+    /** 1-indexed step number within a sequenced arc. */
+    step?: number;
+    /** Total number of steps in a sequenced arc. */
+    total?: number;
+    /** Emitter's current estimate of minutes remaining to done. */
+    eta_minutes?: number;
+    /** UTC timestamp at which the event was generated (RFC 3339). */
+    sent_at: string;
+    /** Optional free-form label naming the kind of work. */
+    arc_kind?: string;
+    /** The Protocol version the emitter targets, e.g. "0.1". */
+    protocol_version?: string;
+    /** Application-specific extensions MUST use the `x_` prefix. */
+    [extension: `x_${string}`]: unknown;
+}
+/**
+ * A sink for arc.status events — the injection point that emitters, transports,
+ * and framework adapters accept so they stay decoupled from any one transport.
+ */
+export type EmitFn = (event: ArcStatusEvent) => void | Promise<void>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,iBAAiB,mEAMpB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,KAAK,EAAE,cAAc,CAAC;IACtB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,CAAC,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * Agent Arc Status Protocol v0.2: TypeScript types.
+ *
+ * These mirror the JSON Schema in `spec/schema.json`. They are the
+ * authoritative type-level representation of a conformant event.
+ */
+export const ARC_STATUS_PHASES = [
+    "started",
+    "milestone",
+    "heartbeat",
+    "done",
+    "blocked",
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,SAAS;IACT,WAAW;IACX,WAAW;IACX,MAAM;IACN,SAAS;CACD,CAAC"}

package/dist/validate.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Runtime validator for arc.status events.
+ *
+ * Mirrors the JSON Schema in `spec/schema.json` but is hand-rolled so the
+ * reference implementation ships with zero runtime dependencies. For users
+ * who want canonical-schema validation, `spec/schema.json` is also published
+ * and works with any standard JSON Schema validator (e.g. ajv).
+ */
+import { type ArcStatusEvent } from "./types.js";
+export interface ValidationIssue {
+    /** Dot-path to the offending field, e.g. "arc_id" or "step". */
+    path: string;
+    /** Human-readable explanation of the failure. */
+    message: string;
+}
+export type ValidationResult = {
+    ok: true;
+    event: ArcStatusEvent;
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+};
+/**
+ * Canonical RFC 3339 grammar for `sent_at`, kept as a string so it can be
+ * shared byte-for-byte with `spec/schema.json`'s `sent_at.pattern`. The
+ * equivalence test asserts the two are identical, preventing future drift.
+ *
+ * It bounds month (01–12), day (01–31), hour (00–23), minute/second (00–59),
+ * and the UTC offset (≤ ±14:00); fractional seconds are optional (1–9 digits).
+ * It rejects leap seconds (`:60`), lowercase `t`/`z`, and the space separator.
+ * Per-month calendar validity (e.g. Feb 30) cannot be expressed portably in a
+ * regex and is enforced by `isValidCalendarDate` below.
+ */
+export declare const RFC3339_PATTERN = "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(\\.\\d{1,9})?(Z|[+-](0\\d|1[0-4]):[0-5]\\d)$";
+/**
+ * Validate a candidate event against the Protocol's wire-format rules.
+ *
+ * This checks structural conformance only: required fields present, types
+ * correct, enums respected, numeric bounds satisfied, timestamp parseable.
+ *
+ * It does NOT validate phase-ordering rules across a sequence of events;
+ * see `validateSequence` for that.
+ */
+export declare function validate(candidate: unknown): ValidationResult;
+export interface SequenceIssue {
+    /** 0-indexed position in the input sequence where the violation was detected. */
+    index: number;
+    message: string;
+}
+export interface SequenceOptions {
+    /**
+     * Treat `events` as an in-flight prefix rather than a complete arc: skip the
+     * requirement (§4.6) that the last event be a terminal (`done` or terminal
+     * `blocked`). Use when validating a live stream that has not finished yet.
+     * Default: false (the sequence is treated as a complete arc).
+     */
+    partial?: boolean;
+    /**
+     * Require `sent_at` to be non-decreasing across the sequence. Off by default:
+     * lossy transports may deliver out of order and §7.5 has consumers reorder by
+     * `sent_at`, so a raw stream is not guaranteed monotonic. Enable only when the
+     * input is known to be in emission order.
+     */
+    checkMonotonicSentAt?: boolean;
+}
+/**
+ * Validate phase-ordering for a sequence of events belonging to a single arc.
+ *
+ * Enforces §4.5–§4.6 of the spec:
+ *   - exactly one `started`, at the beginning
+ *   - the last event is a terminal (`done` or terminal `blocked`), unless
+ *     `options.partial` is set (in-flight prefix)
+ *   - at most one `done`, and no events after it
+ *   - after `blocked`, the next event is `milestone` (resume), `done`, or
+ *     end-of-arc; `started`, `heartbeat`, and a second consecutive `blocked`
+ *     are illegal
+ *   - (optional) `sent_at` is non-decreasing when `checkMonotonicSentAt` is set
+ *
+ * Does NOT re-validate individual events; call `validate` first if needed.
+ */
+export declare function validateSequence(events: ArcStatusEvent[], options?: SequenceOptions): {
+    ok: boolean;
+    issues: SequenceIssue[];
+};
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GACnC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,mIACsG,CAAC;AAsDnI;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,gBAAgB,CAoJ7D;AAED,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,cAAc,EAAE,EACxB,OAAO,GAAE,eAAoB,GAC5B;IACD,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB,CAoHA"}