skilldrop-cli 0.16.45 → 0.16.46

package/packs/solution-architect/skills/context-graph/evals/files/4/src/ledgerline/scheduler/runner.py

@@ -0,0 +1,17 @@
+"""Nightly invoice run entry point."""
+
+from ledgerline.db import direct_connection
+from ledgerline.scheduler.lock import invoice_run_lock
+from ledgerline.invoicing import run_nightly
+
+
+def main():
+    with direct_connection() as conn, invoice_run_lock(conn) as acquired:
+        if not acquired:
+            print("another worker holds the invoice-run lock; exiting")
+            return
+        run_nightly()
+
+
+if __name__ == "__main__":
+    main()

package/packs/solution-architect/skills/context-graph/evals/files/5/lib/types/index.ts

@@ -0,0 +1,13 @@
+export interface FeedEvent {
+  id: string;
+  kind: string;
+  occurredAt: string;
+  payload: Record<string, unknown>;
+}
+
+export interface Invoice {
+  id: string;
+  customerId: string;
+  amountMinor: number;
+  currency: string;
+}

package/packs/solution-architect/skills/context-graph/evals/files/5/rfcs/0001-service-layout.md

@@ -0,0 +1,20 @@
+---
+id: RFC-0001
+title: Service layout and shared code
+status: accepted
+date: 2024-11-02
+authors: [Dara Mensah]
+governs: [services/, lib/]
+---
+
+# RFC-0001: Service layout and shared code
+
+## Decision
+
+Each service under `services/<name>/` owns its own client, retry and error-handling code.
+The only shared package is `lib/types/` (pure type definitions, no runtime behaviour).
+
+## Why
+
+Ingest and export talk to different partners with different idempotency guarantees. A shared
+runtime library would couple their failure behaviour and force lock-step releases.

package/packs/solution-architect/skills/context-graph/evals/files/5/rfcs/0003-ingest-retry-policy.md

@@ -0,0 +1,26 @@
+---
+id: RFC-0003
+title: Retry policy for the ingest service
+status: accepted
+date: 2025-03-11
+authors: [Oskar Byrne]
+governs: [services/ingest/retry.ts]
+cites: [RFC-0001]
+---
+
+# RFC-0003: Retry policy for the ingest service
+
+## Context
+
+INC-114 (2025-02-27): the partner feed API returned 503 for four minutes. Every ingest worker
+retried on a fixed 1 s interval, the retries stayed synchronised, and the partner rate-limited
+our whole account for two hours after recovery.
+
+## Decision
+
+Ingest retries use exponential backoff with full jitter: base 200 ms, cap 30 s, at most
+6 attempts. Fixed-interval retries are not allowed in ingest.
+
+## Consequences
+
+Worst-case retry window is about 60 s per request. Dashboards alert on attempt 5+.

package/packs/solution-architect/skills/context-graph/evals/files/5/rfcs/0006-shared-retry-library.md

@@ -0,0 +1,24 @@
+---
+id: RFC-0006
+title: Extract a shared lib/retry package
+status: rejected
+date: 2025-06-19
+authors: [Lucía Ferraro]
+cites: [RFC-0001, RFC-0003]
+---
+
+# RFC-0006: Extract a shared lib/retry package
+
+## Proposal
+
+Move `services/ingest/retry.ts` and `services/export/retry.ts` into one `lib/retry/` package
+with a single default policy.
+
+## Outcome: rejected
+
+- Export calls to the partner billing API are NOT idempotent; export only retries on 503
+  responses that carry an `Idempotency-Key` echo. A single default policy would retry
+  unsafe calls.
+- RFC-0001 keeps runtime code per service.
+
+Revisit only if RFC-0001 is superseded.

package/packs/solution-architect/skills/context-graph/evals/files/5/rfcs/0008-outbound-http-client.md

