@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/cross-cutting-concerns.md

@@ -0,0 +1,72 @@
+# Cross-Cutting Concerns
+
+## Error Model
+
+- Define a small canonical error taxonomy: success, invalid input, unauthorized, forbidden, not found, conflict, dependency failure, timeout, panic/internal.
+- Keep internal error causes in logs and traces; expose stable code/message pairs to clients.
+- Map transport-native failures into the canonical model:
+  - HTTP status and response body should agree.
+  - RPC domain errors should preserve code/message across client and server middleware.
+  - Worker failures should explicitly decide retry, dead-letter, or skip.
+- Do not let raw dependency errors become public API contracts.
+
+## Context Propagation
+
+- Every inbound request creates or accepts a trace/log id, then returns it in the response metadata where possible.
+- Carry lane/environment, authorization/resource scope, auth subject, and request deadline through HTTP, RPC, DB, Redis, MQ, and external HTTP calls.
+- Async producers should put trace/log metadata into the message when the queue supports it; consumers should create a new log id only when none exists.
+- Avoid storing context values that are domain inputs better represented as typed request fields.
+
+## Auth And Permission Boundary
+
+- Split authentication from authorization.
+- Authentication resolves the subject, token/session state, resource scope, and client application.
+- Authorization checks whether that subject can perform the operation on the target resource.
+- Public bypass paths such as health/debug/login must be explicit and prefix-safe.
+- Permission checks should be injectable so product-specific policy can evolve without rewriting transport middleware.
+
+## Internal Service Trust
+
+- Treat internal RPC and internal HTTP as separate trust boundaries from public API, not as automatically trusted traffic.
+- Prefer workload identity, mTLS, signed service tokens, or an equivalent service identity mechanism for service-to-service calls.
+- Authorize service callers by operation and resource scope when a service boundary protects sensitive data or side effects.
+- Propagate caller service identity separately from end-user subject so audit logs can distinguish user action from service delegation.
+- Bypass rules for internal health, readiness, or discovery endpoints must be explicit and narrower than ordinary internal APIs.
+
+## Timeout Budgeting
+
+- Set default timeouts for every transport and dependency.
+- Allow method-specific overrides for high-latency operations, but keep an upper bound.
+- Honor the caller's context deadline when it is shorter than the local default.
+- For RPC clients, separate connection timeout from request timeout.
+- For background jobs, set both lock lease and max execution time.
+
+## Observability Contract
+
+- Metrics should cover QPS, latency, success, error by canonical error code, panic count, dependency latency, queue lag, retry count, and job duration.
+- Attach low-cardinality tags: service, method/API/job, environment/lane, caller/callee, and canonical error code.
+- Logs should include trace/log id and safe domain identifiers, but avoid request/response bodies unless gated by environment/config.
+- Long-running requests/jobs should have heartbeat or progress visibility when they can exceed normal latency windows.
+
+## Admission Control And Backpressure
+
+- Define inbound request limits by route/method, caller, authorization scope, or operation cost before traffic grows.
+- Use concurrency limits for expensive handlers and worker pools; queue only when bounded wait time and cancellation behavior are defined. Do not share one concurrency/resource budget across workloads with different lifetime profiles (short unary request vs long-lived stream); give each a separate, opt-in budget, and validate the interdependent budget fields as a set rather than individually.
+- Load shedding should return a stable canonical error and emit metrics that separate overload from dependency failure.
+- Circuit breakers protect dependency calls and high-cost workflows; define open, half-open, and recovery behavior explicitly.
+- Backpressure must be visible to upstream callers through retry-after hints, queue depth, or rejection metrics where the protocol supports it.
+
+## Streaming And Large Payloads
+
+- Streaming RPC, server-sent events, WebSocket, upload, and download paths need explicit connection lifetime, idle timeout, max message/body size, and cancellation behavior.
+- Validate content type, content length, file extension, and object metadata before expensive processing.
+- Outbound file or URL fetches need scheme/host allowlists, redirect policy, size limits, content-type checks, and private-network protection.
+- Temporary files and generated artifacts need namespace, quota, cleanup owner, and failure cleanup policy.
+- Stream progress, partial failure, and client disconnects should map to stable errors and metrics.
+
+## Context Propagation Boundary
+
+- The set of ctx keys a portfolio relies on is platform contract, not per-service convenience. Architecture defines tiers: global keys carried on every request (trace/log id, PSM/service identity, lane, IDC, cluster, stress tag), API-context keys derived after gateway auth (user, tenant, organization, role), and inbound HTTP header mappings (`X-*` → canonical ctx name).
+- Every ctx key has a typed accessor; bare-string `ctx.Value(...)` returning `any` is an architecture finding, not an idiom to spread. Type assertion lives behind helpers, not in domain code.
+- For frameworks that propagate metadata over the wire, define which keys travel persistently (every downstream hop forwards them) versus transiently (one hop only). Lane, stress tag, and trace identity are typically persistent; one-off control flags should not be promoted to persistent.
+- Dual-injection compatibility: when one binary serves multiple transports (TTHeader Thrift + HTTP/2 gRPC), the propagation layer writes to both the framework's persistent value (`metainfo.WithPersistentValue`) and the transport's outgoing metadata so the framework's meta handler picks the right wire format at send time. Application code stays transport-agnostic.

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

