Skip to content

Commit 7fb15ae

Browse files
committed
Upgrade README: badges, cross-links, architecture, quick start
1 parent 7e9edcc commit 7fb15ae

1 file changed

Lines changed: 142 additions & 98 deletions

File tree

README.md

Lines changed: 142 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,120 @@
11
![CI](https://github.com/LalaSkye/execution-boundary-lab/actions/workflows/ci.yml/badge.svg)
2+
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
3+
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/)
24

3-
# execution_boundary_lab
5+
# execution-boundary-lab
46

5-
## Purpose
6-
7-
This repository demonstrates a structural phenomenon:
8-
9-
**Information pre-positioning causes cascading execution failures in naive systems.**
10-
11-
When structured action bundles contain implicit authority, hidden defaults, ambiguous targets, or overloaded metadata, downstream execution engines can produce deterministic but unintended side effects.
12-
13-
This lab shows:
14-
15-
1. How syntactically valid inputs can corrupt state under naive execution.
16-
2. Why runtime mitigation is insufficient.
17-
3. Why a pre-execution admissibility gate is structurally necessary.
7+
Deterministic failure harness: syntactically valid inputs corrupt state when there is no upstream admissibility gate.
188

199
---
2010

21-
## Why This Matters
22-
23-
Modern AI-integrated systems increasingly execute structured actions proposed by probabilistic models.
24-
25-
Most governance efforts focus on runtime mitigation — detecting and correcting undesirable states after partial execution.
26-
27-
This lab demonstrates a different architectural claim:
11+
## Why This Exists
2812

