Evidence and protected reads

python -m pip install "soterias==0.1.4"
npm install @soterias/core@0.1.0-rc.5

python workflow.py
node workflow.mjs

from soterias import SourceStore, Citation

# This code runs in the trusted host, outside the agent's context.
store = SourceStore.create("new-private-evidence", passphrase=host_unlock,
                           tenant_id="engagement-42", store_id="sources")
source = store.ingest_file("approved-invoice.txt", media="utf8_text",
                           permitted_uses=["transaction-testing"])
evidence = store.evidence(principal="assigned-auditor", purpose="transaction-testing")
evidence.register_source(source, identity="invoice-42", revision="v1",
                         readers=["assigned-auditor"],
                         stale_after_ms=host_expiry, retain_until_ms=host_retention)
save_independent_checkpoint(store.checkpoint())

# Offsets are explicit original Unicode scalar positions, end exclusive.
citation = Citation(source, start=35, end=45, quote="120.00 EUR")
result = evidence.verify(citation)
fact = evidence.extract_quote(citation)
save_independent_checkpoint(store.checkpoint())
checked = evidence.check_fact(fact)

# Interpretations remain candidates. Model confidence cannot grant trust.
interpretation = evidence.extract_interpretation(
    "The transaction is valid", citations=[citation],
    uncertainty=["purchase-order-not-yet-corroborated"],
)
save_independent_checkpoint(store.checkpoint())
evidence.revoke_source(source)  # Only the original profile publisher may revoke.
save_independent_checkpoint(store.checkpoint())
store.close()

import {SourceStore, Citation} from '@soterias/core';

const store = SourceStore.create({directory: 'new-private-evidence',
  passphrase: hostUnlock, tenantId: 'engagement-42', storeId: 'sources'});
const source = store.ingestFile('approved-invoice.txt', {
  media: 'utf8_text', permittedUses: ['transaction-testing'],
});
const evidence = store.evidence({principal: 'assigned-auditor', purpose: 'transaction-testing'});
evidence.registerSource(source, {identity: 'invoice-42', revision: 'v1',
  readers: ['assigned-auditor'], staleAfterMs: hostExpiry, retainUntilMs: hostRetention});
saveIndependentCheckpoint(store.checkpoint());
const citation = new Citation(source, {start: 35n, end: 45n, quote: '120.00 EUR'});
evidence.verify(citation);
const fact = evidence.extractQuote(citation);
saveIndependentCheckpoint(store.checkpoint());
const result = evidence.checkFact(fact);
store.close();

{"name":"verify_protected_quote","arguments":{
  "inputSha256":"SHA256_FROM_THE_PRIOR_PROTECTED_READ",
  "start":"0","end":"7","quote":"invoice","unit":"unicode_codepoint"
}}

executor.configure_document_evidence(tool_id="accounting.lookup", action="lookup",
                                     store=store, source=source)
reviewer.configure_document_evidence(tool_id="accounting.lookup", action="lookup",
                                     store=store, source=source)

"""Actual local encrypted evidence lifecycle; no model or external account required."""
from __future__ import annotations
import json
import os
from pathlib import Path
import sys
import tempfile
import time
from soterias import Citation, FactReference, SourceStore, SourceStoreError


def main() -> None:
    started = time.perf_counter_ns()
    root = Path(sys.argv[1]) if len(sys.argv) > 1 else Path(tempfile.mkdtemp(prefix="soterias-evidence-"))
    root.mkdir(parents=True, exist_ok=True)
    original = root / "invoice.txt"
    text = "Invoice INV-42: café 😀; amount 120.00 EUR.\n"
    original.write_bytes(text.encode("utf-8"))
    # Disposable local example secret, deliberately not a production credential.
    unlock = b"disposable-local-evidence-example"
    store = SourceStore.create(root / "store", passphrase=unlock, tenant_id="demo", store_id="audit")
    now = time.time_ns() // 1_000_000
    source = store.ingest_file(original, media="utf8_text", permitted_uses=["transaction-testing"], captured_at_ms=now)
    # Production hosts protect the checkpoint independently from the store itself.
    checkpoint_path = root / "checkpoint.json"
    checkpoint_path.write_bytes(store.checkpoint())
    evidence = store.evidence(principal="auditor", purpose="transaction-testing")
    evidence.register_source(source, identity="invoice-42", revision="v1", readers=["auditor"],
                             stale_after_ms=now + 60_000, retain_until_ms=now + 120_000)
    checkpoint_path.write_bytes(store.checkpoint())
    quoted = "120.00 EUR"
    start = text.index(quoted)  # Python Unicode scalar indices, not UTF-8 bytes.
    citation = Citation(source, start=start, end=start + len(quoted), quote=quoted)
    assert evidence.verify(citation)["status"] == "verified"
    proof = store.verify_quote(source, purpose="transaction-testing", start=start,
                               end=start + len(quoted), quote=quoted, current_file=original)
    literal = evidence.extract_quote(citation)
    (root / "fact-id.txt").write_text(literal.digest, encoding="ascii")
    checkpoint_path.write_bytes(store.checkpoint())
    checked = evidence.check_fact(literal)
    assert checked["report"]["quotation_truth"] == "true"
    assert checked["report"]["semantic_truth"] == "not_established"
    interpretation = evidence.extract_interpretation("The transaction is valid", citations=[citation])
    checkpoint_path.write_bytes(store.checkpoint())
    assert evidence.check_fact(interpretation)["report"]["quotation_truth"] == "unknown"
    assert evidence.check_fact(FactReference("0" * 64))["truth"] == "unknown"
    try:
        store.evidence(principal="other-agent", purpose="transaction-testing").verify(citation)
    except SourceStoreError as error:
        assert error.code == "evidence_use_denied"
    else:
        raise AssertionError("reader permission was not enforced")
    original.write_bytes((text + "changed outside quote\n").encode("utf-8"))
    try:
        store.verify_quote(source, purpose="transaction-testing", start=start,
                           end=start + len(quoted), quote=quoted, current_file=original)
    except SourceStoreError as error:
        assert error.code == "evidence_original_changed"
    else:
        raise AssertionError("whole-current-source mutation was not refused")
    # Historical provenance remains explicit and does not assert a current original.
    assert evidence.verify(citation)["status"] == "verified"
    store.close()
    with SourceStore.open(root / "store", passphrase=unlock, checkpoint=checkpoint_path.read_bytes()) as reopened:
        evidence = reopened.evidence(principal="auditor", purpose="transaction-testing")
        assert evidence.check_fact(literal)["report"]["quotation_truth"] == "true"
        evidence.revoke_source(source)
        checkpoint_path.write_bytes(reopened.checkpoint())
        try:
            evidence.check_fact(literal)
        except SourceStoreError as error:
            assert error.code == "evidence_source_revoked"
        else:
            raise AssertionError("revocation did not invalidate dependent fact")
    pure = SourceStore.check_quote(text.encode("utf-8"), start=start, end=start + len(quoted), quote=quoted)
    print(json.dumps({"status": "PASS", "runtime": "python", "mode": "cooperative_host_integrity",
                      "quotation_proof": proof["digest"], "pure_check": pure,
                      "elapsed_ms": (time.perf_counter_ns() - started) / 1_000_000,
                      "model_calls": 0, "provider_tokens": None,
                      "semantic_truth": "not_established", "root": os.fspath(root)}))


