open/llm-ingestion-okf
1
0
Fork 0
Code Issues Releases 1 Activity

docs(security): state plainly that Door A is ungated

Browse source 
The module docstring and README claimed the library "calls the guard at
every persist gate". That described the intended end state in the present
tense. Door A -- the only door shipped -- has zero runtime dependencies and
calls no guard function before writing to disk.

Both places now say so, and state that gating external or untrusted content
is the caller's responsibility (okf.import_bundle, or prepare_input /
screen_output) until the persist gates land with Doors B and C.

Reported as F2 in a dogfood review by claude-playlist-corpus, which read the
earlier wording as safe-by-default and had to wire the gating itself.

No behavior change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WdVgowYC4LARgvNdNMiuvz
This commit is contained in:
Kjell Tore Guttormsen 2026-07-19 10:09:25 +02:00
commit 7fe073ac61
2 changed files with 27 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

19
README.md
View file

@ -36,12 +36,25 @@ Security is owned by the sibling package
- **guard** answers "is this content safe to persist?" — scan, sanitize,
quarantine, fail-secure, provenance stamping.
- **this library** does the plumbing — connect a source, materialize a
deterministic OKF bundle, generate the index — and calls the guard at every
persist gate (`prepare_input`/`screen_output` for extracted text,
`okf.import_bundle` for received bundles).
deterministic OKF bundle, generate the index.
No security functionality is reimplemented here.
### What is gated today: nothing
Door A — the only door shipped so far — is **ungated**. The package has zero
runtime dependencies and calls no guard function before writing to disk.
`materialize_bundle` writes what it is given.
If you materialize external or otherwise untrusted content, gating is **your**
responsibility at the call site: `okf.import_bundle` for received bundles, or
`prepare_input`/`screen_output` around extracted text. The guard-calling
persist gates are part of Doors B and C (phase 2), not of Door A.
This is stated plainly because the earlier wording ("calls the guard at every
persist gate") described the intended end state in the present tense, and a
consumer reasonably read it as safe-by-default.
## Roadmap
The library is built in four phases so that every known OKF surface in the

14
src/llm_ingestion_okf/__init__.py
View file

@ -2,8 +2,16 @@
Three entry doors: spec-based ingestion (manifest -> connector ->
deterministic materialization -> index), a bundle inbox converting common
file types to OKF concepts, and import of external OKF bundles. Security is
delegated to llm-ingestion-guard at every persist gate.
file types to OKF concepts, and import of external OKF bundles.
Security is owned by llm-ingestion-guard, never reimplemented here. Note
what that does and does not mean today: Door A is UNGATED. It has zero
runtime dependencies and calls no guard function on the way to disk. A
caller that materializes external or otherwise untrusted content is
responsible for gating it -- via guard's okf.import_bundle for received
bundles, or prepare_input/screen_output around extracted text. Do not read
"security is delegated" as "safe by default": materialize_bundle writes
what it is given. The guard-calling persist gates arrive with Doors B and C.
Door A (spec-based ingestion) public surface: materialize_bundle plus the
typed error hierarchy rooted in IngestError.
@ -27,7 +35,7 @@ from .manifest import (
)
from .materialize import IngestResult, materialize_bundle
__version__ = "0.3.0"
__version__ = "0.3.1"
__all__ = [
"Extraction",