Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 25 additions & 6 deletions docs/PORTABLE_TOOL_DEFINITION_DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -571,12 +571,31 @@ for every portable-tool record and do not substitute the public record schema
for either token. Digest output is exactly `sha256:` followed by 64 lowercase
hexadecimal characters.

Core schema policy also places non-raiseable limits on individual and aggregate
definition bytes, record count, reference-edge count and depth, string and
array sizes, and selected-closure contributions. Definitions cannot raise those
limits. Publication and consumption apply the same versioned limits before
allocating or traversing the complete graph, preventing an authenticated but
pathological definition from exhausting client or repository resources.
Core schema policy places non-raiseable limits on what a single unit may
contain: individual definition bytes, JSON nesting depth and member count,
string sizes, reference-edge depth, and per-record array sizes. Definitions
cannot raise those limits. Publication and consumption apply the same versioned
limits before decoding a record, so one malformed or hostile file cannot exhaust
a parser.

No upper limit is defined on a definition as a whole. Neither the number of
packages, payloads, records, or closure contributions, nor any aggregate data
size, is bounded by a declared ceiling. This is deliberate rather than pending.
No basis for such a number exists: the tools a definition may describe are
open-ended, so measuring the tools already embedded establishes a floor and
never a ceiling; and Reploy is general purpose, running on hardware from large
servers to single-board computers, so no allocation budget generalizes across
clients. A definition is as large as the tool it describes genuinely requires,
and a selected closure is as large as the request it resolves genuinely
requires.

An aggregate ceiling becomes answerable only alongside repository publication
and publisher authorization. Those introduce definitions authored by someone
other than the client's operator, and with them the question of which client
must be able to consume any published definition. That question, not a number
chosen in advance, is what would determine the limit. Until then every
definition is embedded and first-party, the per-unit limits above bound what any
single record or file may contain, and nothing bounds their sum.

## Acquisition Model

Expand Down
21 changes: 17 additions & 4 deletions docs/PORTABLE_TOOL_DEFINITION_IMPLEMENTATION_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -383,10 +383,23 @@ Non-goals: filesystem catalog discovery or acquisition.
### PTD-07: Load Bounded Hierarchical Portable Tool Catalogs

Scope: add injected-filesystem loading, ownership and namespace discovery,
aggregate byte/record/edge/depth limits, and duplicate/digest checks.

Acceptance: limits apply before unbounded work; misplaced and duplicate records
fail; synthetic loader tests pass; no tool-specific case enters the loader.
reference edge and depth limits, and duplicate/digest checks. The normative
design defines no aggregate byte or record-count ceiling, so this slice adds
none, and `bounded` here does not mean a ceiling on catalog size. It means
three properties that hold however large the catalog is: each record's parse is
bounded by the per-unit limits before that record is decoded; traversal and
recursion are bounded by the edge and depth limits; and no allocation, buffer,
or traversal is ever sized by a count a record declares, only by content the
loader has already observed. Loading a catalog of `n` records therefore costs
work and retention linear in `n`, which is the operator's own embedded input,
rather than work a record can inflate.

Acceptance: per-record limits apply before each record is decoded; no
allocation or traversal is sized by a declared count rather than observed
content; loader work and retention stay linear in the records actually present,
proven by a synthetic wide-catalog case rather than asserted; misplaced and
duplicate records fail; synthetic loader tests pass; no tool-specific case
enters the loader.

Non-goals: graph semantics or request resolution.

Expand Down
Loading