adopt-obs 0.3.0__py3-none-any.whl

adopt_obs/__init__.py

@@ -0,0 +1,63 @@
+"""Structured logging, typed errors, id generation, redaction, the clock.
+
+The public API of this package is the whole of the programme's observability
+surface. Three invariants hold across it and are enforced by CI rather than by
+review:
+
+1. **No log line ever contains client source, item bodies, prompt text or model
+   output.** There is no free-text log parameter, and deny-listed fields are
+   dropped at any depth and counted.
+2. **Every error code is in the contracts §13 registry.** `error-registry-sync`
+   fails the build in either direction.
+3. **Ids are generated nowhere else.** An unregistered prefix is rejected.
+"""
+
+from adopt_obs.clock import (
+    Clock,
+    ManualClock,
+    SystemClock,
+    format_timestamp,
+    now,
+    truncate_to_millisecond,
+)
+from adopt_obs.errors import (
+    CATEGORY_EXIT_CODES,
+    ERROR_CATEGORIES,
+    AdoptError,
+    ErrorCategory,
+    ErrorCode,
+    ExitCode,
+    exit_code_for,
+)
+from adopt_obs.ids import PREFIX_REGISTRY, UnknownPrefixError, new_id, split_id
+from adopt_obs.log import Logger, LogLevel, get_logger, new_run_id, set_sink
+from adopt_obs.redact import DENIED_FIELDS, REDACTED, RedactionResult, redact
+
+__all__ = [
+    "CATEGORY_EXIT_CODES",
+    "DENIED_FIELDS",
+    "ERROR_CATEGORIES",
+    "PREFIX_REGISTRY",
+    "REDACTED",
+    "AdoptError",
+    "Clock",
+    "ErrorCategory",
+    "ErrorCode",
+    "ExitCode",
+    "LogLevel",
+    "Logger",
+    "ManualClock",
+    "RedactionResult",
+    "SystemClock",
+    "UnknownPrefixError",
+    "exit_code_for",
+    "format_timestamp",
+    "get_logger",
+    "new_id",
+    "new_run_id",
+    "now",
+    "redact",
+    "set_sink",
+    "split_id",
+    "truncate_to_millisecond",
+]

adopt_obs/clock.py

@@ -0,0 +1,112 @@
+"""The injectable clock. The only source of "now" in the programme.
+
+Sleeps in tests are banned (implementation spec §5). Time-window logic takes a
+:class:`Clock` and a test supplies :class:`ManualClock`, which makes the test
+both instant and deterministic -- a sleep is a flake with a delay attached.
+
+All times are RFC 3339, UTC, millisecond precision, ``Z``-suffixed. Local time
+never appears in a stored value or a wire payload.
+"""
+
+import datetime as _dt
+from typing import Final, Protocol, runtime_checkable
+
+__all__ = [
+    "Clock",
+    "ManualClock",
+    "SystemClock",
+    "format_timestamp",
+    "now",
+    "truncate_to_millisecond",
+]
+
+_TIMESTAMP_FORMAT: Final[str] = "%Y-%m-%dT%H:%M:%S"
+_MICROSECONDS_PER_MILLISECOND: Final[int] = 1000
+# const-sync: ok -- the width of a millisecond field, not SCHEMA_VERSION.
+_MILLISECOND_DIGITS: Final[int] = 3
+
+
+def format_timestamp(value: _dt.datetime) -> str:
+    """Render RFC 3339, UTC, millisecond precision, ``Z`` suffix.
+
+    Raises:
+        ValueError: the datetime is naive. A naive datetime has no defined
+            instant, and guessing that it means UTC is how a store ends up with
+            timestamps an hour apart from the same event.
+    """
+    if value.tzinfo is None:
+        raise ValueError("naive datetime: every timestamp must carry a timezone")
+    utc = value.astimezone(_dt.UTC)
+    millis = utc.microsecond // _MICROSECONDS_PER_MILLISECOND
+    return f"{utc.strftime(_TIMESTAMP_FORMAT)}.{millis:0{_MILLISECOND_DIGITS}d}Z"
+
+
+def truncate_to_millisecond(value: _dt.datetime) -> _dt.datetime:
+    """Drop precision below a millisecond, in UTC.
+
+    Contracts §1.2 stores millisecond precision, so an instant a writer keeps in
+    memory at microsecond precision is **not** the instant that comes back out.
+    Anything that persists a timestamp truncates first, or the in-memory row and
+    its stored form differ by a value nobody can see and every equality check
+    trips over -- including the byte-identical export round-trip.
+
+    Raises:
+        ValueError: the datetime is naive.
+    """
+    if value.tzinfo is None:
+        raise ValueError("naive datetime: every timestamp must carry a timezone")
+    utc = value.astimezone(_dt.UTC)
+    millis = utc.microsecond // _MICROSECONDS_PER_MILLISECOND
+    return utc.replace(microsecond=millis * _MICROSECONDS_PER_MILLISECOND)
+
+
+@runtime_checkable
+class Clock(Protocol):
+    """The seam. Production passes :class:`SystemClock`; tests pass
+    :class:`ManualClock`."""
+
+    def now(self) -> _dt.datetime:
+        """The current instant, timezone-aware and in UTC."""
+        ...
+
+
+class SystemClock:
+    """The wall clock. The only implementation permitted in production code."""
+
+    def now(self) -> _dt.datetime:
+        return _dt.datetime.now(_dt.UTC)
+
+
+class ManualClock:
+    """A clock a test drives by hand.
+
+    ``advance()`` moves it forward; it never moves on its own, so a test that
+    depends on elapsed time states exactly how much elapsed instead of waiting
+    for it.
+    """
+
+    def __init__(self, start: _dt.datetime) -> None:
+        if start.tzinfo is None:
+            raise ValueError("ManualClock requires a timezone-aware start instant")
+        self._now = start.astimezone(_dt.UTC)
+
+    def now(self) -> _dt.datetime:
+        return self._now
+
+    def advance(self, delta: _dt.timedelta) -> None:
+        if delta < _dt.timedelta(0):
+            raise ValueError("a clock does not run backwards; use a new ManualClock")
+        self._now += delta
+
+
+_default: Final[SystemClock] = SystemClock()
+
+
+def now() -> _dt.datetime:
+    """The process-default clock reading.
+
+    Library code that can take a :class:`Clock` should take one. This exists
+    for the places that genuinely cannot -- module import time, and the logger's
+    own timestamp.
+    """
+    return _default.now()

