beadcyte 0.4.0

package/src/web/dep-headings.ts

@@ -0,0 +1,62 @@
+// dep-headings.ts — tense for the drawer's dependency headings.
+//
+// A dependency edge is a live constraint or a historical one, and the
+// heading should say which. Pure so the rule is testable without the drawer.
+
+export interface DepHeading {
+  prefix: string;
+  /** The word whose tense carries the meaning; rendered emphasised. */
+  tense: string;
+  suffix: string;
+  /** Why this tense, for the reader who hovers the word (bp-67g.47). */
+  explain: string;
+}
+
+interface HasStatus {
+  status: string;
+}
+
+/**
+ * "This bead IS blocked by:" / "This bead WAS blocked by:".
+ *
+ * Past tense only when every blocker is closed. One open blocker means the
+ * bead really is still blocked, so a partially-cleared list must keep the
+ * present tense — otherwise the heading would say the work is unblocked
+ * while something above it still holds.
+ */
+export function blockedByHeading(blockers: readonly HasStatus[]): DepHeading {
+  const allCleared =
+    blockers.length > 0 && blockers.every((b) => b.status === "closed");
+  return {
+    prefix: "This bead ",
+    tense: allCleared ? "was" : "is",
+    suffix: " blocked by:",
+    explain: allCleared
+      ? "Past tense: every bead that blocked this one has closed, so the constraint is history."
+      : "Present tense: at least one bead listed here is still open, so this bead really is blocked. A partly cleared list keeps the present tense.",
+  };
+}
+
+/**
+ * "This bead BLOCKS:" / "This bead BLOCKED:".
+ *
+ * Keyed off the bead being viewed rather than its dependents: what makes
+ * "blocks" moot is this bead closing. Whether the things it blocked have
+ * since closed too doesn't change that it no longer constrains them.
+ */
+export function blocksHeading(viewedStatus: string): DepHeading {
+  return {
+    prefix: "This bead ",
+    tense: viewedStatus === "closed" ? "blocked" : "blocks",
+    suffix: ":",
+    explain:
+      viewedStatus === "closed"
+        ? "Past tense: this bead has closed, so it no longer constrains anything — whatever became of the beads it blocked."
+        : "Present tense: while this bead is open, each bead listed here waits on it.",
+  };
+}
+
+/** A single edge no longer binds once the bead at its far end is closed. */
+export function edgeIsSpent(other: HasStatus): boolean {
+  return other.status === "closed";
+}

package/src/web/economics.ts