@@ -0,0 +1,22 @@
+---
+id: RFC-0008
+title: One outbound HTTP client
+status: accepted
+date: 2025-09-30
+authors: [Dara Mensah]
+governs: [lib/http/, services/ingest/client.ts, services/export/client.ts]
+amends: [RFC-0001]
+cites: [RFC-0007]
+---
+
+# RFC-0008: One outbound HTTP client
+
+## Decision
+
+All outbound HTTP calls go through `lib/http/client.ts`. It sets timeouts, tracing headers and
+applies retries uniformly (fixed 500 ms, 3 attempts). This amends RFC-0001 to allow `lib/http/`
+as a second shared package. Idempotency keys are handled as described in RFC-0007.
+
+## Rollout
+
+Services migrate their `client.ts` to `lib/http/` during Q4 2025.

package/packs/solution-architect/skills/context-graph/evals/files/5/services/export/client.ts

@@ -0,0 +1,15 @@
+import { retryIfSafe } from "./retry";
+import type { Invoice } from "../../lib/types";
+
+const BILLING_URL = process.env.PARTNER_BILLING_URL ?? "https://billing.partner.example/v1/invoices";
+
+export async function pushInvoice(inv: Invoice, idempotencyKey: string): Promise<Response> {
+  return retryIfSafe(() =>
+    fetch(BILLING_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Idempotency-Key": idempotencyKey },
+      body: JSON.stringify(inv),
+      signal: AbortSignal.timeout(15_000),
+    }),
+  );
+}

package/packs/solution-architect/skills/context-graph/evals/files/5/services/export/retry.ts

@@ -0,0 +1,12 @@
+// Export retries are deliberately narrow: the billing API is not idempotent (RFC-0006).
+const DELAY_MS = 1_000;
+const MAX_ATTEMPTS = 3;
+
+export async function retryIfSafe(fn: () => Promise<Response>): Promise<Response> {
+  for (let attempt = 1; ; attempt++) {
+    const res = await fn();
+    const safe = res.status === 503 && res.headers.has("Idempotency-Key");
+    if (!safe || attempt >= MAX_ATTEMPTS) return res;
+    await new Promise((r) => setTimeout(r, DELAY_MS));
+  }
+}

package/packs/solution-architect/skills/context-graph/evals/files/5/services/ingest/client.ts

