# git-cas v6.4.0 Release Notes

`v6.4.0` adds a temporary reachability scope for multi-step application-storage
composition. Applications can build page shards, chunked assets, and structured
bundles without managing Git refs or paying the index and acquisition lifecycle
cost of using a general CacheSet as scratch storage.

## Scoped Staging Workspaces

```javascript
const workspace = await cas.workspaces.open({
  namespace: 'git-warp/materializations',
  ttlMs: 2 * 60 * 60 * 1000,
});

try {
  const page = await workspace.pages.put({ source: encodedShard });
  const bundle = await workspace.bundles.putOrdered({
    members: [['shards/page.cbor', page.handle]],
  });
  await workspace.checkpoint({ handles: [bundle.handle] });
  return await workspace.promoteToCache({
    cache,
    key: materializationKey,
    handle: bundle.handle,
  });
} finally {
  await workspace.release();
}
```

Workspace capabilities mirror `assets.put()`, `assets.adopt()`, `pages.put()`,
`bundles.put()`, and `bundles.putOrdered()`. Each call writes through the
existing application-storage service and returns only after an exact workspace
generation directly reaches the typed result handle. Mutations serialize within
one workspace, so concurrent staging cannot replace rather than accumulate
roots.

`checkpoint()` replaces accumulated roots after an aggregate handle makes its
components transitively reachable. `renew()` extends the current generation's
lease. `release()` is idempotent and deletes only the exact observed generation;
symbolic refs and generation races fail closed.

## Promotion And Failure Ordering

`promoteToCache()` and `promoteToPublication()` require a handle retained by the
active workspace. They establish destination retention before releasing the
temporary root. The destination must return an anchored witness for the exact
handle, ref, and generation. Rejection, malformed evidence, or destination
failure leaves the workspace reachable and reports
`WORKSPACE_PROMOTION_NOT_RETAINED` where applicable. A cleanup conflict after
destination success reports
`WORKSPACE_PROMOTION_CLEANUP_PENDING`, preserving evidence that the durable
destination succeeded while temporary cleanup remains due.

Workspace expiry never revokes reachability automatically. Operators inspect
and sweep one bounded namespace explicitly:

```javascript
let cursor = null;
do {
  const cleanup = await cas.workspaces.sweep({
    namespace,
    limit: 100,
    cursor,
  });
  cursor = cleanup.nextCursor;
} while (cursor !== null);
```

Sweep removes only expired direct refs whose generation still matches the
inspection. Active, invalid, symbolic, and concurrently renewed workspaces are
not deleted. When a result is truncated, pass its opaque `nextCursor` to the
next bounded call so cleanup continues beyond the first page.

## Diagnostics

Workspace inspection and repository doctor report root count, creation time,
age, expiry, active or expired posture, and invalid persisted state. Byte
accounting keeps two meanings separate:

- `logicalBytes` is validated semantic content size across retained typed
  handles;
- `rootObjectBytes` is the loose logical size of unique direct Git root objects.

Neither value claims packed physical residency or unique ownership across
deduplicated support graphs. Inspection validates target names, handles, OIDs,
Git types, and complete application graphs before reporting either count.

## Compatibility

This minor release is API-additive. Existing assets, pages, bundles,
publications, RootSets, CacheSets, ExpiringSets, Vault behavior, and stored
formats remain unchanged. `RepositoryDoctor` keeps its workspace collaborator
optional for direct-constructor compatibility. Workspace witnesses use the
existing `root-set` root kind, while staged-result retention reports
`protection: 'workspace'`; closed retention and diagnostic discriminant unions
remain unchanged for exhaustive TypeScript consumers.

Like all Git-backed composition, the interval between writing a new object and
publishing the workspace ref depends on Git's ordinary unreachable-object grace
period. Immediate-expiry prune running concurrently inside that interval is not
supported.

## Verification

Unit coverage proves exact-generation retention, concurrent staging,
checkpoint compaction, renewal-versus-sweep races, destination-first promotion,
idempotent release, canonical descriptors and refs, date-range bounds,
corruption detection, byte accounting, facade wiring, declarations, and doctor
inventory. Real-Git integration runs `git prune --expire=now` after returned
operations and proves survival through page, asset, and bundle composition,
promotion, expiry, sweep, and release.

The final release-candidate verifier passed 14/14 steps with 6,538 observed
tests: 1,993 Node unit tests, 1,992 Bun unit tests, 1,983 Deno unit tests, and
190 integration tests on each runtime. npm pack and JSR publish dry-runs also
passed. Twenty repeated real-Git ExpiringSet runs verify that concurrent
duplicate-writer behavior remains stable after the RootSet retry correction.

The unchanged downstream `git-warp` ten-second integration hook remains the
release adoption gate after package publication. CI, self-review, Code Rabbit,
and independent Code Lawyer review remain mandatory before tagging.

See [Scoped Staging Workspaces](../API.md#scoped-staging-workspaces) for the
complete API contract and
[PERF-0049](https://github.com/git-stunts/git-cas/blob/main/docs/design/0049-scoped-staging-workspaces/scoped-staging-workspaces.md)
for the design and proof obligations.