@ccoalm/ccl-skills 0.6.2 → 0.8.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/update_review_plan_intent.py

@@ -0,0 +1,513 @@
+#!/usr/bin/env python3
+"""Append or compact bounded intent without lossy truncation.
+
+The caller owns writer serialization and provides a trusted, stable parent
+directory. ``--expected-sha256`` rejects input that was already stale when
+opened; it is not a lock against concurrent writers.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import json
+import os
+import re
+import stat
+import sys
+import tempfile
+from pathlib import Path
+from typing import NoReturn
+
+
+MIN_INTENT_CHARS = 8
+MAX_INTENT_CHARS = 4000
+MAX_PLAN_BYTES = 32_000
+PLAN_FIELDS = {"intent", "acceptance", "self_review", "evidence"}
+SHA256_RE = re.compile(r"[0-9a-f]{64}")
+STABLE_CORE_EVIDENCE_ID = "review-plan-intent-stable-core-v1"
+STABLE_CORE_RESULT_RE = re.compile(r"chars=([1-9][0-9]{0,3});sha256=([0-9a-f]{64})")
+HISTORY_EVIDENCE_PREFIX = "review-plan-intent-history-v1"
+HISTORY_BASE64_CHUNK_CHARS = 1800
+MAX_EVIDENCE_ROWS = 50
+
+
+class UpdateError(Exception):
+    def __init__(self, reason: str, detail: str) -> None:
+        super().__init__(detail)
+        self.reason = reason
+        self.detail = detail
+
+
+class DuplicateKeyError(ValueError):
+    pass
+
+
+def reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise DuplicateKeyError
+        result[key] = value
+    return result
+
+
+def fail(reason: str, detail: str) -> NoReturn:
+    raise UpdateError(reason, detail)
+
+
+def read_regular(path: Path, *, label: str, max_bytes: int) -> tuple[bytes, int]:
+    if not hasattr(os, "O_NOFOLLOW") or not hasattr(os, "O_NONBLOCK"):
+        fail(
+            f"{label}_unsupported",
+            "this platform cannot safely open files without following links or blocking on special files",
+        )
+    flags = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | getattr(os, "O_CLOEXEC", 0)
+    fd = -1
+    try:
+        fd = os.open(path, flags)
+    except OSError as exc:
+        fail(f"{label}_unreadable", str(exc))
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode):
+            fail(f"{label}_not_regular", "expected a regular, non-symlink file")
+        if info.st_nlink != 1:
+            fail(f"{label}_hardlinked", "refusing a multiply-linked file")
+        if label == "plan" and hasattr(os, "geteuid") and info.st_uid != os.geteuid():
+            fail("plan_not_owned", "the plan must be owned by the current user")
+        if info.st_size > max_bytes:
+            fail(f"{label}_too_large", f"maximum is {max_bytes} bytes")
+        with os.fdopen(fd, "rb") as handle:
+            fd = -1
+            chunks: list[bytes] = []
+            remaining = max_bytes + 1
+            while remaining:
+                chunk = handle.read(min(65_536, remaining))
+                if not chunk:
+                    break
+                chunks.append(chunk)
+                remaining -= len(chunk)
+            data = b"".join(chunks)
+    except OSError as exc:
+        fail(f"{label}_unreadable", str(exc))
+    finally:
+        if fd >= 0:
+            os.close(fd)
+    if len(data) > max_bytes:
+        fail(f"{label}_too_large", f"maximum is {max_bytes} bytes")
+    return data, stat.S_IMODE(info.st_mode)
+
+
+def decode_utf8(data: bytes, *, label: str) -> str:
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        fail(f"{label}_invalid_utf8", f"invalid UTF-8 at byte {exc.start}")
+
+
+def digest(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def normalized_intent(
+    value: object, *, reason_prefix: str, minimum: int = MIN_INTENT_CHARS
+) -> str:
+    if not isinstance(value, str):
+        fail(f"{reason_prefix}_not_string", "intent must be a string")
+    stripped = value.strip()
+    if value != stripped:
+        fail(f"{reason_prefix}_not_normalized", "intent must not have outer whitespace")
+    if len(value) < minimum:
+        fail(f"{reason_prefix}_too_short", f"minimum is {minimum} characters")
+    return value
+
+
+def remove_file_line_ending(value: str) -> str:
+    """Remove only the one line ending used as a text-file delimiter."""
+    if value.endswith("\r\n"):
+        return value[:-2]
+    if value.endswith(("\n", "\r")):
+        return value[:-1]
+    return value
+
+
+def render_plan(plan: dict[str, object]) -> bytes:
+    try:
+        encoded = (json.dumps(plan, ensure_ascii=False, indent=2) + "\n").encode(
+            "utf-8"
+        )
+    except UnicodeEncodeError as exc:
+        fail("updated_plan_invalid_unicode", f"cannot encode UTF-8 at character {exc.start}")
+    if len(encoded) > MAX_PLAN_BYTES:
+        fail("updated_plan_too_large", f"maximum is {MAX_PLAN_BYTES} bytes")
+    return encoded
+
+
+def stable_core_identity(plan: dict[str, object]) -> tuple[int, str]:
+    evidence = plan.get("evidence")
+    if not isinstance(evidence, list):
+        fail("intent_core_identity_missing", "plan evidence has no stable-core identity")
+    records = [
+        item
+        for item in evidence
+        if isinstance(item, dict) and item.get("id") == STABLE_CORE_EVIDENCE_ID
+    ]
+    if not records:
+        fail("intent_core_identity_missing", "plan evidence has no stable-core identity")
+    if len(records) != 1:
+        fail("intent_core_identity_invalid", "plan must contain exactly one stable-core identity")
+    record = records[0]
+    if set(record) != {"id", "result"} or not isinstance(record.get("result"), str):
+        fail("intent_core_identity_invalid", "stable-core identity has an invalid schema")
+    match = STABLE_CORE_RESULT_RE.fullmatch(record["result"])
+    if match is None:
+        fail("intent_core_identity_invalid", "stable-core identity has an invalid encoding")
+    core_chars = int(match.group(1))
+    if not MIN_INTENT_CHARS <= core_chars <= MAX_INTENT_CHARS:
+        fail(
+            "intent_core_identity_invalid",
+            f"stable-core character length must be between {MIN_INTENT_CHARS} and {MAX_INTENT_CHARS}",
+        )
+    return core_chars, match.group(2)
+
+
+def text_digest(value: str, *, reason: str, label: str) -> str:
+    try:
+        return digest(value.encode("utf-8"))
+    except UnicodeEncodeError as exc:
+        fail(reason, f"{label} cannot encode as UTF-8 at character {exc.start}")
+
+
+def archive_discarded_intent(
+    plan: dict[str, object], *, old_intent: str, core: str
+) -> None:
+    """Retain the exact old intent bytes before compacting its visible field."""
+    suffix = old_intent[len(core) :]
+    if not suffix:
+        return
+    evidence = plan.get("evidence")
+    if not isinstance(evidence, list):
+        fail("intent_history_invalid", "plan evidence must be an array")
+    used_ids = {
+        item.get("id")
+        for item in evidence
+        if isinstance(item, dict) and isinstance(item.get("id"), str)
+    }
+    group = None
+    for group_number in range(1, MAX_EVIDENCE_ROWS + 1):
+        candidate_group = f"{group_number:04d}"
+        candidate_prefix = f"{HISTORY_EVIDENCE_PREFIX}-{candidate_group}"
+        if not any(
+            evidence_id == f"{candidate_prefix}-manifest"
+            or evidence_id.startswith(f"{candidate_prefix}-part-")
+            for evidence_id in used_ids
+        ):
+            group = candidate_group
+            break
+    if group is None:
+        fail("intent_history_full", "no unique intent-history evidence group remains")
+    try:
+        old_bytes = old_intent.encode("utf-8")
+        suffix_bytes = suffix.encode("utf-8")
+    except UnicodeEncodeError as exc:
+        fail(
+            "intent_history_invalid_unicode",
+            f"old intent cannot encode as UTF-8 at character {exc.start}",
+        )
+    encoded_suffix = base64.b64encode(suffix_bytes).decode("ascii")
+    chunks = [
+        encoded_suffix[index : index + HISTORY_BASE64_CHUNK_CHARS]
+        for index in range(0, len(encoded_suffix), HISTORY_BASE64_CHUNK_CHARS)
+    ]
+    prefix = f"{HISTORY_EVIDENCE_PREFIX}-{group}"
+    rows: list[dict[str, str]] = [
+        {
+            "id": f"{prefix}-manifest",
+            "result": (
+                f"format={HISTORY_EVIDENCE_PREFIX};"
+                f"old_chars={len(old_intent)};"
+                f"old_sha256={hashlib.sha256(old_bytes).hexdigest()};"
+                f"core_chars={len(core)};"
+                f"suffix_bytes={len(suffix_bytes)};"
+                f"suffix_sha256={hashlib.sha256(suffix_bytes).hexdigest()};"
+                f"encoding=base64-utf8;parts={len(chunks)}"
+            ),
+        }
+    ]
+    rows.extend(
+        {
+            "id": f"{prefix}-part-{part_number:04d}",
+            "result": (
+                f"format={HISTORY_EVIDENCE_PREFIX};group={group};"
+                f"part={part_number}/{len(chunks)};data={chunk}"
+            ),
+        }
+        for part_number, chunk in enumerate(chunks, start=1)
+    )
+    if len(evidence) + len(rows) > MAX_EVIDENCE_ROWS:
+        fail(
+            "intent_history_evidence_overflow",
+            f"zero-loss compaction needs {len(rows)} history rows but the plan "
+            f"would exceed {MAX_EVIDENCE_ROWS} evidence rows",
+        )
+    plan["evidence"] = [*evidence, *rows]
+
+
+def atomic_replace(path: Path, data: bytes, mode: int) -> None:
+    fd = -1
+    temp_path: Path | None = None
+    try:
+        try:
+            fd, raw_temp = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+            temp_path = Path(raw_temp)
+            with os.fdopen(fd, "wb") as handle:
+                fd = -1
+                handle.write(data)
+                handle.flush()
+                os.fchmod(handle.fileno(), mode)
+                os.fsync(handle.fileno())
+        except OSError as exc:
+            fail("plan_write_failed", str(exc))
+        try:
+            os.replace(temp_path, path)
+            temp_path = None
+        except OSError as exc:
+            fail("plan_write_failed", str(exc))
+        try:
+            directory_flags = (
+                os.O_RDONLY
+                | getattr(os, "O_DIRECTORY", 0)
+                | getattr(os, "O_CLOEXEC", 0)
+            )
+            directory_fd = os.open(path.parent, directory_flags)
+            try:
+                os.fsync(directory_fd)
+            finally:
+                os.close(directory_fd)
+        except OSError as exc:
+            fail(
+                "plan_committed_durability_unknown",
+                f"the target was replaced with sha256={digest(data)} but directory sync failed ({exc}); re-read the plan and do not retry blindly",
+            )
+    finally:
+        cleanup_errors: list[str] = []
+        if fd >= 0:
+            try:
+                os.close(fd)
+            except OSError as exc:
+                cleanup_errors.append(f"close failed: {exc}")
+        if temp_path is not None:
+            try:
+                temp_path.unlink()
+            except FileNotFoundError:
+                pass
+            except OSError as exc:
+                cleanup_errors.append(f"temporary-file removal failed: {exc}")
+        if cleanup_errors:
+            active_error = sys.exc_info()[1]
+            detail = "; ".join(cleanup_errors)
+            if isinstance(active_error, UpdateError):
+                detail = (
+                    f"{detail}; original failure was {active_error.reason}: "
+                    f"{active_error.detail}"
+                )
+            raise UpdateError("plan_cleanup_failed", detail)
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Update a review plan intent without lossy truncation. Overflow is "
+            "an error and leaves the plan unchanged."
+        )
+    )
+    parser.add_argument("--plan", required=True, type=Path)
+    parser.add_argument("--append-intent-file", type=Path)
+    parser.add_argument("--compact-core-intent-file", type=Path)
+    parser.add_argument("--latest-intent-file", type=Path)
+    parser.add_argument(
+        "--expected-sha256",
+        help="optional stale-input guard for the current plan bytes",
+    )
+    return parser.parse_args(argv)
+
+
+def run(argv: list[str]) -> int:
+    args = parse_args(argv)
+    append_mode = args.append_intent_file is not None
+    compact_mode = (
+        args.compact_core_intent_file is not None or args.latest_intent_file is not None
+    )
+    if append_mode == compact_mode or (
+        compact_mode
+        and (
+            args.compact_core_intent_file is None
+            or args.latest_intent_file is None
+        )
+    ):
+        fail(
+            "intent_update_mode_invalid",
+            "choose append, or supply both compact core and latest intent files",
+        )
+    plan_bytes, plan_mode = read_regular(
+        args.plan, label="plan", max_bytes=MAX_PLAN_BYTES
+    )
+    if plan_mode & 0o7000:
+        fail("plan_mode_unsupported", "setuid, setgid, and sticky plan modes are unsupported")
+    plan_mode &= 0o777
+    current_digest = digest(plan_bytes)
+    if args.expected_sha256 is not None:
+        expected = args.expected_sha256.lower()
+        if SHA256_RE.fullmatch(expected) is None:
+            fail("expected_sha256_invalid", "expected exactly 64 hexadecimal characters")
+        if expected != current_digest:
+            fail("plan_digest_mismatch", "the plan changed after the caller read it")
+
+    try:
+        plan = json.loads(
+            decode_utf8(plan_bytes, label="plan"),
+            object_pairs_hook=reject_duplicate_keys,
+        )
+    except DuplicateKeyError:
+        fail("plan_duplicate_key", "duplicate JSON object keys are unsupported")
+    except json.JSONDecodeError as exc:
+        fail("plan_invalid_json", f"JSON parse failed at line {exc.lineno} column {exc.colno}")
+    if not isinstance(plan, dict) or set(plan) != PLAN_FIELDS:
+        fail("plan_schema_invalid", "top-level fields must be intent, acceptance, self_review, evidence")
+    old_intent = normalized_intent(plan["intent"], reason_prefix="plan_intent")
+
+    if append_mode:
+        if len(old_intent) > MAX_INTENT_CHARS:
+            fail("plan_intent_overflow", f"maximum is {MAX_INTENT_CHARS} characters")
+        incoming_bytes, _ = read_regular(
+            args.append_intent_file, label="intent_input", max_bytes=MAX_PLAN_BYTES
+        )
+        incoming = remove_file_line_ending(
+            decode_utf8(incoming_bytes, label="intent_input")
+        )
+        if not incoming:
+            fail("intent_append_empty", "append input must not be empty")
+        candidate = old_intent + incoming
+        reason_prefix = "intent_append"
+    else:
+        core_bytes, _ = read_regular(
+            args.compact_core_intent_file,
+            label="intent_core",
+            max_bytes=MAX_PLAN_BYTES,
+        )
+        latest_bytes, _ = read_regular(
+            args.latest_intent_file,
+            label="intent_latest",
+            max_bytes=MAX_PLAN_BYTES,
+        )
+        core = normalized_intent(
+            remove_file_line_ending(decode_utf8(core_bytes, label="intent_core")),
+            reason_prefix="intent_core",
+        )
+        latest = normalized_intent(
+            remove_file_line_ending(decode_utf8(latest_bytes, label="intent_latest")),
+            reason_prefix="intent_latest",
+            minimum=1,
+        )
+        if not old_intent.startswith(core):
+            fail(
+                "intent_core_not_preserved",
+                "compact core must be an exact prefix of the current intent",
+            )
+        if latest in old_intent:
+            fail(
+                "intent_latest_not_new",
+                "latest transition is already present in the current intent",
+            )
+        core_chars, core_sha256 = stable_core_identity(plan)
+        if len(old_intent) < core_chars:
+            fail(
+                "plan_core_identity_mismatch",
+                "current intent is shorter than its persisted stable-core identity",
+            )
+        persisted_core = old_intent[:core_chars]
+        if text_digest(
+            persisted_core,
+            reason="plan_core_identity_mismatch",
+            label="persisted stable core",
+        ) != core_sha256:
+            fail(
+                "plan_core_identity_mismatch",
+                "persisted stable-core identity does not match the current intent",
+            )
+        if len(core) != core_chars or text_digest(
+            core,
+            reason="intent_core_identity_mismatch",
+            label="compact core",
+        ) != core_sha256:
+            fail(
+                "intent_core_identity_mismatch",
+                "compact core does not match the plan's persisted stable-core identity",
+            )
+        archive_discarded_intent(plan, old_intent=old_intent, core=core)
+        candidate = f"{core}\n\n{latest}"
+        reason_prefix = "intent_compact"
+
+    candidate = normalized_intent(candidate, reason_prefix=reason_prefix)
+    if len(candidate) > MAX_INTENT_CHARS:
+        fail(
+            f"{reason_prefix}_overflow",
+            f"candidate has {len(candidate)} characters; maximum is {MAX_INTENT_CHARS}; rebuild intent as core + latest and keep history in evidence/prior results",
+        )
+
+    plan["intent"] = candidate
+    updated = render_plan(plan)
+    atomic_replace(args.plan, updated, plan_mode)
+    # flush inside the guarded path: without it the receipt sits in the stdout
+    # buffer and a closed pipe only surfaces BrokenPipeError at interpreter
+    # shutdown, after main() returned rc 0 and past its handler.
+    print(
+        "review_plan_intent_updated "
+        f"mode={'append' if append_mode else 'compact'} "
+        f"chars={len(candidate)} old_sha256={current_digest} new_sha256={digest(updated)}",
+        flush=True,
+    )
+    return 0
+
+
+def main() -> int:
+    try:
+        return run(sys.argv[1:])
+    except UpdateError as exc:
+        print(
+            f"review_plan_intent_error: reason={exc.reason} detail={exc.detail}",
+            file=sys.stderr,
+        )
+        return 2
+    except (BrokenPipeError, OSError):
+        # The success receipt is printed (flushing) only after atomic_replace
+        # committed, and every other file operation converts its OSError to
+        # UpdateError, so an OS-level error here means the receipt was lost on
+        # a closed/broken stdout — not that the update failed. rc 0 with no
+        # receipt would read as "no update happened"; report the committed-but-
+        # unreported state the same way a failed durability sync does.
+        try:
+            print(
+                "review_plan_intent_error: reason=plan_committed_receipt_lost "
+                "detail=stdout closed before the success receipt was delivered; "
+                "re-read the plan for the committed state and do not retry blindly",
+                file=sys.stderr,
+            )
+            sys.stderr.flush()
+        except (BrokenPipeError, OSError):
+            pass
+        # Point stdout at devnull so the interpreter's shutdown flush of the
+        # broken pipe cannot override this exit status with 120.
+        try:
+            devnull = os.open(os.devnull, os.O_WRONLY)
+            os.dup2(devnull, sys.stdout.fileno())
+            os.close(devnull)
+        except (OSError, ValueError):
+            pass
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: go-microservice-architecture
-description: Use when designing, reviewing, or explaining a new product's Go backend or microservice architecture using Kitex or similar RPC, Hertz or similar HTTP gateway, protobuf IDL, MySQL/GORM-style relational storage, Redis cache/locks/rate limiting, service discovery, dynamic config, message queues, observability, DI, and code generation. Product-agnostic; do not depend on existing codebase paths, service names, or legacy repositories. Prefer this for architecture, service boundaries, contracts, data ownership, reliability, security, and platform decisions when no code changes are requested; use go-microservice-dev for implementation work. Triggers also include "Go 后端架构怎么设计", "Go 微服务怎么拆", "RPC 接口怎么定义", "Go 服务边界", "Go 服务重构 / 架构分层重构", "拆分 Go 服务的上帝类/模块边界", "decompose a god class in a Go service".
+description: Design, review, or explain a new product's Go backend/microservice architecture using Kitex or similar RPC, Hertz or similar HTTP gateway, protobuf IDL, MySQL/GORM storage, Redis cache/locks/limits, service discovery, dynamic config, message queues, observability, DI, and code generation. Also owns multi-tenant isolation, event-driven/Kafka, and data-platform (sharding/replicas/HA) architecture. Product-agnostic; no dependence on existing codebase paths, service names, or legacy repos. Prefer this for architecture/boundary/contract/data-ownership/reliability/security/platform decisions with no code changes; use go-microservice-dev for implementation. Triggers include "Go 后端架构怎么设计", "Go 微服务怎么拆", "RPC 接口怎么定义", "Go 服务边界", "Go 服务重构 / 架构分层重构", "拆分 Go 服务的上帝类/模块边界 / decompose a god class".
 ---
 
 # Go Microservice Architecture

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/architecture-playbook.md

@@ -101,6 +101,8 @@ Not appropriate for:
 
 ## Dependency Direction
 
+This layering is the **[Ports-and-Adapters / Hexagonal](https://alistair.cockburn.us/hexagonal-architecture/)** idea in moderation (Alistair Cockburn; borrowed scope: the ports/adapters placement idea only, not the full pattern vocabulary) — infrastructure adapters sit behind interfaces the inner layers own.
+
 Recommended:
 
 ```text

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/data-platform-architecture.md

@@ -4,7 +4,7 @@ Use when designing the data-platform substrate of a service or service-fleet: DB
 
 This complements `data-modeling-and-migrations.md` (which owns schema, index, transaction, outbox, and per-service migration concerns): this file owns the **substrate** that schema and queries sit on. Load both when designing a new data-bound service or auditing an existing one.
 
-> **Sibling sync.** A parallel `python-service-architecture/references/data-platform-architecture.md` mirrors **all non-stack-specific sections** of this file. Only the *Go-specific implementation patterns* section diverges by stack. The mirrored sections stay free of three categories of stack-specific token: DB-engine-specific syntax, runtime/concurrency-mechanic names, and library/framework API names. The concrete token list and grep command live in the *Mirrored-section grep gate* subsection at the end of this file's stack-glue.
+> **Sibling sync.** A parallel `python-service-architecture/references/data-platform-architecture.md` mirrors **all non-stack-specific sections** of this file. Only the *Go-specific implementation patterns* section diverges by stack. The mirrored sections stay free of three categories of stack-specific token: DB-engine-specific syntax, runtime/concurrency-mechanic names, and library/framework API names. The concrete token list and grep command live in the *Mirrored-section grep gate* subsection at the end of this file's stack-glue. Tree-specific routing references are written inline for both trees so the mirrored bytes stay identical; cross-file parity is machine-checked by `skill-extraction-workflow/scripts/check-parallel-stack-parity.sh` (wired into `check-ccl-skills.sh`), which diffs the mirrored regions byte-for-byte (no normalization) and blocks on any divergence.
 
 > **Sanitization boundary.** Vendor names (PostgreSQL, MySQL, Vitess, TiDB, CockroachDB, Aurora, Cloud Spanner, AlloyDB, Cloud SQL, DynamoDB, RDS Proxy, PgBouncer, ProxySQL, S3, Glacier, gp3, io2, etc.) below are illustrative; concrete topology choices, region names, cluster identifiers, and capacity numbers live only in the maintainer's private alias map. The sanitization audience list is positive (external / client / regulator / SOC / procurement / internal-compliance / sales-engineering / partner draft / forwardable-internal); sanitize before any document leaves the implementation team's approved audience.
 >

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/event-driven-architecture.md

@@ -6,7 +6,7 @@ Scope split with the sibling `mq-consumer-architecture.md` (which covers consume
 
 > **Conforms to the parallel-stack references pattern.** This file follows the layout documented in `skill-extraction-workflow/references/parallel-stack-references-pattern.md`: mirrored stack-agnostic core (when-applies through operations checklist), stack-specific implementation patterns section, and the embedded `### Mirrored-section grep gate` at the end of the stack-glue. The sibling `python-service-architecture/references/event-driven-architecture.md` mirrors the same structure. Either this file or `multi-tenant-isolation.md` may be used as a template for new parallel-stack extractions; multi-tenant additionally demonstrates the `## Topic-extension backlog` H2 for topic-wider-than-loop cases.
 
-> **Sibling sync.** A parallel `python-service-architecture/references/event-driven-architecture.md` mirrors **all non-stack-specific sections** of this file (when-applies/not-applies, delivery semantics, event vs command vs query, idempotency, outbox, ordering, schema evolution, retry/DLQ/replay, backpressure, fanout, saga, end-to-end exactly-once, anti-patterns, operations checklist). Only the *Go-specific implementation patterns* section diverges by stack. Maintainers updating any mirrored section here must update the sibling in the same change to prevent drift.
+> **Sibling sync.** A parallel `python-service-architecture/references/event-driven-architecture.md` mirrors **all non-stack-specific sections** of this file (when-applies/not-applies, delivery semantics, event vs command vs query, idempotency, outbox, ordering, schema evolution, retry/DLQ/replay, backpressure, fanout, saga, end-to-end exactly-once, anti-patterns, operations checklist). Only the *Go-specific implementation patterns* section diverges by stack. Maintainers updating any mirrored section here must update the sibling in the same change to prevent drift. Tree-specific routing references are written inline for both trees so the mirrored bytes stay identical; cross-file parity is machine-checked by `skill-extraction-workflow/scripts/check-parallel-stack-parity.sh` (wired into `check-ccl-skills.sh`), which diffs the mirrored regions byte-for-byte (no normalization) and blocks on any divergence.
 
 > **Sanitization boundary.** The named brokers (Kafka, Pulsar, RabbitMQ, NATS JetStream, Redis Streams) and libraries below are concrete examples for **internal** implementation guidance, scoped to the implementation team's approved audience. Before this file (or excerpts) is copied into any document leaving that audience — external / client-facing materials, customer-specific deliverables, regulator or auditor evidence packages, SOC / compliance reports, procurement responses, or partner architecture appendices — replace the named choices with generic categories (`the broker`, `a partitioned log`, `a confirm-mode AMQP queue`) unless the vendor selection is already approved for disclosure to that specific audience.
 
@@ -20,8 +20,8 @@ Apply when the service:
 
 Skip when the service:
 - only does in-process pub-sub or fire-and-forget logging,
-- uses synchronous RPC with no durable async boundary (use `protobuf-contract-architecture.md` instead),
-- uses a job queue purely for in-tenant background work where loss is acceptable (use `notification-architecture.md` or `bulk-workflow-architecture.md`).
+- uses synchronous HTTP/RPC with no durable async boundary (use `api-contract-and-schema.md` on the Python tree / `protobuf-contract-architecture.md` on the Go tree instead),
+- uses a job queue purely for in-tenant background work where loss is acceptable (use `background-jobs-and-scheduling.md` or `batch-and-pipeline-architecture.md` on the Python tree / `notification-architecture.md` or `bulk-workflow-architecture.md` on the Go tree).
 
 ## Delivery semantics taxonomy
 
@@ -39,7 +39,7 @@ The semantic shape determines ownership, schema, and retry posture:
 
 - **Event** — a fact about something that happened. Past tense. Owned by the producer. Many consumers may subscribe. Schema evolves with backward-compatible additions; semantic meaning is fixed once published.
 - **Command** — a request to do something. Imperative. Owned by the recipient's contract. Typically one consumer (a command handler). May fail validation and be rejected; the sender is told.
-- **Query** — a request for state. Synchronous RPC or query API, not a durable message. If you find yourself sending a query as a message, you probably want a query API plus an event subscription for change notifications.
+- **Query** — a request for state. Synchronous HTTP/RPC or query API, not a durable message. If you find yourself sending a query as a message, you probably want a query API plus an event subscription for change notifications.
 
 Mixing these confuses ownership: a command consumer that drops the message because "it's an event, consumers are best-effort" is a bug; an event producer that retries indefinitely because "it's a command, must deliver" creates head-of-line blocking.
 
@@ -77,7 +77,7 @@ The outbox pattern makes "write to DB and publish event" atomic without distribu
 
 Without one of these (and its prerequisites), `SKIP LOCKED` and per-key ordering are mutually exclusive — pick which property the outbox actually delivers and document it on the event contract.
 
-Inbox (the dual) is rarer in Go services: when a consumer must read a message and produce a side effect in a different system atomically, the consumer writes the inbox record + side effect in one DB tx, then acks the broker. On crash before ack, redelivery hits the inbox row and skips the side effect.
+Inbox (the dual) is rarer: when a consumer must read a message and produce a side effect in a different system atomically, the consumer writes the inbox record + side effect in one DB tx, then acks the broker. On crash before ack, redelivery hits the inbox row and skips the side effect.
 
 ## Delivery ordering
 
@@ -100,13 +100,13 @@ Events outlive the producer's current code. Schema discipline is non-negotiable:
 - **Security / compliance exception** — when continuing to emit a field is itself the problem (leaky PII field, secret accidentally embedded, regulator-mandated retraction), additive-only is overruled. The path is: create a new event version that omits the field, inventory active consumers, deploy a coordinated emergency migration plan (consumer flips first, producer flips second, old version retired), and define historical-data handling (purge, redaction in archives, controlled access). Document the security trigger; this path is not the default deprecation flow.
 - **Rolling deprecation (the default)** — create a new event type or version, dual-publish or dual-read across a compatibility window, migrate consumers with monitoring and a rollback path, then retire the old version after explicit approval. Do not stop-the-world.
 - **Schema discovery model** — choose by audience:
-  - *Single-team, single-broker boundary*: in-payload schema or schema embedded in the protobuf/Avro descriptor is acceptable.
+  - *Single-team, single-broker boundary*: in-payload schema or a model-derived schema (from the service's typed model layer) in the envelope header is acceptable.
   - *Multi-team, single-broker fanout*: a schema registry (Confluent-style or self-hosted) validates compatibility at build/deploy time.
   - *Multi-broker, multi-tenant, or external consumers* (webhooks, partner integrations, tenant-private contracts): hybrid — versioned envelope (`event_type`, `event_version`) in payload + per-tenant contract catalog/registry where available + signed schema references for external consumers + broker-specific validation gates. Neither a single registry nor in-payload alone is sufficient.
 - **Metadata leakage in cross-trust boundaries** — for external or multi-tenant contracts, the schema discovery layer itself can leak. `event_type` strings, version names, registry paths, enum labels, and catalog visibility can reveal unreleased products, regulated workflows, internal team structure, or tenant-specific capabilities even when payload fields are field-level protected. Before publishing to an external boundary: classify each of (`event_type`, `event_version`, schema-reference path, registry namespace, enum values, error codes, catalog listings) by audience; use opaque public aliases (`event_type=ext.<opaque-name>`, namespace-by-tenant-without-tenant-name) where the internal name is sensitive; never let an internal event type cross the boundary as-is.
 - **Breaking change discipline** — a semantic-level breaking change (a field's meaning changes, an enum value is repurposed) is not caught by schema compatibility checks. Document semantic changes; coordinate consumer rollout before publishing the new shape.
 
-For Go services using protobuf for events, see also `protobuf-contract-architecture.md` for `message`/`enum`/`oneof` evolution rules.
+For event payloads modelled with the service's typed-model layer, freeze the model at publish time and version the envelope; the producer's evolving model must not reach the wire without a registered new version. The stack-glue section names the specific model library and freezing pattern.
 
 ## Retry, dead-letter, replay
 
@@ -135,11 +135,11 @@ Document which fixture class is used and which classes are deliberately not cove
 Consumer lag, broker queue depth, and producer rate are the three backpressure signals. Wire them:
 
 - **Consumer-side** — bound the work-in-flight, but **the shape depends on ordering**:
-  - *Unordered consumer*: a bounded work-queue sized to the worker pool, N workers reading from the queue; shutdown via the request/service cancellation signal (the stack-glue section names the specific primitive). Order of completion is undefined.
-  - *Ordered partitioned log* (Kafka, Pulsar key-shared, NATS JetStream ordered consumer): **one serial work lane per assigned partition/key**. Feed each partition into its own bounded channel + single worker, or process messages serially within the partition's poll loop. Feeding multiple ordered partitions into a single shared bounded channel + worker pool loses per-partition ordering, and a slow message on one partition can starve cold partitions or let later offsets overtake earlier ones. The bounded-queue-plus-pool shape is correct for unordered work queues; not for ordered partitioned logs.
+  - *Unordered consumer*: a bounded work-queue sized to the worker pool, N workers reading from the queue. A shared shutdown signal stops the workers (the stack-glue section names the specific primitive). Order of completion is undefined.
+  - *Ordered partitioned log* (Kafka, Pulsar key-shared, NATS JetStream ordered consumer): **one serial work lane per assigned partition/key**. Feed each partition into its own bounded work-queue + single worker, or process messages serially within the partition's poll loop. Feeding multiple ordered partitions into a single shared work-queue + worker pool loses per-partition ordering, and a slow message on one partition can starve cold partitions or let later offsets overtake earlier ones. The bounded-queue-plus-pool shape is correct for unordered work queues; not for ordered partitioned logs.
   - *Rebalance handling for partition-assigned consumers* — when a Kafka / Pulsar key-shared / similar consumer group rebalances and a partition is revoked, "one lane per partition" is unsafe without explicit rebalance discipline. The revoked owner must (1) stop fetching from the partition immediately, (2) drain or cancel its in-flight lane (await handler completion to a bounded deadline, or cancel with an explicit `partial-failure` disposition), (3) commit or abort offsets according to the handler outcome (commit only completed offsets; do not commit `last poll` blindly), and (4) be fenced so it cannot still publish a side effect after the new owner has started — typically by tagging each in-flight message with the assignment epoch and refusing side effects whose epoch is stale. Without fencing, the new owner and the old owner can process the same business key concurrently; per-partition ordering at steady state is meaningless if the rebalance window allows concurrent processing.
   - Avoid unbounded worker-per-message fanout in all cases (the stack-glue section names the specific anti-pattern API).
-- **Producer-side** — when the broker buffer fills (Kafka producer queue, NATS slow-consumer warning), block the producer's caller with a bounded wait or shed load at the producer entry point. Never block forever; surface a typed error after a bounded wait so upstream can backpressure further.
+- **Producer-side** — when the broker buffer fills (Kafka producer queue, RabbitMQ unconfirmed-publishes limit, NATS slow-consumer warning), block the producer's caller with a bounded wait or shed load at the producer entry point. Never block forever; surface a typed error after a bounded wait so upstream can backpressure further.
 - **Cross-service** — a slow consumer is an upstream producer's problem to know about. Consumer lag must be exposed as a metric and alerted; producers cannot fix what they cannot see.
 
 ## Fanout patterns
@@ -187,6 +187,8 @@ Stack-agnostic recipe; document each clause for every event-driven boundary that
 
 If any clause is missing, the boundary is at-least-once with duplicates. Tell consumers honestly.
 
+External grounding (adopted in part): this recipe is an instance of the end-to-end argument — [Saltzer, Reed & Clark, *End-to-End Arguments in System Design*, ACM TOCS 2(4), 1984](https://web.mit.edu/Saltzer/www/publications/endtoend/endtoend.pdf) — a function that "can completely and correctly be implemented only with the knowledge and help of the application standing at the endpoints of the communication system" cannot be delegated to the communication layer, and broker-level transactional features are that paper's "incomplete version … useful as a performance enhancement", never the end-to-end guarantee. Borrowed scope: the placement argument only; the five-clause recipe and the atomic-domain boundary are this skill's own operational criteria.
+
 ## Anti-patterns
 
 - **Post-commit publish (durable cross-process)** — publishing the event after the DB transaction commits, without an outbox, when consumers are in another process. A crash between commit and publish silently drops the event. In-process, same-instance, rebuildable post-commit hooks are not this anti-pattern.
@@ -198,7 +200,7 @@ If any clause is missing, the boundary is at-least-once with duplicates. Tell co
 - **DLQ as graveyard** — messages land in DLQ, nobody looks, no replay tooling. The DLQ becomes a silent data-loss channel.
 - **Exactly-once claimed by broker badge** — broker config has an "exactly-once" mode, but the consumer is not idempotent and the producer is not transactional, OR the side effect is outside the atomic domain. The claim is wrong; record correct end-to-end semantics.
 - **Producer-held subscriber list as code** — subscriber list hardcoded at the producer when broker-side subscription is possible. (CDC bridges and webhook dispatchers are exceptions; their lists must live as config with audit and rotation.)
-- **Sync RPC as command** — a "command" sent via blocking RPC with retry and no replay path. If the call needs the durability of a queue, use a queue; if it needs the latency of RPC, accept best-effort.
+- **Sync HTTP/RPC as command** — a "command" sent via blocking HTTP/RPC with retry and no replay path. If the call needs the durability of a queue, use a queue; if it needs the latency of HTTP/RPC, accept best-effort.
 
 ## Operations checklist (event-driven boundary launch)
 
@@ -231,6 +233,7 @@ These are stack-localized recipes that implement the stack-agnostic patterns abo
   3. **Mark-sent tx (short)**: `BEGIN; UPDATE outbox SET sent_at = NOW(), processing_until = NULL WHERE id = $id AND owner = $owner; COMMIT;` — guarded by `owner` so a re-leased row (after the original lease expired) is not double-marked.
   4. **Abandon tx**: after K publish failures, mark row `abandoned` and alert; do not block the partition key forever on a poison row (see the *Dispatcher that refuses to publish `id=N+1`* strategy).
   For per-key ordering across HA pollers, layer one of the strategies in *SKIP LOCKED and per-key ordering* (hash-routed publisher by `hash(partition_key) MOD N`, per-key advisory lease via the DB's advisory-lock primitive — PostgreSQL `pg_try_advisory_xact_lock(hashtext(partition_key))` for tx-scoped locks bound to the connection's current transaction; MySQL `GET_LOCK(name, timeout)` with explicit session-scoped semantics (release explicitly on success or stall, or rely on session close), and lock names server-wide-scoped so use a fully-bounded namespaced name `lk:<env8>:<svc8>:<purpose8>:<hash16>` (total length = 46 chars including separators, fits inside MySQL's 64-char limit; `<env8>`, `<svc8>`, `<purpose8>` are generated from the canonical environment / service / purpose identities by a **documented deterministic function** (e.g., first-8-of-base32(SHA256(canonical_identity))) or allocated from a **collision-checked registry** — human-readable abbreviations are NOT acceptable unless the registry proves uniqueness in the MySQL server-wide lock namespace; `<hash16>` is the first 16 chars of base32(SHA256(length-prefixed-encoding(canonical_partition_key, versioned_namespace))) — e.g., `SHA256(len(pk) + ':' + pk + len(ns) + ':' + ns)` or canonical JSON/CBOR over `[canonical_partition_key, versioned_namespace]`; raw `pk + ':' + ns` concatenation is **not** acceptable because real partition keys (`acme:prod`, `order:123`, user-supplied ids) can contain `:` and the resulting hash input is not injective. **Namespace-migration safety**: changing `versioned_namespace` requires either a drain / stop-the-world for the poller lane, or a dual-lock period (acquire old + new lock names in canonical order) so that mixed namespace versions across a rolling deploy / rollback cannot acquire different locks for the same partition key and publish concurrently. Without this, a version bump silently splits the per-key serialization lane.), and avoid MySQL NDB / multi-mysqld setups where `GET_LOCK` is not cluster-wide; TiDB supports MySQL-style user-level locks (`GET_LOCK`) cluster-wide in supported versions — verify timeout / deadlock semantics for the deployed TiDB version against a scenario-specific compatibility source: **pinned cluster** → checked-in version pin; **managed channel (TiDB Cloud)** → provider channel/SLA *and* current cluster version (channel alone is insufficient — the version still varies inside the channel); **rolling-upgrade fleet** → min/max active versions across the fleet plus the documented rolling-upgrade policy; **ad-hoc verification** → recorded `tidb_version()` output that includes cluster identity and timestamp. Otherwise fall back to an external coordinator (etcd lease, Redis `SET NX` with TTL) with fencing — with bounded TTL and a fencing token written with each publish; or refuse-newer-id dispatcher with abandoned-row state).
+- **Event payload freezing** — the typed-model layer for Go event payloads is protobuf: freezing means serializing the payload to immutable bytes (marshal, or deep-copy then marshal) at the enqueue/publish boundary and binding those bytes to the envelope (`event_type`, `event_version`) — pinning the generated artifact version fixes the schema, not the instance: a queued mutable message object mutated before serialization changes the wire payload despite the pinned schema. See `protobuf-contract-architecture.md` for `message`/`enum`/`oneof` evolution rules.
 - **Idempotency storage** — pick by impact (see *Idempotency design*):
   - Lossy/rebuildable: Redis `SET dedup:<key> 1 EX <window> NX`, branch on success/skip.
   - Source-of-truth: insert into a `processed_events` table with `event_id` as primary key inside the side-effect transaction; on duplicate-key error, skip. Optionally cache the recent N keys in Redis as a hot-path filter, but Redis is not the authority.