@@ -0,0 +1,14 @@
+import { withRetry } from "./retry";
+import type { FeedEvent } from "../../lib/types";
+
+const FEED_URL = process.env.PARTNER_FEED_URL ?? "https://feed.partner.example/v2/events";
+
+export async function fetchEvents(cursor: string): Promise<FeedEvent[]> {
+  return withRetry(async () => {
+    const res = await fetch(`${FEED_URL}?cursor=${encodeURIComponent(cursor)}`, {
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) throw new Error(`feed ${res.status}`);
+    return (await res.json()) as FeedEvent[];
+  });
+}

package/packs/solution-architect/skills/context-graph/evals/files/5/services/ingest/retry.ts

@@ -0,0 +1,20 @@
+// Ingest retry policy — RFC-0003. Do not change to a fixed interval (see INC-114).
+const BASE_MS = 200;
+const CAP_MS = 30_000;
+const MAX_ATTEMPTS = 6;
+
+export async function withRetry<T>(fn: () => Promise<T>): Promise<T> {
+  let attempt = 0;
+  for (;;) {
+    try {
+      return await fn();
+    } catch (err) {
+      attempt += 1;
+      if (attempt >= MAX_ATTEMPTS) throw err;
+      const ceiling = Math.min(CAP_MS, BASE_MS * 2 ** attempt);
+      await sleep(Math.random() * ceiling); // full jitter
+    }
+  }
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

package/packs/solution-architect/skills/context-graph/evals/files/6/README.md

@@ -0,0 +1,4 @@
+# harbourline
+
+Freight billing and invoicing platform. Monorepo: `services/` for deployables, `libs/` for shared code.
+Decision records live in `docs/adr/` (architecture decision records) and `docs/rfcs/` (larger proposals).

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/adr/0001-monorepo-layout.md

@@ -0,0 +1,10 @@
+# ADR-0001: Monorepo layout
+
+- Status: Accepted
+- Date: 2023-02-10
+- Deciders: Platform team (H. Okafor, L. Brandt)
+- Governs: `services/`, `libs/`
+
+## Decision
+One repository. Each deployable service gets its own folder under `services/<name>/`; shared code goes
+under `libs/`. A service folder is never shared by two deployables.

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/adr/0002-billing-on-postgres.md

@@ -0,0 +1,13 @@
+# ADR-0002: Billing data lives in Postgres
+
+- Status: Accepted
+- Date: 2023-05-03
+- Deciders: H. Okafor, M. Szabo
+- Governs: `services/billing/`
+
+## Decision
+The billing service stores charges and the invoice ledger in the shared Postgres cluster
+(table `invoices_ledger`). Writes are transactional updates in place.
+
+## Consequences
+Reporting can join billing tables directly. Corrections overwrite the row and keep no history.

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/adr/0004-ledger-sync-nightly-batch.md

@@ -0,0 +1,9 @@
+# ADR-0004: Ledger sync runs as a nightly batch
+
+- Status: Accepted
+- Date: 2023-09-12
+- Deciders: L. Brandt
+- Governs: `services/ledger-sync/`
+
+## Decision
+Ledger sync to the finance system runs once a night at 02:00 UTC as a batch job, not as a stream.

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/rfcs/RFC-0003-invoice-ids.md

@@ -0,0 +1,9 @@
+# RFC-0003: Invoice identifiers
+
+- Status: Accepted
+- Date: 2023-06-20
+- Author: M. Szabo
+- Governs: `services/invoicing/ids/`
+
+## Proposal
+Invoice IDs are sequential integers issued by a Postgres sequence, formatted `INV-000123`.

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/rfcs/RFC-0007-invoice-ids-ulid.md

@@ -0,0 +1,11 @@
+# RFC-0007: Switch invoice identifiers to ULIDs
+
+- Status: Accepted
+- Date: 2024-03-01
+- Author: R. Achebe
+- Supersedes: RFC-0003
+- Governs: `services/invoicing/ids/`
+
+## Proposal
+Sequential IDs leaked customer invoice volumes and forced a single writer. Invoice IDs become ULIDs,
+generated in-process, formatted `INV-<ulid>`. Existing `INV-000123` IDs stay valid.

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/rfcs/RFC-0009-billing-event-store.md

@@ -0,0 +1,15 @@
+# RFC-0009: Billing writes go to an append-only event store
+
+- Status: Accepted
+- Date: 2024-08-14
+- Author: R. Achebe
+- Governs: `services/billing/`
+- Builds on: RFC-0012 (event schema registry)
+
+## Proposal
+Billing records every charge and correction as an immutable event in the DynamoDB table
+`billing-events`. Current balances are projections of the event stream. This gives auditors a full
+history of corrections.
+
+## Rollout
+Phase 1: write events alongside the existing store. Phase 2: read balances from projections.

package/packs/solution-architect/skills/context-graph/evals/files/6/docs/rfcs/RFC-0010-revenue-service.md

@@ -0,0 +1,13 @@
+# RFC-0010: Merge billing and invoicing into a revenue service
+
+- Status: Proposed
+- Date: 2026-09-30
+- Author: L. Brandt
+- Governs: `services/revenue/` (new)
+
+## Proposal
+Move `services/billing/` and `services/invoicing/` into a single deployable at `services/revenue/`,
+with `billing/` and `invoicing/` as internal modules. Both old folders are deleted after the move.
+
+## Records affected
+- ADR-0002 (billing storage) — path changes to `services/revenue/billing/`.

package/packs/solution-architect/skills/context-graph/evals/files/6/libs/money/ulid.py

@@ -0,0 +1,8 @@
+"""Minimal ULID helper (placeholder implementation for the fixture)."""
+
+import os
+import time
+
+
+def new_ulid():
+    return f"{int(time.time() * 1000):012x}{os.urandom(10).hex()}"

package/packs/solution-architect/skills/context-graph/evals/files/6/services/billing/src/events.py

@@ -0,0 +1,10 @@
+"""Phase 1 of the event store rollout: append every charge as an event."""
+
+EVENTS_TABLE = "billing-events"
+
+
+def append_charge_event(client, invoice_id, amount_minor, at):
+    client.put_item(
+        TableName=EVENTS_TABLE,
+        Item={"invoice_id": invoice_id, "type": "charge", "amount_minor": amount_minor, "at": at},
+    )

package/packs/solution-architect/skills/context-graph/evals/files/6/services/billing/src/store.py

@@ -0,0 +1,10 @@
+"""Billing persistence: in-place updates to the Postgres invoice ledger."""
+
+LEDGER_TABLE = "invoices_ledger"
+
+
+def record_charge(conn, invoice_id, amount_minor):
+    conn.execute(
+        f"UPDATE {LEDGER_TABLE} SET balance_minor = balance_minor + %s WHERE invoice_id = %s",
+        (amount_minor, invoice_id),
+    )

package/packs/solution-architect/skills/context-graph/evals/files/6/services/invoicing/ids/generator.py

@@ -0,0 +1,7 @@
+"""Invoice ID generation."""
+
+from libs.money.ulid import new_ulid
+
+
+def new_invoice_id():
+    return f"INV-{new_ulid()}"

package/packs/solution-architect/skills/context-graph/evals/files/6/services/ledger/README.md

@@ -0,0 +1,4 @@
+# ledger
+
+Formerly `services/ledger-sync/` (renamed in 2025 when it gained the reconciliation report).
+Still runs the nightly sync to the finance system at 02:00 UTC.

package/packs/solution-architect/skills/context-graph/evals/files/6/services/ledger/sync.py

@@ -0,0 +1,3 @@
+"""Nightly ledger sync to the finance system."""
+
+SCHEDULE_CRON = "0 2 * * *"

package/packs/solution-architect/skills/context-graph/evals/files/7/README.md

@@ -0,0 +1,4 @@
+# fernwood
+
+Multi-tenant data platform: ingest pipelines, an event bus, and the services on top.
+Design decisions: `design/decisions/` (DD-nnn). Bigger proposals: `rfcs/`.

package/packs/solution-architect/skills/context-graph/evals/files/7/db/queries/orders.sql

@@ -0,0 +1,2 @@
+-- name: get_order
+SELECT id, tenant_id, total_minor FROM orders WHERE id = %(id)s AND tenant_id = %(tenant_id)s;

package/packs/solution-architect/skills/context-graph/evals/files/7/db/sharding/router.py

@@ -0,0 +1,9 @@
+"""Pick the shard for a tenant (DD-006)."""
+
+import hashlib
+
+SHARD_COUNT = 16
+
+
+def shard_for(tenant_id: str) -> int:
+    return int(hashlib.sha256(tenant_id.encode()).hexdigest(), 16) % SHARD_COUNT

package/packs/solution-architect/skills/context-graph/evals/files/7/design/decisions/DD-001-postgres-primary.md

@@ -0,0 +1,8 @@
+# DD-001: Postgres is the primary datastore
+
+Status: Accepted
+Date: 2022-04-11
+Deciders: O. Mensah
+Governs: db/, services/
+
+All service state lives in Postgres. No second OLTP database without a new decision.

package/packs/solution-architect/skills/context-graph/evals/files/7/design/decisions/DD-002-kafka-event-bus.md

@@ -0,0 +1,20 @@
+# DD-002: Kafka is the event bus
+
+Status: Accepted
+Date: 2022-06-02
+Deciders: O. Mensah, T. Lindqvist
+Governs: pipelines/ingest/, pipelines/fanout/
+
+## Context
+Ingest events must reach several independent consumers (fan-out, billing export, the audit sink),
+and a consumer that is down for a deploy must be able to catch up afterwards.
+
+## Options considered
+1. Postgres LISTEN/NOTIFY — rejected: notifications are lost if no listener is connected at the
+   moment they fire, there is no replay, and payloads are capped at 8000 bytes.
+2. RabbitMQ — rejected: no long replay window without extra plugins.
+3. Kafka — chosen.
+
+## Decision
+Use Kafka. Every topic keeps 7 days of retention so any consumer can replay a week of events.
+Retention policy details: see DD-007.

package/packs/solution-architect/skills/context-graph/evals/files/7/design/decisions/DD-003-no-orm.md

@@ -0,0 +1,9 @@
+# DD-003: No ORM in services
+
+Status: Accepted
+Date: 2022-07-19
+Deciders: T. Lindqvist
+Governs: services/
+
+Services use hand-written SQL kept in db/queries/. No ORM: we want query plans reviewable in code
+review and no lazy-loading surprises on hot paths.

package/packs/solution-architect/skills/context-graph/evals/files/7/design/decisions/DD-006-tenant-sharding.md

@@ -0,0 +1,9 @@
+# DD-006: Shard by tenant
+
+Status: Accepted
+Date: 2023-01-30
+Deciders: Platform guild (O. Mensah, R. Vidal)
+Governs: db/sharding/
+
+Each tenant's data lives on exactly one shard, chosen by a hash of tenant_id. Cross-tenant queries
+go through the reporting replica, never the shards.

package/packs/solution-architect/skills/context-graph/evals/files/7/design/decisions/DD-011-orm-for-admin-console.md

@@ -0,0 +1,11 @@
+# DD-011: Allow SQLAlchemy in the admin console
+
+Status: Accepted
+Date: 2024-05-08
+Deciders: R. Vidal
+Amends: DD-003
+Governs: services/admin-console/
+
+The admin console is internal, low-traffic CRUD over ~40 tables. Hand-written SQL there cost more
+than it saved. SQLAlchemy is allowed in services/admin-console/ only. Every other service keeps
+DD-003's no-ORM rule.

package/packs/solution-architect/skills/context-graph/evals/files/7/pipelines/fanout/router.py

@@ -0,0 +1,4 @@
+"""Fans ingest.normalised out to downstream consumers."""
+
+GROUP_ID = "fanout-router"
+SOURCE_TOPIC = "ingest.normalised"

package/packs/solution-architect/skills/context-graph/evals/files/7/pipelines/ingest/consumer.py

@@ -0,0 +1,5 @@
+"""Reads ingest.raw, normalises records, publishes to ingest.normalised."""
+
+GROUP_ID = "ingest-normaliser"
+SOURCE_TOPIC = "ingest.raw"
+SINK_TOPIC = "ingest.normalised"

package/packs/solution-architect/skills/context-graph/evals/files/7/pipelines/ingest/topics.yaml

@@ -0,0 +1,8 @@
+# Kafka topic config for ingest
+topics:
+  - name: ingest.raw
+    partitions: 12
+    retention.ms: 259200000
+  - name: ingest.normalised
+    partitions: 12
+    retention.ms: 259200000

package/packs/solution-architect/skills/context-graph/evals/files/7/rfcs/0004-region-sharding.md

@@ -0,0 +1,15 @@
+# RFC 0004: Shard by region instead of tenant
+
+Status: Withdrawn
+Date: 2025-02-14
+Author: P. Tamboli
+Supersedes: DD-006
+Governs: db/sharding/
+
+## Proposal
+Move from tenant sharding to region sharding (eu, us, apac) so data-residency rules map to shards.
+
+## Withdrawal note (2025-03-20)
+Withdrawn after the cost review: re-sharding every tenant was estimated at two quarters of work and
+residency can be met by pinning tenants to regional shards under the existing scheme. Tenant
+sharding (DD-006) stays.

package/packs/solution-architect/skills/context-graph/evals/files/7/services/admin-console/models.py

@@ -0,0 +1,11 @@
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Tenant(Base):
+    __tablename__ = "tenants"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str]

package/packs/solution-architect/skills/context-graph/evals/files/7/services/orders/repo.py

@@ -0,0 +1,9 @@
+"""Orders persistence. SQL lives in db/queries/orders.sql."""
+
+from pathlib import Path
+
+QUERIES = Path(__file__).resolve().parents[2] / "db" / "queries" / "orders.sql"
+
+
+def load_queries():
+    return QUERIES.read_text()

package/packs/solution-architect/skills/context-graph/evals/files/8/README.md

@@ -0,0 +1,11 @@
+# harbor-ledger
+
+Double-entry ledger service for the Harbor payments platform.
+
+- `services/ledger/` — the ledger service (Python)
+- `api/` — service interface definitions
+- `config/` — runtime configuration
+- `docs/adr/` — architecture decision records
+- `docs/rfcs/` — proposals under discussion
+
+`services/ledger/api/gen/` is generated from `api/ledger.proto` at build time and is not checked in.

package/packs/solution-architect/skills/context-graph/evals/files/8/api/ledger.proto

@@ -0,0 +1,30 @@
+syntax = "proto3";
+
+package harbor.ledger.v1;
+
+// Public interface of the ledger service. Client stubs are generated from this file.
+service Ledger {
+  rpc PostEntry(PostEntryRequest) returns (PostEntryResponse);
+  rpc GetBalance(GetBalanceRequest) returns (Balance);
+}
+
+message PostEntryRequest {
+  string idempotency_key = 1;
+  string account_id = 2;
+  int64 amount_minor = 3;
+  string currency = 4;
+}
+
+message PostEntryResponse {
+  string entry_id = 1;
+}
+
+message GetBalanceRequest {
+  string account_id = 1;
+}
+
+message Balance {
+  string account_id = 1;
+  int64 balance_minor = 2;
+  string currency = 3;
+}

package/packs/solution-architect/skills/context-graph/evals/files/8/config/http.yaml

@@ -0,0 +1,10 @@
+# Outbound HTTP settings for the payment-provider client
+provider:
+  base_url: https://provider.example.invalid/v2
+  timeout_seconds: 30
+  max_retries: 5
+  backoff:
+    base_ms: 200
+    jitter: full
+  retry_methods: [GET, POST]
+  api_key: REPLACE_ME

package/packs/solution-architect/skills/context-graph/evals/files/8/config/messaging.yaml

@@ -0,0 +1,8 @@
+# Domain event publishing
+broker: kafka
+bootstrap_servers:
+  - kafka-0.harbor.internal:9092
+  - kafka-1.harbor.internal:9092
+topic: ledger.entry-events
+key: account_id
+acks: all

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,20 @@
+# 1. Record architecture decisions
+
+Date: 2024-01-10
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as described by Michael Nygard, kept in `docs/adr/`.
+Larger proposals that need discussion first go in `docs/rfcs/` and become an ADR once accepted.
+
+## Consequences
+
+See Michael Nygard's article for a detailed description of the process.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0002-postgresql-for-ledger.md

@@ -0,0 +1,22 @@
+# 2. Use PostgreSQL for ledger storage
+
+Date: 2024-01-22
+
+## Status
+
+Accepted
+
+## Context
+
+The ledger needs transactional writes across journal entries and account balances, and the
+team already operates PostgreSQL for two other services.
+
+## Decision
+
+Ledger state lives in PostgreSQL. Schema changes are plain SQL migrations under
+`services/ledger/db/migrations/`, numbered sequentially and never edited once merged.
+
+## Consequences
+
+- Balances are computed inside a transaction with the entries that change them.
+- No ORM-generated migrations.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0003-rabbitmq-domain-events.md

@@ -0,0 +1,22 @@
+# 3. Publish domain events over RabbitMQ
+
+Date: 2024-02-14
+
+## Status
+
+Accepted
+
+## Context
+
+Downstream services (notifications, reporting) need to react when entries are posted.
+
+## Decision
+
+The ledger publishes `EntryPosted` and `AccountFrozen` events to a RabbitMQ topic exchange
+named `ledger.events`. Publishing code lives in `services/ledger/events/`. Broker settings
+are in `config/messaging.yaml`.
+
+## Consequences
+
+- Consumers bind their own queues; the ledger does not know who listens.
+- Events are at-least-once; consumers must be idempotent.