29-
> If a system permits certain categories of state to form, mitigation becomes an ongoing operational burden.
30-
31-
Reducing admissibility upstream reduces mitigation workload downstream.
32-
33-
This is not an alignment argument. It is a systems design argument.
13+
Most AI system governance efforts apply runtime mitigation — detecting and correcting bad state after partial execution. This lab demonstrates why that is structurally insufficient. When structured action bundles carry implicit authority, hidden defaults, or ambiguous targets, a naive executor produces deterministic but unintended side effects. The failure is not randomness; it is an admissibility problem. This repo is the negative case that motivates the upstream [interpretation-boundary-lab](https://github.com/LalaSkye/interpretation-boundary-lab).
3414

3515
---
3616

37-
## What This Repository Is
38-
39-
- A deterministic simulation environment.
40-
- A failure harness.
41-
- A conformance test surface.
42-
- A behavioural contract for admissibility gating.
17+
## Architecture
4318

44-
---
45-
46-
## What This Repository Is Not
47-
48-
- It does **NOT** include the Trinity gate implementation.
49-
- It does **NOT** expose gating logic.
50-
- It does **NOT** implement scoring heuristics.
51-
- It does **NOT** provide production security tooling.
19+
```
20+
Input Bundle
21+
|
22+
v
23+
┌─────────────────────┐
24+
│ naive_executor.py │ <-- no gate, no admissibility check
25+
└─────────────────────┘
26+
|
27+
[state corruption]
28+
|
29+
┌───────┴────────┐
30+
v v
31+
contaminated clean
32+
case_1..6.json case_1.json
33+
|
34+
v
35+
reports/example_trace_without_gate.txt
36+
```
5237

53-
This is a boundary demonstration only.
38+
```
39+
Input Bundle
40+
|
41+
v
42+
┌──────────────────────┐
43+
│ gate_api/interface.py│ <-- implement Gate here
44+
└──────────────────────┘
45+
|
46+
[admitted or rejected]
47+
|
48+
v
49+
┌─────────────────────┐
50+
│ executor pipeline │
51+
└─────────────────────┘
52+
|
53+
v
54+
reports/example_trace_with_gate.txt
55+
```
5456

5557
---
5658

57-
## Core Concept
58-
59-
### Information Pre-Positioning
59+
## Quick Demo
6060

61-
Information pre-positioning occurs when structured data embeds executable consequences that are not explicit at the point of execution.
62-
63-
Examples include:
64-
65-
- Implicit privilege escalation fields.
66-
- Hidden default behaviours.
67-
- Ambiguous resource targets.
68-
- Metadata that alters execution ordering.
69-
- Conflation of descriptive and authoritative fields.
70-
71-
A naive executor processes these structures deterministically, yet produces state corruption.
72-
73-
The failure is not randomness. The failure is **admissibility**.
74-
75-
---
61+
```bash
62+
git clone https://github.com/LalaSkye/execution-boundary-lab.git
63+
cd execution-boundary-lab
64+
pip install pytest
65+
python run_demo.py
66+
```
7667

77-
## Architectural Distinction
68+
Expected output (truncated):
7869

79-
**Runtime mitigation:**
80-
- Detects and handles problematic states *after* they form.
70+
```
71+
[CASE] contaminated_case_1.json
72+
[EXECUTOR] processing action bundle...
73+
[FAIL] implicit privilege escalation detected in state
74+
resource.permissions = ADMIN (was USER)
75+
76+
[CASE] contaminated_case_2.json
77+
[EXECUTOR] processing action bundle...
78+
[FAIL] ambiguous target resolved to wrong resource
79+
resource.target = /prod (expected /staging)
80+
81+
[CASE] clean_case_1.json
82+
[EXECUTOR] processing action bundle...
83+
[OK] no state corruption
84+
```
8185

82-
**Pre-execution admissibility gating:**
83-
- Prevents problematic state categories from *entering* the system.
86+
Run the full conformance test suite:
8487

85-
This repository illustrates why the latter reduces systemic workload and failure surface.
88+
```bash
89+
python -m pytest tests/ -v
90+
```
8691

8792
---
8893

8994
## Repository Structure
9095

9196
```
92-
/execution_boundary_lab
97+
execution-boundary-lab/
9398
README.md
94-
SPEC.md
99+
SPEC.md # formal specification
100+
run_demo.py # entry point
95101
/sim
96-
__init__.py
97-
executor.py
98-
resources.py
99-
logger.py
102+
executor.py # simulation environment
103+
resources.py # resource state model
104+
logger.py # trace logger
100105
/cases
101-
contaminated_case_1.json
102-
contaminated_case_2.json
103-
contaminated_case_3.json
104-
contaminated_case_4.json
105-
contaminated_case_5.json
106-
contaminated_case_6.json
107-
clean_case_1.json
106+
contaminated_case_1.json # implicit privilege escalation
107+
contaminated_case_2.json # ambiguous resource target
108+
contaminated_case_3.json # hidden default behaviour
109+
contaminated_case_4.json # metadata altering execution order
110+
contaminated_case_5.json # overloaded descriptive/authoritative fields
111+
contaminated_case_6.json # conflated authority scope
112+
clean_case_1.json # baseline — no corruption
108113
/gate_api
109-
__init__.py
110-
interface.py
114+
interface.py # Gate interface definition
111115
/baseline
112-
__init__.py
113-
naive_executor.py
116+
naive_executor.py # executor with no admissibility gate
114117
/tests
115-
__init__.py
116-
conftest.py
117118
test_prepositioning_failures.py
118119
test_gate_contract.py
119120
/reports
@@ -123,32 +124,75 @@ This repository illustrates why the latter reduces systemic workload and failure
123124

124125
---
125126

126-
## Running Tests
127+
## Core Concept: Information Pre-Positioning
127128

128-
```bash
129-
pip install pytest
130-
python -m pytest
131-
```
129+
Information pre-positioning occurs when structured data embeds executable consequences that are not explicit at the point of execution. Examples:
130+
131+
- Implicit privilege escalation fields
132+
- Hidden default behaviours
133+
- Ambiguous resource targets
134+
- Metadata that alters execution ordering
135+
- Conflation of descriptive and authoritative fields
136+
137+
A naive executor processes these structures deterministically, yet produces state corruption. The failure is not randomness. The failure is **admissibility**.
138+
139+
---
140+
141+
## Architectural Distinction
142+
143+
| Approach | Mechanism | Consequence |
144+
|---|---|---|
145+
| Runtime mitigation | Detects and handles problematic states *after* they form | Ongoing operational burden; failure surface grows with system complexity |
146+
| Pre-execution admissibility gating | Prevents problematic state categories from *entering* the system | Reduces mitigation workload downstream; failure surface is bounded upstream |
147+
148+
> If a system requires mitigation logic at runtime, it has already admitted instability. Admissibility is upstream of enforcement.
149+
150+
---
151+
152+
## What This Repository Is
153+
154+
- A deterministic simulation environment
155+
- A failure harness for six contamination patterns
156+
- A conformance test surface for gate implementations
157+
- A behavioural contract for admissibility gating
158+
159+
## What This Repository Is Not
160+
161+
- It does **not** include the Trinity gate implementation
162+
- It does **not** expose gating logic
163+
- It does **not** implement scoring heuristics
164+
- It does **not** provide production security tooling
165+
166+
This is a boundary demonstration only.
132167

133168
---
134169

135-
## Extension
170+
## Extending with a Real Gate
136171

137-
To test a real admissibility gate:
172+
To test an admissibility gate against the conformance suite:
138173

139-
1. Implement the `Gate` interface defined in `gate_api/interface.py`.
140-
2. Inject it into the executor pipeline.
141-
3. Ensure all conformance tests pass.
174+
1. Implement the `Gate` interface defined in `gate_api/interface.py`
175+
2. Inject it into the executor pipeline
176+
3. Ensure all conformance tests pass
142177

143178
---
144179

145-
## Position
180+
## Part of the Execution Boundary Series
146181

147-
> If a system requires mitigation logic at runtime, it has already admitted instability.
148-
> Admissibility is upstream of enforcement.
182+
| Repo | Layer | What It Does |
183+
|---|---|---|
184+
| [interpretation-boundary-lab](https://github.com/LalaSkye/interpretation-boundary-lab) | Upstream boundary | 10-rule admissibility gate for interpretations |
185+
| [dual-boundary-admissibility-lab](https://github.com/LalaSkye/dual-boundary-admissibility-lab) | Full corridor | Dual-boundary model with pressure monitoring and C-sector rotation |
186+
| [execution-boundary-lab](https://github.com/LalaSkye/execution-boundary-lab) | Execution boundary | Demonstrates cascading failures without upstream governance |
187+
| [stop-machine](https://github.com/LalaSkye/stop-machine) | Control primitive | Deterministic three-state stop controller |
188+
| [constraint-workshop](https://github.com/LalaSkye/constraint-workshop) | Control primitives | Authority gate, invariant litmus, stop machine |
189+
| [csgr-lab](https://github.com/LalaSkye/csgr-lab) | Measurement | Contracted stability and drift measurement |
190+
| [invariant-lock](https://github.com/LalaSkye/invariant-lock) | Drift prevention | Refuse execution unless version increments |
191+
| [policy-lint](https://github.com/LalaSkye/policy-lint) | Policy validation | Deterministic linter for governance statements |
192+
| [deterministic-lexicon](https://github.com/LalaSkye/deterministic-lexicon) | Vocabulary | Fixed terms, exact matches, no inference |
149193

150194
---
151195

152-
## Licence
196+
## License
153197

154198
Apache 2.0. See `LICENSE`.

0 commit comments

Comments
 (0)