adopt_obs/errors.py

@@ -0,0 +1,254 @@
+"""Typed errors, the code registry, categories, and the exit-code mapping.
+
+Every error the programme raises across a package boundary is an
+:class:`AdoptError` carrying a code from :class:`ErrorCode`. The registry below
+is the executable half of ``02-contracts-build0.md`` §13;
+``scripts/error_registry_sync.py`` fails the build when the two disagree in
+either direction, so a code cannot be added to the code without being
+documented, nor documented without being implemented.
+
+**Category is derived from the code, not supplied by the caller.** The
+implementation spec's signature ``AdoptError(code, category, message, hint)``
+still works, but passing a category that contradicts the registry raises rather
+than being accepted -- one code meaning two categories on two call sites is
+exactly the drift the registry exists to prevent.
+
+The exit-code mapping lives here rather than in the CLI because it is a
+function of the category, and the category is owned here. A second copy in the
+CLI would be a second place to get it wrong.
+"""
+
+from enum import StrEnum
+from typing import Final
+
+__all__ = [
+    "CATEGORY_EXIT_CODES",
+    "ERROR_CATEGORIES",
+    "AdoptError",
+    "ErrorCategory",
+    "ErrorCode",
+    "ExitCode",
+    "exit_code_for",
+]
+
+
+class ErrorCategory(StrEnum):
+    """The five categories in contracts §13."""
+
+    USAGE = "usage"
+    POLICY = "policy"
+    INTEGRITY = "integrity"
+    TRANSIENT = "transient"
+    INTERNAL = "internal"
+
+
+class ExitCode:
+    """Stable process exit codes (contracts §13, PRD F16.7).
+
+    Not an enum: these are returned to a shell, compared by integrators in
+    scripts, and must stay plain integers at every boundary.
+    """
+
+    SUCCESS: Final[int] = 0
+    OPERATIONAL_FAILURE: Final[int] = 1
+    USAGE_ERROR: Final[int] = 2
+    # const-sync: ok -- a contracts §13 exit code, fixed by contract, not a tunable.
+    POLICY_REFUSAL: Final[int] = 3
+    DEGRADED_WITH_FINDINGS: Final[int] = 4
+
+
+CATEGORY_EXIT_CODES: Final[dict[ErrorCategory, int]] = {
+    ErrorCategory.USAGE: ExitCode.USAGE_ERROR,
+    ErrorCategory.POLICY: ExitCode.POLICY_REFUSAL,
+    ErrorCategory.INTEGRITY: ExitCode.OPERATIONAL_FAILURE,
+    ErrorCategory.INTERNAL: ExitCode.OPERATIONAL_FAILURE,
+    # A transient failure is an operational failure to the caller. It is
+    # retriable, but the process still did not do what it was asked.
+    ErrorCategory.TRANSIENT: ExitCode.OPERATIONAL_FAILURE,
+}
+
+
+class ErrorCode(StrEnum):
+    """Every error code in contracts §13. Adding one here without adding it
+    there (or the reverse) fails `error-registry-sync`."""
+
+    ADOPT_OFFLINE_DENIED = "ADOPT_OFFLINE_DENIED"
+    ADOPT_CONFIG_UNRESOLVED = "ADOPT_CONFIG_UNRESOLVED"
+
+    SCHEMA_NON_ADDITIVE = "SCHEMA_NON_ADDITIVE"
+    SCHEMA_GENERATED_DRIFT = "SCHEMA_GENERATED_DRIFT"
+    SCHEMA_VERSION_TOO_NEW = "SCHEMA_VERSION_TOO_NEW"
+    SCHEMA_MIGRATION_PENDING = "SCHEMA_MIGRATION_PENDING"
+    SCHEMA_MIGRATION_FAILED = "SCHEMA_MIGRATION_FAILED"
+    SCHEMA_ASSETS_MISSING = "SCHEMA_ASSETS_MISSING"
+
+    STORE_READ_ONLY = "STORE_READ_ONLY"
+
+    SCOPE_SLUG_INVALID = "SCOPE_SLUG_INVALID"
+    SCOPE_SLUG_IMMUTABLE = "SCOPE_SLUG_IMMUTABLE"
+    SCOPE_SLUG_REUSED = "SCOPE_SLUG_REUSED"
+    SCOPE_VIOLATION = "SCOPE_VIOLATION"
+
+    URI_MALFORMED = "URI_MALFORMED"
+    URI_TOO_LONG = "URI_TOO_LONG"
+    URI_SCHEME_UNKNOWN = "URI_SCHEME_UNKNOWN"
+    URI_DOUBLE_ENCODED = "URI_DOUBLE_ENCODED"
+
+    REVISION_CHAIN_FORK = "REVISION_CHAIN_FORK"
+    REVISION_IMMUTABLE = "REVISION_IMMUTABLE"
+    REVISION_HEAD_DANGLING = "REVISION_HEAD_DANGLING"
+
+    COVERAGE_CACHE_DISAGREEMENT = "COVERAGE_CACHE_DISAGREEMENT"
+    FRESHNESS_SENSOR_DEGRADED = "FRESHNESS_SENSOR_DEGRADED"
+
+    EXPORT_VERSION_UNSUPPORTED = "EXPORT_VERSION_UNSUPPORTED"
+    EXPORT_DIGEST_MISMATCH = "EXPORT_DIGEST_MISMATCH"
+    EXPORT_ROUNDTRIP_UNSTABLE = "EXPORT_ROUNDTRIP_UNSTABLE"
+    EXPORT_SCOPE_AMBIGUOUS = "EXPORT_SCOPE_AMBIGUOUS"
+    EXPORT_BUNDLE_MALFORMED = "EXPORT_BUNDLE_MALFORMED"
+    EXPORT_TARGET_NOT_EMPTY = "EXPORT_TARGET_NOT_EMPTY"
+
+    DETECT_AMBIGUOUS = "DETECT_AMBIGUOUS"
+    TIER_INSUFFICIENT = "TIER_INSUFFICIENT"
+    TIER_DECLINE_RECOMMENDED = "TIER_DECLINE_RECOMMENDED"
+    TIER_ANSWERS_INVALID = "TIER_ANSWERS_INVALID"
+
+    MANIFEST_UNDECLARED_HOST = "MANIFEST_UNDECLARED_HOST"
+    MANIFEST_MISSING_SAFE_PATH = "MANIFEST_MISSING_SAFE_PATH"
+    MANIFEST_INVALID = "MANIFEST_INVALID"
+
+    ENVELOPE_CONTENT_UNDER_METADATA_ONLY = "ENVELOPE_CONTENT_UNDER_METADATA_ONLY"
+    ENVELOPE_POLICY_NOT_PERMITTED = "ENVELOPE_POLICY_NOT_PERMITTED"
+
+    AGENT_ADAPTER_UNKNOWN = "AGENT_ADAPTER_UNKNOWN"
+    AGENT_OFFLINE_ADAPTER_DENIED = "AGENT_OFFLINE_ADAPTER_DENIED"
+    AGENT_BUDGET_EXHAUSTED = "AGENT_BUDGET_EXHAUSTED"
+    AGENT_OUTPUT_SCHEMA = "AGENT_OUTPUT_SCHEMA"
+    AGENT_PROVIDER_ERROR = "AGENT_PROVIDER_ERROR"
+
+    WORKFLOW_STEP_EXHAUSTED = "WORKFLOW_STEP_EXHAUSTED"
+    WORKFLOW_BODY_IMPURE = "WORKFLOW_BODY_IMPURE"
+    WORKFLOW_DUPLICATE_START = "WORKFLOW_DUPLICATE_START"
+
+    LICENCE_POLICY_VIOLATION = "LICENCE_POLICY_VIOLATION"
+
+
+#: Code -> category, verbatim from the contracts §13 table.
+ERROR_CATEGORIES: Final[dict[ErrorCode, ErrorCategory]] = {
+    ErrorCode.ADOPT_OFFLINE_DENIED: ErrorCategory.POLICY,
+    ErrorCode.ADOPT_CONFIG_UNRESOLVED: ErrorCategory.USAGE,
+    ErrorCode.SCHEMA_NON_ADDITIVE: ErrorCategory.POLICY,
+    ErrorCode.SCHEMA_GENERATED_DRIFT: ErrorCategory.INTEGRITY,
+    ErrorCode.SCHEMA_VERSION_TOO_NEW: ErrorCategory.POLICY,
+    ErrorCode.SCHEMA_MIGRATION_PENDING: ErrorCategory.USAGE,
+    ErrorCode.SCHEMA_MIGRATION_FAILED: ErrorCategory.INTEGRITY,
+    # The installed artefact does not carry the schema assets it needs. Integrity
+    # rather than usage: the operator did nothing wrong and no flag fixes it --
+    # what they hold was built incompletely.
+    ErrorCode.SCHEMA_ASSETS_MISSING: ErrorCategory.INTEGRITY,
+    ErrorCode.STORE_READ_ONLY: ErrorCategory.POLICY,
+    ErrorCode.SCOPE_SLUG_INVALID: ErrorCategory.USAGE,
+    ErrorCode.SCOPE_SLUG_IMMUTABLE: ErrorCategory.POLICY,
+    ErrorCode.SCOPE_SLUG_REUSED: ErrorCategory.POLICY,
+    ErrorCode.SCOPE_VIOLATION: ErrorCategory.POLICY,
+    ErrorCode.URI_MALFORMED: ErrorCategory.USAGE,
+    ErrorCode.URI_TOO_LONG: ErrorCategory.USAGE,
+    ErrorCode.URI_SCHEME_UNKNOWN: ErrorCategory.USAGE,
+    ErrorCode.URI_DOUBLE_ENCODED: ErrorCategory.USAGE,
+    ErrorCode.REVISION_CHAIN_FORK: ErrorCategory.INTEGRITY,
+    ErrorCode.REVISION_IMMUTABLE: ErrorCategory.POLICY,
+    ErrorCode.REVISION_HEAD_DANGLING: ErrorCategory.INTEGRITY,
+    ErrorCode.COVERAGE_CACHE_DISAGREEMENT: ErrorCategory.INTEGRITY,
+    ErrorCode.FRESHNESS_SENSOR_DEGRADED: ErrorCategory.POLICY,
+    ErrorCode.EXPORT_VERSION_UNSUPPORTED: ErrorCategory.POLICY,
+    ErrorCode.EXPORT_DIGEST_MISMATCH: ErrorCategory.INTEGRITY,
+    ErrorCode.EXPORT_ROUNDTRIP_UNSTABLE: ErrorCategory.INTEGRITY,
+    ErrorCode.EXPORT_SCOPE_AMBIGUOUS: ErrorCategory.POLICY,
+    ErrorCode.EXPORT_BUNDLE_MALFORMED: ErrorCategory.INTEGRITY,
+    ErrorCode.EXPORT_TARGET_NOT_EMPTY: ErrorCategory.POLICY,
+    ErrorCode.DETECT_AMBIGUOUS: ErrorCategory.USAGE,
+    ErrorCode.TIER_INSUFFICIENT: ErrorCategory.POLICY,
+    ErrorCode.TIER_DECLINE_RECOMMENDED: ErrorCategory.POLICY,
+    ErrorCode.TIER_ANSWERS_INVALID: ErrorCategory.USAGE,
+    ErrorCode.MANIFEST_UNDECLARED_HOST: ErrorCategory.POLICY,
+    ErrorCode.MANIFEST_MISSING_SAFE_PATH: ErrorCategory.POLICY,
+    ErrorCode.MANIFEST_INVALID: ErrorCategory.USAGE,
+    ErrorCode.ENVELOPE_CONTENT_UNDER_METADATA_ONLY: ErrorCategory.POLICY,
+    ErrorCode.ENVELOPE_POLICY_NOT_PERMITTED: ErrorCategory.POLICY,
+    ErrorCode.AGENT_ADAPTER_UNKNOWN: ErrorCategory.USAGE,
+    ErrorCode.AGENT_OFFLINE_ADAPTER_DENIED: ErrorCategory.POLICY,
+    ErrorCode.AGENT_BUDGET_EXHAUSTED: ErrorCategory.POLICY,
+    ErrorCode.AGENT_OUTPUT_SCHEMA: ErrorCategory.INTERNAL,
+    ErrorCode.AGENT_PROVIDER_ERROR: ErrorCategory.TRANSIENT,
+    ErrorCode.WORKFLOW_STEP_EXHAUSTED: ErrorCategory.INTERNAL,
+    ErrorCode.WORKFLOW_BODY_IMPURE: ErrorCategory.POLICY,
+    ErrorCode.WORKFLOW_DUPLICATE_START: ErrorCategory.USAGE,
+    ErrorCode.LICENCE_POLICY_VIOLATION: ErrorCategory.POLICY,
+}
+
+#: `AGENT_BUDGET_EXHAUSTED` is returned as `AgentResult.status` and is **never
+#: raised** (contracts §13). Constructing it as an exception is a programming
+#: error, not a runtime condition, so it is refused at construction.
+_NEVER_RAISED: Final[frozenset[ErrorCode]] = frozenset({ErrorCode.AGENT_BUDGET_EXHAUSTED})
+
+
+def exit_code_for(code: ErrorCode) -> int:
+    """The process exit code a given error code should terminate with."""
+    return CATEGORY_EXIT_CODES[ERROR_CATEGORIES[code]]
+
+
+class AdoptError(Exception):
+    """The one error type that crosses a package boundary.
+
+    Never raise a bare exception across a package boundary and never swallow
+    one. A message is for a human; the ``code`` is what callers, tests and the
+    CLI's exit status branch on.
+    """
+
+    def __init__(
+        self,
+        code: ErrorCode,
+        category: ErrorCategory | None = None,
+        message: str = "",
+        hint: str | None = None,
+        *,
+        run_id: str | None = None,
+    ) -> None:
+        registered = ERROR_CATEGORIES[code]
+        if category is not None and category is not registered:
+            raise ValueError(
+                f"{code} is registered as {registered}, not {category}. "
+                "Change contracts §13 and ERROR_CATEGORIES together, or use the "
+                "registered category."
+            )
+        if code in _NEVER_RAISED:
+            raise ValueError(f"{code} is a returned status, never a raised error (contracts §13).")
+        self.code: Final[ErrorCode] = code
+        self.category: Final[ErrorCategory] = registered
+        self.message: Final[str] = message
+        self.hint: Final[str | None] = hint
+        self.run_id: Final[str | None] = run_id
+        super().__init__(message or str(code))
+
+    @property
+    def exit_code(self) -> int:
+        """The process exit code this error should terminate with."""
+        return exit_code_for(self.code)
+
+    def to_envelope(self) -> dict[str, dict[str, str | None]]:
+        """Render the one documented error envelope from contracts §13.
+
+        Only the fields the contract declares. In particular the traceback and
+        the exception chain are deliberately absent: an envelope is emitted to
+        a client-facing surface, and a traceback carries file paths and, via
+        local variables in some renderings, content.
+        """
+        return {
+            "error": {
+                "code": str(self.code),
+                "category": str(self.category),
+                "message": self.message,
+                "hint": self.hint,
+                "run_id": self.run_id,
+            }
+        }