@@ -0,0 +1,79 @@
+# Data Modeling And Migrations
+
+Use this when designing relational data ownership, schema, indexes, migrations, sharding, or generated DAL boundaries for a Go microservice.
+
+## Ownership
+
+- Each service owns its write schema. Other services should not write owned tables directly.
+- Cross-service reads should use RPC/API, events, or explicit read models.
+- Shared database servers are an infrastructure detail; shared write ownership is an architecture smell.
+- A table should have a clear owning service, lifecycle owner, retention policy, and operational contact.
+
+## Schema Design
+
+- Start from domain invariants, not handler DTOs.
+- Define primary key, domain unique keys, status/state fields, version fields, timestamps, and soft-delete behavior deliberately.
+- Prefer explicit integer or enum-like status fields over free-form strings for state machines.
+- Store counters, quotas, mutable quantities, and precise numeric amounts in types that preserve precision and are safe for atomic updates.
+- Avoid JSON columns for core queryable truth unless the schema is intentionally extensible and indexed access is not required.
+- Include created/updated metadata only when the product can maintain it consistently.
+
+## Index And Query Model
+
+- Every list/query API should name its expected filters, sort order, and pagination strategy before schema is finalized.
+- Unique constraints should represent product invariants, not just performance hints.
+- Composite indexes should match common equality filters first, then range/order fields.
+- Review composite indexes against actual access paths, not table columns in isolation. For each important read, update, delete, and post-upsert re-query path, name the leading equality or `IN` fields, optional range/order fields, join fields, soft-delete predicate, and expected cardinality; then verify the DDL has a matching left-prefix index or a deliberate projection/search alternative.
+- When an upsert or de-duplication path later re-queries rows to recover generated fields, the schema must expose a stable unique or conflict key that matches that re-query. Extra predicates in the re-query must be redundant, indexed, or explicitly justified; otherwise the write path can silently miss rows or rely on accidental data shape.
+- Add non-production query-plan checks when the stack supports them, but treat them as a safety net rather than a replacement for schema review.
+- DAL/query helpers should make unsafe scans difficult: require explicit conditions for updates/deletes, require bounded limits for list reads, cap maximum batch size, and force explicit justification for full-table work.
+- Avoid offset pagination for large or operational lists; prefer keyset pagination with a stable order.
+- Leading-wildcard `LIKE`, broad `OR`, tuple or large `IN`, and `DISTINCT` over joined tables are schema-design warnings for hot user paths. Either prove bounded cardinality and a plan budget, or split the use case into exact-match filters plus a search/read-model path.
+- Full-table reads need an explicit justification, bounded cardinality, or an offline/backfill execution model.
+- Search, analytics, and document stores are projections unless explicitly chosen as source of truth.
+
+## Transactions
+
+- A transaction boundary should align with one service-owned relational store.
+- Re-read mutable state inside the transaction before applying quantities, quotas, counters, or state transitions.
+- Prefer compare-and-update, row lock, optimistic version, or unique-key idempotency for concurrent writes.
+- Cross-system writes need outbox/inbox, idempotency, compensation, or a clear reconciliation process.
+- Do not rely on Redis locks as the only correctness mechanism for durable relational truth.
+
+## Sharding
+
+- Decide sharding before data volume forces it; retrofitting sharding is a migration project.
+- Define shard key, shard count, suffix format, routing function, and whether a main table is retained during migration.
+- Shard key must be present in writes and targeted reads.
+- Do not allow updates to shard key columns.
+- Multi-shard queries should be rare, explicit, bounded, and preferably served by a projection/read model.
+- DDL and index changes must apply consistently to every shard.
+
+## Migration Strategy
+
+- Migrations must be compatible with currently deployed code and rollback path.
+- Migration design should cover historical data, queued messages, cached values, generated models, and read/write compatibility rather than only the final schema.
+- Safe order for most changes:
+  - add nullable column or new table.
+  - deploy code that dual-reads or writes both shapes when needed.
+  - backfill in bounded batches.
+  - switch reads.
+  - remove old shape only after all code paths are migrated.
+- Risky migrations need feature gates, progress metrics, retry/skip behavior, and resume markers.
+- Rollback plans should cover schema, data backfill, generated code, dynamic config, and message compatibility.
+
+## Generated DAL Boundary
+
+- DDL can be the source for generated model structs, table constants, query builders, update builders, and baseline DAL interfaces.
+- Generated code should protect immutable columns such as primary key, create time, creator, and unique domain keys from generic updates.
+- Generated query/update builders should expose typed comparison operators and explicit update-column selection rather than raw string fragments by default.
+- Generated query builders are for simple filters; complex query methods still belong in hand-written repositories with tests.
+- Generated output is part of the change and should be reviewed for semantic drift.
+- Generated repository helpers should encode write-safety invariants, but architecture review still owns the invariant behind them: which columns are immutable, which fields form unique identity, which filters are mandatory for tenant or scope isolation, and which paths are allowed to bypass normal sharding or soft-delete behavior.
+
+## Outbox And Dual-Write Consistency
+
+- DB-plus-Redis or DB-plus-MQ writes that must reflect the same business fact use an outbox table; the outbox row is written in the same transaction as the business write. A relay (worker, sidecar, or CDC consumer) publishes pending rows at-least-once and marks them processed.
+- Architecture declares which write paths cross a durability boundary and therefore need outbox; ad hoc dual writes are review findings. The consumer-side idempotency mechanism (unique key, idempotency store, state machine) is named per outbox topic.
+- High-throughput paths may use CDC (binlog tail, logical replication) instead of polling; architecture names the chosen strategy and the durability contract it provides.
+- Outbox health signals (oldest-pending-age, failed-publish count) belong to the platform observability layer; this skill names the emission contract.

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

