Airlock v3

[kenwalger]

No description provided.

[greptile-apps]

Greptile Summary

This PR introduces sovereign-sdk-airlock (v1.4.0), a new monorepo workspace member implementing a model-neutral outbound governance boundary. The package enforces YAML-configured policies, runs payload through a sieve convergence pass, and produces a signed ForensicReceipt committed to the sovereign ledger.

• Five new modules (boundary.py, payload.py, policy.py, receipt.py, telemetry.py) implement the four-component Airlock lifecycle \u2014 policy evaluation, sieve convergence, post-sieve telemetry evaluation, and evidence generation \u2014 behind a single async AirlockBoundary.process() entry point.
• 73-case test suite across four test files covers happy-path lifecycle, deny/warn/allow policy actions, transport normalisation (OpenAI, Anthropic, raw), deep payload immutability, ledger resiliency, and post-sieve telemetry rules.

Confidence Score: 4/5

The core orchestration, signing, ledger resiliency, and transport normalisation are solid. The one real concern is in policy.py’s rule parser — a mistyped metric name passes silently through init and causes the rule to evaluate the wrong data at runtime instead of rejecting the config early.

The policy engine validates scope and action at init time but omits the same validation for the metric field on telemetry rules. A typo like metric: raw_token is accepted without error and then silently falls back to token_estimate during pre-sieve evaluation rather than raising AirlockConfigurationError, meaning governance rules can appear configured while quietly checking the wrong value. All other modules are well-structured, immutably designed, and well-tested.

packages/sovereign-airlock/src/sovereign_airlock/policy.py — specifically the _parse_rule method and its handling of the metric field for telemetry-scoped rules.

Important Files Changed

Filename	Overview
packages/sovereign-airlock/src/sovereign_airlock/boundary.py	Async orchestrator for the four-component Airlock lifecycle; pre/post-sieve policy evaluation, non-fatal evidence recording, and clean AirlockResult assembly are all correctly implemented.
packages/sovereign-airlock/src/sovereign_airlock/policy.py	PolicyEngine loads and evaluates YAML rules with good early-fail validation for scope and action, but the metric field for telemetry-scoped rules is not validated at init time — a typo silently proxies against token_estimate. The prose_tax_warning_threshold fractional-vs-percentage unit convention is also easy to misconfigure.
packages/sovereign-airlock/src/sovereign_airlock/telemetry.py	Frozen AirlockTelemetry with zero-token guard and negative-savings clamp; upper-bound clamp to 100.0 is documented but not enforced.
packages/sovereign-airlock/src/sovereign_airlock/payload.py	NormalizedPayload frozen dataclass with deep immutability (tuple + MappingProxyType); three factory functions for OpenAI, Anthropic, and raw normalisation are well-implemented.
packages/sovereign-airlock/src/sovereign_airlock/receipt.py	ReceiptBuilder correctly separates signing (fatal) from ledger commit (non-fatal) per SAR-0009; metadata assembly is accurate and matches test assertions.
packages/sovereign-airlock/tests/test_boundary.py	Comprehensive 25-case async test suite covering the full lifecycle, all three transports, resiliency scenarios, prose-tax threshold, and payload immutability; asyncio_mode=auto in root pyproject.toml covers async test collection.
packages/sovereign-airlock/pyproject.toml	New workspace member at v1.4.0 with correct runtime dependencies (core, ledger, sieve, pyyaml); workspace registration in root pyproject.toml and uv.lock is consistent.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Caller
    participant AirlockBoundary
    participant PolicyEngine
    participant sieve_with_metrics
    participant AirlockTelemetry
    participant ReceiptBuilder
    participant SovereignKeyManager
    participant SovereignLedger

    Caller->>AirlockBoundary: process(NormalizedPayload)
    AirlockBoundary->>PolicyEngine: evaluate(payload)
    PolicyEngine-->>AirlockBoundary: PolicyVerdict
    alt deny verdict
        AirlockBoundary-->>Caller: raise AirlockPolicyViolation
    end
    AirlockBoundary->>sieve_with_metrics: sieve_with_metrics(raw_content)
    sieve_with_metrics-->>AirlockBoundary: SieveOutput
    AirlockBoundary->>AirlockTelemetry: from_sieve_output(sieve_output, raw_content)
    AirlockTelemetry-->>AirlockBoundary: AirlockTelemetry (frozen)
    AirlockBoundary->>PolicyEngine: evaluate_post_sieve(telemetry)
    PolicyEngine-->>AirlockBoundary: post PolicyVerdict
    alt post-sieve deny verdict
        AirlockBoundary-->>Caller: raise AirlockPolicyViolation
    end
    AirlockBoundary->>ReceiptBuilder: build_and_commit(sieved_content, telemetry, warnings, source)
    ReceiptBuilder->>SovereignKeyManager: generate_receipt(payload_dict, metadata)
    SovereignKeyManager-->>ReceiptBuilder: ForensicReceipt
    ReceiptBuilder->>SovereignLedger: append_receipt(receipt, sieved_content)
    Note over ReceiptBuilder,SovereignLedger: Ledger failure → WARNING log, non-fatal
    SovereignLedger-->>ReceiptBuilder: ok
    ReceiptBuilder-->>AirlockBoundary: ForensicReceipt
    AirlockBoundary-->>Caller: AirlockResult(sieved_content, telemetry, receipt, warnings)

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Caller
    participant AirlockBoundary
    participant PolicyEngine
    participant sieve_with_metrics
    participant AirlockTelemetry
    participant ReceiptBuilder
    participant SovereignKeyManager
    participant SovereignLedger

    Caller->>AirlockBoundary: process(NormalizedPayload)
    AirlockBoundary->>PolicyEngine: evaluate(payload)
    PolicyEngine-->>AirlockBoundary: PolicyVerdict
    alt deny verdict
        AirlockBoundary-->>Caller: raise AirlockPolicyViolation
    end
    AirlockBoundary->>sieve_with_metrics: sieve_with_metrics(raw_content)
    sieve_with_metrics-->>AirlockBoundary: SieveOutput
    AirlockBoundary->>AirlockTelemetry: from_sieve_output(sieve_output, raw_content)
    AirlockTelemetry-->>AirlockBoundary: AirlockTelemetry (frozen)
    AirlockBoundary->>PolicyEngine: evaluate_post_sieve(telemetry)
    PolicyEngine-->>AirlockBoundary: post PolicyVerdict
    alt post-sieve deny verdict
        AirlockBoundary-->>Caller: raise AirlockPolicyViolation
    end
    AirlockBoundary->>ReceiptBuilder: build_and_commit(sieved_content, telemetry, warnings, source)
    ReceiptBuilder->>SovereignKeyManager: generate_receipt(payload_dict, metadata)
    SovereignKeyManager-->>ReceiptBuilder: ForensicReceipt
    ReceiptBuilder->>SovereignLedger: append_receipt(receipt, sieved_content)
    Note over ReceiptBuilder,SovereignLedger: Ledger failure → WARNING log, non-fatal
    SovereignLedger-->>ReceiptBuilder: ok
    ReceiptBuilder-->>AirlockBoundary: ForensicReceipt
    AirlockBoundary-->>Caller: AirlockResult(sieved_content, telemetry, receipt, warnings)