adopt_obs/ids.py

@@ -0,0 +1,182 @@
+"""Prefixed ULID generation. The only place an id is created in the programme.
+
+Ids are ``<prefix>_<26-char Crockford base32>``, generated store-side and never
+by callers. The prefix registry below is the executable copy of
+``02-contracts-build0.md`` §1.1: an unregistered prefix is rejected rather than
+minted, because a typo'd prefix produces an id that looks valid, joins to
+nothing, and is indistinguishable from data loss six months later.
+
+Ids are **monotonic**. Two ids minted in the same millisecond still sort in
+creation order, which is what lets export row ordering be deterministic by
+primary key without a separate sequence column.
+"""
+
+import os
+import threading
+import time
+from typing import Final
+
+__all__ = ["PREFIX_REGISTRY", "UnknownPrefixError", "new_id", "split_id"]
+
+# Crockford base32: no I, L, O or U, so a transcribed id cannot become a
+# different valid id through a reading mistake.
+_ALPHABET: Final[str] = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+# const-sync: ok -- base32 packs five bits per character, not WORKFLOW_STEP_MAX_ATTEMPTS.
+_BITS_PER_CHAR: Final[int] = 5
+_CHAR_MASK: Final[int] = 0x1F
+# const-sync: ok -- a byte is eight bits, not CONFORMANCE_CI_MAX_MINUTES.
+_BITS_PER_BYTE: Final[int] = 8
+
+# ULID layout: 48 bits of millisecond timestamp, 80 bits of randomness.
+# const-sync: ok -- 48 here is the ULID timestamp width, not SLUG_MAX_CHARS.
+_TIMESTAMP_BITS: Final[int] = 48
+_RANDOM_BITS: Final[int] = 80
+# const-sync: ok -- ten base32 characters cover the timestamp, not a minute budget.
+_TIMESTAMP_CHARS: Final[int] = 10
+_RANDOM_CHARS: Final[int] = 16
+_ULID_CHARS: Final[int] = _TIMESTAMP_CHARS + _RANDOM_CHARS
+_MAX_RANDOM: Final[int] = (1 << _RANDOM_BITS) - 1
+_MAX_TIMESTAMP: Final[int] = (1 << _TIMESTAMP_BITS) - 1
+_RANDOM_BYTES: Final[int] = _RANDOM_BITS // _BITS_PER_BYTE
+_MS_PER_SECOND: Final[int] = 1000
+
+#: The prefix registry, verbatim from contracts §1.1.
+#:
+#: `run_` is the log and trace correlation id. It appears in the error envelope
+#: (`error.run_id`) and on every structured log line, so it must be mintable
+#: here; it was added to §1.1 in the same change that introduced this module.
+PREFIX_REGISTRY: Final[dict[str, str]] = {
+    "firm": "firm",
+    "eng": "engagement",
+    "sys": "system",
+    "env": "environment",
+    "sle": "system_lifecycle_event",
+    "idn": "identity",
+    "irev": "identity_revision",
+    "ki": "knowledge_item",
+    "krev": "knowledge_revision",
+    "prov": "provenance",
+    "bnd": "binding",
+    "brev": "binding_revision",
+    "cf": "conflict",
+    "conn": "connector",
+    "sen": "sensor",
+    "pd": "probe_definition",
+    "pdrev": "probe_definition_revision",
+    "prun": "probe_run",
+    "pobs": "probe_observation",
+    "bv": "baseline_version",
+    "ce": "change_event",
+    "cls": "classification",
+    "clsv": "classifier_version",
+    "sre": "silent_repair_eligibility",
+    "rb": "review_batch",
+    "ri": "review_item",
+    "apr": "approval",
+    "esc": "escalation",
+    "own": "ownership_assignment",
+    "aud": "audit_event",
+    "ob": "observability_boundary",
+    "vb": "value_baseline",
+    "ve": "value_event",
+    "act": "actor (external reference)",
+    "ag": "agent_run (runtime annex)",
+    "run": "run (log and trace correlation)",
+}
+
+
+class UnknownPrefixError(ValueError):
+    """Raised when a caller asks for an id with an unregistered prefix."""
+
+
+_lock = threading.Lock()
+_last_timestamp_ms: int = -1
+_last_random: int = 0
+
+
+def _wall_clock_ms() -> int:
+    """Wall-clock milliseconds.
+
+    Deliberately not the injectable clock: a ULID's timestamp component is an
+    ordering device, not an observation. Freezing it in a test would make ids
+    non-monotonic across the freeze and would be asserting the wrong thing --
+    monotonicity is guaranteed by the counter below, not by time moving.
+    """
+    return int(time.time() * _MS_PER_SECOND)
+
+
+def _encode(value: int, length: int) -> str:
+    out = ["0"] * length
+    for i in range(length - 1, -1, -1):
+        out[i] = _ALPHABET[value & _CHAR_MASK]
+        value >>= _BITS_PER_CHAR
+    return "".join(out)
+
+
+def _next_ulid() -> str:
+    """Mint a monotonic ULID.
+
+    Within one millisecond the random component is incremented rather than
+    redrawn, so ordering is total even under a tight write loop. On the
+    astronomically unlikely overflow the timestamp advances by one millisecond,
+    which keeps ordering correct at the cost of a timestamp one tick ahead.
+    """
+    global _last_timestamp_ms, _last_random
+
+    with _lock:
+        now = _wall_clock_ms()
+        if now > _MAX_TIMESTAMP:  # pragma: no cover -- year 10889
+            raise OverflowError("ULID timestamp space exhausted")
+        if now == _last_timestamp_ms:
+            if _last_random >= _MAX_RANDOM:
+                _last_timestamp_ms += 1
+                _last_random = int.from_bytes(os.urandom(_RANDOM_BYTES)) >> 1
+            else:
+                _last_random += 1
+        elif now < _last_timestamp_ms:
+            # The wall clock moved backwards (NTP step, VM restore). Hold the
+            # previous millisecond and keep incrementing: an id that sorts
+            # correctly matters more than an id whose timestamp is accurate.
+            _last_random += 1
+        else:
+            _last_timestamp_ms = now
+            _last_random = int.from_bytes(os.urandom(_RANDOM_BYTES)) >> 1
+        timestamp, randomness = _last_timestamp_ms, _last_random
+
+    return _encode(timestamp, _TIMESTAMP_CHARS) + _encode(randomness, _RANDOM_CHARS)
+
+
+def new_id(prefix: str) -> str:
+    """Mint a prefixed ULID.
+
+    ``prefix`` is accepted with or without its trailing underscore -- both
+    ``new_id("firm")`` and ``new_id("firm_")`` yield ``firm_01J...``.
+
+    Raises:
+        UnknownPrefixError: the prefix is not in the contracts §1.1 registry.
+    """
+    key = prefix[:-1] if prefix.endswith("_") else prefix
+    if key not in PREFIX_REGISTRY:
+        known = ", ".join(sorted(PREFIX_REGISTRY))
+        raise UnknownPrefixError(
+            f"unregistered id prefix {prefix!r}; "
+            f"register it in contracts §1.1 and PREFIX_REGISTRY first. Known: {known}"
+        )
+    return f"{key}_{_next_ulid()}"
+
+
+def split_id(value: str) -> tuple[str, str]:
+    """Split a prefixed id into ``(prefix, ulid)``, validating both halves.
+
+    Raises:
+        UnknownPrefixError: the prefix is unregistered.
+        ValueError: the ULID component is malformed.
+    """
+    prefix, separator, ulid = value.partition("_")
+    if not separator:
+        raise ValueError(f"malformed id {value!r}: no prefix separator")
+    if prefix not in PREFIX_REGISTRY:
+        raise UnknownPrefixError(f"unregistered id prefix {prefix!r} in {value!r}")
+    if len(ulid) != _ULID_CHARS or any(c not in _ALPHABET for c in ulid):
+        raise ValueError(f"malformed ULID component in {value!r}")
+    return prefix, ulid

