code-coordinator 0.5.202__tar.gz → 0.5.204__tar.gz

{code_coordinator-0.5.202 → code_coordinator-0.5.204}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.202
+Version: 0.5.204
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.202 → code_coordinator-0.5.204}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.202
+Version: 0.5.204
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.202 → code_coordinator-0.5.204}/code_coordinator.egg-info/SOURCES.txt

@@ -586,6 +586,7 @@ tests/test_plan_parser.py
 tests/test_platform_paths.py
 tests/test_portal_bridge.py
 tests/test_portal_config.py
+tests/test_portal_store.py
 tests/test_portal_sync.py
 tests/test_pr_body_lint.py
 tests/test_prereqs.py

{code_coordinator-0.5.202 → code_coordinator-0.5.204}/code_coordinator.egg-info/scm_file_list.json

@@ -648,6 +648,7 @@
     "tests/test_platform_paths.py",
     "tests/test_portal_bridge.py",
     "tests/test_portal_config.py",
+    "tests/test_portal_store.py",
     "tests/test_portal_sync.py",
     "tests/test_pr_body_lint.py",
     "tests/test_prereqs.py",

{code_coordinator-0.5.202 → code_coordinator-0.5.204}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.202",
+  "tag": "0.5.204",
   "distance": 0,
-  "node": "ga9e29961ca26348c484ecee55a737e8c98826ac8",
+  "node": "g471c14e8906b4f0ebf43a5b08365c101a0b02156",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-21"

{code_coordinator-0.5.202 → code_coordinator-0.5.204}/coord/commands/portal.py

@@ -31,6 +31,8 @@ follow-up); this is the "fail loud instead of running wrong" half.
 
 from __future__ import annotations
 
+import datetime
+import getpass
 import json
 
 import click
@@ -44,6 +46,13 @@ from coord.portal_bridge import (
 )
 
 