@@ -0,0 +1,440 @@
+// economics.ts — derives a bead's time-and-cost picture from
+// metadata.economics.
+//
+// Pure so the arithmetic is testable without a drawer. The shape of this
+// data in practice (measured against a 558-bead repo) drives the design:
+//
+//   hours_unclaimed   105 beads, median 101h   <- where the time actually goes
+//   hours_in_review   110 beads, median 5.5h
+//   by_seat             8 beads                <- work hours, barely recorded
+//   totals              3 beads
+//
+// unclaimed + in_review accounts for a median 99% of created->closed, so the
+// two waiting phases explain essentially a whole bead lifetime. Work hours
+// are the exception rather than the rule, which is why absent work data has
+// to read as "not recorded" instead of zero.
+//
+// ## Derived values
+//
+// `hours_unclaimed` is `started_at - created_at`. That is pure arithmetic on
+// data the tracker already holds, so where the field is absent and both
+// timestamps exist, it is computed here rather than left empty — the same
+// subtraction a ship-record does at close time, applied late. docs/economics.md
+// argues you should "compute the calendar; only log the work" when writing;
+// this is that rule applied to reading, and it is why nothing has to be
+// written back to anyone's beads DB to make the phase bar work.
+//
+// What that costs is a distinction the app did not previously have to make.
+// Before this, an economics value meant "somebody measured this", and the
+// drawer read it that way. A computed value that looks identical would
+// silently convert reconstruction into apparent measurement, with no way to
+// separate them again afterwards. So every phase carries its provenance, and
+// the UI is expected to show it (bp-67g.54).
+//
+// `hours_in_review` is derived too (bp-67g.57), but not from the list
+// payload: the first `in_review` transition lives only in `bd history`, which
+// the server walks in the background and hands over as `bead.history`. The
+// arithmetic — entry to close, or to now while open — is here, and the
+// figure carries `derived:bd-history` so the drawer badges it like the queue
+// wait. A bead the walk has not reached, or that never entered review, stays
+// ABSENT: null, never zero.
+//
+// Worked hours are deliberately never derived. The estimator PREFERS
+// `metadata.economics.totals.agent_hours` over wall-clock, so an invented
+// figure would not add noise at the margin — it would take precedence over
+// the one real signal and dominate every bucket median.
+
+import { readProvenance, RECORDED } from "../provenance.mjs";
+import type { Provenance } from "../provenance.mjs";
+
+const MS_PER_HOUR = 3_600_000;
+
+export interface EconomicsSession {
+  date: string | null;
+  hours: number;
+  human: string | null;
+  /** Tokens the session spent, when the record carries them per session (bp-0z5). Null: not recorded. */
+  tokensIn: number | null;
+  tokensOut: number | null;
+}
+
+export interface EconomicsSeat {
+  seat: string;
+  hours: number;
+  sessions: EconomicsSession[];
+}
+
+export interface EconomicsTotals {
+  agentHours: number | null;
+  tokensIn: number | null;
+  tokensOut: number | null;
+}
+
+/**
+ * Where a phase figure came from.
+ *
+ *   "recorded"    someone measured it and wrote it down
+ *   "derived"     beadcyte computed it here, now, from the bead's timestamps
+ *   "reconstructed"
+ *                 the record itself declares it was not measured — see
+ *                 `metadata.economics.provenance` below
+ *
+ * "derived" and "reconstructed" both mean "not measured" and are still worth
+ * separating: a derived figure is arithmetic on data in front of you, and a
+ * reconstructed one is a number some other tool admits it inferred. Different
+ * things to trust differently.
+ *
+ * The absence of a provenance entry on a stored record is read as
+ * "recorded". That is an assumption, and it is the only one available: every
+ * economics record written before this existed was written at close time by a
+ * script that had measured it. A tool that reconstructs a value is expected
+ * to say so.
+ */
+export type { Provenance } from "../provenance.mjs";
+export type ProvenanceKind = "recorded" | "derived" | "reconstructed";
+
+/**
+ * Provenance per phase, `null` where the phase itself is absent.
+ *
+ * A sibling map rather than wrapping each value in an object, so every
+ * existing reader of `unclaimedHours` keeps working and only code that cares
+ * about provenance has to look it up.
+ */
+export interface EconomicsProvenance {
+  unclaimedHours: Provenance | null;
+  reviewHours: Provenance | null;
+  workedHours: Provenance | null;
+}
+
+// ── what each phase means (bp-67g.47) ─────────────────────────────────────
+// Kept with the fields, because these sentences are only true of THIS
+// arithmetic: change what unclaimed subtracts, and its sentence changes here.
+
+export type EconomicsPhase = "unclaimed" | "review" | "worked" | "unaccounted";
+
+export const PHASE_EXPLANATIONS: Record<EconomicsPhase, string> = {
+  unclaimed:
+    "From the bead being created until someone started it — the queue wait, as started_at − created_at. Recorded at close on a ship record when there is one; otherwise derived here from those two timestamps and marked as such.",
+  review:
+    "Time between the work being finished and the bead closing: from the ship record's hours_in_review when one exists, otherwise derived from the first in_review transition in bd history — walked in the background by the server, and marked as derived. Absent when the bead never entered review.",
+  worked:
+    "Hours of work logged against the bead, summed across every seat's sessions in its economics record. Never derived — an invented figure would outrank the one real signal the estimator prefers — so absent means not recorded, not zero.",
+  unaccounted:
+    "The rest of created→closed that no phase claims. A large remainder says time went unrecorded, not that nothing happened.",
+};
+
+export interface BeadEconomics {
+  /**
+   * False when the bead carries no *recorded* economics at all — most of
+   * them. Deliberately unchanged by derivation, so a caller asking "did
+   * anyone write this down?" still gets an honest answer.
+   */
+  hasAny: boolean;
+  /**
+   * True when at least one figure below was computed here rather than read.
+   * A UI wanting "is there anything worth drawing?" should test
+   * `hasAny || hasDerived`.
+   */
+  hasDerived: boolean;
+  /** created -> closed, or created -> now while still open. Null if undated. */
+  elapsedHours: number | null;
+  /** True when elapsed is still accumulating. */
+  elapsedOngoing: boolean;
+  unclaimedHours: number | null;
+  reviewHours: number | null;
+  /** Summed from by_seat. Null means NOT RECORDED, which is not zero. */
+  workedHours: number | null;
+  /**
+   * Elapsed not explained by the phases above. Negative would mean the parts
+   * exceed the whole, so it clamps at zero and `overAccounted` says so —
+   * better than a bar with a phase hanging off the end.
+   */
+  unaccountedHours: number | null;
+  overAccounted: boolean;
+  seats: EconomicsSeat[];
+  totals: EconomicsTotals;
+  /** Where each phase figure above came from. */
+  provenance: EconomicsProvenance;
+}
+
+/** Accepts only finite non-negative numbers; anything else is absent. */
+function num(v: unknown): number | null {
+  return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
+}
+
+function parseDate(v: unknown): number | null {
+  if (typeof v !== "string" || !v) return null;
+  const t = new Date(v).getTime();
+  return Number.isFinite(t) ? t : null;
+}
+
+function parseSeats(raw: unknown): EconomicsSeat[] {
+  if (!raw || typeof raw !== "object") return [];
+  const out: EconomicsSeat[] = [];
+  for (const [seat, value] of Object.entries(raw as Record<string, unknown>)) {
+    const v = (value ?? {}) as Record<string, unknown>;
+    const sessionsRaw = Array.isArray(v.sessions) ? v.sessions : [];
+    const sessions: EconomicsSession[] = sessionsRaw.map((s) => {
+      const o = (s ?? {}) as Record<string, unknown>;
+      return {
+        date: typeof o.date === "string" ? o.date : null,
+        hours: num(o.hours) ?? 0,
+        human: typeof o.human === "string" ? o.human : null,
+        tokensIn: num(o.tokens_in),
+        tokensOut: num(o.tokens_out),
+      };
+    });
+    // Prefer the seat's own total; fall back to summing its sessions, since
+    // a seat can carry sessions without a rolled-up figure.
+    const hours =
+      num(v.hours) ?? sessions.reduce((a, s) => a + s.hours, 0);
+    out.push({ seat, hours, sessions });
+  }
+  return out.sort((a, b) => b.hours - a.hours || a.seat.localeCompare(b.seat));
+}
+
+interface BeadLike {
+  status?: string;
+  created_at?: string | null;
+  started_at?: string | null;
+  closed_at?: string | null;
+  metadata?: { economics?: unknown } | null;
+  /** What the server's history walk knows (bp-67g.57, bp-7c9); absent until it has run. */
+  history?: { in_review_at?: string | null; assigned_at?: string | null } | null;
+}
+
+// ── stage boundaries (bp-7c9) ─────────────────────────────────────────────
+// The owner's five: filed, assigned, first MR, first QA, merged — plus
+// started, which bd records and which sits between assigned and the MR.
+// Each comes from one place and says where:
+//
+//   filed     created_at                           recorded by bd
+//   assigned  history.assigned_at                  derived from bd history (the walk)
+//   started   started_at                           recorded by bd (the claim)
+//   first MR  metadata.ship.mr_opened_at           written by the close script; provenance under metadata.ship.provenance
+//   first QA  metadata.economics.qa_started_at     written by the close script; provenance under metadata.economics.provenance
+//   merged    closed_at                            recorded by bd
+//
+// The tracker never sees an MR open or QA begin, so those two are absent
+// until something writes them — and absent is shown as absent.
+
+export type StageId = "filed" | "assigned" | "started" | "mr" | "qa" | "merged";
+
+export const STAGE_ORDER: readonly StageId[] = ["filed", "assigned", "started", "mr", "qa", "merged"];
+
+export const STAGE_LABELS: Record<StageId, string> = {
+  filed: "filed",
+  assigned: "assigned",
+  started: "started",
+  mr: "first MR",
+  qa: "first QA",
+  merged: "merged",
+};
+
+export const STAGE_EXPLANATIONS: Record<StageId, string> = {
+  filed: "When the bead was created — bd's created_at.",
+  assigned: "When it first had an assignee, from the first bd history snapshot carrying one; derived by the server's background walk, so it is marked derived and may lag a fresh assignment until the walk reaches the bead.",
+  started: "When work began — bd's started_at, set by a claim.",
+  mr: "When its first merge request opened — metadata.ship.mr_opened_at, written by the close script; the tracker never sees an MR, so absent means nobody recorded it.",
+  qa: "When QA first picked it up — metadata.economics.qa_started_at, written by the close script; absent means nobody recorded it.",
+  merged: "When the bead closed — bd's closed_at; a merged MR closes the bead.",
+};
+
+export interface StageBoundary {
+  id: StageId;
+  at: string | null;
+  provenance: Provenance | null;
+}
+
+const DERIVED_HISTORY_ASSIGNED: Provenance = {
+  kind: "derived",
+  method: "derived:bd-history",
+  note: "first snapshot with an assignee",
+  at: null,
+};
+
+/** The six boundaries in order, each dated or absent, each with its provenance. */
+export function beadStages(bead: BeadLike): StageBoundary[] {
+  const raw = bead.metadata?.economics;
+  const e = (raw && typeof raw === "object" ? raw : {}) as Record<string, unknown>;
+  const shipRaw = (bead.metadata as { ship?: unknown } | null | undefined)?.ship;
+  const ship = (shipRaw && typeof shipRaw === "object" ? shipRaw : {}) as Record<string, unknown>;
+  const at = (v: unknown): string | null => (typeof v === "string" && v ? v : null);
+  const mr = at(ship.mr_opened_at);
+  const qa = at(e.qa_started_at);
+  return [
+    { id: "filed", at: at(bead.created_at), provenance: bead.created_at ? RECORDED : null },
+    { id: "assigned", at: at(bead.history?.assigned_at), provenance: bead.history?.assigned_at ? DERIVED_HISTORY_ASSIGNED : null },
+    { id: "started", at: at(bead.started_at), provenance: bead.started_at ? RECORDED : null },
+    { id: "mr", at: mr, provenance: mr ? (readProvenance(ship.provenance, "mr_opened_at") ?? RECORDED) : null },
+    { id: "qa", at: qa, provenance: qa ? (readProvenance(e.provenance, "qa_started_at") ?? RECORDED) : null },
+    { id: "merged", at: at(bead.closed_at), provenance: bead.closed_at ? RECORDED : null },
+  ];
+}
+
+export interface StageSpan {
+  from: StageId;
+  to: StageId;
+  hours: number;
+  /** Not measured if either end was derived or reconstructed. */
+  derived: boolean;
+}
+
+/** Hours between each pair of consecutive KNOWN boundaries, in order. */
+export function stageSpans(stages: readonly StageBoundary[]): StageSpan[] {
+  const known = stages.filter((s) => s.at !== null);
+  const out: StageSpan[] = [];
+  for (let i = 1; i < known.length; i++) {
+    const a = known[i - 1]!;
+    const b = known[i]!;
+    const ta = parseDate(a.at);
+    const tb = parseDate(b.at);
+    if (ta === null || tb === null) continue;
+    out.push({
+      from: a.id,
+      to: b.id,
+      hours: Math.max(0, (tb - ta) / MS_PER_HOUR),
+      derived: (a.provenance?.kind ?? "recorded") !== "recorded" || (b.provenance?.kind ?? "recorded") !== "recorded",
+    });
+  }
+  return out;
+}
+
+/**
+ * Read `metadata.economics.provenance.<field>` for one field.
+ *
+ * Accepts either a bare string (`"derived:timestamps"`) or an object with a
+ * `method`, because both are what people actually write. Any entry at all
+ * means the value was not measured; the specific method is not interpreted
+ * here, only its presence.
+ */
+const DERIVED_TIMESTAMPS: Provenance = {
+  kind: "derived",
+  method: "derived:timestamps",
+  note: "started_at − created_at",
+  at: null,
+};
+
+const DERIVED_HISTORY: Provenance = {
+  kind: "derived",
+  method: "derived:bd-history",
+  note: "first in_review transition in bd history → close",
+  at: null,
+};
+
+export function buildEconomics(
+  bead: BeadLike,
+  now: number = Date.now(),
+): BeadEconomics {
+  const raw = bead.metadata?.economics;
+  const e = (raw && typeof raw === "object" ? raw : {}) as Record<
+    string,
+    unknown
+  >;
+
+  const recordedUnclaimed = num(e.hours_unclaimed);
+  const recordedReview = num(e.hours_in_review);
+  const seats = parseSeats(e.by_seat);
+  const totalsRaw = (e.totals ?? {}) as Record<string, unknown>;
+  const totals: EconomicsTotals = {
+    agentHours: num(totalsRaw.agent_hours),
+    tokensIn: num(totalsRaw.tokens_in),
+    tokensOut: num(totalsRaw.tokens_out),
+  };
+
+  // Work hours: seats first, else the rolled-up agent_hours. Null when
+  // neither exists — nobody logged it, which is different from zero.
+  const seatHours = seats.reduce((a, s) => a + s.hours, 0);
+  const workedHours =
+    seats.length > 0 ? seatHours : totals.agentHours;
+
+  const created = parseDate(bead.created_at);
+  const started = parseDate(bead.started_at);
+  const closed = parseDate(bead.closed_at);
+  const end = closed ?? (created !== null ? now : null);
+  const elapsedHours =
+    created !== null && end !== null
+      ? Math.max(0, (end - created) / MS_PER_HOUR)
+      : null;
+
+  // Derive the queue wait when nobody recorded it. Requires `started_at`, so
+  // the figure always describes a wait that ENDED — a bead still sitting
+  // unclaimed gets nothing here, because created->now is already what
+  // `elapsedHours` reports for it and a second identical number dressed as a
+  // phase would be one fact pretending to be two.
+  //
+  // Clamped at zero: `started_at` before `created_at` should be impossible
+  // and is not worth a negative segment if a tracker ever produces one.
+  const derivedUnclaimed =
+    recordedUnclaimed === null && created !== null && started !== null
+      ? Math.max(0, (started - created) / MS_PER_HOUR)
+      : null;
+  const unclaimedHours = recordedUnclaimed ?? derivedUnclaimed;
+
+  // Review: recorded wins; else the walk's first in_review transition, to
+  // the close or to now. Nothing known → null, which the UI keeps absent.
+  const inReviewAt = parseDate(bead.history?.in_review_at ?? null);
+  const derivedReview =
+    recordedReview === null && inReviewAt !== null && end !== null
+      ? Math.max(0, (end - inReviewAt) / MS_PER_HOUR)
+      : null;
+  const reviewHours = recordedReview ?? derivedReview;
+
+  const provenance: EconomicsProvenance = {
+    unclaimedHours:
+      recordedUnclaimed !== null
+        ? (readProvenance(e.provenance, "hours_unclaimed") ?? RECORDED)
+        : derivedUnclaimed !== null
+          ? DERIVED_TIMESTAMPS
+          : null,
+    reviewHours:
+      recordedReview !== null
+        ? (readProvenance(e.provenance, "hours_in_review") ?? RECORDED)
+        : derivedReview !== null
+          ? DERIVED_HISTORY
+          : null,
+    workedHours: null, // set below, once workedHours is known
+  };
+
+  const accounted =
+    (unclaimedHours ?? 0) + (reviewHours ?? 0) + (workedHours ?? 0);
+  const hasPhase =
+    unclaimedHours !== null || reviewHours !== null || workedHours !== null;
+  const remainder =
+    elapsedHours !== null && hasPhase ? elapsedHours - accounted : null;
+
+  // Worked hours are never derived (see the header), so their provenance is
+  // only ever what the record says.
+  provenance.workedHours =
+    workedHours !== null
+      ? (readProvenance(e.provenance, seats.length > 0 ? "by_seat" : "totals") ??
+        RECORDED)
+      : null;
+
+  return {
+    // Recorded, not derived: a caller asking "did anyone write this down?"
+    // must not be answered by arithmetic beadcyte did itself.
+    hasAny:
+      recordedUnclaimed !== null ||
+      recordedReview !== null ||
+      seats.length > 0 ||
+      totals.agentHours !== null ||
+      totals.tokensIn !== null ||
+      totals.tokensOut !== null,
+    hasDerived: derivedUnclaimed !== null || derivedReview !== null,
+    elapsedHours,
+    elapsedOngoing: closed === null && created !== null,
+    unclaimedHours,
+    reviewHours,
+    workedHours,
+    unaccountedHours: remainder === null ? null : Math.max(0, remainder),
+    overAccounted: remainder !== null && remainder < -0.01,
+    seats,
+    totals,
+    provenance,
+  };
+}
+
+// Re-exported so the web's many callers keep their import site, while the
+// definition lives in one place the SVG CLI can reach too.
+export { formatHours } from "../format.mjs";