adopt_obs/log.py

@@ -0,0 +1,169 @@
+"""Structured logging. One JSON object per line, no free text, ever.
+
+The signature is the control. :meth:`Logger.emit` takes an ``event`` -- a stable
+snake_case name -- and keyword fields. There is **no message parameter**, so
+there is no channel through which a body, a prompt, a model output or a chunk of
+client source can be logged as prose. That is what makes the log queryable and
+what makes "no client content in any log line" a structural property rather than
+a habit.
+
+Every line carries ``ts``, ``level``, ``event`` and ``run_id``. Deny-listed
+fields are dropped at any depth and the drop count is emitted as
+``redacted_fields``, so an attempted leak is visible in the log rather than
+silent.
+
+OSS mode is local only, with zero telemetry, permanently. Lines go to stderr or
+to a local file the operator chose. There is no opt-in switch to add later.
+"""
+
+import json
+import sys
+from enum import StrEnum
+from typing import Any, Final, TextIO
+
+from adopt_obs.clock import Clock, SystemClock, format_timestamp
+from adopt_obs.ids import new_id
+from adopt_obs.redact import redact
+
+__all__ = ["LogLevel", "Logger", "get_logger", "new_run_id", "set_sink"]
+
+_RESERVED_FIELDS: Final[frozenset[str]] = frozenset(
+    {"ts", "level", "event", "logger", "run_id", "redacted_fields"}
+)
+
+
+class LogLevel(StrEnum):
+    DEBUG = "debug"
+    INFO = "info"
+    WARN = "warn"
+    ERROR = "error"
+    #: Alarm-grade: a defect signal that must page, not merely be recorded.
+    #: `COVERAGE_CACHE_DISAGREEMENT` is the canonical example.
+    ALARM = "alarm"
+
+
+# Ordering is derived from declaration order rather than written out, so the
+# ranks cannot drift from the enum and no integer literal appears here at all.
+_LEVEL_ORDER: Final[dict[LogLevel, int]] = {
+    level: rank
+    for rank, level in enumerate(
+        (LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARN, LogLevel.ERROR, LogLevel.ALARM)
+    )
+}
+
+_sink: TextIO = sys.stderr
+_min_level: LogLevel = LogLevel.INFO
+
+
+def set_sink(stream: TextIO, *, min_level: LogLevel = LogLevel.INFO) -> None:
+    """Point the log at a stream. Used by the CLI and by tests.
+
+    There is no network sink and no remote handler to configure, by design.
+    """
+    global _sink, _min_level
+    _sink = stream
+    _min_level = min_level
+
+
+def new_run_id() -> str:
+    """Mint a correlation id for one CLI invocation or one unit of work."""
+    return new_id("run")
+
+
+class Logger:
+    """A named emitter. Obtain one with :func:`get_logger`.
+
+    A logger may carry its own ``sink``. Without one it writes to the process
+    sink set by :func:`set_sink`. Per-logger sinks exist so a caller -- a test,
+    or an embedded use where two components log to different destinations --
+    never has to mutate process-wide state to redirect output.
+    """
+
+    __slots__ = ("_clock", "_name", "_run_id", "_sink")
+
+    def __init__(self, name: str, run_id: str, clock: Clock, sink: TextIO | None = None) -> None:
+        self._name = name
+        self._run_id = run_id
+        self._clock = clock
+        self._sink = sink
+
+    @property
+    def run_id(self) -> str:
+        return self._run_id
+
+    def bind_run(self, run_id: str) -> "Logger":
+        """A copy of this logger correlated to a different run."""
+        return Logger(self._name, run_id, self._clock, self._sink)
+
+    def emit(self, level: LogLevel, event: str, /, **fields: Any) -> None:
+        """Emit one line.
+
+        Args:
+            level: severity.
+            event: a stable snake_case event name. Positional-only, so it can
+                never be mistaken for a formatted message.
+            **fields: structured fields. Deny-listed names are dropped at any
+                depth and counted.
+
+        Raises:
+            ValueError: the event name is not a stable lowercase identifier, or
+                a field collides with a reserved key.
+        """
+        if _LEVEL_ORDER[level] < _LEVEL_ORDER[_min_level]:
+            return
+        if not event or not event.replace("_", "").replace(".", "").isalnum():
+            raise ValueError(
+                f"event name {event!r} must be a stable snake_case identifier "
+                "(dots permitted for namespacing); log lines carry no free text"
+            )
+        if event != event.lower():
+            raise ValueError(f"event name {event!r} must be lowercase")
+        collisions = _RESERVED_FIELDS & fields.keys()
+        if collisions:
+            raise ValueError(f"fields {sorted(collisions)} collide with reserved log keys")
+
+        result = redact(fields)
+        line: dict[str, Any] = {
+            "ts": format_timestamp(self._clock.now()),
+            "level": str(level),
+            "event": event,
+            "logger": self._name,
+            "run_id": self._run_id,
+        }
+        line.update(result.value)
+        if result.dropped:
+            line["redacted_fields"] = result.dropped
+        # `default=str` renders an unexpected object as its repr rather than
+        # raising mid-emit. A logger that can throw while reporting a failure
+        # turns one incident into two.
+        sink = self._sink if self._sink is not None else _sink
+        sink.write(json.dumps(line, sort_keys=False, default=str) + "\n")
+        sink.flush()
+
+    def debug(self, event: str, /, **fields: Any) -> None:
+        self.emit(LogLevel.DEBUG, event, **fields)
+
+    def info(self, event: str, /, **fields: Any) -> None:
+        self.emit(LogLevel.INFO, event, **fields)
+
+    def warn(self, event: str, /, **fields: Any) -> None:
+        self.emit(LogLevel.WARN, event, **fields)
+
+    def error(self, event: str, /, **fields: Any) -> None:
+        self.emit(LogLevel.ERROR, event, **fields)
+
+    def alarm(self, event: str, /, **fields: Any) -> None:
+        """Alarm-grade: a defect signal that pages. Use sparingly and never for
+        an expected condition."""
+        self.emit(LogLevel.ALARM, event, **fields)
+
+
+def get_logger(
+    name: str,
+    *,
+    run_id: str | None = None,
+    clock: Clock | None = None,
+    sink: TextIO | None = None,
+) -> Logger:
+    """Obtain a named logger, minting a run id when one is not supplied."""
+    return Logger(name, run_id or new_run_id(), clock or SystemClock(), sink)

