Folder Scope evidence capability 0.1

folderbase.folder-scope-evidence@0.1.0 is a stable optional Core capability. It supplies the local filesystem continuity evidence needed to allocate a durable Folder Scope without making a path, inode, App scan, or Cloud record the identity of the folder.

It does not upload files, create a share, grant permission, or return a Folder Scope ID. Those are authenticated Folderbase Cloud operations.

Discover support

folderbase protocol contract --json

Continue only when the returned capabilities array advertises folderbase.folder-scope-evidence@0.1.0 as stable.

Observe one selected folder

folderbase folder-scope observe \
  /absolute/path/to/folderbase \
  "clients/project-2" \
  --json

The root must already be an attested Folderbase. The selected path is a safe, nonempty, root-relative ordinary directory. It may be a repository and may contain Markdown, source code, PDFs, CSV, SQLite, office documents, videos, archives, or unknown regular files. Core inventories metadata and boundaries; it does not parse or upload file contents.

Success returns one closed record:

{
  "format": "folderbase-folder-scope-evidence-v1",
  "folderbase_id": "folderbase_019fb97e-9c5f-73ca-9bb2-03dc80f94792",
  "selected_path": "clients/project-2",
  "event_id": "folder_scope_event_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "device_sequence": 1,
  "opaque_binding_proof": "fb_scope_binding_v1_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "nested_boundaries": []
}

The opaque proof is continuity evidence, not authorization. It contains no absolute path, raw filesystem identity, Cloud credential, observer capability, grant, file contents, or unrelated Object metadata.

Continuity behavior

• An identical observation replays the same event and sequence.
• A proven rename creates a new path event while preserving the opaque binding proof.
• A Local Head advance creates new evidence for the current exact state.
• Replacing the selected folder or root fails closed. Core combines every held authority-bearing directory ID with host creation evidence, so a recycled inode or file ID does not inherit the prior binding or journal authority.
• Adding, removing, or replacing a nested Folderbase beneath the selection fails closed. Each nested root is bound to its own host creation evidence.
• Symlink escape, unsupported nodes, stale capture, event tampering, and loss of the separately anchored journal continuity fail without changing ordinary workspace files.
• Core compares deterministic commitments to the complete metadata-only inventory before and after the locked observation. An ordinary entry change fails with folder_scope_observation_changed and does not advance the journal.

Nested Folderbases remain independent governance boundaries. Their strictly sorted root-relative paths are included so an observer cannot accidentally publish across them. One evidence record contains at most 256 boundaries; larger topologies return folder_scope_limit_exceeded before publication. Core also caps the complete private encoded event chain at 64 MiB, including a recoverable orphan, and enforces the bound before reading or appending further history.

TypeScript adapter

const outcome = await folderbase.observeFolderScope(
  "/absolute/path/to/folderbase",
  "clients/project-2",
);

console.log(outcome.document.event_id);

The SDK supervises the exact Core process, validates every known v0.1 field, and preserves additive fields for forward-compatible clients. The exact v0.1 candidate conformance schema remains closed. The SDK never reads or repairs .folderbase state itself. Daemon stdio 0.1 remains query-only; use the one-shot command for this journaled operation.

Independent conformance

node protocol/conformance/capabilities/folder-scope-evidence-0.1/run.mjs \
  --implementation /absolute/path/to/folderbase

The eleven black-box cases prove discovery, idempotent arbitrary-folder observation, non-genesis Local Head progress, stale-observation refusal, rename continuity, selected and root replacement refusal, attested nested-boundary identity, cross-platform escaping-link refusal, unsupported-node refusal, crash recovery, event tampering, deleted-journal refusal, and the closed aggregate journal namespace. Candidate commands run under a bounded whole-process-tree supervisor: Unix process groups and a Windows kill-on-close Job Object assigned before the candidate payload is released. On Windows the FIFO-specific case is reported as not_applicable rather than counted as a pass.

See the public folder-scope-evidence.schema.json, capability package, and ADR-0018.