@@ -0,0 +1,210 @@
+# Data Platform Architecture (Go)
+
+Use when designing the data-platform substrate of a service or service-fleet: DB engine choice (single-instance OLTP, managed cloud DB, distributed SQL, sharding middleware), HA topology, read scaling and replica routing, sharding and resharding strategy, cross-region replication, backup and restore (with rehearsed recovery), cluster lifecycle (provision / scale / decommission / re-shard), capacity planning, fleet-wide schema-migration coordination, and connection-pool / proxy topology.
+
+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.
+
+> **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.
+>
+> **Sanitization vs grep gate are separate concerns.** The mirrored-section grep gate at the end of this file's stack-glue forbids *stack-specific implementation syntax* in mirrored content; "zero hits" on the gate is not "safe to forward externally." The illustrative vendor / cloud-service / storage-tier names above are *intentionally* in mirrored content (an architect must reason about engine choice across stacks); they require **manual sanitization review** before this file or excerpts are forwarded to the audiences above. Maintain the vendor-name list above as the canonical set of names that require manual replacement before external publication.
+
+## When this applies / does not apply
+
+Apply when:
+- the service owns a durable relational store (its own DB instance, schema, or shared cluster),
+- the team owns operations of that store (per the business-team-owns-data-infra ownership model),
+- the service or fleet faces a sharding, HA, replication, backup, or capacity decision that goes beyond schema design,
+- the team is choosing between standard OLTP + manual sharding, sharding middleware, or a distributed SQL engine.
+
+Skip when:
+- the service uses a fully-managed external DB whose lifecycle is owned by the cloud provider (RDS Aurora / Cloud Spanner / DynamoDB), and the team is only choosing schema and queries — route to `data-modeling-and-migrations.md`,
+- the service is stateless and only consumes data via the data platform owned by another team — route to that team's contract.
+
+## DB engine choice axis
+
+The choice is not "PostgreSQL or MySQL" — it is the position on this axis:
+
+- **Single-instance OLTP** (PostgreSQL / MySQL on one node, with replicas). Familiar, broad ecosystem, low operational complexity. Sharding becomes a migration project once one instance maxes out.
+- **Single-instance OLTP + sharding middleware** (Vitess in front of MySQL, ShardingSphere, application-layer sharding). Keeps the operational model of single-instance OLTP per shard while spreading load across shards. Adds middleware layer to operate; routing complexity moves into the proxy.
+- **Distributed SQL engine** (TiDB, CockroachDB, YugabyteDB, Spanner-shape). Native horizontal scale, transactions across shards, native HA. Trades latency (Raft / Paxos quorum write path) and operational model (cluster of stateful nodes with consensus protocols) for transparent scale.
+- **Cloud-managed equivalents** (Aurora, Cloud SQL, AlloyDB, DynamoDB, Spanner). The provider owns operations; the team owns schema, queries, and contract. Cost model differs; vendor-specific scaling and pricing characteristics matter.
+
+Pick by:
+- **Expected scale** — single-instance maxes out at the box's IOPS / connection ceiling; sharding middleware scales horizontally but each shard is still single-instance ops; distributed SQL scales nodes transparently but at consensus latency cost.
+- **Transaction shape** — single-shard transactions are cheap on all engines; multi-shard transactions are expensive on middleware (two-phase commit, distributed coordinator), built-in on distributed SQL, impossible without an outbox/saga on per-shard apps.
+- **Operational ownership** — single-instance is straightforward; sharding middleware adds a layer to monitor; distributed SQL needs in-house consensus-protocol experience or vendor support; managed cloud DB outsources ops.
+- **Migration path** — choose so the next-tier migration is reachable from this one (start single-instance with a sharding-key contract so a future shard migration does not require schema rewrite).
+
+Document the chosen engine, the next-tier migration trigger, and the operational footprint per cluster.
+
+## HA topology
+
+State the HA model explicitly per cluster:
+
+- **Failover model** — single-primary + synchronous standby with automatic failover (most common); single-primary + async replicas (no automatic failover, RTO = manual promotion time); multi-primary (rare, conflict-resolution required); consensus-based (Raft / Paxos with N replicas, leader election internal to the engine).
+- **Synchronous vs asynchronous replication** — sync gives RPO = 0 at the cost of write latency (every write waits for the standby to ack); async writes are faster but the standby lags. Mixed: sync to one standby (RPO = 0) + async to others (read scaling).
+- **Failover trigger** — health check threshold, automatic promotion, split-brain protection (fencing of the demoted primary). Define the failover time budget; test it on a real schedule.
+- **Quorum semantics** — for consensus engines, the write quorum (e.g., majority of N replicas). Loss of quorum = no writes. The minimum healthy replica count to remain writable is part of the topology contract.
+- **Cross-AZ vs single-AZ** — single-AZ failover handles instance failure; cross-AZ handles AZ failure; cross-region handles region failure. Each tier costs more in latency.
+
+Document the failover RTO and RPO targets per cluster, and the last date a failover was tested in production-like conditions (tested vs theoretical).
+
+## Read scaling and replica routing
+
+Once read load exceeds a single primary's capacity, read replicas spread the load:
+
+- **Replica lag** — async replicas lag the primary by milliseconds to seconds; sync replicas lag by zero but slow writes. Define the maximum acceptable lag per use case.
+- **Read-your-writes consistency** — a read replica may not yet show a write the same client just made. Either route those reads to the primary (the standard "session pinning" pattern), use a per-tenant or per-session replica with a lag budget, or accept eventual consistency on that path.
+- **Replica routing** — at the application layer (the service chooses primary or replica per query), at the proxy layer (the proxy routes by SQL shape), or at the engine layer (the engine routes read-only transactions to replicas). The proxy / engine path is more transparent but moves correctness into infrastructure.
+- **Staleness budget** — per query class, declare the maximum acceptable replica lag; monitor and alert when exceeded; fall back to primary when budget is breached.
+
+Replica use is not free: failure modes include lagging replicas serving stale rows, replica connection-pool exhaustion, and replicas falling out of sync after primary failover (must re-attach).
+
+## Sharding and resharding
+
+When a single primary cannot handle write volume or storage, shard:
+
+- **Shard key** — the column or hash that determines which shard a row lives on. Once committed it is hard to change. Choose carefully: tenant_id for SaaS; resource_id for partitioned workloads; time bucket for time-series; composite (tenant_id, year) for both.
+- **Shard count and growth** — start with more shards than nodes (each node holds N shards), so adding nodes redistributes existing shards rather than re-keying. Shard count growth requires a re-shard migration.
+- **Sharding model** — hash (uniform distribution, no range queries cross-shard), range (range queries cheap, hot range risk), lookup-table / directory (flexible, indirection layer to maintain), composite (tenant + sub-shard).
+- **Cross-shard transactions** — expensive (two-phase commit or distributed coordinator) or impossible (no XA support). Design the domain so cross-shard transactions are rare; route those to outbox/saga workflows when needed.
+- **Resharding path** — the upgrade from N shards to N+M, or from one engine to another. Define: new-shard provisioning, dual-write window, reconciliation, cutover, decommission. Resharding is a multi-week project; estimate it before starting.
+
+## Cross-region replication
+
+When the service serves users in multiple regions, or compliance requires data residency, replicate across regions:
+
+- **Sync vs async cross-region** — sync gives RPO = 0 but adds inter-region RTT to every write (50–100 ms typical, business-critical or not). Async lets writes complete in the originating region; the secondary region lags.
+- **Multi-region writes** — global tables (each region writes locally, conflict resolution per-row), per-region partitions (each tenant pinned to one region, no cross-region writes for that tenant), single-primary-with-read-replicas-elsewhere (writes only in the home region, reads anywhere).
+- **Data residency** — when "tenant X's data stays in region Y" is a contractual obligation (see `multi-tenant-isolation.md`), the data plane is region-per-tenant or region-pinned by tenant.
+- **Cross-region failure scope** — what happens when a region goes down? Define which clusters fail over to which, which tenants are affected, and the time budget for restore-to-secondary.
+
+## Backup, restore, and tested recovery
+
+Backup strategy is not the backup itself; it is the **tested ability to restore**:
+
+- **Backup types** — full snapshots (consistent point-in-time, large), incremental snapshots (diff from last snapshot), WAL / binlog archive (continuous, supports PITR), logical exports (portable, slower restore).
+- **Recovery objectives** — RPO (max data loss in seconds/minutes; depends on backup frequency and WAL archival), RTO (max time to restore; depends on backup size, restore mechanism, and tested practice).
+- **Cross-region backup** — store backups in a different region than the primary so a region outage does not also lose the backups.
+- **Encryption at rest in backups** — backups carry the same encryption boundary as the primary; key rotation includes backup re-encryption (or accept that old backups remain on old keys).
+- **Tested recovery (the rule that distinguishes real from theatre)** — restore from backup on a schedule. Validate the restored state matches expected. Time the restore and compare to RTO. A backup that has never been restored is a backup of unknown quality. Date the last successful restore in the cluster contract.
+
+## Cluster lifecycle
+
+The cluster has a lifecycle as concrete as any service:
+
+- **Provision** — declarative infra (Terraform / equivalent), parameter group, encryption-at-rest configuration, network placement, audit log destination, monitoring scrape config, identity / role setup. Provisioning is reproducible; one-off manual clusters are technical debt.
+- **Scale up** — increasing instance class (vertical) without downtime requires planned maintenance windows on most engines; budget for it.
+- **Scale out** — adding nodes (replicas, shards) requires re-balancing and may briefly affect write latency. Define the scale-out runbook.
+- **Decommission** — taking a cluster out of service: drain traffic, verify zero writes/reads against it for an observation window, snapshot for retention, then destroy. Premature destroy after "looks idle" is a real outage class.
+- **Cluster identity** — the cluster has a name, owner, lifecycle stage, and a connection contract documented; services that connect to it are listed.
+
+## Capacity planning
+
+A data cluster has multiple capacity dimensions, each can become the bottleneck:
+
+- **Storage** — current usage, growth rate, headroom; alert at 70% / 80% / 90% with an explicit response. Storage growth past auto-extend limits is a hard outage.
+- **IOPS / throughput** — provisioned (e.g., AWS gp3 / io2) or burst-limited; monitor utilization vs limit; right-size before the limit is hit.
+- **Connection ceiling** — the engine's max connections; the proxy's connection pool size; the per-service pool. A connection storm at startup (every instance opens 100 connections) can exceed the ceiling instantly.
+- **Query latency budget** — p50 / p95 / p99 latency; growth in p99 is a leading indicator before throughput saturates.
+- **Replica lag headroom** — lag spikes during heavy writes are normal; sustained lag indicates the replica cannot keep up.
+
+Each dimension has a documented limit, current usage, growth rate, and the action when the threshold trips. Capacity planning is monthly minimum, weekly during growth.
+
+## Fleet-wide schema migration coordination
+
+When the fleet has more than ~20 service DBs and migration tooling is per-DB, fleet-wide coordination becomes its own concern:
+
+- **Migration registry** — a catalog of which service owns which DB, which schema version each is on, and which migrations are pending. Without this, a fleet-wide change (e.g., adding a tenant_id column for compliance) cannot be tracked.
+- **Coordinated change rollout** — when the change spans services (a new column in shared semantics, a deprecation of a cross-service contract), define the order: which service migrates first, which dual-reads, when the old shape is retired.
+- **Migration tool unification** — fleet-wide migrations work best when every service uses the same migration tool with the same conventions; mixed tooling makes fleet operations brittle.
+- **Migration approval gate** — at fleet scale, migrations need pre-merge review (does it break replicas? does it lock tables? does it require downtime?). A "migration approval" workflow + checklist beats heroics.
+
+## Connection pool and proxy topology
+
+The path from app to DB has its own architecture:
+
+- **Per-service pool** — each service instance holds its own connection pool. Simple, but fleet-wide connection count = (services × instances × pool_size). Watch the engine's max-connections ceiling.
+- **Proxy layer** (PgBouncer, ProxySQL, Vitess gateway, RDS Proxy) — a proxy multiplexes many service connections into fewer DB connections. Reduces the connection count seen by the engine. Adds a hop (latency) and a layer to operate.
+- **Transaction-mode vs session-mode pooling** — transaction-mode is denser (more service connections per DB connection) but breaks features that rely on session state (prepared statements, advisory locks, session variables). Session-mode preserves features at the cost of density.
+- **Connection lifecycle** — the pool's idle timeout, max lifetime, and reconnect-on-error policy. A connection storm on app start (every instance opens 50 connections at once) is a common outage trigger.
+- **Proxy HA** — the proxy must be HA-paired or per-AZ; a single proxy is a single point of failure for every service behind it.
+
+## Cost and efficiency
+
+Data layer cost grows with scale; explicit cost ownership prevents drift:
+
+- **Right-sizing** — instance class, storage tier (provisioned IOPS vs gp3 vs gp2), backup retention. Over-provisioned clusters are real money.
+- **Cold storage and archival** — old rows that are rarely read move to cheaper storage (S3 / Glacier / equivalent); the archival path must preserve tenant scope and support re-hydration (see `multi-tenant-isolation.md`).
+- **Read-replica tax** — replicas cost as much as primaries; only run replicas that have a real reader.
+- **Cross-region transfer** — egress and inter-region replication traffic costs add up; budget per cluster.
+
+## Anti-patterns
+
+Block these:
+
+- **Sharding decided after a single-instance outage** — emergency sharding under load is a real outage class. Decide shard key and shard count before the migration is forced.
+- **Backups that have never been restored** — backups of unknown quality; the first restore is during the incident. Schedule restore drills.
+- **Failover that has never been tested in production-like conditions** — RTO is theoretical until proven. Test on a schedule with realistic load.
+- **Cross-region sync writes used to hide application bugs** — using cross-region sync replication to mask consistency bugs in the app layer; the latency tax is permanent. Fix the bug.
+- **Hot shard** — one shard absorbs the majority of writes (popular tenant, hot resource, time-bucket clustering). Audit shard key cardinality before launch.
+- **Long-running transactions on primary** — analytical queries that hold long locks, blocking writes. Route analytical traffic to replicas or a separate warehouse.
+- **Connection storm on app start** — every instance opens its full pool at boot, exceeding the engine ceiling. Stagger pool warmup or use a proxy.
+- **Proxy as single point of failure** — one PgBouncer instance fronting the whole cluster. Pair or per-AZ.
+- **Engine choice driven by hype, not by transaction shape** — picking distributed SQL for a 100-write/sec workload, or single-instance OLTP for a workload that needs distributed transactions. The transaction shape determines the engine, not vice versa.
+- **Schema migration that locks the table on a hot path** — a migration that holds a strong lock for minutes; the service is effectively down. Use online-DDL tooling and review migration locking behavior pre-merge.
+- **Backup retention shorter than the deletion / regulatory clock** — restoring a 30-day backup to recover yesterday's data only works if the backup is within retention. Coordinate backup retention with data-deletion SLAs (see `multi-tenant-isolation.md` per-store deletion modes).
+- **Primary DB as cross-service queue** — using a service's primary OLTP table as the substrate for cross-service async messaging via polling. Adds queue load to the primary's connection pool and IOPS budget; couples the broker semantics to the DB's locking and transaction model; lacks fanout, replay, and lag visibility that a proper broker provides. Route durable cross-service async messaging to `event-driven-architecture.md` (broker + outbox poller); allow only low-volume same-service jobs with an explicit capacity budget against the primary.
+
+## Operations checklist (data platform launch)
+
+Each item is a verifiable action:
+
+- Engine choice declared with the next-tier migration trigger (e.g., "single-instance until 50k QPS sustained; migrate to sharding middleware at that threshold").
+- HA topology documented: failover model, sync/async configuration, quorum semantics, cross-AZ placement, failover RTO/RPO targets, last tested-failover date.
+- Read-replica routing decision documented per query class with staleness budget and fallback-to-primary path.
+- Sharding model declared (shard key, shard count, growth path) before the first shard is provisioned; not retrofitted.
+- Cross-region replication mode declared per cluster (sync / async / multi-region / per-region partitioned); residency commitments enforced at the data plane.
+- Backup strategy declared: type (snapshot / WAL / logical), frequency, retention, cross-region location, encryption-at-rest, RPO target.
+- Restore drill scheduled on a documented cadence; last successful restore dated; restore time vs RTO target measured.
+- Cluster lifecycle steps documented: provision (declarative IaC), scale up/out (runbook), decommission (drain + observe + snapshot + destroy); no one-off manual clusters.
+- Capacity dimensions monitored (storage, IOPS, connections, latency p99, replica lag) with documented alert thresholds and response runbooks.
+- Fleet-wide migration registry exists; per-service migration tool + version recorded; coordinated migrations have an order and approval gate.
+- Connection pool sizes documented per service; proxy topology declared (per-service / proxy layer / mixed) with HA pairing where a proxy is used.
+- Cost reviewed monthly; right-sizing reviewed quarterly; cold-storage / archival path tested.
+
+## Go-specific implementation patterns
+
+Stack-localized recipes; the sibling Python file localizes the same patterns differently.
+
+- **DB driver and pool** — `database/sql` with the engine-specific driver (`pgx`/`lib/pq` for PostgreSQL, `go-sql-driver/mysql` for MySQL). Configure `SetMaxOpenConns`, `SetMaxIdleConns`, `SetConnMaxLifetime`, `SetConnMaxIdleTime` explicitly; do not rely on defaults. For higher-level access, GORM or sqlx on top of `database/sql`.
+- **Sharding middleware integration** — Vitess via its grpc / mysql wire protocol; treat as a regular MySQL connection in `database/sql`. Sharding decisions visible to the proxy via routing rules (VSchema for Vitess); the app's job is to include the shard key in every query.
+- **Replica routing** — connect strings for primary vs replica are separate DSNs; a small router in the service picks per-query (e.g., a wrapper around `*sql.DB` that exposes `PrimaryDB() *sql.DB` and `ReplicaDB() *sql.DB`). For session-stuck reads (read-your-writes), pin to primary for the session.
+- **Migration tooling** — `golang-migrate/migrate` or `goose` for per-service migrations; `Atlas` for declarative schema management; pick one and stick to it across the fleet for the migration registry to be useful.
+- **Outbox poller integration** — the data-platform-architecture decisions (which engine, what HA, replica lag budget) feed into the outbox poller's behavior described in `event-driven-architecture.md` and `data-modeling-and-migrations.md` (Outbox And Dual-Write Consistency).
+- **PgBouncer with Go** — Go's `database/sql` works fine with PgBouncer in transaction-mode IF the app avoids prepared statements (`?` placeholders) and session-scoped state (advisory locks, session variables). For session-mode, all Go features work. Choose mode per service's feature usage.
+- **Vitess gateway** — looks like MySQL on the wire; transactions across shards require explicit 2PC or routing to a single shard. The Vitess `vtgate` exposes a `direct` mode for unrouted queries; use sparingly.
+- **Health checks for HA** — a service's readiness probe pings the DB; a failed ping → mark un-ready. Distinguish "primary unreachable" (fail) from "replica lagging" (degrade but still ready for non-critical reads).
+- **Connection storm mitigation** — staggered pool warmup (sleep N×instance_id ms before opening connections at boot); circuit breaker on DB connect failures; exponential backoff on reconnect.
+- **Test substitution** — define a repository interface; provide a real-DB integration test (`testcontainers-go` for PostgreSQL / MySQL containers); avoid mocking the DB driver directly (mocks lose SQL semantics).
+
+### Mirrored-section grep gate
+
+The sibling-sync header forbids three categories of stack-specific token in mirrored sections (everything from "When this applies" through "Operations checklist"; everything *before* the `## Go-specific implementation patterns` H2). Run this grep against the mirrored region before every commit; zero hits required.
+
+Forbidden tokens for this Go file's mirrored sections:
+
+- **DB-engine syntax** — `SET LOCAL`, `set_config\(`, `current_setting\(`, `pg_try_advisory`, `pg_stat_activity`, `BYPASSRLS`, `FORCE ROW LEVEL SECURITY`, `search_path`, `GET_LOCK\(`.
+- **Runtime / concurrency mechanic names** — `context\.Context`, `\bgoroutine\b`, `\bgoroutines\b`, `ctx\.Done`, `database/sql`, `\bsqlx\b`, `contextvars`, `\basyncio\b`, `run_in_executor`, `to_thread`, `ThreadPoolExecutor`, `ProcessPoolExecutor`, `copy_context`, `async with`, `after_commit`, `listens_for`, `asyncio\.Queue`, `asyncio\.Event`, `asyncio\.create_task`, `asyncio\.Task`.
+- **Library / framework API names** — `GORM`, `Hertz`, `Kitex`, `golang-migrate`, `\bgoose\b`, `\bAtlas\b`, `pgx`, `lib/pq`, `go-sql-driver/mysql`, `SetMaxOpenConns`, `SetMaxIdleConns`, `SetConnMaxLifetime`, `SetConnMaxIdleTime`, `PingContext`, `(^|[^[:alnum:]_])\*?sql\.DB\b`, `(^|[^[:alnum:]_])sql\.Tx\b`, `BeginTx`, `QueryContext`, `ExecContext`, `(^|[^[:alnum:]_])sql\.Rows\b`, `(^|[^[:alnum:]_])sql\.NullString\b`, `DB\.Stats`, `PrimaryDB\(`, `ReplicaDB\(`, `testcontainers-go`, `\btestcontainers\b`, `SQLAlchemy`, `FastAPI`, `Starlette`, `Pydantic`, `httpx`, `Alembic`, `asyncpg`, `psycopg`, `aiomysql`, `asyncmy`, `mysqlclient`, `PyMySQL`, `Django`, `databases`, `sqlmodel`, `tortoise`, `pool_pre_ping`.
+
+Run:
+
+```
+awk '/^## Go-specific implementation patterns/{exit} 1' data-platform-architecture.md \
+  | grep -nE '(SET LOCAL|set_config\(|current_setting\(|pg_try_advisory|pg_stat_activity|BYPASSRLS|FORCE ROW LEVEL SECURITY|search_path|GET_LOCK\(|context\.Context|\bgoroutine\b|\bgoroutines\b|ctx\.Done|database/sql|\bsqlx\b|contextvars|\basyncio\b|run_in_executor|to_thread|ThreadPoolExecutor|ProcessPoolExecutor|copy_context|async with|after_commit|listens_for|asyncio\.Queue|asyncio\.Event|asyncio\.create_task|asyncio\.Task|GORM|Hertz|Kitex|golang-migrate|\bgoose\b|\bAtlas\b|pgx|lib/pq|go-sql-driver/mysql|SetMaxOpenConns|SetMaxIdleConns|SetConnMaxLifetime|SetConnMaxIdleTime|PingContext|(^|[^[:alnum:]_])\*?sql\.DB\b|(^|[^[:alnum:]_])sql\.Tx\b|BeginTx|QueryContext|ExecContext|(^|[^[:alnum:]_])sql\.Rows\b|(^|[^[:alnum:]_])sql\.NullString\b|DB\.Stats|PrimaryDB\(|ReplicaDB\(|testcontainers-go|\btestcontainers\b|SQLAlchemy|FastAPI|Starlette|Pydantic|httpx|Alembic|asyncpg|psycopg|aiomysql|asyncmy|mysqlclient|PyMySQL|Django|databases|sqlmodel|tortoise|pool_pre_ping)'
+```
+
+Allowed exception: the *Sibling sync* header itself names the three category classes (without tokens) and references this gate; the *Sanitization boundary* header does not contain any of these tokens. Vendor names in mirrored sections that name a DB engine class (PostgreSQL / MySQL / Vitess / TiDB / CockroachDB / PgBouncer / ProxySQL) are allowed because they are engine choices an architect must reason about across stacks; the gate forbids stack-specific *implementation syntax*, not generic engine names.

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