adopt_obs/redact.py

@@ -0,0 +1,80 @@
+"""The field deny-list: the mechanism behind "no client content in a log line".
+
+Deny-listed field names are **dropped and counted**, at any nesting depth, on
+every structured log line and every error envelope. Counting matters as much as
+dropping: a silent drop looks identical to a caller that never passed the field,
+so the count is what makes an attempted leak visible in the log itself.
+
+This is defence in depth, not the primary control. The primary control is that
+:func:`adopt_obs.log.get_logger` has **no free-text message argument** -- there
+is no parameter through which a body, a prompt or a model output can be
+smuggled as prose. The deny-list catches the remaining case: a caller who puts
+content into a structured field.
+"""
+
+from typing import Any, Final
+
+__all__ = ["DENIED_FIELDS", "REDACTED", "RedactionResult", "redact"]
+
+#: Verbatim from implementation spec §4.2 and PRD F16.4.
+#:
+#: Matching is on the field *name*, case-insensitively, at any depth. It is not
+#: a heuristic over values: a value-sniffing redactor gives false confidence,
+#: because the moment it misses once the promise "no content in logs" is false
+#: and nobody knows.
+DENIED_FIELDS: Final[frozenset[str]] = frozenset(
+    {"body", "content", "prompt", "output", "source", "text", "answer", "question"}
+)
+
+#: What a dropped field is replaced by when the caller asked for replacement
+#: rather than removal. Never the value, never a truncation of the value, and
+#: never a hash of the value -- a hash of a short secret is a lookup away from
+#: the secret.
+REDACTED: Final[str] = "[redacted]"
+
+_MAX_DEPTH: Final[int] = 32
+
+
+class RedactionResult:
+    """A sanitized value together with how many fields were dropped."""
+
+    __slots__ = ("dropped", "value")
+
+    def __init__(self, value: Any, dropped: int) -> None:
+        self.value = value
+        self.dropped = dropped
+
+    def __repr__(self) -> str:
+        return f"RedactionResult(dropped={self.dropped})"
+
+
+def _walk(value: Any, depth: int, counter: list[int]) -> Any:
+    if depth > _MAX_DEPTH:
+        # A structure this deep is not a log field. Refusing to descend caps
+        # the work done on a hostile input and cannot leak, because the value
+        # is replaced rather than rendered.
+        return REDACTED
+    if isinstance(value, dict):
+        cleaned: dict[str, Any] = {}
+        for key, item in value.items():
+            name = str(key)
+            if name.casefold() in DENIED_FIELDS:
+                counter[0] += 1
+                continue
+            cleaned[name] = _walk(item, depth + 1, counter)
+        return cleaned
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [_walk(item, depth + 1, counter) for item in value]
+    return value
+
+
+def redact(value: Any) -> RedactionResult:
+    """Drop every deny-listed field at any depth, counting the drops.
+
+    Scalars pass through untouched: this function sanitizes *shapes*, and a
+    caller who passes a bare secret string as the whole payload has already
+    bypassed the field vocabulary the logger enforces.
+    """
+    counter = [0]
+    cleaned = _walk(value, 0, counter)
+    return RedactionResult(cleaned, counter[0])