package/src/web/env.d.ts

@@ -0,0 +1,85 @@
+/// <reference types="vite/client" />
+
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  const c: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>;
+  export default c;
+}
+
+// The estimator + scheduler ship as untyped .mjs (they're shared with the CLI
+// SVG mode). Declare their public surface so store.ts can import them without
+// downgrading tsconfig to allowJs=loose.
+declare module "*/estimator.mjs" {
+  export interface EstimatorStats {
+    shipped_sample_size: number;
+    global_median_days: number;
+    global_p90_days: number;
+    used_type_pri: number;
+    used_type: number;
+    used_global: number;
+  }
+  export interface EstimateResult {
+    days: number;
+    p90: number | null;
+    source: string;
+  }
+  export function buildEstimator(
+    allBeads: unknown[],
+    opts?: { lookback?: number },
+  ): {
+    estimate: (bead: unknown) => EstimateResult;
+    stats: EstimatorStats;
+  };
+}
+
+declare module "*/scheduler.mjs" {
+  export function scheduleGreedy(
+    beads: unknown[],
+    roster: unknown,
+    estimate: (bead: unknown) => { days: number; p90: number | null; source: string },
+    horizon: Date,
+    opts?: {
+      waits?: { unclaimedDays?: number | null; reviewDays?: number | null };
+      minLeadDays?: number;
+      capacityFor?: (human: unknown) => number;
+      now?: Date;
+    },
+  ): {
+    schedule: Map<string, unknown>;
+    unscheduled: string[];
+    unassignedBacklog: unknown[];
+    unassignedProjection: Map<string, unknown>;
+    waits: { unclaimedDays: number; reviewDays: number | null; minLeadDays: number };
+  };
+  export function dailyCapacityFor(human: unknown): number;
+}
+
+// The wait clock's inputs (bp-m0g).
+declare module "*/stage-waits.mjs" {
+  export function stageWaits(beads: readonly unknown[]): {
+    unclaimedDays: number | null;
+    unclaimedN: number;
+    assignedDays: number | null;
+    assignedN: number;
+    reviewDays: number | null;
+    reviewN: number;
+  };
+}
+
+// The write whitelist shared with the server (bp-ocs).
+declare module "*/mutate.mjs" {
+  export const MUTATION_ACTIONS: readonly ["claim", "assign", "priority", "spec-ready", "unspec-ready", "add-label", "defer", "create"];
+  export const DEFER_CHOICES: ReadonlyArray<{ until: string; label: string }>;
+  export const READY_LABEL: string;
+  export function validateMutation(raw: unknown): { action: string; id: string; label?: string; until?: string; assignee?: string; priority?: number; title?: string; type?: string; labels?: string[] };
+  export function bdArgsFor(m: { action: string; id: string; label?: string; until?: string; assignee?: string; priority?: number; title?: string; type?: string; labels?: string[] }): string[];
+  export function describeMutation(m: { action: string; id: string; label?: string; until?: string; assignee?: string; priority?: number; title?: string; type?: string; labels?: string[] }): string;
+  export function createdIdFrom(stdout: string): string | null;
+  export function describeOutcome(m: { action: string; id: string; label?: string; until?: string; assignee?: string; priority?: number; title?: string; type?: string; labels?: string[] }): string;
+  export function applyOptimistic<B extends { id: string; status: string }>(
+    bead: B,
+    m: { action: string; id: string; label?: string; until?: string; assignee?: string; priority?: number; title?: string; type?: string; labels?: string[] },
+    actor: string | null,
+    now?: Date,
+  ): B;
+}