@@ -0,0 +1,105 @@
+# Dependency Platform
+
+Use this when designing reusable dependency access for new Go backend services.
+
+## Secret Provider Contract
+
+- Treat secrets as runtime dependencies, not config literals.
+- Repo-committed config may contain secret references, credential names, key ids, roles, service identifiers, and endpoint identities; it must not contain raw app secrets, webhook secrets, passwords, access keys, or private tokens.
+- Secret lookups need typed accessors per credential class: database, Redis, MQ, object storage, external API, and application credential.
+- The secret provider should expose read paths separately from write/admin paths.
+- Startup may fail fast when required credentials are missing; request handling should not panic on missing runtime secrets. More generally, never let a critical invariant ride on a dependency's incidental or undocumented behavior (e.g. it happening to panic on nil wiring); assert and own the invariant locally with a construction-time fail-fast guard, keeping an explicit test opt-out.
+- Cache short-lived credentials with a safety buffer before expiry.
+- Validate local clock skew when using time-bound credentials.
+- Never log secret values, temporary tokens, signatures, raw encrypted payloads, or decrypted config.
+- Prefer authenticated encryption or a managed secret store. If local encryption is unavoidable, keep keys outside source/config and rotate deliberately.
+
+## Service Discovery And Lane Routing
+
+- Internal clients should resolve endpoints through a discovery abstraction, not hardcoded host lists.
+- Health-filtered instances are the default.
+- Lane/environment tags may route traffic, but fallback is operation-specific: read-only requests on idempotent endpoints MAY fall back to a stable baseline lane; writes, tenant-sensitive reads, and any request that mutates state or carries canary/stress assumptions MUST fail closed when the requested lane has no healthy instance. Document the fallback policy per route, default to fail-closed for unmarked routes.
+- Keep service identity, lane, and endpoint selection visible in logs and traces.
+- Do not let service discovery failure silently fall back to an unrelated public endpoint.
+- If external components are registered into service discovery from config, model it as desired-state reconciliation: load desired endpoints, resolve hostnames, compare endpoint plus metadata, register changed instances, and deregister stale instances.
+- Registration metadata should be low-cardinality and intentional: source host, lane/environment, protocol, ownership, and routing tags when needed.
+- Reconciliation loops need a cancellable ticker, bounded lookup/register/deregister timeouts, and metrics for changed, unchanged, removed, and failed instances.
+
+## Dependency Client Policy
+
+- Define a standard client wrapper for each dependency type with:
+  - context propagation.
+  - connect timeout and request timeout.
+  - credential source.
+  - retry budget.
+  - low-cardinality metrics.
+  - safe structured logs.
+  - test fake interface.
+- Prefer constructing clients in DI providers; domain logic should receive interfaces.
+- Separate internal service clients from external internet clients because timeout, auth, retry, and data-safety rules differ.
+- For dependency status responses, validate transport success and domain success separately.
+
+## Dynamic Config
+
+- If etcd is used, state explicitly whether it is a dynamic-config backing store or service discovery. Service mesh based systems may allow etcd for platform-owned dynamic config while still banning in-process etcd registry/resolver clients.
+- First-party KMS can be backed by dynamic config for early versions, but secret envelopes must be encrypted, master keys must stay outside repo config, and readiness must fail closed when the KMS store or master key is unavailable.
+- Dynamic config keys need typed accessors, namespace ownership, timeout, cache policy, and default behavior.
+- Cache hot-path reads briefly and emit cache hit/miss/error metrics when the config system supports it.
+- Watch/listener APIs must update local cache and recover panics inside callback handling.
+- Keep admin write/delete APIs separate from ordinary runtime read clients.
+- For missing or malformed dynamic config, choose fail-closed for safety controls and fail-open only for explicitly non-critical behavior.
+
+## ID Generation
+
+- Decide whether IDs are generated locally, by a central service, or by the database before schema/API design.
+- Central ID services need namespace registration, batch allocation, caller identity, timeout, and quota controls.
+- Client-side ID caches should have bounded size and timeout on allocation.
+- Local fallback generators are acceptable only when their uniqueness domain is explicit and collision risk is understood.
+- Do not use timestamp-only fallback IDs for durable cross-service records unless collision handling exists.
+- Persist allocator state durably when ID monotonicity or non-reuse matters.
+
+## Object Storage Architecture
+
+- Wrap object storage behind an interface such as `Put`, `Get`, `Head`, `Delete`, `Sign`, and `List`.
+- Store object metadata and tags for source service, lane/environment, trace/log id, retention class, and ownership when useful.
+- Large uploads require multipart/resumable design, part size, retry policy, and abort/cleanup behavior.
+- Range downloads should validate object size with metadata first.
+- Signed URLs need explicit expiry, permission scope, and audit visibility.
+- Object keys are durable identifiers; define namespace, uniqueness, lifecycle, and cleanup before exposing them in API contracts.
+- Object storage is not a relational source of truth. Persist durable resource records in the service database when users or workflows depend on them.
+
+## Projection Stores
+
+- Treat search indexes, document stores, and analytics stores as projections unless the service explicitly defines them as the source of truth.
+- Define index/collection ownership, schema or mapping ownership, rebuild path, sync trigger, and eventual-consistency expectations.
+- Projection clients need timeout, health policy, pool bounds, tracing, credential source, and endpoint-discovery policy.
+- Query APIs need max limit, deterministic sort, filter allowlist, and pagination strategy.
+- Bulk writes need chunk size, retry policy, per-item failure inspection, and reconciliation path.
+- Avoid coupling domain invariants only to projection-store constraints; enforce durable invariants in the source-of-truth path.
+
+## Controlled Concurrency
+
+- Fan-out work needs an explicit concurrency limit, timeout, retry count, retry interval, and partial-failure policy.
+- Preserve output order or stable key mapping when concurrent work returns out of order.
+- Recover panics at task boundaries and convert them into ordinary errors.
+- Decide whether the first error cancels remaining work or whether all results should be collected.
+- Avoid launching background goroutines from hot paths unless lifecycle, shutdown, and test isolation are defined.
+
+## Inference-As-RPC Client (Go Business → Python Inference)
+
+When a Go business service calls a Python inference service (model server, OCR, VL chat, ML pipeline), the call sits between "regular HTTP/RPC client" and a domain-specific inference protocol. The architecture-layer rules:
+
+- **Transport choice**: HTTP POST + JSON body is the common cross-language transport even when the inference server can speak gRPC or Triton-native. The trade-off is broad client support + easy debugging vs binary efficiency. Document the choice per service tier; do not let one service mix transports across methods.
+- **URL construction**: derive the inference endpoint from a `method-name → service-identifier` mapping plus a `GeneratePredictPath(method, version)` helper. Hard-coded inference IPs in business code are a finding. Discovery owns the address; the helper owns the path.
+- **Method-level timeout per model SLA**: each inference method has its own SLA (image feature extract ~90 s, image match ~120 s, OCR ~90 s, lightweight classifier ~10 s). The client picks the per-request timeout as `min(method-timeout, config-override, ctx-deadline)`. A single global "inference timeout" is wrong for fleets spanning two orders of magnitude in latency.
+- **Per-attempt context discipline**: every HTTP attempt uses a sub-context of the request context. When the caller's deadline elapses, the in-flight call is cancelled. Long-running inference holding the socket past cancellation is a leak.
+- **Large payload routing**: when the call carries an image, document, or multi-MB binary, the client uploads via signed URL (object storage) and sends URL + metadata, not inline bytes. Inline base64 is acceptable as a fallback with a documented size threshold. When the inference response is itself a binary, the server side should return a signed URL when possible; if the contract requires inline bytes, do not strip them from the response (that breaks callers) — apply size limits or field redaction at the logger / persistence layer so logs and traces are bounded without changing the wire contract.
+- **Signed URL trust on the caller side**: a signed URL is a bearer credential plus a server-side fetch target. When the Go business service constructs the URL for the inference service to fetch, scope it strictly: short expiry (minutes), HTTP method GET (or PUT for upload — exclusive), narrow object key (caller-namespaced), content-length cap, and rotate the signing key on schedule. Log the URL with the signature query parameters redacted. The inference service is expected to validate the bucket/host against its allowlist and reject URLs outside it; design the caller's URL accordingly.
+- **Inter-service authN/authZ**: the inference service is not behind an implicit trust boundary just because it sits inside the mesh. The Go caller authenticates with a verified workload identity (mTLS service cert, SPIFFE/SPIRE id, JWT issued by the platform IdP, or k8s service-account token) — the inference service refuses unauthenticated callers. The caller's allowlist on the inference side names which Go services are permitted to invoke which models. Tenant id and resource id carried in the request body are inputs to authorization, not statements of truth; the inference side validates the caller is permitted to use that tenant's / resource's data before loading inputs. Quota / rate-limit per caller × model × tenant is part of the contract; a GPU model is a shared resource.
+- **Trace propagation**: every outbound inference request injects `X-Request-ID` and `X-Log-Id` (or the project's equivalent) so the Python service correlates. The Python service reads these headers in middleware once and threads them through every internal log line. Without this, the Go-to-Python call chain breaks at the boundary.
+- **Cross-stack ctx-key constants**: define context-key constants in one shared package (e.g. request-id key, business-shard key, experiment-router key — name them per the platform's context-keys convention); business code reads through typed accessors, not raw string keys. The set is part of the inference contract.
+- **Failure classification**: HTTP 2xx + envelope `code != success` is a domain inference error; HTTP non-2xx is a transport error. Map both to distinguishable Go error types so business retry and circuit-breaker rules can act differently. Generic `ServerError` swallowing both is a finding.
+- **Inference-specific error codes**: reserve a numeric range or a typed error class for inference-side failures (model not found, GPU OOM, input shape mismatch, model load failed, version mismatch). Business code should branch on these without parsing free-text error messages.
+- **Bounded retry without circuit breaker is incomplete**: short retry loops (2-3 attempts with backoff jitter) handle transient blips; sustained failure needs a circuit breaker per upstream / per model so the service fails fast and sheds load instead of amplifying the upstream incident.
+- **Experiment / traffic routing as data**: when the inference fleet runs multiple model variants concurrently, the routing layer is data (rules with traffic ratio + matcher condition + target model/version), not code branches. Strategy types — A/B, canary, orthogonal, shadow — share one engine. Per-request metadata records the experiment id, variant, and served model version so evaluation can join.
+- **TrafficLog persistence**: an out-of-band log of every inference call (caller, callee, method, version, latency, code, message, cost) goes to async storage. Failed call-record writes do not fail the inference call. Benchmark and offline lanes can persist locally for replay.

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

@@ -0,0 +1,38 @@
+# Developer Tooling Architecture
+
+Use this when designing CLIs, code generators, scaffolding commands, or generated-file ownership for a Go service stack.
+
+## Tool Boundaries
+
+- Treat generators as build/development tools with explicit inputs, outputs, versions, and ownership.
+- Prefer non-interactive command flags for CI and agent use; interactive prompts can be a convenience wrapper only.
+- Generation inputs should be source-controlled where possible: DDL, IDL, templates, config, and command docs.
+- Generated outputs should be clearly marked and should not require hand edits.
+- Tools should be runnable from the repo root or document their required working directory.
+
+## Reproducibility
+
+- Pin generator versions or verify them in preflight checks.
+- Fail fast when required inputs, modules, config files, or external binaries are missing.
+- Use temporary files safely and remove them after command completion.
+- Avoid developer-local absolute paths in generated commands.
+- Format generated Go files and keep generated diffs deterministic.
+
+## Safety
+
+- Do not overwrite hand-written files unless the command explicitly opts in.
+- Prefer generated file suffixes or directories that make ownership obvious.
+- Tools that touch deploy config, database schemas, or remote systems need dry-run output and confirmation gates.
+- Generated code should include tests or compile checks in the owning repo's verification workflow.
+
+## Codegen Entrypoint Ownership
+
+- For multi-service portfolios, architecture mandates one canonical command per codegen kind (`make wire` for DI, `make gen_db` for DAL from DDL, `make idl` / `make_service` for IDL → server/client stubs, `make doc` for API docs) and a top-level fan-out target (`make codegen`) that runs all of them. New service onboarding and post-IDL-bump refreshes use the top-level target.
+- The Makefile is the source of truth for both developers and CI; CI does not invoke generator binaries directly. Tool versions are pinned at the Makefile or container layer, not at the developer's local environment.
+- Generated output directories are committed and reviewed; reformatters and linters skip them. Architecture review treats hand-edits to generated files as a finding unless the generator explicitly supports custom hooks.
+
+## Breaking-Change Governance
+
+- Any IDL surface consumed by more than one team, more than one binary, or external clients requires a CI breaking-change gate (`buf breaking`, `kitex check`, or equivalent). Pre-commit syntax/format checks alone are not breaking-change checks.
+- The gate compares the proposed IDL against the previous merged revision; intentional breaks route through an explicit approval path (PR label, separate branch, marker file the gate recognizes). Architecture review owns the approval list and the rationale per break.
+- Multi-language consumers inherit the contract; if the canonical language has integration tests but other languages do not, architecture documents that asymmetry so consumers can decide whether to add their own coverage.

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

@@ -0,0 +1,36 @@
+# Error Contract Architecture
+
+Use this when designing service error codes, response envelopes, transport mappings, and cross-service error propagation.
+
+## Contract
+
+- Define one canonical error shape with code, safe message, optional details, retryability, and trace id.
+- Keep success separate from failure; success should not be represented by an absent or default error.
+- Success and failure envelopes must be explicit and structurally stable; callers should never infer success from a missing error field or missing status field.
+- Callers must check the canonical success/failure indicator before reading optional result fields.
+- Reserve code ranges for common classes: invalid input, unauthorized, forbidden, not found, conflict, rate limit, timeout, dependency failure, internal error, and panic.
+- Response envelopes should be consistent across HTTP, RPC, workers, and callbacks.
+- Error messages returned to clients must be safe; logs may contain richer internal context under redaction policy.
+
+## Mapping
+
+- Map transport status to canonical codes at the boundary.
+- Preserve error chains internally, but expose only the canonical code and safe message externally. Error mapping is a total function — every error resolves to a canonical code, unknown falls back to the internal-failure class — and before any code is written into a client-facing response body it passes an allow-list separating client-safe codes from internal-only ones: codes that carry no client-actionable contract (raw panic, unclassified internal failure, and any diagnostic-only code) collapse to a generic safe code instead of being emitted, while genuinely client-facing classes (e.g. rate-limited, timeout, dependency-unavailable) stay on the wire only when the public contract declares them, keeping transport status and envelope code distinct.
+- Dependency errors should be normalized before leaving the infrastructure adapter.
+- Validation errors should identify fields without exposing sensitive values.
+- Panics should map to a distinct internal failure class and include trace/log id for support.
+
+## Governance
+
+- Error definitions should live near the owning module while common codes stay shared.
+- Codes are API contracts; do not reuse retired codes for different meanings.
+- New shared codes need documentation and tests for transport mapping.
+- Metrics should group by canonical code and operation, not raw error string.
+
+## Cross-RPC Envelope And Code Range Allocation
+
+- Architecture declares which transport-level slot carries the typed error envelope per protocol: for gRPC, encode structured details via `google.rpc.Status` with `details` (transported via the `grpc-status-details-bin` trailer or the framework's native details mechanism); for header-based RPC protocols, use protocol-native metadata frames; for HTTP, use a response body envelope. Do NOT pack JSON into the gRPC status message field — it is freeform text limited in size, not a structured channel. The serdes contract is symmetric — server writes, client reads — and is part of the platform contract, not per-service.
+- Code range allocation is centrally governed. Reserve a numeric range (e.g., `[0, 11999]`) for shared codes and sub-allocate to tiers: platform codes (200/400/401/403/404/500/503/504), gateway/api codes, per-domain biz codes. Architecture owns the allocation table; new code requests route through the table.
+- Distinguish system errors from biz errors in the envelope. Middleware decisions — alert vs ignore, retry-safe vs not, fallback path — depend on the class, not the specific code.
+- i18n boundary: error message in the envelope is one language (often English). User-facing translations belong to the gateway or front-end, keyed by the code. Do not localize on the producer side.
+- HTTP-200-always vs HTTP-status-as-semantic is a portfolio-level decision. The 200-always pattern simplifies SDK error parsing and avoids partial-success ambiguity but loses the ability for intermediate infrastructure (proxies, monitoring) to classify by HTTP status. Architecture documents the choice and applies it consistently.