@mgiles/perk 3.2.0 → 3.3.0

package/extension/delivery/submit.ts

@@ -0,0 +1,171 @@
+// The change-publication feature (the submit half of the delivery pair), Pi-free.
+//
+// One entry point — `submitChange` — owns the ordering and failure semantics of publishing the
+// active plan's change: external publish first, session-side updates ONLY on verified success
+// (the implementation pointer, the reset-on-clean), then the bounded conflict follow-up
+// decision. The composable internals (`publishVerified`, `decideConflictFollowUp`) are exported
+// for the sibling address feature, whose conflict-decision timing is deliberately DIFFERENT
+// (structural, not stylistic): `/submit` decides immediately after publish; `finalizeAddress`
+// decides only after full corroborated resolve success — a resolve failure never burns an
+// attempt.
+//
+// Ports are action-specific (never a DeliveryBackend/Git facade): `PublishChange` has exactly
+// ONE production adapter — the `perk pr submit --json` cold-door composition in
+// `pi/v1/delivery/submit.ts`, which also owns the `operation.notes` warning reports at
+// publish-success time. Refusals (`planning_session`, `bad_input`) are adapter shapes — they
+// never enter the outcome union.
+
+/** The published-change facts — the structured `details` surface doubles as branch-safe
+ * persisted state. `issue` is the opaque string id the Python boundary sends (contracts §8.21). */
+export interface PublishedChange {
+  pr: { number: number; url: string; is_draft: boolean; existed: boolean };
+  branch?: string;
+  issue?: string;
+  plan_embedded?: boolean;
+  /** The target branch the PR merges into (the conflict-resolver rebases onto it). */
+  base?: string;
+  /** Tri-state mergeability from the Python `git merge-tree` probe: true/false/null/absent. */
+  mergeable?: boolean | null;
+  /** The conflicted paths when `mergeable === false`; `[]` otherwise (advisory). */
+  conflicts?: string[];
+  /** `"stacked"` when the submit routed through the delivery publish operation (§8.47). */
+  delivery?: string;
+  /** The native-stack facts of a stacked submit (absent for the bottom layer). */
+  stack?: { number: number; size: number; position: number };
+  /** Lenient summary of an automatic suffix synchronization. */
+  operation?: {
+    kind: string;
+    operation_id: string | null;
+    no_op: boolean;
+    affected_count: number;
+    notes: string[];
+  };
+}
+
+/** One external publish attempt: the verified facts, or the adapter's soft failure. */
+export type PublishAttempt =
+  | { ok: true; change: PublishedChange }
+  | { ok: false; message: string; errorType: string };
+
+/** The publish port — ONE production adapter (`createChangePublisher`). */
+export type PublishChange = (opts: { runId: string | null }) => Promise<PublishAttempt>;
+
+/**
+ * The bounded conflict-attempt capability. `write` returns the persistence result (strict
+ * read-back / equal-value short-circuit true) — callers decide whether the boolean gates.
+ */
+export interface ConflictAttempts {
+  read(): number;
+  write(next: number): boolean;
+}
+
+/**
+ * The bounded conflict-resolution re-drive cap: drive the resolver at most this many times.
+ * The counter behind it (`conflict_resolution_attempts`) is SHARED with `/objective-sync`'s
+ * retained-continuation conflict drive (delivery/stackConflict.ts) — submit- and sync-episode
+ * attempts deliberately share one bound, reset on any clean completion of either surface.
+ */
+export const CONFLICT_RESOLUTION_ATTEMPT_CAP = 2;
+
+/** The budget read: room for one more attempt (carrying the next attempt number), or spent. */
+export type ConflictBudget =
+  | { kind: "available"; next: number; cap: number }
+  | { kind: "exhausted"; attempts: number };
+
+/**
+ * The ONE cap/read comparison both conflict surfaces share (the submit/address decision here,
+ * the stack dispatch pipeline in `delivery/stackConflict.ts`). Deliberately read-only — the
+ * stack path interleaves its resolver claim between this inspect and its strict
+ * `attempts.write(next)`, whose read-back boolean each consumer passes through UNSOFTENED (a
+ * `false` means the counter is unverifiable, and an unverifiable counter must never bypass
+ * the cap — both consumers withhold the dispatch on it). A throwing counter read propagates
+ * (the 7.2-pinned load-bearing failure arm on the submit path; the stack pipeline's total
+ * boundary translates it to `state_error`).
+ */
+export function inspectConflictBudget(attempts: ConflictAttempts): ConflictBudget {
+  const n = attempts.read();
+  if (n >= CONFLICT_RESOLUTION_ATTEMPT_CAP) return { kind: "exhausted", attempts: n };
+  return { kind: "available", next: n + 1, cap: CONFLICT_RESOLUTION_ATTEMPT_CAP };
+}
+
+/** The bounded conflict follow-up decision (surface translation stays adapter-side). */
+export type ConflictFollowUp =
+  | { kind: "none" }
+  | { kind: "drive"; base: string; attempt: number; cap: number }
+  | { kind: "exhausted"; base: string; attempts: number }
+  /** The increment could not be persisted-and-verified — the dispatch is withheld (an
+   * unverifiable counter must never bypass the cap; surface-uniform with the stack path). */
+  | { kind: "withheld"; base: string };
+
+export interface PublishDeps {
+  publish: PublishChange;
+  /** The adapter's DIRECT run-id read, invoked at publish time — AFTER any pre-effect refusal
+   * (the finalize empty-batch check) but BEFORE the external call, so a throwing branch read
+   * still fails before publication (today's parity); `""` ⇒ `null` is the adapter's job. */
+  readRunId: () => string | null;
+  /** CONTRACT: never throws; owns its own failure reporting (production:
+   * `captureSessionPointer` — best-effort + non-fatal, a successful publish must stand).
+   * Receives the run id `readRunId` returned for this publish. */
+  recordImplementationPointer: (runId: string) => void;
+  attempts: ConflictAttempts;
+}
+
+export type SubmitChangeOutcome =
+  | { kind: "publish_failed"; message: string; errorType: string }
+  | { kind: "published"; change: PublishedChange; conflict: ConflictFollowUp };
+
+/**
+ * Publish the change, then apply the verified-success session updates. A failed publish returns
+ * as-is with NO session-side activity (no pointer, no counter read/write). On success: the
+ * implementation pointer is recorded iff the run id exists (no catch — the capability contract
+ * is never-throws), and the shared conflict counter resets on a clean (or undetermined) submit
+ * so a later independent conflict starts fresh. The reset's persistence result is deliberately
+ * unchecked — today's posture; the seam warns loudly on a read-back miss.
+ */
+export async function publishVerified(deps: PublishDeps): Promise<PublishAttempt> {
+  const runId = deps.readRunId();
+  const attempt = await deps.publish({ runId });
+  if (!attempt.ok) return attempt;
+  if (runId !== null) deps.recordImplementationPointer(runId);
+  if (attempt.change.mergeable !== false && deps.attempts.read() !== 0) {
+    deps.attempts.write(0);
+  }
+  return attempt;
+}
+
+/**
+ * The bounded conflict follow-up decision for a published change: mergeable (or undetermined) ⇒
+ * `none`; at the cap ⇒ `exhausted` (no write); definitively unmergeable under the cap ⇒ the
+ * verified increment gates the drive — a `false` commit ⇒ `withheld` (the surface-uniform
+ * withhold posture: an unverifiable counter must never bypass the cap; the adapter reports
+ * loudly, no dispatch). A THROWING counter read/write still propagates — the 7.2-pinned
+ * load-bearing failure arm; only the `false` return changed posture.
+ */
+export function decideConflictFollowUp(
+  change: PublishedChange,
+  attempts: ConflictAttempts,
+): ConflictFollowUp {
+  if (change.mergeable !== false) return { kind: "none" };
+  const base = change.base ?? "";
+  const budget = inspectConflictBudget(attempts);
+  if (budget.kind === "exhausted") return { kind: "exhausted", base, attempts: budget.attempts };
+  if (!attempts.write(budget.next)) return { kind: "withheld", base };
+  return { kind: "drive", base, attempt: budget.next, cap: budget.cap };
+}
+
+/**
+ * The one standalone-submit operation: external publish → verified-success session updates →
+ * the bounded conflict decision, taken immediately after publish (the standalone surface's
+ * structural timing; the address finalizer defers it until corroborated resolve success).
+ */
+export async function submitChange(deps: PublishDeps): Promise<SubmitChangeOutcome> {
+  const attempt = await publishVerified(deps);
+  if (!attempt.ok) {
+    return { kind: "publish_failed", message: attempt.message, errorType: attempt.errorType };
+  }
+  return {
+    kind: "published",
+    change: attempt.change,
+    conflict: decideConflictFollowUp(attempt.change, deps.attempts),
+  };
+}