Filesystem, Obsidian, and Charter #

Watched roots #

Each filesystem connector is configured with:

• A stable source id.
• One absolute root.
• Include globs.
• Ignore globs.
• Maximum file size.
• Allowed text extensions.
• Whether to store full content, a redacted snapshot, or metadata only.
• Debounce/coalescing window.

The connector refuses paths that escape the root after symlink resolution. .git, .thoughtstream, caches, lock files, editor temporaries, and configured secret patterns are ignored by default.

Stable document identity #

Identity priority:

1. Explicit frontmatter id for Markdown documents.
2. Source-specific inode/device identity when reliable within a scan window.
3. Content hash plus rename-window matching.
4. Normalized source id and relative path.

Path is mutable metadata, not the only identity. A rename emits one rename event where confidently detected; otherwise delete plus add is acceptable and explicitly marked as uncertain.

Version and diff sequence #

For a text addition or change:

1. Read a stable snapshot after debounce and stat verification.
2. Compute SHA-256 and canonical newline-normalized text.
3. If hash matches the current version, emit nothing.
4. Insert an immutable document version.
5. Compute a unified diff against the prior version when bounded by size.
6. Append the file source event referencing previous/current version ids.
7. Update the mutable current-document projection.

Binary and oversized files produce metadata events with no embedded content.

Obsidian #

An Obsidian vault is an ordinary bounded filesystem source with Markdown-aware metadata:

• frontmatter
• headings
• wikilinks and Markdown links
• tags
• blocks/anchors
• optional backlinks calculated as a projection

The first live configuration must point to a selected subtree, not all of The Coil. Private vault content is sensitive even when the file itself has no explicit privacy marker.

Charter bridge #

thought stream observes document changes and emits generic file/document events. A Charter-specific consumer can emit stream.thought.derived.charter.reevaluation with:

• Changed document/version ids.
• Affected spec ids and links.
• Invariants or decisions that may need re-evaluation.
• Suggested Charter consumer/work-item type.
• Confidence and evidence spans.

Charter may consume this event through a versioned adapter. thought stream does not write Charter's database or spec files in the initial release. Charter remains authority for spec semantics, work items, and any eventual application of changes.

First fixture #

Tests use fixtures/vault/ with a small linked document graph. The acceptance scenario edits one Markdown file, renames a second, and deletes a third, then verifies exact versions, diffs, lineage, agent outputs, and projection state.