rcf-lite 0.17.0 → 0.19.0

package/blueprints/observability-logging/README.md

@@ -0,0 +1,44 @@
+# Logging blueprint (v1.0.0)
+
+Structured single-line JSON emission for a rcf-lite project. General enterprise practice, no vendor lock-in. Ships the shelf-canonical `logging` global topic on `ADR-1601-observability-logging-line-shape` (transferred from `application-api-rest-ADR-304`, retained there as superseded history). Provides the `logging` role for the companion-suggestion mechanism.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/observability-logging
+```
+
+Applies namespaced contributions into the project tree and records `manifest.blueprints[]`. Apply is idempotent; `rcf define blueprint list` shows the applied entry; `rcf define blueprint remove observability-logging` cleanly removes an unreferenced application.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version 1.0.0, category `observability`, `providesRoles: ["logging"]`, and the 19 contributions with scope/topic on `ADR-1601` |
+| Doc set | `contributions/` | 5 REQs, 8 USs (13 ACs), 2 TACs, 4 ADRs, schema-valid and namespaced (`observability-logging-REQ-001` prefix family; `ADR-1601-observability-logging-line-shape` suffix family) |
+| Log line sample | `assets/samples/log-line.json` | Exact JSON shape of one emitted line carrying the shared minimum field set |
+| Guide | `guide/observability-logging.md` | Operator-facing: when to use it, when not, what stays your call, mechanism-reach gaps |
+| Coordination vocabulary | `docs/topics.md` | The `logging` global-topic string this blueprint claims, plus the shelf-wide id band registry update |
+
+The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets and docs are package-resident references.
+
+## What it contributes, and what it deliberately does not
+
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision 5) and no code.
+
+Deliberately not contributed: a specific log-shipping transport (Elastic Common Schema over Logstash, Loki push endpoints, Datadog agent, Splunk HEC); a rotation policy for on-disk log files (the shipped emission target is stdout, and the surrounding platform owns the pipe); a metrics-export surface (out of scope, sits with the metrics-store companion when the shelf ships one); a distributed-tracing surface (spans, propagation, sampling; out of scope for v1). The choice of ECS library (Elastic's, `pino-elastic-common-schema`, a project-authored shim) stays project-side; the blueprint names the ECS-neutral field set the AC binds to.
+
+## The one global decision
+
+`ADR-1601-observability-logging-line-shape` ships `scope: global` on topic `logging`. This is the project's structured emission contract: one JSON object per line to stdout with the shared minimum field set (message, level, timestamp, correlationId, environment, serviceName, serviceVersion). A composing blueprint that holds a different opinion (structured multi-line, per-service special format, non-JSON) conflicts here by design; the operator resolves at project level with `rcf define blueprint supersede logging --incoming <source>`.
+
+See `docs/topics.md` for the exact string, the expected resolutions, and the AC id band allocation (observability-logging owns 15101-15899, ADR/TAC suffix block 16xx).
+
+## Quality bar
+
+One JSON object per line on stdout carrying the shared minimum field set; serialisation failures caught at the boundary with a stderr notice and no service crash; correlation identifier accepted from an inbound header (default `X-Correlation-Id`, elicited alternative), propagated onto every log line, reflected on outbound requests, `null` when no ambient context; PII fields redacted at the emission boundary by named category (recommended defaults: credential, pii.email, pii.name, pii.address, token, bearer; elicited additions); operator-elicited minimum level per environment filtered per line; environment, serviceName and serviceVersion supplied at boot and stamped on every line; an in-memory capture mode for hermetic tests. Every bar is carried by ACs in the doc set, not by this README.
+
+## Known mechanism-reach gaps
+
+- **Call-site coverage.** The blueprint cannot prove every log-emitting call site uses the factory. A rogue `console.log` from any code path bypasses the boundary and lands unstructured text on stdout. Turning the discipline into a runtime-observable AC either becomes document-observable ("the source contains no `console.log`") or requires a project-side gate the blueprint does not ship. Named here rather than smuggled in as a v1 requirement. Promotion signal: a lint-rule contribution in a future rcf-lite blueprint or in the `delivery-ci-workflows` blueprint's shipped ruleset. Project-side workaround: a grep gate as a project-authored TC bound to `AC-15101-1` that walks the source tree for bare `console.` calls outside a whitelist.
+- **Text-level redaction.** ADR-1603 redacts at field-name granularity. A payload string that concatenates an email into the `message` field carries the email through the emission. Field-name redaction is fast and predictable; text-level redaction is expensive and prone to false positives. Project-side workaround: wrap the log call sites in a project-authored redaction pass; long-term, a future companion blueprint may claim a text-level `logRedaction` topic.

package/blueprints/observability-logging/assets/samples/log-line.json

@@ -0,0 +1,13 @@
+{
+  "message": "request completed",
+  "level": "info",
+  "timestamp": "2026-09-04T12:20:00.123Z",
+  "correlationId": "c3b8d0f1-4a2e-4a6f-9c1a-1234567890ab",
+  "environment": "production",
+  "serviceName": "orders-api",
+  "serviceVersion": "1.4.2",
+  "httpStatus": 200,
+  "requestPath": "/orders/42",
+  "durationMs": 37,
+  "userId": "[REDACTED:pii.name]"
+}

package/blueprints/observability-logging/blueprint.json

@@ -0,0 +1,27 @@
+{
+  "slug": "observability-logging",
+  "version": "1.0.0",
+  "category": "observability",
+  "providesRoles": ["logging"],
+  "contributions": [
+    { "id": "observability-logging-REQ-001", "kind": "req", "path": "requirements/observability-logging-req-001.json" },
+    { "id": "observability-logging-REQ-002", "kind": "req", "path": "requirements/observability-logging-req-002.json" },
+    { "id": "observability-logging-REQ-003", "kind": "req", "path": "requirements/observability-logging-req-003.json" },
+    { "id": "observability-logging-REQ-004", "kind": "req", "path": "requirements/observability-logging-req-004.json" },
+    { "id": "observability-logging-REQ-005", "kind": "req", "path": "requirements/observability-logging-req-005.json" },
+    { "id": "observability-logging-US-15101", "kind": "us", "path": "user-stories/observability-logging-us-15101.json" },
+    { "id": "observability-logging-US-15102", "kind": "us", "path": "user-stories/observability-logging-us-15102.json" },
+    { "id": "observability-logging-US-15103", "kind": "us", "path": "user-stories/observability-logging-us-15103.json" },
+    { "id": "observability-logging-US-15104", "kind": "us", "path": "user-stories/observability-logging-us-15104.json" },
+    { "id": "observability-logging-US-15105", "kind": "us", "path": "user-stories/observability-logging-us-15105.json" },
+    { "id": "observability-logging-US-15106", "kind": "us", "path": "user-stories/observability-logging-us-15106.json" },
+    { "id": "observability-logging-US-15107", "kind": "us", "path": "user-stories/observability-logging-us-15107.json" },
+    { "id": "observability-logging-US-15108", "kind": "us", "path": "user-stories/observability-logging-us-15108.json" },
+    { "id": "TAC-1601-observability-logging-logger-factory", "kind": "tac", "path": "tacs/tac-1601-observability-logging-logger-factory.json" },
+    { "id": "TAC-1602-observability-logging-redaction-boundary", "kind": "tac", "path": "tacs/tac-1602-observability-logging-redaction-boundary.json" },
+    { "id": "ADR-1601-observability-logging-line-shape", "kind": "adr", "path": "adrs/adr-1601-observability-logging-line-shape.json", "scope": "global", "topic": "logging" },
+    { "id": "ADR-1602-observability-logging-correlation-id-header", "kind": "adr", "path": "adrs/adr-1602-observability-logging-correlation-id-header.json", "recommendedDefault": true, "elicited": true, "standardsTraceClause": "generic enterprise practice" },
+    { "id": "ADR-1603-observability-logging-redaction-categories", "kind": "adr", "path": "adrs/adr-1603-observability-logging-redaction-categories.json", "recommendedDefault": true, "elicited": true, "standardsTraceClause": "generic enterprise practice" },
+    { "id": "ADR-1604-observability-logging-level-vocabulary", "kind": "adr", "path": "adrs/adr-1604-observability-logging-level-vocabulary.json", "recommendedDefault": true, "elicited": true, "standardsTraceClause": "generic enterprise practice" }
+  ]
+}

package/blueprints/observability-logging/contributions/adrs/adr-1601-observability-logging-line-shape.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1601-observability-logging-line-shape",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Structured single-line JSON to standard output with the shared minimum field set",
+  "context": "Every log ingestion pipeline the applying project's operator might reach for (Elastic Common Schema pipelines, Loki, Datadog, Splunk) parses one JSON object per line. Emissions that break this shape (multi-line stack traces, unstructured text, non-JSON) either drop from the pipeline silently or produce a per-service special case the operator maintains forever. The core shelf owned the 'logging' topic on application-api-rest-ADR-304 through the 0.18.0 line; from this blueprint the topic transfers to observability-logging so a shelf project without api-rest still gets a logging contract, and api-rest becomes a consumer.",
+  "decision": "Every log emission from the applying application lands as exactly one JSON object per line on process stdout. Every line carries the shared minimum field set: message (string), level (one string from the ADR-1604 vocabulary), timestamp (ISO-8601 with millisecond precision), correlationId (string or null), environment (string), serviceName (string), serviceVersion (string). Payload fields fold onto the top level of the object. A JSON serialisation failure at the boundary drops the emission with one stderr notice and returns to the caller without throwing.",
+  "consequences": "Any log ingestion pipeline that parses one JSON object per line consumes the applying application's stdout without a service-specific parser. Message search, level filtering, environment partitioning and service-version debugging all become one-field queries. The shared minimum field set is stable across every applying project; a project cannot silently rename or drop one of the seven without a major version bump. This ADR is the shelf-canonical owner of the 'logging' topic; the previously superseded application-api-rest-ADR-304 defers to it. Composing blueprints that want a different logging surface (structured multi-line, per-service special format, non-JSON) conflict on the 'logging' topic and the operator resolves at project level.",
+  "alternativesConsidered": [
+    {
+      "name": "Free-form text emission",
+      "summary": "The application writes plain text log messages with no structural discipline.",
+      "reasonNotChosen": "Every ingestion pipeline needs a per-service parser, and every parser breaks the moment a caller changes a phrase. The industry-standard shape for the tier this blueprint targets is one JSON object per line."
+    },
+    {
+      "name": "Multi-line JSON with pretty-printing",
+      "summary": "One JSON object per emission but pretty-printed across multiple lines for human readability.",
+      "reasonNotChosen": "Breaks the one-line assumption every log pipeline holds. Pretty printing is a rendering concern of the consuming tool, not of the emitter."
+    }
+  ],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/adrs/adr-1602-observability-logging-correlation-id-header.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1602-observability-logging-correlation-id-header",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Correlation identifier header name is X-Correlation-Id by recommended default; operator elicits an alternative at apply",
+  "context": "Inbound requests may arrive with correlation identifiers under different header names depending on the surrounding platform: X-Correlation-Id in generic HTTP tooling, X-Request-Id in reverse proxies, traceparent in W3C Trace Context clients. Picking one at the code level forces every applying project to align; making it operator-elicited lets the applying platform's convention win.",
+  "decision": "The recommended default correlation header is X-Correlation-Id. The applying operator elicits an alternative at apply time; the elicited value is recorded on the applied ADR. The application accepts the elicited header on inbound requests and reflects it as the SAME header name on outbound requests.",
+  "consequences": "A project sitting behind a reverse proxy that already stamps X-Request-Id sets the elicited value to X-Request-Id and inherits the proxy's identifier without a code change. A project with no upstream stamping keeps the recommended default and mints v4 UUIDs. The header name is fixed for the process lifetime; changing it is a re-apply.",
+  "alternativesConsidered": [
+    {
+      "name": "Hard-code X-Correlation-Id",
+      "summary": "The application accepts only X-Correlation-Id and no elicited alternative.",
+      "reasonNotChosen": "Projects sitting behind a proxy that stamps a different header lose the upstream identifier and mint a new one on every request; the whole point of the mechanism is to inherit an existing identifier when one is present."
+    },
+    {
+      "name": "Adopt W3C Trace Context traceparent as the sole surface",
+      "summary": "The application requires the traceparent header for correlation, following the W3C Trace Context standard.",
+      "reasonNotChosen": "The applying tier for this blueprint is small greenfield applications; requiring a Trace Context client on every calling service would force upstream tooling the tier does not otherwise need. A project that operates in a Trace Context ecosystem elicits traceparent as the header name and inherits the standard."
+    }
+  ],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/adrs/adr-1603-observability-logging-redaction-categories.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1603-observability-logging-redaction-categories",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Redaction categories: credential, pii.email, pii.name, pii.address, token, bearer by recommended default; operator elicits additions",
+  "context": "PII redaction in logs is one of the most common compliance surfaces (GDPR, PCI DSS, HIPAA); a blueprint that ships no default vocabulary forces every applying project to invent its own on day one, which reliably produces a coverage gap. A vocabulary that pretends to be exhaustive fights every project's actual field surface. Splitting recommended defaults from elicited additions gets both.",
+  "decision": "The recommended default category set is credential, pii.email, pii.name, pii.address, token, bearer. A field whose name equals or path-tail-matches any of these categories is redacted at the emission boundary. The applying operator elicits additional category names at apply (kebab or dotted-namespace grammar; refused with a boot error otherwise); elicited additions apply alongside the defaults. The applied ADR records the final category list the applying project uses.",
+  "consequences": "A project's logs never emit a field named 'credential', 'pii.email', 'pii.name', 'pii.address', 'token' or 'bearer' with a real value out of the box, before the operator has thought about redaction. Additional per-domain categories (ssn, iban, jwt) land through the elicited additions at apply without a code change. Free-text redaction inside the message string (an email pasted into an error message) is out of scope; the mechanism reach is field-level, not text-level.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship no default vocabulary",
+      "summary": "The blueprint ships a redaction contract but no default category list; every applying project supplies its own from scratch.",
+      "reasonNotChosen": "Reliably produces a coverage gap on day one because the operator has not yet enumerated the field surface. Recommended defaults with elicited additions give a working floor and a project-side extension path in the same round."
+    },
+    {
+      "name": "Redact by field-value pattern rather than field-name category",
+      "summary": "The boundary walks every value and redacts against pattern lists (regex for emails, credit cards, tokens).",
+      "reasonNotChosen": "Pattern-matching every value on every emission is expensive at scale and produces false positives that make logs unusable. Field-name category matching is fast and predictable; the trade-off is that a field with an unrelated name that holds a PII value is not redacted, which is what the field-name grammar exists to catch."
+    }
+  ],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/adrs/adr-1604-observability-logging-level-vocabulary.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-1604-observability-logging-level-vocabulary",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Level vocabulary is trace, debug, info, warn, error, fatal; operator elicits the minimum level per environment",
+  "context": "The industry has settled on a six-level vocabulary (trace, debug, info, warn, error, fatal); most log tooling (structured or otherwise) already understands these strings without translation. Production and development want different minimum levels; hard-coding info-and-above helps neither.",
+  "decision": "The recommended default vocabulary is exactly trace, debug, info, warn, error, fatal, in that severity order. The applying operator elicits a minimum level per environment at apply; the applied ADR records the elicited value. The factory refuses to construct with an unknown level string and drops emissions below the minimum before serialisation.",
+  "consequences": "The vocabulary is stable across every applying project; log tooling wires its level filter once. Per-environment minimums honour the production-development split without changing call sites. A future project that wants a different vocabulary (Apache-style FATAL/ERROR/WARN/INFO/DEBUG/TRACE) supersedes this ADR at project level; the vocabulary transfer is a mechanical string rename in call sites.",
+  "alternativesConsidered": [
+    {
+      "name": "Adopt Apache log4j-style ALL/TRACE/DEBUG/INFO/WARN/ERROR/FATAL/OFF vocabulary",
+      "summary": "The blueprint ships the historically-familiar seven-plus-two vocabulary from log4j.",
+      "reasonNotChosen": "ALL and OFF are configuration meta-levels, not emission levels; conflating them with severities has produced enough confusion that modern structured-logging tools omit them. The six emission levels above match what today's tools accept out of the box."
+    }
+  ],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/requirements/observability-logging-req-001.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "observability-logging-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Every service surface emits structured single-line JSON log lines through the shared factory",
+  "description": "Every log emission from the applying application passes through the logger factory contract TAC-1601 produces, writes one JSON object per line to standard output, and includes at minimum the fields message (string), level (one of the level vocabulary in ADR-1604), timestamp (ISO-8601 with millisecond precision), correlationId (string, may be null when no ambient context), environment (string), serviceName (string) and serviceVersion (string). A log emission that fails to serialise (a value that is not JSON-representable, a circular reference) is caught, dropped with a one-time stderr notice, and the calling code path continues; a serialisation failure never crashes the service.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "Downstream log ingestion tooling (Elastic Common Schema pipelines, Loki, Datadog, Splunk) parses one JSON object per line. Multi-line stack traces or unstructured text break the pipeline and produce silent data loss. Threading every emission through one factory closes the drift class where a stray console.log lands unstructured text alongside structured lines.",
+  "tags": ["blueprint:observability-logging", "category:01-structured-emission"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/requirements/observability-logging-req-002.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "observability-logging-REQ-002",
+  "prdId": "PRD-001",
+  "title": "The application accepts, propagates and reflects a correlation identifier on every log line",
+  "description": "The application reads a correlation identifier from an inbound request header (name governed by ADR-1602; default X-Correlation-Id, elicited per project), threads it through the request-scoped context using the mechanism the TAC exposes, includes it on every log line emitted during that request, and reflects it on any outbound request initiated inside the same context. When no inbound identifier is present, the application mints a v4 UUID and treats it as the ambient value. Requests processed with no ambient context (a scheduled task boot, a background worker startup line) log with correlationId equal to null; the field is always present.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "Correlation identifiers are the mechanism that stitches together the log lines of a single logical request across multiple services and multiple retries. Without acceptance-and-reflection at every hop, log search cannot follow the chain. Present-but-null is a legitimate ambient state (boot-time logs, cron); refusing to log without an identifier fights the operator when they need the emission most.",
+  "tags": ["blueprint:observability-logging", "category:02-correlation-id"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/requirements/observability-logging-req-003.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "observability-logging-REQ-003",
+  "prdId": "PRD-001",
+  "title": "PII fields are redacted by named category at the emission boundary, not at the call site",
+  "description": "The logger factory exposes a redaction contract (ADR-1603 recommended-default categories: credential, pii.email, pii.name, pii.address, token, bearer; elicited additions per project). A field named or path-labelled with a category is replaced with the string [REDACTED:<category>] before the line is serialised, whether the log call site remembered to redact or not. Redaction happens at the emission boundary (TAC-1602): a rogue field name in a caller-supplied object is redacted by rule, not by hope. The redaction pass never mutates the caller's original object; the emission pipeline copies the object first.",
+  "category": "nonFunctional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "PII leaks through logs are one of the most common data-exposure defects in production systems. Placing the redaction responsibility at the call site produces a coverage gap the size of the codebase; placing it at the boundary is the only scalable enforcement. Named categories keep the vocabulary auditable and let a project add its own categories at apply time.",
+  "tags": ["blueprint:observability-logging", "category:03-pii-redaction"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/requirements/observability-logging-req-004.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "observability-logging-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Every environment has an operator-elicited minimum log level; the factory refuses to emit below it",
+  "description": "The logger factory reads a minimum level per environment (ADR-1604 recommended default vocabulary: trace, debug, info, warn, error, fatal; the minimum level per environment is elicited at apply). Emissions below the minimum are dropped before serialisation; emissions at or above the minimum land on stdout. The environment name is supplied at boot (REQ-005) and the level filter is applied per line, not batched. Changing the minimum level mid-run through a documented hook (SIGHUP re-read, admin endpoint, config reload) is out of scope for v1; the minimum is fixed for the process lifetime.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "Production log volume is dominated by debug and trace lines; enabling them everywhere buries the signal. Development wants them; production does not. A per-environment operator-elicited minimum keeps the discipline explicit at apply time and lets the same code path serve both environments with the same call sites.",
+  "tags": ["blueprint:observability-logging", "category:04-level-vocabulary"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/requirements/observability-logging-req-005.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "observability-logging-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Every log line carries environment, service name and service version, all operator-elicited at boot",
+  "description": "The three fields (environment, serviceName, serviceVersion) are supplied to the logger factory at boot from operator-elicited configuration (environment variables, config file, deployment manifest); the factory refuses to construct a logger when any of the three is missing or blank. Every emitted line carries all three at fixed field names so log ingestion can partition by environment and service without prose parsing.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "A shared log destination sees lines from every environment and every service. Without machine-readable partitioning fields, filtering by environment or service requires string search on the message field, which is fragile and prone to false positives. Requiring the three fields at boot puts the discipline at the earliest possible surface.",
+  "tags": ["blueprint:observability-logging", "category:05-boot-fields"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/tacs/tac-1601-observability-logging-logger-factory.json

@@ -0,0 +1,46 @@
+{
+  "tacId": "TAC-1601-observability-logging-logger-factory",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Logger factory",
+  "purpose": "Owns the construction of every logger the application uses. Threads the operator-elicited boot fields (environment, serviceName, serviceVersion, minimum level, correlation header name, redaction categories) into a shared factory contract; every call site takes a logger from the factory and never constructs one directly. Provides a hermetic in-memory capture mode for tests.",
+  "responsibilities": [
+    "Construct a logger from operator-elicited boot fields; refuse construction when environment, serviceName or serviceVersion is missing or blank (AC-15105-1), and refuse when the minimum level is not one of the recommended-default vocabulary (AC-15106-1).",
+    "Emit each log call as one JSON line to standard output carrying the shared minimum field set (AC-15101-1), applying the level filter per line (AC-15104-1).",
+    "Expose an in-memory capture mode returning an ordered array of the structured objects the same emission would have written to stdout (AC-15107-1), with zero stdout side effects.",
+    "Catch serialisation failures (BigInt, function reference, circular object) at the boundary, drop the emission with one stderr notice naming the offending field, and return without throwing to the caller (AC-15101-2).",
+    "Read the ambient correlation context per emission and thread it onto the correlationId field (AC-15102-1), or null when no context is active (AC-15102-3)."
+  ],
+  "internalStructure": "One module exporting createLoggerFactory({ environment, serviceName, serviceVersion, minimumLevel, correlationHeader, redactionCategories, now, sink }) -> { getLogger(name) -> Logger, capturedLines() }. The factory closes over boot fields, a now() clock (default () -> new Date()) and a pluggable sink (default process.stdout; test-mode sink is an in-memory array). Loggers are lightweight wrappers around the sink. Serialisation is JSON.stringify with a replacer function that folds BigInt to string and short-circuits on circularity via a WeakSet, throwing a controlled SerializationRefusedError caught at the boundary.",
+  "interfaces": [
+    {
+      "name": "createLoggerFactory",
+      "kind": "factory",
+      "description": "createLoggerFactory({ environment, serviceName, serviceVersion, minimumLevel, correlationHeader, redactionCategories, now, sink }) -> { getLogger(name), capturedLines() }. The factory is constructed exactly once at boot; getLogger returns a per-module logger with .trace/.debug/.info/.warn/.error/.fatal methods each taking (message, payload?)."
+    },
+    {
+      "name": "Logger",
+      "kind": "interface",
+      "description": "One method per level; each takes (message: string, payload?: object). Emits one JSON line carrying message, level, timestamp, correlationId, environment, serviceName, serviceVersion, and every payload field folded onto the top level."
+    },
+    {
+      "name": "correlationHeader",
+      "kind": "config",
+      "description": "Operator-elicited inbound header name governing the correlation identifier acceptance and outbound propagation; recommended default X-Correlation-Id per ADR-1602."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Redaction boundary",
+      "kind": "tac",
+      "tacId": "TAC-1602-observability-logging-redaction-boundary",
+      "description": "The factory calls the redaction boundary on every serialised payload before the line is written to the sink; the boundary encapsulates the category vocabulary and the [REDACTED:<category>] rewriting."
+    }
+  ],
+  "tradeoffs": "The factory owns the field vocabulary; a project that wants an additional top-level field beyond the shared minimum authors it as a payload field (which appears on the line) rather than as a factory-side hook. Capture mode is a first-class interface, not a test-only afterthought: the runtime sink is one strategy the same interface serves, so the capture path exercises the same serialisation logic as the runtime path. The v1 blueprint does not ship a dynamic level-change interface; the level is fixed for the process lifetime (REQ-004).",
+  "notes": "Known mechanism-reach gap: the blueprint cannot prove every emission call site uses the factory. A project-side grep gate ('every log call is a factory-returned logger method, not a bare console.log') or a lint rule closes the class; the blueprint's guide names this gap.",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/tacs/tac-1602-observability-logging-redaction-boundary.json

@@ -0,0 +1,27 @@
+{
+  "tacId": "TAC-1602-observability-logging-redaction-boundary",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Redaction boundary",
+  "purpose": "Owns the redaction pass every emission passes through before the line lands on the sink. Encapsulates the category vocabulary from ADR-1603 (recommended defaults plus elicited additions) and the field-name matching rule; a payload field whose name or path label matches a category is replaced with the literal string [REDACTED:<category>] in the SERIALISED line, never in the caller's original object.",
+  "responsibilities": [
+    "Apply the redaction rule on a deep-cloned copy of the emission payload so the caller's original object is not mutated (AC-15103-1).",
+    "Accept elicited additional category names at boot (kebab or dotted-namespace grammar) and apply them alongside the recommended defaults (AC-15103-2).",
+    "Refuse construction when an elicited category name fails the accepted grammar (AC-15108-1)."
+  ],
+  "internalStructure": "One module exporting createRedactionBoundary({ categories }) -> { redact(payload) -> payload }. Categories is a Set of strings; matching walks payload keys (dot-path in nested objects) and replaces the value on the returned clone when the key equals or ends in a category name. The clone is a structuredClone unless the payload includes non-cloneable values, in which case the boundary falls back to a JSON round-trip clone with the serialisation-refused fold from TAC-1601.",
+  "interfaces": [
+    {
+      "name": "createRedactionBoundary",
+      "kind": "factory",
+      "description": "createRedactionBoundary({ categories: string[] }) -> { redact(payload: object): object }. Called once at boot from the logger factory; the factory holds the returned redact function and applies it on every emission."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "Redaction runs at the serialisation boundary and therefore only redacts fields the payload declares under a category-named key. Free-text redaction in the message string (an email pasted into a warning message) is out of scope for v1: the mechanism reach is field-level, not text-level. A project that needs text-level redaction wires a project-side wrapper around the logger call sites; the blueprint's guide names this gap.",
+  "notes": "",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/user-stories/observability-logging-us-15101.json

@@ -0,0 +1,34 @@
+{
+  "usId": "observability-logging-US-15101",
+  "prdId": "PRD-001",
+  "reqId": "observability-logging-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every log emission lands as one JSON object per line on stdout with the ratified minimum field set",
+  "asA": "operator running the application and consuming its stdout through a log ingestion pipeline",
+  "iWant": "every log emission to arrive as one JSON object on one line, carrying the shared minimum field set the pipeline expects",
+  "soThat": "the ingestion pipeline parses every line without special cases and no emission escapes as unstructured text",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15101-1",
+      "description": "A log emission at any level from any call site produces exactly one line on stdout, that line parses as valid JSON, and the parsed object carries every field of the shared minimum set: message, level, timestamp, correlationId, environment, serviceName, serviceVersion.",
+      "given": "a running application with the logger factory constructed and an ambient correlation context",
+      "when": "any call site emits at any level",
+      "then": "one stdout line results, JSON.parse succeeds, and the object has all seven minimum fields present with the correct types",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15101-2",
+      "description": "A log emission whose payload contains a non-JSON-representable value (a BigInt, a function reference, a circular object) is caught at the boundary, dropped with one stderr notice naming the offending field, and the calling code path returns as if the emission had succeeded; the service does not crash.",
+      "given": "a running application and a caller passing a BigInt or a circular object as part of a log payload",
+      "when": "the emission is attempted",
+      "then": "stdout carries no line for this emission, stderr carries one notice naming the offending field, and the caller's next line of code executes without throwing",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1601-observability-logging-logger-factory"],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/user-stories/observability-logging-us-15102.json

@@ -0,0 +1,43 @@
+{
+  "usId": "observability-logging-US-15102",
+  "prdId": "PRD-001",
+  "reqId": "observability-logging-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A correlation identifier read from the inbound request header rides every log line and every outbound request until the request ends",
+  "asA": "operator debugging a request path that spans multiple services",
+  "iWant": "the correlation identifier from the inbound request to appear on every log line the application emits during the request AND on every outbound request the application initiates within the same context",
+  "soThat": "log search returns the whole chain of a logical request across services from one string query",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15102-1",
+      "description": "A request arriving with the elicited correlation header (default X-Correlation-Id per ADR-1602) causes every log line emitted during the handler and its callees to carry correlationId equal to the header value; a request arriving without the header causes the application to mint a v4 UUID and the same value appears on every log line for the request.",
+      "given": "a running application with the correlation header configured and an inbound request",
+      "when": "the request is processed (with or without the header set)",
+      "then": "every log line emitted during the request carries the same correlationId value; header value wins when present; a v4 UUID is minted otherwise",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15102-2",
+      "description": "An outbound HTTP request initiated from within a request-scoped handler carries the ambient correlationId as the same elicited header name.",
+      "given": "an inbound request handler that issues an outbound HTTP call",
+      "when": "the outbound request is sent",
+      "then": "the outbound request headers include the correlation header with the ambient value",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15102-3",
+      "description": "A log emission with no ambient correlation context (boot line, scheduled task, background worker startup) carries correlationId equal to null; the field is present.",
+      "given": "a running application with no ambient request context",
+      "when": "a boot-time or background emission occurs",
+      "then": "the line carries correlationId: null",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1601-observability-logging-logger-factory"],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/user-stories/observability-logging-us-15103.json

@@ -0,0 +1,34 @@
+{
+  "usId": "observability-logging-US-15103",
+  "prdId": "PRD-001",
+  "reqId": "observability-logging-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Fields named or path-labelled with a PII category are redacted at the boundary regardless of call-site discipline",
+  "asA": "operator concerned that PII leaks through logs",
+  "iWant": "the emission boundary to redact fields with named PII categories automatically",
+  "soThat": "a rogue caller that forgets to redact does not leak PII to the log destination",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15103-1",
+      "description": "A log payload containing a field named or path-tagged with any of the recommended-default categories (credential, pii.email, pii.name, pii.address, token, bearer) is replaced with the literal string [REDACTED:<category>] in the emitted line; the caller's original object is not mutated (a subsequent read of the same object still shows the original value).",
+      "given": "an emission at any level whose payload includes a field tagged as pii.email",
+      "when": "the emission passes through the boundary",
+      "then": "the stdout line's field value equals [REDACTED:pii.email] and the caller-side object still holds the original address",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15103-2",
+      "description": "A project may add its own redaction categories at apply through the ADR-1603 elicited-additions parameter; a new category name (kebab or dotted-namespace) is accepted and applied by the boundary in the same round.",
+      "given": "a project that elicited an additional category ssn on ADR-1603",
+      "when": "an emission includes a field tagged ssn",
+      "then": "the stdout line's field value equals [REDACTED:ssn]",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1602-observability-logging-redaction-boundary"],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/user-stories/observability-logging-us-15104.json

@@ -0,0 +1,25 @@
+{
+  "usId": "observability-logging-US-15104",
+  "prdId": "PRD-001",
+  "reqId": "observability-logging-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Emissions below the operator-elicited minimum level are dropped before serialisation",
+  "asA": "operator sizing log volume for a production environment",
+  "iWant": "emissions below the minimum level to be dropped without serialising them",
+  "soThat": "log volume matches the operator's chosen signal budget and the level filter is honoured line-by-line",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15104-1",
+      "description": "With the elicited minimum level set to info, an emission at trace or debug produces no stdout line; an emission at info, warn, error or fatal produces one stdout line each.",
+      "given": "a running application with minimum level set to info",
+      "when": "one emission is issued at each of the six levels",
+      "then": "the stdout line count equals 4 (info, warn, error, fatal), and no line at trace or debug appears",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1601-observability-logging-logger-factory"],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/user-stories/observability-logging-us-15105.json

@@ -0,0 +1,34 @@
+{
+  "usId": "observability-logging-US-15105",
+  "prdId": "PRD-001",
+  "reqId": "observability-logging-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every log line reflects the operator-elicited environment, serviceName and serviceVersion",
+  "asA": "operator debugging in a shared log destination",
+  "iWant": "every log line to carry the environment, serviceName and serviceVersion the operator set at boot",
+  "soThat": "log queries partition by those three fields without prose parsing on the message string",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15105-1",
+      "description": "The logger factory refuses to construct when environment, serviceName or serviceVersion is missing or blank; construction failure throws with a message naming the missing field.",
+      "given": "an application booting with one of the three fields absent",
+      "when": "the logger factory is constructed",
+      "then": "the construction throws, the error message names the missing field, and the process exits before any emission is possible",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-15105-2",
+      "description": "Every emitted line carries environment, serviceName and serviceVersion at fixed field names and equal to the values the operator supplied at boot.",
+      "given": "a running application constructed with the three fields set",
+      "when": "any emission is issued",
+      "then": "the stdout line's three fields equal the operator-supplied values verbatim",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1601-observability-logging-logger-factory"],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/user-stories/observability-logging-us-15106.json

@@ -0,0 +1,25 @@
+{
+  "usId": "observability-logging-US-15106",
+  "prdId": "PRD-001",
+  "reqId": "observability-logging-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The logger factory refuses to construct with an unknown level string",
+  "asA": "operator wiring the logger factory at boot with a mis-configured minimum level",
+  "iWant": "the factory to refuse construction with a message naming the unknown level and the accepted vocabulary",
+  "soThat": "a typo in the environment variable is caught at boot rather than silently dropping every emission",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15106-1",
+      "description": "The factory refuses to construct when the elicited minimum level is not one of the recommended-default vocabulary (trace, debug, info, warn, error, fatal); the thrown error names the offending value and lists the accepted set.",
+      "given": "an application booting with minimum level set to 'verbose'",
+      "when": "the factory is constructed",
+      "then": "the construction throws with a message naming 'verbose' as the offending value and listing the accepted vocabulary",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1601-observability-logging-logger-factory"],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/blueprints/observability-logging/contributions/user-stories/observability-logging-us-15107.json

@@ -0,0 +1,25 @@
+{
+  "usId": "observability-logging-US-15107",
+  "prdId": "PRD-001",
+  "reqId": "observability-logging-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A test double captures emitted lines for assertion without touching stdout",
+  "asA": "test author verifying that the application emits the expected log lines during a test",
+  "iWant": "a test double the factory produces that captures emitted lines in memory instead of writing to stdout",
+  "soThat": "assertions on log emissions do not depend on stdout capture and do not pollute test output",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15107-1",
+      "description": "The blueprint's guide names an in-memory capture mode of the factory contract that returns an ordered array of the emitted structured objects; the capture mode is a documented API of TAC-1601 and can be constructed in a test without any stdout redirection.",
+      "given": "a test that constructs the factory in capture mode",
+      "when": "the code under test emits any number of log lines",
+      "then": "the returned array contains one entry per emission with the same object shape the runtime writes to stdout, and stdout carries no line",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1601-observability-logging-logger-factory"],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}