Wardline 01 07 annotation vocabulary
7. Annotation vocabulary¶
A wardline MUST be able to express the following categories of institutional knowledge. Each category represents a class of semantic constraint that is invisible to standard tooling but routinely violated by agent-generated code. The categories are stated here as declaration requirements — what an application MUST be able to express — not as syntax in any particular language.
These 17 groups are the minimum practical declaration surface required for this framework's threat model. They are empirically derived (groups 1–8 from case study, 9–17 from generic extension) and expected to evolve as the framework is applied to additional codebases and domains. Groups 1–8 are grounded in the case-study codebase that motivated the framework. Groups 9–17 generalise the model to broader enforcement surfaces and MAY evolve more substantially as additional deployments validate or refine them.
The groups fall into two categories. Core classification annotations (groups 1–4, 16–17) declare the application's trust topology — which data belongs to which authority tier, where trust boundaries lie, and how data may cross them. These are the annotations that define the wardline's classification function. Supplementary contract annotations (groups 5–15) declare code-behaviour contracts — failure modes, sensitivity handling, lifecycle constraints — that the enforcement tool can verify but that are not classification decisions in themselves.
Both categories are part of the wardline vocabulary and REQUIRED for conformance at the expressiveness level (§15.5), but the distinction clarifies what the wardline classifies (trust topology) versus what it additionally enforces (code contracts). Conformance requires that a binding can express all 17 groups; it does not require uniform enforcement depth for all supplementary groups. Organisations adopting the framework incrementally MAY deploy core classification annotations first and add supplementary contract annotations as annotation investment grows; this is both an adoption convenience and a dependency order, because the core groups establish the trust topology on which many supplementary checks depend.
Annotation identity across bindings. The Key Declarations column names abstract declaration concepts, not binding syntax. Where a label resembles Python decorator spelling, it is a mnemonic, not a requirement that other bindings use Python syntax. Cross-binding machine identity is carried by the manifest schema identifiers in §14 and the SARIF wardline.annotationGroups property in §11.1. Bindings MAY expose binding-specific names such as @validates_shape or @ValidatesShape in diagnostics, but those names are presentation-layer details, not the framework's interoperability surface.
| # | Group | Institutional Knowledge | Key Declarations | Enforcement Consequences |
|---|---|---|---|---|
| 1 | Authority Tier Flow | Where the system's trust boundaries are — which functions receive external data, shape-validate it, semantically validate it, read authoritative records, or write to the audit trail | @external_boundary; @validates_shape (T4→T3); @validates_semantic (T3→T2); @validates_external (combined T4→T2); @integral_read; @integral_writer; @integral_construction | Taint analysis between declared boundaries. Pattern rules (§8) activate per enclosing tier. Data reaching a sink without the validation required by its target tier produces a finding: T4 data reaching a T3/T2/T1 sink without shape validation; T3 data reaching a T2/T1 sink without semantic validation |
| 2 | Integrity Primacy | Which operations constitute the legal record and their ordering constraints relative to telemetry and logging | Audit-critical operation; audit ordering | No catch-and-continue around audit calls. On any execution path where both occur, the audit call dominates the telemetry call — that is, telemetry does not execute unless the audit action has already completed on that path; within the minimum analysis scope defined below, the scanner produces a finding when this ordering is violated. Fallback paths that skip the audit call produce a finding |
| 3 | Plugin/Component Contract | Which components are system-owned and what failure semantics apply | System-owned component | Crash-not-catch on internal failures. Broad exception handling within system components produces a finding |
| 4 | Data Provenance | Which data sources are provenance-sensitive — internal data that carries authority distinct from external input. Group 4 declares the sources; Group 17 declares the restoration act by which serialised representations regain their tier | Internal data source | Same restrictions as Tier 1 — no fallback defaults, no broad exception handling. Parse failure on internal data is an integrity failure, not a data quality issue. Group 4 does not by itself establish Tier 1 restoration; without Group 17 evidence, restored values remain in UNKNOWN_* states as specified in §6.3 |
| 5 | Schema Contracts | That transformations MUST map all fields from a source type, that outputs conform to declared schemas, that field coverage is complete, that optional fields with approved defaults are declared as such, and that schema-level defaults on tier-classified fields are governed — partial mappings and unmapped output fields risk silent data loss; undeclared defaults on external data risk silent data fabrication (§8.2.1); defaults declared in schema definitions (e.g., Pydantic model Field(default=...), dataclass field(default=...), JSON Schema "default" properties) on fields that participate in tier-classified flows are semantically equivalent to optional-field declarations and MUST be scanned and governed as such under the Assurance governance profile (§15.3.2), and SHOULD be scanned under the Lite governance profile | Complete field mapping from declared source type; output schema; field completeness; optional field with approved default; schema-level default governance | Conformant scanners SHALL verify that all fields of the source type are accessed. Unmapped fields produce a finding. Multiple functions declaring the same output field produce a collision finding. Optional-field declarations interact with WL-001 at declared boundaries (§8.2.1). Schema-level defaults on fields that participate in tier-classified data flows MUST be treated as implicit optional-field declarations under the Assurance governance profile (§15.3.2) and SHOULD be treated as such under the Lite governance profile — if the default value has not been declared as an approved default in the overlay (§8.2.1), the enforcement tool SHOULD produce a finding equivalent to an undeclared WL-001 access with fallback default. This closes the evasion path where a fabricated default is declared in the schema definition rather than at the access site, bypassing WL-001's AST-level pattern detection |
| 6 | Layer Boundaries | The application's architectural layering and permitted dependency direction | Layer membership (level or name) | Import/dependency direction enforcement. Reverse-direction imports produce a finding |
| 7 | Template/Parse Safety | That certain operations (template compilation, schema parsing) SHOULD occur at initialisation, not per-record | Initialisation-only operation | Call-site context analysis. Initialisation-only functions called from per-record processing paths produce a finding |
| 8 | Secret Handling | Which functions handle sensitive credentials and what restrictions apply to their outputs | Secret handler | The scanner verifies that return values are not persisted in plaintext or logged. Taint tracking follows the return value to output paths |
| 9 | Operation Semantics | Whether a function is idempotent, atomic, or compensatable | Idempotent; atomic; compensatable | Guard-before-side-effect for idempotent functions. Transaction context for atomic functions. Declared compensation for compensatable functions. Detection criteria are binding-defined unless specified otherwise in Part II |
| 10 | Failure Mode | How a function is required to fail and which functions may make terminal exception policy decisions | Fail-closed; fail-open; emit-or-explain; exception translation boundary | Declared vs actual failure behaviour comparison. Fail-closed functions with fallback paths produce a finding. Only authorised functions are permitted to translate exceptions from high-stakes paths; the scanner fires when an unauthorised function does so |
| 11 | Data Sensitivity | Which functions handle PII or classified data, and which are authorised to downgrade classification level | PII handler; classified data handler; classification downgrade authority | The scanner verifies that sensitive data does not appear in logs, error messages, or unprotected output. Taint tracking follows sensitive data through callers. Classification downgrade requires explicit declaration with source and target levels; undeclared downgrades are findings |
| 12 | Determinism | Whether a function MUST produce identical output for identical input | Deterministic; time-dependent | Conformant scanners SHALL verify that deterministic functions do not call binding-defined non-deterministic operations within the required analysis scope (see detailed note below). Bindings MAY extend detection depth beyond the required minimum |
| 13 | Concurrency/Ordering | Thread safety, ordering constraints, reentrancy restrictions | Thread-safe; ordered-after; not-reentrant | Ordering verified at call sites within the binding-defined required analysis scope (see detailed note below). Invoking B without prior invocation of declared predecessor A produces a finding |
| 14 | Access/Attribution | Which operations require authenticated identity or elevated authorisation | Requires identity; privileged operation | The scanner verifies that an authorisation check precedes any privileged action and that identity is propagated to the function |
| 15 | Lifecycle/Scope | Whether code is test-only, deprecated, or feature-gated | Test-only; deprecated-by; feature-gated | Test-only imports from production produce a finding. Post-expiry use of deprecated functions produces a finding |
| 16 | Generic Trust Boundary | Parameterised tier transitions for non-standard trust models. Two declaration types: trust boundary (enforcement-bearing tier transition) and data flow (descriptive documentation marker for pass-through or consumption/production roles — no enforcement activated) | Trust boundary (from-tier, to-tier): tier values 1, 2, 3, 4. Constraint: to-tier=1 is valid only when from-tier=2 (§6.2 invariant 4). Data flow (consumes, produces): descriptive-only, does not activate tier-promotion enforcement | Trust boundary: parameterised tier flow validation. Declared transitions are verified for structural support. Promotions spanning multiple tiers (e.g., T4→T2) are verified against the intermediate validation requirements (§6.2 invariant 3); the scanner produces a finding when they are not satisfied. Skip-promotions to Tier 1 (e.g., T4→T1, T3→T1) are schema-invalid and MUST be rejected at declaration-load time — Tier 1 construction is reached through composed steps. Data flow: no enforcement consequences — the declaration documents the function's tier role for humans and tooling but does not activate pattern rules, require rejection paths, or participate in taint-flow tracking. Functions that perform actual tier transitions are expected to use a trust boundary declaration, not a data flow declaration |
| 17 | Restoration Boundaries | The governed restoration act by which raw representations may be restored to a tier supported by available evidence (§6.3) — distinct from Group 4, which declares provenance-sensitive data sources | Trusted restoration boundary; provenance evidence categories | Structural verification (WL-007) applies. Four evidence categories (structural, semantic, integrity, provenance-institutional) govern the restoration. Institutional evidence is the gate between known-provenance tiers (T1–T3) and unknown-provenance states (UNKNOWN_*). Without institutional evidence, only UNKNOWN_GUARDED or UNKNOWN_ASSURED is reachable. Full restoration to Tier 1 requires all four categories |
- The 17 annotation groups defining the wardline declaration surface
Detailed notes for high-complexity groups.
Group 2 — Integrity Primacy minimum analysis scope. Conformant scanners SHALL verify audit-primacy ordering within a single function using path-sensitive analysis over explicit control flow that is statically visible in the function body: conditionals, loops, early returns, exception edges, and local helper calls that the binding can inline or analyse directly. Interprocedural ordering through callbacks, dynamic dispatch, framework interception, or higher-order functions is outside the required minimum scope. Bindings MAY extend the analysis depth and SHOULD document the analysis boundary.
Group 5 — Independently assessable mechanisms. Group 5 bundles several related but separable schema-contract checks: field-mapping completeness, output-schema conformance, field-collision detection, optional-field declaration governance, and schema-level default governance. These mechanisms are independently assessable for tooling and conformance reporting. The schema-default governance behaviour is closely coupled to WL-001 evasion prevention and therefore cross-references §8.2.1; §7 states the declaration surface and enforcement intent, while rule-specific fallback-default semantics remain defined in §8.
Group 9 — Binding-defined detection criteria. The framework requires that bindings define what counts as a guard for idempotency, what constitutes transaction context for atomicity, and how declared compensation is represented. §7 establishes the declaration categories and enforcement intent; Part II defines the language-specific detection criteria and minimum scanner behaviour.
Group 12 — Determinism minimum analysis scope. Conformant scanners SHALL verify that deterministic-annotated functions do not contain direct calls to a binding-defined set of known non-deterministic operations. Indirect calls through callbacks, higher-order functions, dynamic dispatch, reflection, or framework-generated code are outside the required minimum scope unless the binding states otherwise. Bindings MAY extend detection depth and SHOULD document the additional analysis they perform.
Group 13 — Concurrency/ordering minimum analysis scope. Because concurrency and ordering checks often require interprocedural reasoning, the minimum required analysis scope is binding-defined. A binding claiming enforcement for Group 13 SHALL document the required minimum scope for each declaration type (thread_safe, ordered_after, not_reentrant) and any approximations used. Tools MAY provide advisory-only checks beyond that scope.
Cross-group interactions. Implementers building support group-by-group SHOULD account for at least the following interactions:
- Groups 4 + 17: provenance-sensitive sources and restoration evidence compose to determine whether restored values re-enter known-provenance tiers or remain in UNKNOWN_* states.
- Groups 5 + WL-001: schema defaults and optional-field declarations interact with fallback-default detection; schema-declared defaults can be semantically equivalent to access-site defaults.
- Groups 8 + 11: secret handling and data-sensitivity handling share taint-propagation infrastructure and can produce overlapping sink restrictions.
- Groups 1 + 10: failure-mode enforcement often depends on the enclosing trust topology established by core classification annotations.