@futurelastic/colab-handbook 1.14.0-rc.9 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -513,7 +513,10 @@ function laneHold({ batches, trunkNow, nowMs, graceSec = LANE_GRACE_SEC } = {})
513
513
  const fresh = (atMs) => Number.isFinite(atMs) && Number.isFinite(nowMs) && (nowMs - atMs) < graceSec * 1000;
514
514
  const mins = (atMs) => `${Math.max(0, Math.round((nowMs - atMs) / 60000))}m ago`;
515
515
  for (const b of (Array.isArray(batches) ? batches : [])) {
516
- if (!b || !b.base7 || !now.startsWith(b.base7)) continue;
516
+ // #605: a chained batch (`rooted`, from batchChains) is part of the one holder its root is —
517
+ // built on another batch's head, so it reaches trunk only through that chain. Without the flag,
518
+ // only a batch built on trunk's tip counts, exactly as before.
519
+ if (!b || !b.base7 || !(b.rooted === undefined ? now.startsWith(b.base7) : b.rooted)) continue;
517
520
  const v = b.verdict || { state: 'pending', why: 'the run list could not be read' };
518
521
  if (v.state === 'red') { released.push({ ref: b.ref, why: `declined — ${v.why}` }); continue; }
519
522
  if (v.state === 'pending') return { held: true, ref: b.ref, why: `combined run in flight (${v.why})` };
@@ -532,6 +535,72 @@ function laneHold({ batches, trunkNow, nowMs, graceSec = LANE_GRACE_SEC } = {})
532
535
  return { held: false, released };
533
536
  }
534
537
 
538
+ /**
539
+ * #605: speculative chains. A batch built with `--onto <ship-batch ref>` sits on that ref's HEAD, and
540
+ * its name already says so: `ship-batch/<parent-head-sha7>`. So the whole chain is read from
541
+ * `ls-remote` alone — a ref's parent is the ref whose head sha starts with its base7, and a ref is
542
+ * ROOTED when following parents ends at a ref built on trunk's tip. No chain state is kept anywhere.
543
+ *
544
+ * In: refs `[{ ref, base7, sha }]` (every ship-batch/* on the remote), `trunkNow`.
545
+ * Out: Map ref → `{ ref, base7, sha, parentRef, rootRef, rootSha, depth, rooted, why }`:
546
+ * - parentRef null for a batch built on trunk's tip, else the ref it was built on (null too
547
+ * when that ref is gone — then `rooted` is false);
548
+ * - rootSha trunk's tip when rooted, else null;
549
+ * - depth 1 at trunk's tip, 2 for its child, …;
550
+ * - why for an unrooted ref, the reason it is (the sweep deletes it, and says this).
551
+ * A chain deeper than MAX_CHAIN_DEPTH is not rooted: every link pins trunk for one more combined run,
552
+ * and a wrong guess low in the chain throws away every run above it.
553
+ */
554
+ const MAX_CHAIN_DEPTH = 3;
555
+
556
+ function batchChains({ refs, trunkNow } = {}) {
557
+ const now = String(trunkNow || '');
558
+ const all = (Array.isArray(refs) ? refs : []).filter((r) => r && r.ref && r.base7 && r.sha);
559
+ const parentOf = (r) => all.find((p) => p !== r && String(p.sha).startsWith(r.base7)) || null;
560
+ const out = new Map();
561
+ for (const r of all) {
562
+ const atTip = !!now && now.startsWith(r.base7);
563
+ const parent = atTip ? null : parentOf(r);
564
+ let cur = r, depth = 1, why = null, root = null;
565
+ const seen = new Set([r.ref]);
566
+ while (true) {
567
+ if (now && now.startsWith(cur.base7)) { root = cur; break; }
568
+ const p = parentOf(cur);
569
+ if (!p) {
570
+ why = cur === r ? `its base ${r.base7} is neither trunk's tip nor the head of another batch ref — trunk moved, or its parent was rebuilt or deleted`
571
+ : `its chain breaks at ${cur.ref}, whose base ${cur.base7} is neither trunk's tip nor another batch's head`;
572
+ break;
573
+ }
574
+ if (seen.has(p.ref)) { why = `its chain loops at ${p.ref}`; break; }
575
+ seen.add(p.ref);
576
+ cur = p;
577
+ depth += 1;
578
+ if (depth > MAX_CHAIN_DEPTH) { why = `its chain is deeper than ${MAX_CHAIN_DEPTH}`; break; }
579
+ }
580
+ out.set(r.ref, {
581
+ ref: r.ref, base7: r.base7, sha: r.sha, parentRef: parent ? parent.ref : null,
582
+ rootRef: root ? root.ref : null, rootSha: root ? now : null, depth, rooted: !!root, why,
583
+ });
584
+ }
585
+ return out;
586
+ }
587
+
588
+ /**
589
+ * #605: what a chained batch (built `--onto` a parent) does when it is ready to land but its parent
590
+ * has not landed yet — trunk's tip is not its base. Facts: the parent's chain entry (null = gone)
591
+ * and the parent's combined verdict.
592
+ * wait the parent is rooted and its run is in flight, not yet run, or green → exit 3
593
+ * decline the parent is gone, unrooted, or red → nothing of this chain can land in order: delete
594
+ * this batch and decline it (exit 4)
595
+ */
596
+ function chainedLandStep({ parent, parentVerdict } = {}) {
597
+ if (!parent) return { step: 'decline', why: 'its parent batch is gone — discarded, or rebuilt on another head' };
598
+ if (!parent.rooted) return { step: 'decline', why: `its parent ${parent.ref} is no longer rooted at trunk's tip (${parent.why})` };
599
+ const v = parentVerdict || { state: 'pending', why: 'the run list could not be read' };
600
+ if (v.state === 'red') return { step: 'decline', why: `its parent ${parent.ref} is red (${v.why}) — it will not land at the sha this batch was built on` };
601
+ return { step: 'wait', why: `its parent ${parent.ref} has not landed yet (${v.state === 'green' ? 'green, waiting for its lander' : (v.why || v.state)})` };
602
+ }
603
+
535
604
  /** #581: when a batch's combined run settled — the newest `updatedAt` among its finished rows, else null. */