adopt_obs-0.3.0.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.5
+Name: adopt-obs
+Version: 0.3.0
+Summary: Structured logging, typed errors, id generation, redaction, the injectable clock.
+Project-URL: Homepage, https://github.com/onboardux/onboard-core
+Project-URL: Source, https://github.com/onboardux/onboard-core
+Project-URL: Issues, https://github.com/onboardux/onboard-core/issues
+Author: The Adopt Authors
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.12
+Requires-Dist: adopt-const

adopt_obs-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+adopt_obs/__init__.py,sha256=rwCPTYzBP-S7cL_nOdlHtDlNgoNZLDYa3_3-3gkn_Tg,1681
+adopt_obs/clock.py,sha256=bRVSZUgyCZtUhrEvuKKdrevl4SnWCHnP4BH9qcRr63M,3836
+adopt_obs/errors.py,sha256=Rz5mOULoQXUpAaiNiJZdCKdhcbxV2POJp5TnFXYTt7U,10737
+adopt_obs/ids.py,sha256=BeVnHaNarosoFtc4Kx0ZSF1WkqT_FDnNKu8dvOYJ5_o,6857
+adopt_obs/log.py,sha256=EQI8qwoybrYx9EbV_JoCf6rodU5DjciMbWSnkr0W23o,6189
+adopt_obs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+adopt_obs/redact.py,sha256=180EC96sh_lN82VoP2y1hq3V8w4cK0KsxuONFxteLgk,3171
+adopt_obs-0.3.0.dist-info/METADATA,sha256=yCYb9UZ0o_ze-v7TmN-f0kJhDcP22SBt9xDZ6UhAfvE,493
+adopt_obs-0.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+adopt_obs-0.3.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+adopt_obs-0.3.0.dist-info/licenses/NOTICE,sha256=2_mgo6v6IM9fAn52L5-wXFpISnC6PVU_geTutoRhbWk,1897
+adopt_obs-0.3.0.dist-info/RECORD,,

adopt_obs-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

adopt_obs-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

adopt_obs-0.3.0.dist-info/licenses/NOTICE

@@ -0,0 +1,39 @@
+Adopt — Adoption-Phase Platform, shared substrate (`adopt-core`)
+Copyright 2026 The Adopt Authors
+
+This product includes software developed by The Adopt Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+--------------------------------------------------------------------------------
+Attribution note
+--------------------------------------------------------------------------------
+
+The copyright holder is recorded here as "The Adopt Authors" pending the legal
+entity name. The owner must settle that attribution before the 0.3.0 tag,
+because published package metadata cannot be changed retroactively for a
+release that has already left the machine. The product name itself is settled:
+handoff-index CR-50 keeps `Adopt` distinct from the `onboard` URI namespace.
+
+--------------------------------------------------------------------------------
+Third-party dependencies
+--------------------------------------------------------------------------------
+
+Every third-party dependency linked into this distribution is permissively
+licensed. The complete list, with licence hash, security status, usage mode,
+owner and re-verification date, is maintained in `licence-verifications.md` and
+enforced by `scripts/licence_gate.py`.
+
+Copyleft-licensed tools are invoked as subprocesses only and are never linked
+into this distribution. They are declared in `subprocess-deps.toml` together
+with their invocation sites.