Loading

Comments Outside Diff (3)

1. packages/sovereign-airlock/src/sovereign_airlock/policy.py, line 1008-1054 (link)

   Missing metric name validation for telemetry-scoped rules

   _parse_rule validates scope against _VALID_SCOPES and action against _VALID_ACTIONS at init time, raising AirlockConfigurationError on unknown values — but it does not validate the metric field for telemetry-scoped rules. A typo such as metric: raw_token (missing the trailing s) is silently accepted.

   At evaluation time the inconsistency becomes a governance defect: in _evaluate_telemetry, when telemetry=None, any metric name that is not in _POST_SIEVE_METRICS falls back to metric_value = payload.token_estimate (the raw_tokens fallback path), so the rule silently evaluates the wrong value instead of failing. A _VALID_METRICS: frozenset[str] = frozenset({"raw_tokens", "sieved_tokens", "tax_savings_percentage"}) check in _parse_rule (for scope == "telemetry") would catch this at the same time as malformed regex patterns — providing the same early-fail guarantee the rest of the config loading establishes.

2. packages/sovereign-airlock/src/sovereign_airlock/telemetry.py, line 1449-1454 (link)

   Upper bound of tax_savings_percentage not enforced despite documented [0.0, 100.0] clamp

   The docstring states the field is "clamped to [0.0, 100.0]", but only the lower bound is enforced via max(0.0, ...). While token counts from sovereign_sieve cannot go negative today, if sieve_output.optimized_token_count were ever negative (an upstream contract change or bug), the calculated percentage would exceed 100% with no guard. Adding min(100.0, max(0.0, ...)) would match the stated invariant and future-proof the clamp.

3. packages/sovereign-airlock/src/sovereign_airlock/policy.py, line 1137-1143 (link)

   prose_tax_warning_threshold unit convention is implicit and inconsistent with max_token_ceiling

   _prose_tax_warning_threshold is stored as a raw decimal fraction (e.g., 0.35) and converted to percentage at comparison time via * 100.0. The peer config field max_token_ceiling uses direct integer counts. A user who reads the YAML side-by-side might configure prose_tax_warning_threshold: 35 intending 35%, which would produce threshold_pct = 3500.0 and permanently trigger a warning on every payload. The README example of 0.35 demonstrates the correct form but does not call out the fractional-vs-direct distinction. Adding a docstring note or an upper-bound validation (if value > 1.0: raise AirlockConfigurationError(...)) would prevent silent misconfiguration.

_{Reviews (1): Last reviewed commit: "fix(airlock): resolve three Round 3 PR r..." | Re-trigger Greptile}