Skip to content
Merged
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
2 changes: 2 additions & 0 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -374,6 +374,8 @@ Pure utility functions with no domain or infrastructure coupling:
- **`kdfPolicy.js`** — KDF parameter validation and sensible defaults.
- **`aesGcmMeta.js`** — AES-GCM metadata validation (IV length, tag length).
- **`canonicalBase64.js`** — base64 encoding round-trip integrity check.
- **`boundedPromiseCache.js`** — fixed-residency LRU coalescing for immutable
async reads; rejected work is never retained.

## Storage Model

Expand Down
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

- **Direct bundle references** - `bundles.getMemberReference()` and
`bundles.iterateMemberReferences()` validate bundle structure, canonical
descriptors, direct Git edges, and direct target object types without
recursively resolving each member's support graph. Existing member and root
methods retain complete-validation semantics.

### Performance

- **Bounded immutable Git metadata coalescing** - repeated exact tree-entry and
object-info reads now share successful in-flight and completed work through a
fixed-residency LRU. BundleService separately retains only structural
descriptor bytes under both entry and byte bounds. Rejected work is evicted,
mutable records are cloned for callers, and no application payloads or ref
state enter either cache.

## [6.4.0] — 2026-07-17

### Added
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,8 +138,8 @@ Core capabilities:
read-only, and `sweep()` can release only markers whose expiry has passed.
- **Application storage**: `assets`, `pages`, `bundles`, `retention`, and
`publications` compose streaming CAS writes, bounded structured
materializations, targeted member reads, reachability roots,
compare-and-swap refs, and immutable lifecycle evidence.
materializations, direct-reference or complete-validation member reads,
reachability roots, compare-and-swap refs, and immutable lifecycle evidence.
- **Scoped staging workspaces**: `workspaces.open()` mirrors application writes
behind one renewable temporary RootSet, returns only after each handle is
anchored, promotes destination-first, and exposes bounded age, expiry,
Expand Down
41 changes: 41 additions & 0 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -1077,6 +1077,47 @@ The canonical bundle token is:
git-cas:1:bundle:fanout-tree:<codec>:<sha1|sha256>:<oid>
```

### Direct bundle references

```javascript
const reference = await cas.bundles.getMemberReference({
handle: materializationHandle,
path: 'nodes/root',
});

for await (const reference of cas.bundles.iterateMemberReferences({
handle: materializationHandle,
})) {
indexHandle(reference.path, reference.handle);
}
```

`getMemberReference()` and `iterateMemberReferences()` are the explicit lazy
integrity surfaces. They validate the bundle root, persisted limits, fanout
summaries, canonical member descriptor, direct Git tree edge, and direct target
object type. They do not recursively resolve the referenced member's complete
support graph. Use them for indexes and manifests that dereference only selected
members.

Each immutable `BundleMemberReference` contains `version`, `path`, `handle`,
`type`, and declared `size`. Missing paths return `null`; malformed bundle
structure, mismatched edges, and missing or mistyped direct targets fail closed.
Completing reference iteration still validates root and fanout summaries.

The Git persistence adapter coalesces successful exact tree-entry and
object-info reads in one process-local LRU with a fixed 2,048-entry default.
Bundle traversal separately retains immutable structural descriptor bytes under
a 1,024-entry and 16 MiB total bound. Rejected work is removed, returned
tree-entry records are cloned, and application payloads, refs, and collection
state are never cached. Advanced direct adapter construction may set
`metadataCacheEntries` to another positive safe integer.

Object identity is immutable, but external pruning can change whether an
unretained object remains available. Keep roots retained for the adapter's
operation lifetime and do not race active reads with destructive repository
maintenance. Payload access performs authoritative Git I/O if availability
changes despite that precondition.

### `bundles.getMember()`, `bundles.iterateMembers()`, and `bundles.openMember()`

```javascript
Expand Down
Loading
Loading