Semantic Core gives files, documents and the real things they describe stable identities and typed relationships that live outside any one app. It is built first for one person on their own Mac and iPhone, with no account, server or model required.
Identity is opaque and never derived from a path, a hash or a device, so a move keeps a relationship and a copy is recorded as a new instance. Every change is an append-only, hash-chained event; undo is a compensating event, and any relationship can explain why it exists. The core is Rust with a C ABI, and a Swift package reproduces the same signed golden vector independently.
Status Stage 1 Rust core and Swift package are implemented and tested; a Spotlight indexed-entity spike is done, and live Spotlight registration is Stage 2.
Technical reference & source account
A portable, local-first identity and relationship substrate for files, information artifacts, and the things they describe.
Files have locations. Information has identity. Things have relationships.
A receipt, a warranty, a manual and a service record can all refer to the same dishwasher while living in unrelated folders. Moving a file does not sever a justified relationship. Copying a file does not create the same instance. Identical bytes do not prove identical meaning. Semantic Core keeps those distinctions as data, with provenance and a reversible history, independently of any application, renderer or model.
Status
Stage 1 Rust core implemented and tested: sc-envelope, sc-vocab, sc-core and sc-cli pass their fixtures under cargo test --workspace, and the Reflective Rust golden vector reproduces. sc-ffi (C ABI) and the Swift package swift/SemanticCore are implemented and tested: the golden vector reproduces through the FFI and independently in Swift, CryptoKit verifies the signed vector, and the Stage 1 demonstration runs through the Swift store. A Spotlight indexed-entity spike is done; live Spotlight registration needs an app bundle and is Stage 2. Nothing in this repository is a conformance claim for any external protocol.
- Definition v0.2.2 is the architecture of record: ontology, decision boundaries, protocol responsibilities, macOS integration, security, stage plan, fixtures, and the nine answered design decisions.
- Roadmap is the stage plan and task order.
Shape
crates/
sc-envelope sc-event-0.1 envelope: JCS canonical JSON, sha256 identity, Ed25519, access projection, freshness
sc-vocab sc-vocab-1 predicate registry: class constraints, inverses, unknown predicates kept as values
sc-core things, artifacts, revisions, instances, presentations, relationships, assertions,
observations, hash-chained event log, SQLite materialization, resolver
sc-cli sc: link, move-resolve, inspect, retract, export, import, why
sc-ffi C ABI for the Swift package
swift/SemanticCore Swift package over sc-ffi: Envelope, Signature, Hash, JCS, Store; golden vector both ways
fixtures/ moves, copies, edits, deletes, ambiguous, containers, access, vectorsStage 1 proof
Link two files, move one, resolve and inspect the relationship, retract it, inspect the history. Offline, with no model, no server, and no Finder extension. Stage 1 is complete when the nine proofs in the definition and the fixture list pass in CI; see the roadmap.
Principles that do not move
- Object identity is opaque and never derived from a path, a hash, a device or a signing key.
- Observations are not assertions. Assertions are not accepted truth. Qualification is not promotion.
- Verdicts attach to commitments, never to relationships.
- Access is enforced before traversal, counting, search, export and surface participation.
- History is append-only. Undo is a compensating event.
- The graph outlives every consumer. Finder, assistants, editors and renderers read it; none of them own it.
License
MIT OR Apache-2.0, at your option.