+def _actor() -> str:
+    try:
+        return getpass.getuser()
+    except Exception:  # noqa: BLE001 — no passwd entry in some containers
+        return "unknown"
+
+
 def _refuse_if_thin_client(cmd_name: str) -> None:
     """Refuse *cmd_name* when this machine isn't the daemon host (#2336).
 
@@ -194,6 +203,87 @@ def portal_push(config_path, submission_id: str, revision: int, status: str) ->
     raise SystemExit(1)
 
 
+# ── #2507: milestone ↔ portal submission linkage ────────────────────────────
+
+
+@portal_group.command("link")
+@_CONFIG_OPTION
+@click.argument("repo")
+@click.argument("milestone_number", type=int)
+@click.argument("submission_id", required=False)
+def portal_link(
+    config_path, repo: str, milestone_number: int, submission_id: str | None
+) -> None:
+    """Record, or read, one milestone's portal submission_id link (#2507).
+
+    With SUBMISSION_ID: link REPO's milestone MILESTONE_NUMBER to it.
+    Operator-run — submission creation is driven by the portal's own intake
+    flow, not by coord, so there is currently no automatic way for coord to
+    learn a submission exists at all.
+
+    Without SUBMISSION_ID: report the current link, mirroring `coord gate-a`'s
+    read/write dual-mode shape.
+
+    Nothing downstream resolves this automatically yet — PDR-3's auto-push
+    and PDR-4's verdict consumer (the epic's later legs, #2506) are what will
+    read it once they exist.
+    """
+    _refuse_if_thin_client("link")
+
+    from coord import portal_store  # noqa: PLC0415
+    from coord.audit import record_audit  # noqa: PLC0415
+
+    cfg = _load_config(config_path)
+    repo_cfg = cfg.repo(repo)
+    if repo_cfg is None:
+        click.secho(f"error: unknown repo {repo!r}", fg="red")
+        raise SystemExit(2)
+
+    if submission_id is None:
+        link = portal_store.get_milestone_link(
+            repo_name=repo_cfg.name, milestone_number=milestone_number
+        )
+        if link is None:
+            click.echo(f"{repo_cfg.name} ms-{milestone_number}: not linked")
+            raise SystemExit(1)
+        when = datetime.datetime.fromtimestamp(
+            link.linked_at, tz=datetime.timezone.utc
+        ).strftime("%Y-%m-%d %H:%M UTC")
+        click.echo(
+            f"{repo_cfg.name} ms-{milestone_number}: "
+            f"submission_id={link.submission_id} "
+            f"(linked by {link.actor or 'unknown'} at {when})"
+        )
+        return
+
+    link = portal_store.link_milestone(
+        repo_name=repo_cfg.name,
+        milestone_number=milestone_number,
+        submission_id=submission_id,
+        actor=_actor(),
+    )
+    record_audit(
+        tier="business",
+        category="portal",
+        event_type="portal_link",
+        actor=link.actor,
+        summary=(
+            f"linked {repo_cfg.name} ms-{milestone_number} to portal "
+            f"submission {submission_id}"
+        ),
+        repo=repo_cfg.name,
+        details={
+            "milestone_number": milestone_number,
+            "submission_id": submission_id,
+        },
+    )
+    click.secho(
+        f"linked: {repo_cfg.name} ms-{milestone_number} -> "
+        f"submission_id={submission_id}",
+        fg="green",
+    )
+
+
 # ── #1982: the sync loop's operator surface ─────────────────────────────────
 
 

{code_coordinator-0.5.202 → code_coordinator-0.5.204}/coord/merge_queue.py

@@ -4981,6 +4981,119 @@ def _maybe_clear_expected_red(entry: QueuedMerge, board, gh_ops: GhOps) -> Merge
     return MergeEvent(entry, event_type, msg)
 
 
+def _maybe_push_design_round(
+    entry: QueuedMerge, config, gh_ops: GhOps
+) -> "MergeEvent | None":
+    """PDR-3 (#2508): right after a `type="mock-author"` (Gate A) PR has
+    actually merged into ``entry.target_branch``, push its rendered mock
+    bundle + contract to the portal as a design round — the epic-#2506
+    bridge's third leg, wiring PDR-1's link (``coord portal link``,
+    #2507) and PDR-2's upload route (coord-portal#120) into the one signal
+    ``coord/merge_queue.py`` already fires for any assignment type: a real
+    merge.
+
+    Returns ``None`` for every "nothing to do" reason — not a `mock-author`
+    entry, no ``portal:`` block configured, the tracking issue isn't under
+    a milestone, or (the common case pre-#2508) the milestone has no portal
+    link on file. That last one is the fail-open posture
+    ``coord.portal_bridge``'s module docstring already states for the rest
+    of this bridge: "a portal outage must never block a merge or a
+    dispatch" applies just as much to "there's simply no portal submission
+    for this milestone yet" — until an operator runs ``coord portal link``,
+    this is silently, correctly, a no-op. Every other failure (can't fetch
+    the tracking issue, can't collect the bundle, upload/enqueue rejected)
+    degrades to a ``design_round_push_failed`` event rather than raising —
+    called from ``process()`` inside its own try/except, same discipline as
+    :func:`_maybe_clear_expected_red` right above it, but belt-and-braces
+    here too since this reaches out to two different externals (GitHub's
+    Contents API and the portal itself).
+    """
+    if entry.assignment_type != "mock-author":
+        return None
+    portal_cfg = getattr(config, "portal", None)
+    if portal_cfg is None or not portal_cfg.enabled:
+        return None
+
+    # #1467-style optional probe: `get_issue` isn't part of the GhOps
+    # Protocol proper (most stubs in tests never need it), so a stub that
+    # doesn't implement it degrades to "nothing to do" rather than an
+    # AttributeError — mirrors `branch_has_merge_commit`'s optional-probe
+    # pattern used for the rebase→squash fallback above.
+    get_issue = getattr(gh_ops, "get_issue", None)
+    if get_issue is None:
+        return None
+    try:
+        issue_data = get_issue(entry.repo_github, entry.issue_number)
+    except Exception as e:  # noqa: BLE001 — best-effort, see docstring
+        return MergeEvent(
+            entry, "design_round_push_failed",
+            f"could not fetch tracking issue #{entry.issue_number}: {e}",
+        )
+    milestone = (issue_data or {}).get("milestone") or {}
+    milestone_number = milestone.get("number")
+    if milestone_number is None:
+        # A "mock-author" entry not scoped to a milestone at all (shouldn't
+        # happen via `coord acceptance mock`, which always resolves one —
+        # but this hook must survive a hand-dispatched entry that skips it).
+        return None
+
+    from coord import portal_store  # noqa: PLC0415
+
+    link = portal_store.get_milestone_link(
+        repo_name=entry.repo_name, milestone_number=milestone_number
+    )
+    if link is None:
+        # PDR-1: no `coord portal link` recorded for this milestone yet —
+        # the whole point of the fail-open posture (see docstring above).
+        return None
+
+    from coord.mock_author import build_design_round, collect_mock_bundle_files  # noqa: PLC0415
+    from coord.portal_bridge import PortalBridgeError, client_from_config  # noqa: PLC0415
+    from coord.portal_sync import PortalSyncError, enqueue_design_round  # noqa: PLC0415
+
+    client = client_from_config(portal_cfg)
+    if client is None:
+        return None
+
+    try:
+        files = collect_mock_bundle_files(
+            entry.repo_github, milestone_number, entry.target_branch
+        )
+    except Exception as e:  # noqa: BLE001 — best-effort, see docstring
+        return MergeEvent(
+            entry, "design_round_push_failed",
+            f"could not collect mock bundle: {e}",
+        )
+    if not files:
+        return MergeEvent(
+            entry, "design_round_push_skipped",
+            f"no rendered mock bundle found on {entry.target_branch} for "
+            f"ms-{milestone_number} — nothing to push",
+        )
+
+    try:
+        bundle_key = client.upload_bundle(link.submission_id, files)
+    except PortalBridgeError as e:
+        return MergeEvent(entry, "design_round_push_failed", f"bundle upload failed: {e}")
+
+    design_round = build_design_round(
+        milestone_title=milestone.get("title") or f"ms-{milestone_number}",
+        tracking_issue_title=issue_data.get("title") or "",
+        tracking_issue_body=issue_data.get("body") or "",
+        bundle_key=bundle_key,
+    )
+    try:
+        row = enqueue_design_round(link.submission_id, design_round)
+    except PortalSyncError as e:
+        return MergeEvent(entry, "design_round_push_failed", f"enqueue failed: {e}")
+
+    return MergeEvent(
+        entry, "design_round_queued",
+        f"queued design round for portal submission {link.submission_id} "
+        f"(seq={row.seq}, bundle_key={bundle_key})",
+    )
+
+
 def process(
     items: list[QueuedMerge],
     gh_ops: GhOps,
@@ -6205,6 +6318,20 @@ def process(
                     clear_event = MergeEvent(entry, "expected_red_clear_failed", str(e))
                 if clear_event is not None:
                     events.append(clear_event)
+                # PDR-3 (#2508): a merged Gate-A (`type="mock-author"`)
+                # branch auto-pushes a design round to the portal, if (and
+                # only if) its milestone has a portal link on file. Best
+                # effort, same as the expected_red clear above — a portal
+                # outage, or simply no `coord portal link` recorded, must
+                # never undo a real merge.
+                try:
+                    design_round_event = _maybe_push_design_round(entry, config, gh_ops)
+                except Exception as e:  # noqa: BLE001 — bookkeeping, never undoes a real merge
+                    design_round_event = MergeEvent(
+                        entry, "design_round_push_failed", str(e)
+                    )
+                if design_round_event is not None:
+                    events.append(design_round_event)
                 continue
             entry.state = CONFLICT
             entry.error = msg

{code_coordinator-0.5.202 → code_coordinator-0.5.204}/coord/mock_author.py

@@ -25,10 +25,18 @@ TYPES``) and the matching exemption from the acceptance-dir auto-forbid in
 Work → Test → Review → Merge pipeline as any other branch (`required_gates`
 is the repo's normal `default_gates`) — Gate A produces a normal reviewed
 commit, not a special-cased one.
+
+**PDR-3 (#2508):** :func:`collect_mock_bundle_files` and
+:func:`build_design_round` are the other end of Gate A's output — read back
+off a merged mock-author branch and reshaped into a portal design round by
+``coord.merge_queue``'s post-merge hook, so a Gate-A merge auto-pushes a
+design round to any milestone with a portal link (`coord portal link`,
+PDR-1/#2507) instead of that link sitting unread.
 """
 from __future__ import annotations
 
 import uuid
+from typing import Any
 
 import httpx
 
@@ -332,3 +340,97 @@ def dispatch_acceptance_mock(
         pass
 
     return assignment_id, machine.name
+
+
+# ── PDR-3 (#2508): reading a merged Gate-A branch back into a design round ──
+
+
+def collect_mock_bundle_files(
+    repo_github: str, milestone_number: int, branch: str
+) -> dict[str, str]:
+    """Read a rendered Gate-A bundle off *branch* (post-merge) via the
+    GitHub Contents API — no local checkout, the same "gh-only wire layer"
+    posture the merge queue's other post-merge reads already use (see e.g.
+    ``coord.acceptance.clear_expected_red_via_pr``'s docstring).
+
+    Returns a ``{relative_path: content}`` mapping — ``"contract.md"`` plus
+    every ``mocks/*.html`` fixture under
+    ``tests/acceptance/ms-<milestone_number>/`` — ready to hand straight to
+    :meth:`coord.portal_bridge.PortalBridgeClient.upload_bundle`. Empty
+    when the directory doesn't exist on *branch* (Gate A hasn't merged
+    anything there yet, or the repo's acceptance driver renders to a
+    different mock glob than ``*.html``) — callers treat that as "nothing
+    to push", not an error.
+    """
+    ms_dir = f"tests/acceptance/{ms_dirname(milestone_number)}"
+    files: dict[str, str] = {}
+    if github_ops.repo_file_exists(repo_github, f"{ms_dir}/contract.md", branch):
+        files["contract.md"] = github_ops.get_repo_file(
+            repo_github, f"{ms_dir}/contract.md", branch
+        )
+    try:
+        mock_names = github_ops.list_repo_dir(repo_github, f"{ms_dir}/mocks", branch)
+    except RuntimeError:
+        # No `mocks/` dir on this branch at all — same "nothing to push"
+        # case list_repo_dir already returns [] for a missing path; the
+        # explicit catch is only for a `gh` error shaped differently.
+        mock_names = []
+    for name in mock_names:
+        if name.endswith(".html"):
+            files[f"mocks/{name}"] = github_ops.get_repo_file(
+                repo_github, f"{ms_dir}/mocks/{name}", branch
+            )
+    return files
+
+
+def build_design_round(
+    *,
+    milestone_title: str,
+    tracking_issue_title: str,
+    tracking_issue_body: str,
+    bundle_key: str,
+    round_number: int = 1,
+) -> dict[str, Any]:
+    """Build the D1 metadata half of a design round from the same inputs
+    `coord milestone chat`'s steward already reads: the tracking issue's
+    title/body (source of the plain-language ``outcome_definition``) and its
+    ``## Work order`` block (source of the ``decomposition``).
+
+    *bundle_key* is the R2 object key
+    :meth:`coord.portal_bridge.PortalBridgeClient.upload_bundle` returned
+    for this round's rendered mock bundle + contract — see that method's
+    docstring and :func:`coord.portal_sync.enqueue_design_round`'s for why
+    the bundle itself is never inlined into this payload.
+
+    A missing/malformed ``## Work order`` block degrades to an empty
+    ``decomposition`` rather than raising — a milestone that hasn't written
+    one yet (or has a stale one that fails validation) should still get a
+    design round pushed with whatever plain-language description its
+    tracking issue carries; the portal shows a design round with no listed
+    decomposition just fine.
+    """
+    from coord.milestone_order import WorkOrderError, parse_work_order  # noqa: PLC0415
+
+    try:
+        work_order = parse_work_order(tracking_issue_body)
+    except WorkOrderError:
+        work_order = None
+    decomposition = [
+        {
+            "issue_number": node.issue_number,
+            "group": node.group,
+            "after": list(node.after),
+        }
+        for node in (work_order.nodes if work_order is not None else ())
+    ]
+    outcome_definition = (
+        tracking_issue_body.strip()
+        or tracking_issue_title.strip()
+        or milestone_title
+    )
+    return {
+        "round": round_number,
+        "outcome_definition": outcome_definition,
+        "decomposition": decomposition,
+        "bundle_key": bundle_key,
+    }

{code_coordinator-0.5.202 → code_coordinator-0.5.204}/coord/portal_bridge.py

@@ -3,9 +3,12 @@
 **The gap this closes.** coord-portal has offered ``POST /api/bridge/push``
 since ms-1, and the entire ms-3 mail pipeline (``docs/CUSTOMER_PORTAL.md``) is
 live and waiting downstream of a queued outbox row — but nothing on this side
-has ever called it. This module is that client: a thin wrapper over the three
-bridge routes (``push``, ``pull``, ``heartbeat``), matching the wire contract
-coord-portal's ``src/bridge/*`` and ``src/routes/bridge.ts`` define.
+has ever called it. This module is that client: a thin wrapper over
+coord-portal's bridge routes (``push``, ``pull``, ``heartbeat``, and — as of
+PDR-3/#2508 — ``upload``), matching the wire contract coord-portal's
+``src/bridge/*`` and ``src/routes/bridge.ts`` define. ``upload`` is the one
+route that carries a bundle's raw content rather than D1 metadata — see
+:meth:`PortalBridgeClient.upload_bundle`.
 
 **What this module deliberately does NOT do**, per #2179's own framing —
 those are separate, harder design questions and belong to follow-up issues:
@@ -13,9 +16,13 @@ those are separate, harder design questions and belong to follow-up issues:
 * It does not decide **when** to push. Nothing here reads coord's board or
   watches assignment status transitions. Callers hand it
   ``(submission_id, revision, status)`` and it sends that; where those three
-  values come from — the submission↔work association, and the mapping from
-  coord's internal states to the portal's pinned customer vocabulary — is
-  out of scope here.
+  values come from is out of scope here. The submission↔work association is
+  now resolvable — :func:`coord.portal_store.get_milestone_link` reads the
+  durable ``(repo, milestone_number) -> submission_id`` mapping an operator
+  records with ``coord portal link`` (#2507) — but nothing in this module
+  calls it: this client still just sends whatever ``submission_id`` a caller
+  hands it. The mapping from coord's internal states to the portal's pinned
+  customer vocabulary is a separate, still-unaddressed question.
 * It does not persist a revision counter. The portal is idempotent by
   ``(submission_id, revision)`` and ignores anything at or below its stored
   watermark (see ``applyUpdate`` in coord-portal's ``src/bridge/updates.ts``),
@@ -315,6 +322,45 @@ class PortalBridgeClient:
         except ValueError as exc:
             raise PortalBridgeError(f"GET /api/bridge/pull: non-JSON response: {exc}") from exc
 
+    def upload_bundle(self, submission_id: str, files: dict[str, str]) -> str:
+        """``POST /api/bridge/upload`` — store a design round's rendered
+        mock bundle + contract in the portal's R2 (coord-portal#120, PDR-2).
+
+        Deliberately a fourth route, not folded into :meth:`push`: the
+        three ``/api/bridge/*`` routes this module otherwise speaks
+        (``push``/``pull``/``heartbeat``) carry only D1 metadata —
+        :func:`coord.portal_sync.enqueue_design_round`'s own docstring
+        already says the mock bundle itself "is not uploaded here". This is
+        that upload, kept separate so a bundle (arbitrarily large HTML) is
+        never accidentally routed through :data:`MAX_PUSH_UPDATES`-bounded
+        ``push`` batching.
+
+        *files* maps a path relative to the bundle root — e.g.
+        ``"contract.md"``, ``"mocks/index.html"`` — to its text content; see
+        :func:`coord.mock_author.collect_mock_bundle_files`, which builds
+        exactly this mapping by reading a merged Gate-A branch back off
+        GitHub. Returns the R2 object key the portal assigns the bundle —
+        callers thread that straight into the ``design_round`` payload
+        :func:`coord.portal_sync.enqueue_design_round` queues, so the
+        customer's browser has something to fetch. Raises
+        :class:`PortalBridgeError` the same way every other method here
+        does: a transport failure, a 401, a 4xx/5xx, or a response with no
+        usable ``bundle_key``.
+        """
+        if not files:
+            raise PortalBridgeError("upload_bundle() got an empty files mapping")
+        data = self._post(
+            "/api/bridge/upload",
+            {"submission_id": submission_id, "files": files},
+        )
+        bundle_key = data.get("bundle_key")
+        if not isinstance(bundle_key, str) or not bundle_key:
+            raise PortalBridgeError(
+                f"POST /api/bridge/upload: response had no 'bundle_key' "
+                f"string: {data!r}"
+            )
+        return bundle_key
+
 
 def _utcnow_iso() -> str:
     return (

{code_coordinator-0.5.202 → code_coordinator-0.5.204}/coord/portal_store.py

@@ -762,3 +762,135 @@ def note_error(error: str) -> None:
 
 def clear_error() -> None:
     _update_sync_state(last_error="")
+
+
+# ── #2507: milestone ↔ portal submission linkage ────────────────────────────
+#
+# Every table above is part of the sync bridge's own SQLite schema
+# (``coord.db``'s ``_ensure_schema``) and, per the module docstring, is
+# deliberately daemon-host-only. The link between a coord milestone and a
+# portal ``submission_id`` is a DIFFERENT kind of fact — nothing here creates
+# or drives it (the portal's own intake flow does, out of coord's sight) —
+# but it still needs the same durability and the same "read anywhere, write
+# on the daemon host" story, so it is persisted through
+# :mod:`coord.state`'s ``portal_links`` board_meta seam (same shape as
+# ``coord.gate_a``'s ``GateAApproval`` / ``gate_a_approvals``) rather than a
+# fifth table here. This is the domain half — :mod:`coord.state` only knows
+# plain dicts, this is where the dict shape is pinned down and given a
+# tolerant decoder.
+#
+# Consumers: PDR-3's auto-push (resolve a milestone's outbox destination) and
+# PDR-4's verdict consumer (resolve an inbound portal event back to a
+# milestone) both need exactly this lookup and have nowhere else to get it
+# (#2507 — confirmed by grep, ``submission_id`` appeared in neither
+# ``coord/config.py``, ``coord/milestone*.py``, nor ``coord/gate_a.py``
+# before this).
+
+_LINK_SCHEMA = 1
+
+
+@dataclass(frozen=True)
+class PortalLink:
+    """One durable ``(repo_name, milestone_number)`` → portal ``submission_id``
+    mapping, set by an operator with ``coord portal link`` once a submission
+    exists on the portal side.
+    """
+
+    repo_name: str
+    milestone_number: int
+    submission_id: str
+    linked_at: float = 0.0
+    actor: str = ""
+    schema: int = _LINK_SCHEMA
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "repo_name": self.repo_name,
+            "milestone_number": self.milestone_number,
+            "submission_id": self.submission_id,
+            "linked_at": self.linked_at,
+            "actor": self.actor,
+            "schema": self.schema,
+        }
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> "PortalLink | None":
+        """Tolerant decode — ``None`` for anything this build can't read.
+
+        Same posture as :meth:`coord.gate_a.GateAApproval.from_dict`: a
+        record written by a newer schema, or a corrupt one, degrades to "no
+        link recorded" rather than crashing a caller that resolves one
+        milestone at a time.
+        """
+        if not isinstance(raw, dict):
+            return None
+        if int(raw.get("schema", _LINK_SCHEMA) or _LINK_SCHEMA) != _LINK_SCHEMA:
+            return None
+        repo_name = raw.get("repo_name")
+        if not isinstance(repo_name, str) or not repo_name:
+            return None
+        milestone_number = _as_int_or_none(raw.get("milestone_number"))
+        if milestone_number is None:
+            return None
+        submission_id = raw.get("submission_id")
+        if not isinstance(submission_id, str) or not submission_id:
+            return None
+        return cls(
+            repo_name=repo_name,
+            milestone_number=milestone_number,
+            submission_id=submission_id,
+            linked_at=float(raw.get("linked_at") or 0.0),
+            actor=str(raw.get("actor") or ""),
+        )
+
+
+def _as_int_or_none(value: Any) -> int | None:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def link_milestone(
+    *,
+    repo_name: str,
+    milestone_number: int,
+    submission_id: str,
+    actor: str = "",
+    now: float | None = None,
+) -> PortalLink:
+    """Record (or overwrite) the portal submission_id for one milestone.
+
+    Overwrite, not append: there is exactly one live submission_id per
+    milestone, matching :func:`coord.state.save_gate_a_approval`'s semantics
+    for the same reason. Relinking is expected — an operator fixing a typo'd
+    submission_id, or correcting an id entered against the wrong milestone —
+    not an error case.
+    """
+    from coord import state  # noqa: PLC0415
+
+    record = PortalLink(
+        repo_name=repo_name,
+        milestone_number=int(milestone_number),
+        submission_id=submission_id,
+        linked_at=time.time() if now is None else now,
+        actor=actor,
+    )
+    state.save_portal_link(record.to_dict())
+    return record
+
+
+def get_milestone_link(*, repo_name: str, milestone_number: int) -> PortalLink | None:
+    """The current portal link for one milestone, or ``None`` if unlinked."""
+    from coord import state  # noqa: PLC0415
+
+    raw = state.get_portal_link(repo_name=repo_name, milestone_number=milestone_number)
+    return PortalLink.from_dict(raw) if raw is not None else None
+
+
+def list_milestone_links() -> list[PortalLink]:
+    """Every recorded milestone ↔ submission link."""
+    from coord import state  # noqa: PLC0415
+
+    links = [PortalLink.from_dict(raw) for raw in state.list_portal_links()]
+    return [link for link in links if link is not None]

{code_coordinator-0.5.202 → code_coordinator-0.5.204}/coord/portal_sync.py

@@ -177,11 +177,16 @@ def enqueue_design_round(
 ) -> portal_store.OutboxRow:
     """Queue a design round (the D1 metadata half) for *submission_id*.
 
-    The mock bundle itself is an R2 object and is **not** uploaded here: the
-    portal's upload route is not part of the three bridge routes this side
-    speaks (:mod:`coord.portal_bridge`), so *design_round* is expected to
-    already carry whatever reference the customer's browser will follow. What
-    this function guarantees is the ordering — see :func:`enqueue_status`.
+    The mock bundle itself is an R2 object and is **not** uploaded here:
+    that goes through :meth:`coord.portal_bridge.PortalBridgeClient.
+    upload_bundle` (coord-portal#120, PDR-2) — a separate call from the
+    three ``push``/``pull``/``heartbeat`` D1-metadata routes this queue
+    drains — so *design_round* is expected to already carry whatever
+    reference (the returned bundle key) the customer's browser will follow.
+    The auto-push caller (:mod:`coord.merge_queue`'s post-merge hook,
+    PDR-3/#2508) uploads first and passes the resulting key through
+    :func:`coord.mock_author.build_design_round`. What this function
+    guarantees is the ordering — see :func:`enqueue_status`.
     """
     if not isinstance(design_round, dict) or not design_round:
         raise PortalSyncError("design_round payload must be a non-empty mapping")