YYyycore.ai

Open source · Python

yy-corpus-evidence

Deterministic, content-addressed evidence for a local corpus. Scan the files you already have, record exactly which ones you counted and what they contained, state what you want to state about them, and let anyone re-check the whole thing later.

  • Scan
  • Declaration
  • Manifest
  • Check
  • Verify
GitHub repositorySchemas

Install

Getting it

The library is published as a Python package and developed in the open. The initial alpha supports CPython 3.11 on Windows.

Install command
python -m pip install yy-corpus-evidence
Language
CPython 3.11
Source
github.com/yycore/yy-corpus-evidence
Runs
Locally on Windows in the initial supported release
Outputs
A deterministic manifest; optional declarations use a published input schema

How it works

Five steps, no surprises

The whole design goal is that two people running the same thing over the same files get the same answer, and that a disagreement points at something specific.

  1. Scan a local corpus

    Point the library at a directory on a machine you control. It walks the tree and reads the files there. Nothing leaves the machine as part of the scan.

  2. Add declarations when you have them

    A declaration is a human assertion scoped to an exact path or path prefix. It may reference local evidence files. The tool records the assertion; it does not decide whether the assertion is true or legally sufficient.

  3. Produce a deterministic manifest

    Each inventoried file is recorded with its relative path, byte size, and SHA-256 digest. Entries and declarations are ordered and serialized consistently, so the same supported inputs produce the same manifest bytes.

  4. Surface evidence states

    Each asset is marked unknown, declared, incomplete, or conflicting according to the applicable declarations and referenced evidence files. Gaps stay visible instead of being silently treated as approval.

  5. Verify later

    Given the corpus, a prior manifest, and the declarations used for that scan, verification recomputes the record and reports filesystem or declaration drift.

Why it is built this way

Content addressing, plainly

A file path is a label. It can be renamed, moved, or repointed at different bytes without anyone noticing. A content hash is not a label: it is derived from the bytes themselves, so it changes the moment the bytes do.

File-content hashes make byte-level changes visible. The manifest also records relative paths because names and layout matter during corpus review. Each declaration receives its own deterministic identity from its canonical content and is embedded in the manifest alongside the assets to which it applies.

Determinism is what makes this checkable by someone else. Ordering, normalization, and serialization are fixed, so the manifest can be regenerated later from the same supported inputs and compared without relying on a timestamp or an opaque database.

Scope

What it deliberately does not do

A tool that overstates its scope is worse than no tool. These are the boundaries.

  • It does not upload your corpusScanning and verification happen locally. The library does not transmit the contents of your files, and this website never receives anything from it.
  • It does not reach legal or compliance conclusionsA manifest describes what was on disk. A declaration records what you said about it. Neither is a license clearance, an audit, a certification, or legal advice — those judgments stay with you and your counsel.
  • It does not interpret contentThe library has no opinion about what your files mean or whether you should have them. It records file identities and human assertions so later review can start from a fixed record.
  • It does not prove when something happenedContent addressing shows that two things are the same bytes or that they are not. On its own it is not a timestamping service or a chain of custody.

Formats

Published schemas

Declaration input and manifest output are ordinary JSON described by JSON Schema, so their structure can be reviewed without our code. Runtime checks additionally enforce computed identities, references, and summary consistency.

Manifest v1
/schemas/corpus-evidence/manifest-v1.schema.json
Declaration v1
/schemas/corpus-evidence/declaration-v1.schema.json

Questions and reports

Getting in touch about it

Bugs, questions, and feature discussion belong in the GitHub repository, where the conversation stays with the code.

For anything with a security impact, use the repository's private vulnerability-reporting channel rather than opening a public issue. Our security page explains what to include.