if __name__ == "__main__":
    main()

// Actual native source/SQLite lifecycle. No external provider or model is invoked.
import assert from 'node:assert/strict';
import {mkdirSync,mkdtempSync,writeFileSync,readFileSync} from 'node:fs';
import {join} from 'node:path';
import {tmpdir} from 'node:os';
import {performance} from 'node:perf_hooks';
import {Citation,FactReference,SourceStore} from '@soterias/core';

const started=performance.now(),root=process.argv[2]??mkdtempSync(join(tmpdir(),'soterias-evidence-'));
mkdirSync(root,{recursive:true});
const original=join(root,'invoice.txt'),text='Invoice INV-42: café 😀; amount 120.00 EUR.\n';
writeFileSync(original,text);
const unlock=Buffer.from('disposable-local-evidence-example');
const store=SourceStore.create({directory:join(root,'store'),passphrase:unlock,tenantId:'demo',storeId:'audit'});
const now=Date.now(),source=store.ingestFile(original,{media:'utf8_text',permittedUses:['transaction-testing'],capturedAtMs:now});
const checkpoint=join(root,'checkpoint.json');writeFileSync(checkpoint,store.checkpoint());
let evidence=store.evidence({principal:'auditor',purpose:'transaction-testing'});
evidence.registerSource(source,{identity:'invoice-42',revision:'v1',readers:['auditor'],staleAfterMs:now+60_000,retainUntilMs:now+120_000});
writeFileSync(checkpoint,store.checkpoint());
const quoted='120.00 EUR';
// JS string indices are UTF-16. Explicitly convert to Unicode scalar indices.
const start=Array.from(text.slice(0,text.indexOf(quoted))).length,end=start+Array.from(quoted).length;
const citation=new Citation(source,{start,end,quote:quoted});
assert.equal(evidence.verify(citation).status,'verified');
const proof=store.verifyQuote(source,{purpose:'transaction-testing',start,end,quote:quoted,currentFile:original});
const literal=evidence.extractQuote(citation);writeFileSync(checkpoint,store.checkpoint());
writeFileSync(join(root,'fact-id.txt'),literal.digest);
const checked=evidence.checkFact(literal);
assert.equal(checked.report.quotation_truth,'true');assert.equal(checked.report.semantic_truth,'not_established');
const interpretation=evidence.extractInterpretation('The transaction is valid',{citations:[citation]});
writeFileSync(checkpoint,store.checkpoint());
assert.equal(evidence.checkFact(interpretation).report.quotation_truth,'unknown');
assert.equal(evidence.checkFact(new FactReference('0'.repeat(64))).truth,'unknown');
assert.throws(()=>store.evidence({principal:'other-agent',purpose:'transaction-testing'}).verify(citation),error=>error.code==='evidence_use_denied');
writeFileSync(original,text+'changed outside quote\n');
assert.throws(()=>store.verifyQuote(source,{purpose:'transaction-testing',start,end,quote:quoted,currentFile:original}),error=>error.code==='evidence_original_changed');
assert.equal(evidence.verify(citation).status,'verified');
store.close();
const reopened=SourceStore.open({directory:join(root,'store'),passphrase:unlock,checkpoint:readFileSync(checkpoint)});
try{
  evidence=reopened.evidence({principal:'auditor',purpose:'transaction-testing'});
  assert.equal(evidence.checkFact(literal).report.quotation_truth,'true');
  evidence.revokeSource(source);writeFileSync(checkpoint,reopened.checkpoint());
  assert.throws(()=>evidence.checkFact(literal),error=>error.code==='evidence_source_revoked');
}finally{reopened.close();unlock.fill(0);}
const pure=SourceStore.checkQuote(Buffer.from(text),{start,end,quote:quoted});
console.log(JSON.stringify({status:'PASS',runtime:'node',mode:'cooperative_host_integrity',quotation_proof:proof.digest,pure_check:pure,elapsed_ms:performance.now()-started,model_calls:0,provider_tokens:null,semantic_truth:'not_established',root}));