open-refinery 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- open_refinery-0.1.0/.claude/rules/simplicity.md +6 -0
- open_refinery-0.1.0/.claude/rules/tests-tdd.md +7 -0
- open_refinery-0.1.0/.gitignore +14 -0
- open_refinery-0.1.0/CLAUDE.md +45 -0
- open_refinery-0.1.0/CONTRIBUTING.md +38 -0
- open_refinery-0.1.0/LICENSE +21 -0
- open_refinery-0.1.0/PKG-INFO +94 -0
- open_refinery-0.1.0/README.md +74 -0
- open_refinery-0.1.0/docs/ARCHITECTURE.md +54 -0
- open_refinery-0.1.0/pyproject.toml +37 -0
- open_refinery-0.1.0/src/open_refinery/__init__.py +22 -0
- open_refinery-0.1.0/src/open_refinery/audit.py +35 -0
- open_refinery-0.1.0/src/open_refinery/authz.py +30 -0
- open_refinery-0.1.0/src/open_refinery/cli.py +33 -0
- open_refinery-0.1.0/src/open_refinery/factory.py +73 -0
- open_refinery-0.1.0/src/open_refinery/provenance.py +44 -0
- open_refinery-0.1.0/tests/test_factory.py +57 -0
- open_refinery-0.1.0/uv.lock +78 -0
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# Simplicity
|
|
2
|
+
|
|
3
|
+
- The minimum code that solves the problem. No speculative abstractions.
|
|
4
|
+
- Keep the core dependency-free while the standard library suffices.
|
|
5
|
+
- No configurability, flexibility, or error handling that wasn't asked for.
|
|
6
|
+
- Prefer `typing.Protocol` seams over class hierarchies.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Tests
|
|
2
|
+
|
|
3
|
+
- Non-trivial logic lands with a test.
|
|
4
|
+
- Prove a bug with a failing test before fixing it.
|
|
5
|
+
- The production loop's ordering (authorize before run; record/log only after
|
|
6
|
+
success) is behavior — keep it covered.
|
|
7
|
+
- Run `uv run pytest`; all green before a commit or PR.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.pyc
|
|
4
|
+
.venv/
|
|
5
|
+
.pytest_cache/
|
|
6
|
+
*.egg-info/
|
|
7
|
+
dist/
|
|
8
|
+
build/
|
|
9
|
+
# audit trails / runtime state — regenerated, not versioned
|
|
10
|
+
*.jsonl
|
|
11
|
+
# env
|
|
12
|
+
.env
|
|
13
|
+
# personal Claude Code permissions (not shared)
|
|
14
|
+
.claude/settings.local.json
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# CLAUDE.md — open-refinery
|
|
2
|
+
|
|
3
|
+
*Manage complexity ruthlessly. The minimum code that solves the problem.*
|
|
4
|
+
|
|
5
|
+
## What this is
|
|
6
|
+
|
|
7
|
+
A factory that produces artifacts under governance. The production loop is:
|
|
8
|
+
**authorize → run recipe → record provenance + ownership → audit → log**.
|
|
9
|
+
Core pillars: observability, auditability, authorization, ownership,
|
|
10
|
+
provenance, logging — and, on the roadmap, **governance via policies**.
|
|
11
|
+
|
|
12
|
+
## Layout
|
|
13
|
+
|
|
14
|
+
- `src/open_refinery/` — src layout, `hatchling` build, `uv` for env/deps.
|
|
15
|
+
- `factory.py` — recipe registry + production loop
|
|
16
|
+
- `provenance.py` — immutable `Record` + I/O digests
|
|
17
|
+
- `authz.py` — `Authorizer` protocol (`AllowAll`, `AllowList`)
|
|
18
|
+
- `audit.py` — `AuditSink` protocol (`MemorySink`, `JsonlSink`)
|
|
19
|
+
- `cli.py` — demo entry point (`open-refinery`)
|
|
20
|
+
- `tests/` — pytest
|
|
21
|
+
- `docs/ARCHITECTURE.md` — the loop, modules, roadmap
|
|
22
|
+
|
|
23
|
+
## Working rules
|
|
24
|
+
|
|
25
|
+
- **Keep the core dependency-free** while the stdlib suffices. A new dependency
|
|
26
|
+
needs a reason.
|
|
27
|
+
- **Protocols over inheritance** for the seams (`Authorizer`, `AuditSink`).
|
|
28
|
+
- **Immutable records, append-only audit.** Never mutate a `Record`.
|
|
29
|
+
- **Test non-trivial logic.** Prove a bug with a failing test first.
|
|
30
|
+
- **Surgical changes.** Touch only what the task needs; match existing style.
|
|
31
|
+
- Order in `produce` is load-bearing: authorize before running; record/log only
|
|
32
|
+
after a successful run.
|
|
33
|
+
|
|
34
|
+
## Commands
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
uv sync --extra dev
|
|
38
|
+
uv run pytest
|
|
39
|
+
uv run open-refinery --actor ian --text hello
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Roadmap (don't build ahead of need)
|
|
43
|
+
|
|
44
|
+
Governance policy layer, observability read-model, pluggable sinks, async
|
|
45
|
+
recipes. See `docs/ARCHITECTURE.md`.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Contributing to open-refinery
|
|
2
|
+
|
|
3
|
+
Thanks for your interest. This is an early-stage project; the core is small on
|
|
4
|
+
purpose.
|
|
5
|
+
|
|
6
|
+
## Setup
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
uv sync --extra dev
|
|
10
|
+
uv run pytest
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Principles
|
|
14
|
+
|
|
15
|
+
- **Manage complexity ruthlessly.** The minimum code that solves the problem.
|
|
16
|
+
No speculative abstractions, no configurability that wasn't asked for.
|
|
17
|
+
- **Test non-trivial logic.** New behavior lands with a test. Prove a bug with
|
|
18
|
+
a failing test before fixing it.
|
|
19
|
+
- **Surgical changes.** Touch only what the change requires; match existing
|
|
20
|
+
style.
|
|
21
|
+
- **Keep the core dependency-free** where the standard library suffices.
|
|
22
|
+
|
|
23
|
+
## Workflow
|
|
24
|
+
|
|
25
|
+
1. Branch from `main`.
|
|
26
|
+
2. Make the change with tests.
|
|
27
|
+
3. `uv run pytest` — all green.
|
|
28
|
+
4. Open a PR against `main` with a clear description of the *why*.
|
|
29
|
+
|
|
30
|
+
## Commit style
|
|
31
|
+
|
|
32
|
+
Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`). Subject
|
|
33
|
+
in the imperative, ≤50 chars; body only when the *why* isn't obvious.
|
|
34
|
+
|
|
35
|
+
## Scope
|
|
36
|
+
|
|
37
|
+
Discuss larger changes (new pillars, dependencies, policy engine) in an issue
|
|
38
|
+
first — see the roadmap in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ian Johnson
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: open-refinery
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A factory for producing artifacts under governance — provenance, ownership, authorization, and an append-only audit trail on every output.
|
|
5
|
+
Project-URL: Homepage, https://github.com/tacoda/open-refinery
|
|
6
|
+
Project-URL: Repository, https://github.com/tacoda/open-refinery
|
|
7
|
+
Author-email: Ian Johnson <ian@tacoda.dev>
|
|
8
|
+
License: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: audit,factory,governance,observability,provenance
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
16
|
+
Requires-Python: >=3.11
|
|
17
|
+
Provides-Extra: dev
|
|
18
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
|
|
21
|
+
# open-refinery
|
|
22
|
+
|
|
23
|
+
A factory for producing artifacts under governance. Every output carries its
|
|
24
|
+
**provenance**, an **owner**, and an **audit trail**; every production is
|
|
25
|
+
**authorized** before it runs and **logged** as it happens.
|
|
26
|
+
|
|
27
|
+
> Status: **0.1.0 — proof of concept.** The core loop (authorize → produce →
|
|
28
|
+
> record → audit) is real and tested. Policy-based governance, richer
|
|
29
|
+
> observability, and pluggable sinks are on the roadmap.
|
|
30
|
+
|
|
31
|
+
## Install
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
uv add open-refinery # or: pip install open-refinery
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Use
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
from open_refinery import Factory
|
|
41
|
+
|
|
42
|
+
factory = Factory()
|
|
43
|
+
|
|
44
|
+
@factory.recipe("upper")
|
|
45
|
+
def upper(text: str) -> str:
|
|
46
|
+
return text.upper()
|
|
47
|
+
|
|
48
|
+
artifact, record = factory.produce("upper", actor="ian", text="hello")
|
|
49
|
+
# artifact -> "HELLO"
|
|
50
|
+
# record -> Record(recipe="upper", actor="ian", owner="ian",
|
|
51
|
+
# artifact_id=..., input_digest=..., output_digest=..., created_at=...)
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Try the demo CLI:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
uv run open-refinery --actor ian --text hello
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Pillars
|
|
61
|
+
|
|
62
|
+
| Pillar | Where it lives |
|
|
63
|
+
|-----------------|-------------------------------------------------------------|
|
|
64
|
+
| Authorization | `Authorizer` (`AllowAll`, `AllowList`) — checked before produce |
|
|
65
|
+
| Provenance | `Record` — recipe, actor, timestamp, input/output digests |
|
|
66
|
+
| Ownership | `owner` on every record (defaults to the actor) |
|
|
67
|
+
| Auditability | `AuditSink` (`MemorySink`, `JsonlSink`) — append-only trail |
|
|
68
|
+
| Logging | stdlib `logging`, logger name `open_refinery` |
|
|
69
|
+
| Observability | *(roadmap)* read-model / metrics over the audit trail |
|
|
70
|
+
| Governance | *(roadmap)* policy layer that constrains what may be produced |
|
|
71
|
+
|
|
72
|
+
## Durable audit trail
|
|
73
|
+
|
|
74
|
+
```python
|
|
75
|
+
from open_refinery import Factory, JsonlSink
|
|
76
|
+
|
|
77
|
+
factory = Factory(audit=JsonlSink("audit.jsonl"))
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Each production appends one JSON line — a replayable record of who produced
|
|
81
|
+
what, from which inputs, and when.
|
|
82
|
+
|
|
83
|
+
## Development
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
uv sync --extra dev
|
|
87
|
+
uv run pytest
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
|
|
91
|
+
|
|
92
|
+
## License
|
|
93
|
+
|
|
94
|
+
[MIT](LICENSE) © Ian Johnson
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# open-refinery
|
|
2
|
+
|
|
3
|
+
A factory for producing artifacts under governance. Every output carries its
|
|
4
|
+
**provenance**, an **owner**, and an **audit trail**; every production is
|
|
5
|
+
**authorized** before it runs and **logged** as it happens.
|
|
6
|
+
|
|
7
|
+
> Status: **0.1.0 — proof of concept.** The core loop (authorize → produce →
|
|
8
|
+
> record → audit) is real and tested. Policy-based governance, richer
|
|
9
|
+
> observability, and pluggable sinks are on the roadmap.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
uv add open-refinery # or: pip install open-refinery
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Use
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
from open_refinery import Factory
|
|
21
|
+
|
|
22
|
+
factory = Factory()
|
|
23
|
+
|
|
24
|
+
@factory.recipe("upper")
|
|
25
|
+
def upper(text: str) -> str:
|
|
26
|
+
return text.upper()
|
|
27
|
+
|
|
28
|
+
artifact, record = factory.produce("upper", actor="ian", text="hello")
|
|
29
|
+
# artifact -> "HELLO"
|
|
30
|
+
# record -> Record(recipe="upper", actor="ian", owner="ian",
|
|
31
|
+
# artifact_id=..., input_digest=..., output_digest=..., created_at=...)
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Try the demo CLI:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
uv run open-refinery --actor ian --text hello
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Pillars
|
|
41
|
+
|
|
42
|
+
| Pillar | Where it lives |
|
|
43
|
+
|-----------------|-------------------------------------------------------------|
|
|
44
|
+
| Authorization | `Authorizer` (`AllowAll`, `AllowList`) — checked before produce |
|
|
45
|
+
| Provenance | `Record` — recipe, actor, timestamp, input/output digests |
|
|
46
|
+
| Ownership | `owner` on every record (defaults to the actor) |
|
|
47
|
+
| Auditability | `AuditSink` (`MemorySink`, `JsonlSink`) — append-only trail |
|
|
48
|
+
| Logging | stdlib `logging`, logger name `open_refinery` |
|
|
49
|
+
| Observability | *(roadmap)* read-model / metrics over the audit trail |
|
|
50
|
+
| Governance | *(roadmap)* policy layer that constrains what may be produced |
|
|
51
|
+
|
|
52
|
+
## Durable audit trail
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
from open_refinery import Factory, JsonlSink
|
|
56
|
+
|
|
57
|
+
factory = Factory(audit=JsonlSink("audit.jsonl"))
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Each production appends one JSON line — a replayable record of who produced
|
|
61
|
+
what, from which inputs, and when.
|
|
62
|
+
|
|
63
|
+
## Development
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
uv sync --extra dev
|
|
67
|
+
uv run pytest
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
|
|
71
|
+
|
|
72
|
+
## License
|
|
73
|
+
|
|
74
|
+
[MIT](LICENSE) © Ian Johnson
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Architecture
|
|
2
|
+
|
|
3
|
+
open-refinery is a **factory under governance**. The unit of work is a
|
|
4
|
+
*production*: an actor asks the factory to run a named *recipe*; the factory
|
|
5
|
+
gates, runs, and records it.
|
|
6
|
+
|
|
7
|
+
## The production loop
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
produce(name, actor, owner?, **inputs)
|
|
11
|
+
│
|
|
12
|
+
├─ 1. resolve recipe (UnknownRecipe if absent)
|
|
13
|
+
├─ 2. authorize (Unauthorized if denied) ← authz.py
|
|
14
|
+
├─ 3. run recipe(**inputs) → artifact
|
|
15
|
+
├─ 4. build Record (provenance + ownership) ← provenance.py
|
|
16
|
+
├─ 5. append to audit sink ← audit.py
|
|
17
|
+
├─ 6. log the event ← stdlib logging
|
|
18
|
+
└─ return (artifact, record)
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Order matters: nothing is recorded or logged unless authorization passed and
|
|
22
|
+
the recipe ran. An unauthorized call leaves no artifact and no audit record.
|
|
23
|
+
|
|
24
|
+
## Modules
|
|
25
|
+
|
|
26
|
+
| Module | Responsibility |
|
|
27
|
+
|-----------------|-----------------------------------------------------------|
|
|
28
|
+
| `factory.py` | Recipe registry + the production loop |
|
|
29
|
+
| `provenance.py` | `Record` (immutable) + stable SHA-256 digests of I/O |
|
|
30
|
+
| `authz.py` | `Authorizer` protocol; `AllowAll`, `AllowList` |
|
|
31
|
+
| `audit.py` | `AuditSink` protocol; `MemorySink`, `JsonlSink` |
|
|
32
|
+
|
|
33
|
+
`Authorizer` and `AuditSink` are `typing.Protocol`s — swap implementations
|
|
34
|
+
without touching the factory.
|
|
35
|
+
|
|
36
|
+
## Design choices
|
|
37
|
+
|
|
38
|
+
- **Dependency-free core.** Everything above is stdlib. Dependencies join only
|
|
39
|
+
when a pillar genuinely needs one.
|
|
40
|
+
- **Immutable records.** A `Record` is a frozen dataclass; the audit trail is
|
|
41
|
+
append-only. Provenance you can't rewrite is provenance you can trust.
|
|
42
|
+
- **Digests, not payloads.** Records store SHA-256 of inputs/outputs, keeping
|
|
43
|
+
the trail small and non-sensitive while still verifiable.
|
|
44
|
+
|
|
45
|
+
## Roadmap
|
|
46
|
+
|
|
47
|
+
- **Governance via policies** — a policy layer that constrains *what may be
|
|
48
|
+
produced* (and by whom, from which inputs), evaluated in the production loop
|
|
49
|
+
alongside authorization. Policies as data/code, cascading (org ▸ repo ▸
|
|
50
|
+
local, outer wins).
|
|
51
|
+
- **Observability** — a read-model / metrics view built by replaying the audit
|
|
52
|
+
trail (counts, actors, ownership, failure clusters).
|
|
53
|
+
- **Pluggable sinks** — SQLite, cloud logging, event stream.
|
|
54
|
+
- **Async recipes** and batching.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "open-refinery"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "A factory for producing artifacts under governance — provenance, ownership, authorization, and an append-only audit trail on every output."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.11"
|
|
7
|
+
license = { text = "MIT" }
|
|
8
|
+
authors = [{ name = "Ian Johnson", email = "ian@tacoda.dev" }]
|
|
9
|
+
keywords = ["provenance", "audit", "governance", "factory", "observability"]
|
|
10
|
+
classifiers = [
|
|
11
|
+
"Development Status :: 3 - Alpha",
|
|
12
|
+
"License :: OSI Approved :: MIT License",
|
|
13
|
+
"Programming Language :: Python :: 3",
|
|
14
|
+
"Programming Language :: Python :: 3.11",
|
|
15
|
+
"Topic :: Software Development :: Libraries",
|
|
16
|
+
]
|
|
17
|
+
dependencies = []
|
|
18
|
+
|
|
19
|
+
[project.optional-dependencies]
|
|
20
|
+
dev = ["pytest>=8.0"]
|
|
21
|
+
|
|
22
|
+
[project.urls]
|
|
23
|
+
Homepage = "https://github.com/tacoda/open-refinery"
|
|
24
|
+
Repository = "https://github.com/tacoda/open-refinery"
|
|
25
|
+
|
|
26
|
+
[project.scripts]
|
|
27
|
+
open-refinery = "open_refinery.cli:main"
|
|
28
|
+
|
|
29
|
+
[build-system]
|
|
30
|
+
requires = ["hatchling"]
|
|
31
|
+
build-backend = "hatchling.build"
|
|
32
|
+
|
|
33
|
+
[tool.hatch.build.targets.wheel]
|
|
34
|
+
packages = ["src/open_refinery"]
|
|
35
|
+
|
|
36
|
+
[tool.pytest.ini_options]
|
|
37
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
"""open-refinery — a factory for producing artifacts under governance."""
|
|
2
|
+
|
|
3
|
+
from .audit import AuditSink, JsonlSink, MemorySink
|
|
4
|
+
from .authz import AllowAll, AllowList, Authorizer, Unauthorized
|
|
5
|
+
from .factory import Factory, UnknownRecipe
|
|
6
|
+
from .provenance import Record
|
|
7
|
+
|
|
8
|
+
__version__ = "0.1.0"
|
|
9
|
+
|
|
10
|
+
__all__ = [
|
|
11
|
+
"Factory",
|
|
12
|
+
"UnknownRecipe",
|
|
13
|
+
"Record",
|
|
14
|
+
"Authorizer",
|
|
15
|
+
"AllowAll",
|
|
16
|
+
"AllowList",
|
|
17
|
+
"Unauthorized",
|
|
18
|
+
"AuditSink",
|
|
19
|
+
"MemorySink",
|
|
20
|
+
"JsonlSink",
|
|
21
|
+
"__version__",
|
|
22
|
+
]
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
"""Audit sink — append-only trail of production events."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Protocol
|
|
8
|
+
|
|
9
|
+
from .provenance import Record
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class AuditSink(Protocol):
|
|
13
|
+
def write(self, record: Record) -> None: ...
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class MemorySink:
|
|
17
|
+
"""In-memory trail. Default; useful for tests and ephemeral runs."""
|
|
18
|
+
|
|
19
|
+
def __init__(self) -> None:
|
|
20
|
+
self.records: list[Record] = []
|
|
21
|
+
|
|
22
|
+
def write(self, record: Record) -> None:
|
|
23
|
+
self.records.append(record)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class JsonlSink:
|
|
27
|
+
"""Append each record as one JSON line. The durable audit trail."""
|
|
28
|
+
|
|
29
|
+
def __init__(self, path: str | Path) -> None:
|
|
30
|
+
self.path = Path(path)
|
|
31
|
+
self.path.parent.mkdir(parents=True, exist_ok=True)
|
|
32
|
+
|
|
33
|
+
def write(self, record: Record) -> None:
|
|
34
|
+
with self.path.open("a", encoding="utf-8") as fh:
|
|
35
|
+
fh.write(json.dumps(record.to_dict(), sort_keys=True) + "\n")
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"""Authorization — the gate checked before a recipe runs."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Protocol
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class Unauthorized(Exception):
|
|
9
|
+
"""Raised when an actor may not run a recipe."""
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class Authorizer(Protocol):
|
|
13
|
+
def allows(self, actor: str, recipe: str) -> bool: ...
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class AllowAll:
|
|
17
|
+
"""Default authorizer — permits every actor. Replace in production."""
|
|
18
|
+
|
|
19
|
+
def allows(self, actor: str, recipe: str) -> bool:
|
|
20
|
+
return True
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class AllowList:
|
|
24
|
+
"""Permit only (actor, recipe) pairs present in the grant set."""
|
|
25
|
+
|
|
26
|
+
def __init__(self, grants: set[tuple[str, str]]) -> None:
|
|
27
|
+
self._grants = grants
|
|
28
|
+
|
|
29
|
+
def allows(self, actor: str, recipe: str) -> bool:
|
|
30
|
+
return (actor, recipe) in self._grants
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""Demo CLI — produces one artifact and prints its provenance record."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import json
|
|
7
|
+
import logging
|
|
8
|
+
|
|
9
|
+
from .factory import Factory
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def main(argv: list[str] | None = None) -> int:
|
|
13
|
+
parser = argparse.ArgumentParser(prog="open-refinery")
|
|
14
|
+
parser.add_argument("--actor", default="demo-user")
|
|
15
|
+
parser.add_argument("--text", default="hello", help="text to refine")
|
|
16
|
+
args = parser.parse_args(argv)
|
|
17
|
+
|
|
18
|
+
logging.basicConfig(level=logging.INFO, format="%(message)s")
|
|
19
|
+
|
|
20
|
+
factory = Factory()
|
|
21
|
+
|
|
22
|
+
@factory.recipe("upper")
|
|
23
|
+
def upper(text: str) -> str:
|
|
24
|
+
return text.upper()
|
|
25
|
+
|
|
26
|
+
artifact, record = factory.produce("upper", actor=args.actor, text=args.text)
|
|
27
|
+
print(f"artifact: {artifact!r}")
|
|
28
|
+
print(json.dumps(record.to_dict(), indent=2, sort_keys=True))
|
|
29
|
+
return 0
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
if __name__ == "__main__":
|
|
33
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
"""Factory — produces artifacts, wrapping each output in governance."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import logging
|
|
6
|
+
from typing import Callable
|
|
7
|
+
|
|
8
|
+
from .audit import AuditSink, MemorySink
|
|
9
|
+
from .authz import AllowAll, Authorizer, Unauthorized
|
|
10
|
+
from .provenance import Record
|
|
11
|
+
|
|
12
|
+
log = logging.getLogger("open_refinery")
|
|
13
|
+
|
|
14
|
+
Recipe = Callable[..., object]
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class UnknownRecipe(KeyError):
|
|
18
|
+
"""Raised when producing from an unregistered recipe."""
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class Factory:
|
|
22
|
+
"""Registers recipes and produces artifacts under governance.
|
|
23
|
+
|
|
24
|
+
Every ``produce`` call is authorized, run, recorded with provenance and
|
|
25
|
+
ownership, and appended to the audit trail — in that order.
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
def __init__(
|
|
29
|
+
self,
|
|
30
|
+
authorizer: Authorizer | None = None,
|
|
31
|
+
audit: AuditSink | None = None,
|
|
32
|
+
) -> None:
|
|
33
|
+
self._recipes: dict[str, Recipe] = {}
|
|
34
|
+
self._authorizer = authorizer or AllowAll()
|
|
35
|
+
self._audit = audit or MemorySink()
|
|
36
|
+
|
|
37
|
+
def register(self, name: str, recipe: Recipe) -> None:
|
|
38
|
+
self._recipes[name] = recipe
|
|
39
|
+
|
|
40
|
+
def recipe(self, name: str) -> Callable[[Recipe], Recipe]:
|
|
41
|
+
"""Decorator form of :meth:`register`."""
|
|
42
|
+
|
|
43
|
+
def decorate(fn: Recipe) -> Recipe:
|
|
44
|
+
self.register(name, fn)
|
|
45
|
+
return fn
|
|
46
|
+
|
|
47
|
+
return decorate
|
|
48
|
+
|
|
49
|
+
def produce(
|
|
50
|
+
self,
|
|
51
|
+
name: str,
|
|
52
|
+
*,
|
|
53
|
+
actor: str,
|
|
54
|
+
owner: str | None = None,
|
|
55
|
+
**inputs: object,
|
|
56
|
+
) -> tuple[object, Record]:
|
|
57
|
+
if name not in self._recipes:
|
|
58
|
+
raise UnknownRecipe(name)
|
|
59
|
+
if not self._authorizer.allows(actor, name):
|
|
60
|
+
raise Unauthorized(f"{actor} may not run {name}")
|
|
61
|
+
|
|
62
|
+
owner = owner or actor
|
|
63
|
+
artifact = self._recipes[name](**inputs)
|
|
64
|
+
record = Record.of(name, actor, owner, inputs, artifact)
|
|
65
|
+
self._audit.write(record)
|
|
66
|
+
log.info(
|
|
67
|
+
"produced recipe=%s artifact=%s actor=%s owner=%s",
|
|
68
|
+
name,
|
|
69
|
+
record.artifact_id,
|
|
70
|
+
actor,
|
|
71
|
+
owner,
|
|
72
|
+
)
|
|
73
|
+
return artifact, record
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""Provenance record — the governance metadata attached to every produced artifact."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
import json
|
|
7
|
+
import uuid
|
|
8
|
+
from dataclasses import asdict, dataclass, field
|
|
9
|
+
from datetime import datetime, timezone
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def _digest(value: object) -> str:
|
|
13
|
+
"""Stable SHA-256 of any JSON-serializable value; repr fallback for the rest."""
|
|
14
|
+
try:
|
|
15
|
+
payload = json.dumps(value, sort_keys=True, default=repr)
|
|
16
|
+
except TypeError:
|
|
17
|
+
payload = repr(value)
|
|
18
|
+
return hashlib.sha256(payload.encode()).hexdigest()
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@dataclass(frozen=True)
|
|
22
|
+
class Record:
|
|
23
|
+
"""Immutable provenance for a single production event."""
|
|
24
|
+
|
|
25
|
+
recipe: str
|
|
26
|
+
actor: str
|
|
27
|
+
owner: str
|
|
28
|
+
input_digest: str
|
|
29
|
+
output_digest: str
|
|
30
|
+
artifact_id: str = field(default_factory=lambda: uuid.uuid4().hex)
|
|
31
|
+
created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
|
|
32
|
+
|
|
33
|
+
@classmethod
|
|
34
|
+
def of(cls, recipe: str, actor: str, owner: str, inputs: dict, output: object) -> Record:
|
|
35
|
+
return cls(
|
|
36
|
+
recipe=recipe,
|
|
37
|
+
actor=actor,
|
|
38
|
+
owner=owner,
|
|
39
|
+
input_digest=_digest(inputs),
|
|
40
|
+
output_digest=_digest(output),
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
def to_dict(self) -> dict:
|
|
44
|
+
return asdict(self)
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import pytest
|
|
2
|
+
|
|
3
|
+
from open_refinery import AllowList, Factory, MemorySink, Unauthorized
|
|
4
|
+
from open_refinery.factory import UnknownRecipe
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
def make_factory(**kw):
|
|
8
|
+
f = Factory(**kw)
|
|
9
|
+
f.register("upper", lambda text: text.upper())
|
|
10
|
+
return f
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def test_produce_returns_artifact_and_record():
|
|
14
|
+
f = make_factory()
|
|
15
|
+
artifact, record = f.produce("upper", actor="ian", text="hi")
|
|
16
|
+
assert artifact == "HI"
|
|
17
|
+
assert record.recipe == "upper"
|
|
18
|
+
assert record.actor == "ian"
|
|
19
|
+
assert record.owner == "ian" # defaults to actor
|
|
20
|
+
assert record.artifact_id
|
|
21
|
+
assert record.input_digest and record.output_digest
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def test_owner_override():
|
|
25
|
+
f = make_factory()
|
|
26
|
+
_, record = f.produce("upper", actor="ian", owner="team", text="hi")
|
|
27
|
+
assert record.owner == "team"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def test_audit_trail_records_every_production():
|
|
31
|
+
sink = MemorySink()
|
|
32
|
+
f = make_factory(audit=sink)
|
|
33
|
+
f.produce("upper", actor="ian", text="a")
|
|
34
|
+
f.produce("upper", actor="ian", text="b")
|
|
35
|
+
assert len(sink.records) == 2
|
|
36
|
+
assert {r.output_digest for r in sink.records} # distinct digests captured
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def test_unknown_recipe():
|
|
40
|
+
f = make_factory()
|
|
41
|
+
with pytest.raises(UnknownRecipe):
|
|
42
|
+
f.produce("missing", actor="ian")
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def test_authorization_blocks_disallowed_actor():
|
|
46
|
+
f = make_factory(authorizer=AllowList({("ian", "upper")}))
|
|
47
|
+
f.produce("upper", actor="ian", text="ok") # allowed
|
|
48
|
+
with pytest.raises(Unauthorized):
|
|
49
|
+
f.produce("upper", actor="mallory", text="no")
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def test_unauthorized_leaves_no_audit_record():
|
|
53
|
+
sink = MemorySink()
|
|
54
|
+
f = make_factory(authorizer=AllowList(set()), audit=sink)
|
|
55
|
+
with pytest.raises(Unauthorized):
|
|
56
|
+
f.produce("upper", actor="ian", text="no")
|
|
57
|
+
assert sink.records == []
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
version = 1
|
|
2
|
+
revision = 3
|
|
3
|
+
requires-python = ">=3.11"
|
|
4
|
+
|
|
5
|
+
[[package]]
|
|
6
|
+
name = "colorama"
|
|
7
|
+
version = "0.4.6"
|
|
8
|
+
source = { registry = "https://pypi.org/simple" }
|
|
9
|
+
sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
|
|
10
|
+
wheels = [
|
|
11
|
+
{ url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
|
|
12
|
+
]
|
|
13
|
+
|
|
14
|
+
[[package]]
|
|
15
|
+
name = "iniconfig"
|
|
16
|
+
version = "2.3.0"
|
|
17
|
+
source = { registry = "https://pypi.org/simple" }
|
|
18
|
+
sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503, upload-time = "2025-10-18T21:55:43.219Z" }
|
|
19
|
+
wheels = [
|
|
20
|
+
{ url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
|
|
21
|
+
]
|
|
22
|
+
|
|
23
|
+
[[package]]
|
|
24
|
+
name = "open-refinery"
|
|
25
|
+
version = "0.1.0"
|
|
26
|
+
source = { editable = "." }
|
|
27
|
+
|
|
28
|
+
[package.optional-dependencies]
|
|
29
|
+
dev = [
|
|
30
|
+
{ name = "pytest" },
|
|
31
|
+
]
|
|
32
|
+
|
|
33
|
+
[package.metadata]
|
|
34
|
+
requires-dist = [{ name = "pytest", marker = "extra == 'dev'", specifier = ">=8.0" }]
|
|
35
|
+
provides-extras = ["dev"]
|
|
36
|
+
|
|
37
|
+
[[package]]
|
|
38
|
+
name = "packaging"
|
|
39
|
+
version = "26.2"
|
|
40
|
+
source = { registry = "https://pypi.org/simple" }
|
|
41
|
+
sdist = { url = "https://files.pythonhosted.org/packages/d7/f1/e7a6dd94a8d4a5626c03e4e99c87f241ba9e350cd9e6d75123f992427270/packaging-26.2.tar.gz", hash = "sha256:ff452ff5a3e828ce110190feff1178bb1f2ea2281fa2075aadb987c2fb221661", size = 228134, upload-time = "2026-04-24T20:15:23.917Z" }
|
|
42
|
+
wheels = [
|
|
43
|
+
{ url = "https://files.pythonhosted.org/packages/df/b2/87e62e8c3e2f4b32e5fe99e0b86d576da1312593b39f47d8ceef365e95ed/packaging-26.2-py3-none-any.whl", hash = "sha256:5fc45236b9446107ff2415ce77c807cee2862cb6fac22b8a73826d0693b0980e", size = 100195, upload-time = "2026-04-24T20:15:22.081Z" },
|
|
44
|
+
]
|
|
45
|
+
|
|
46
|
+
[[package]]
|
|
47
|
+
name = "pluggy"
|
|
48
|
+
version = "1.6.0"
|
|
49
|
+
source = { registry = "https://pypi.org/simple" }
|
|
50
|
+
sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
|
|
51
|
+
wheels = [
|
|
52
|
+
{ url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
|
|
53
|
+
]
|
|
54
|
+
|
|
55
|
+
[[package]]
|
|
56
|
+
name = "pygments"
|
|
57
|
+
version = "2.20.0"
|
|
58
|
+
source = { registry = "https://pypi.org/simple" }
|
|
59
|
+
sdist = { url = "https://files.pythonhosted.org/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f", size = 4955991, upload-time = "2026-03-29T13:29:33.898Z" }
|
|
60
|
+
wheels = [
|
|
61
|
+
{ url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" },
|
|
62
|
+
]
|
|
63
|
+
|
|
64
|
+
[[package]]
|
|
65
|
+
name = "pytest"
|
|
66
|
+
version = "9.1.1"
|
|
67
|
+
source = { registry = "https://pypi.org/simple" }
|
|
68
|
+
dependencies = [
|
|
69
|
+
{ name = "colorama", marker = "sys_platform == 'win32'" },
|
|
70
|
+
{ name = "iniconfig" },
|
|
71
|
+
{ name = "packaging" },
|
|
72
|
+
{ name = "pluggy" },
|
|
73
|
+
{ name = "pygments" },
|
|
74
|
+
]
|
|
75
|
+
sdist = { url = "https://files.pythonhosted.org/packages/e4/47/b9efed96c114afcfa3c9d3fe98a76a1d14c74a9e266d397cf6eb64be5e01/pytest-9.1.1.tar.gz", hash = "sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313", size = 1636369, upload-time = "2026-06-19T10:58:32.857Z" }
|
|
76
|
+
wheels = [
|
|
77
|
+
{ url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536, upload-time = "2026-06-19T10:58:31.347Z" },
|
|
78
|
+
]
|