536
605
  function settledAt(rows) {
537
606
  const t = (Array.isArray(rows) ? rows : []).filter((r) => r && r.status === 'completed')
@@ -599,5 +668,5 @@ module.exports = {
599
668
  droppedTrailer, parseDroppedTrailers, appendTrailers,
600
669
  branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
601
670
  batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
602
- LANE_GRACE_SEC, laneHold, settledAt,
671
+ LANE_GRACE_SEC, laneHold, settledAt, MAX_CHAIN_DEPTH, batchChains, chainedLandStep,
603
672
  };
@@ -475,6 +475,9 @@ const WORKFLOW_FINGERPRINTS = [
475
475
  { marker: 'CI (Node) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'ci-node' },
476
476
  { marker: 'CI (Laravel) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'ci-laravel' },
477
477
  { marker: 'CI (Python) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'ci-python' },
478
+ { marker: 'CI heavy lane (Node) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'ci-node-heavy' },
479
+ { marker: 'CI heavy lane (Laravel) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'ci-laravel-heavy' },
480
+ { marker: 'CI heavy lane (Python) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'ci-python-heavy' },
478
481
  { marker: 'Release (tag) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'release-tag' },
479
482
  { marker: 'Release (auto) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'release-auto' },
480
483
  { marker: 'Deploy (SSH/rsync to shared hosting) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'deploy-xserver' },
@@ -557,6 +560,18 @@ function workflowProvenance(text, stem, tmplNames) {
557
560
  return { origin: 'none', template: null, evidence: [] };
558
561
  }
559
562
 
563
+ /**
564
+ * Is this provenance a CI template copy (#607)? Its named template is a `ci-*` one, or — when the
565
+ * evidence names several (a heavy-lane copy carries the light lane's step names too) — every
566
+ * attributed marker it matched belongs to a `ci-*` template. A CI copy's drift is information.
567
+ */
568
+ function isCiProvenance(prov) {
569
+ if (!prov || prov.origin !== 'derived') return false;
570
+ if (prov.template) return /^ci-/.test(prov.template);
571
+ const owners = WORKFLOW_FINGERPRINTS.filter((fp) => fp.template && prov.evidence.some((e) => e === fp.marker || e.includes(fp.marker) || fp.marker.includes(e))).map((fp) => fp.template);
572
+ return owners.length > 0 && owners.every((n) => /^ci-/.test(n));
573
+ }
574
+
560
575
  /**
561
576
  * The single source of the advice both tools print, so the two can never drift apart on the one
562
577
  * thing that matters here: whether to suggest asserting provenance.
@@ -745,7 +760,7 @@ module.exports = {
745
760
  AXES, axesPredating,
746
761
  WRITES_VETO_MARKER, writesRulingKnownAt,
747
762
  stampLine, stampCommentPrefix, insertStamp, parseWorkflowStamp, parseClaudeStamp,
748
- fingerprintHits, workflowProvenance, unstampedFinding,
763
+ fingerprintHits, workflowProvenance, unstampedFinding, isCiProvenance,
749
764
  looksLikeHandbookWorkflow, looksLikeHandbookClaude,
750
765
  cmpParts, cmpSemver, sameContent, classifyStamped,
751
766
  };