Penghou.Siming.Testing
1.0.0
dotnet add package Penghou.Siming.Testing --version 1.0.0
NuGet\Install-Package Penghou.Siming.Testing -Version 1.0.0
<PackageReference Include="Penghou.Siming.Testing" Version="1.0.0" />
<PackageVersion Include="Penghou.Siming.Testing" Version="1.0.0" />
<PackageReference Include="Penghou.Siming.Testing" />
paket add Penghou.Siming.Testing --version 1.0.0
#r "nuget: Penghou.Siming.Testing, 1.0.0"
#:package Penghou.Siming.Testing@1.0.0
#addin nuget:?package=Penghou.Siming.Testing&version=1.0.0
#tool nuget:?package=Penghou.Siming.Testing&version=1.0.0
Penghou.Siming
Penghou.Siming is a small, embedded, tamper-evident event ledger for .NET. It combines a versioned cryptographic hash-chain format with transactional SQLite persistence for local-first audit and provenance workloads.
Siming is intended for AI-assisted engineering sessions, workflow audit trails, tool execution provenance, approvals, decisions, workspace promotions, and other histories where committed events must remain ordered and independently verifiable.
canonical payload bytes
+ ordered event envelope
+ previous row hash
-> SHA-256 row hash
-> atomic SQLite append
Siming is tamper-evident, not tamper-proof. A party that can replace the entire database can also recompute a replacement chain. Detecting rewriting or rollback therefore requires comparison with a previously trusted checkpoint, optionally anchored in Git, signed, or stored elsewhere.
Packages
| Package | Responsibility |
|---|---|
Penghou.Siming |
Cryptographic format, canonical payload contracts, verification, ledger heads, and checkpoints |
Penghou.Siming.Sqlite |
SQLite persistence, atomic transactions, writer serialization, crash recovery, and append-only enforcement |
Penghou.Siming.Cryptography |
Optional detached Ed25519 checkpoint signing and public-key verification |
Penghou.Siming.Testing |
Provider-neutral conformance checks reusable by SQLite and future storage providers |
Penghou.Siming.Verify |
Standalone SQLite ledger and checkpoint verification CLI |
The five packages target .NET 8. The supported graduation profile covers Windows, Linux and macOS; no additional framework is included. The stable contract defines ownership, retry, format, binary compatibility and migration promises. See the graduation inventory and release evidence before claiming a candidate has completed publication.
Design principles
- SQLite owns storage, transactions, locking, and crash recovery.
- Siming owns ordering, integrity, verification, and checkpoint semantics.
- The core cryptographic layer operates on canonical bytes, not CLR objects.
- Hash input is versioned, length-delimited, and independently reproducible.
- Normal APIs expose append and read operations but no historical mutation.
- SQLite triggers protect against accidental
UPDATEandDELETE; cryptographic verification remains the real integrity boundary. - A global sequence and hash chain are authoritative. Streams are logical query partitions and do not form independently verifiable chains in v1.
- Optional idempotency keys are globally unique per ledger, cryptographically committed, atomically deduplicated, and directly queryable by every conforming provider.
- Optional expected-head appends provide atomic optimistic concurrency. An identical idempotent retry still resolves to its original entry before the head condition is evaluated.
- Sensitive payload retention is a caller policy. Applications should prefer bounded provenance and content identities over raw secrets or model payloads.
- Append inputs are bounded before persistence. Defaults are conservative and
each provider accepts the same provider-neutral
LedgerInputLimitspolicy. - The v1 suite uses unkeyed SHA-256. Epoch 2 binds a public ledger context and
epoch 3 adds the optional externally keyed
hmac-sha256-v1suite; neither reinterprets earlier history nor replaces trusted checkpoints.
Quick start
await using var ledger = new SqliteAppendOnlyLedger<CanonicalJsonPayloadSerializerV2>(
new SimingSqliteOptions { DatabasePath = "session-ledger.db" }, new());
var entry = await ledger.AppendAsync(new LedgerAppendRequest<WorkspacePromoted>(
sessionId, "WorkspacePromoted", new WorkspacePromoted(/* ... */)));
var checkpoint = await LedgerCheckpoints.CaptureAsync(ledger);
var verification = await ledger.VerifyAsync(checkpoint);
See samples/Penghou.Siming.Samples for a runnable tour covering idempotency,
pagination, signed checkpoints, context-bound epochs, the keyed suite, and
anchoring a checkpoint to a Git trailer with re-verification.
Typed payloads can use CanonicalJsonPayloadSerializer (the historical v1
contract) or CanonicalJsonPayloadSerializerV2. The v2 contract rejects
duplicate object names and canonicalizes number tokens without a lossy
double/decimal conversion. Both are named contracts protected by portable
JSON/hash vectors; existing v1 rows and Guyabano hashes are never
reinterpreted. Its ComputeSha256 and VerifySha256 helpers derive logical
identity from either a JsonElement or persisted UTF-8 JSON. Exact envelope or
file-byte integrity remains a separate hash. Configure stricter append limits
when appropriate:
var options = new SimingSqliteOptions
{
DatabasePath = "session-ledger.db",
InputLimits = LedgerInputLimits.Default with
{
MaxPayloadBytes = 1024 * 1024,
MaxEventTypeUtf8Bytes = 128
}
};
Text limits measure encoded UTF-8 bytes, not UTF-16 characters. Limit failures occur before SQLite opens a write transaction and expose the rejected field, actual byte count, and configured maximum.
Verification captures the target head and processes bounded pages without retaining the complete ledger. Cancellation is checked between reads and rows; progress is reported at page boundaries.
To verify a SQLite database from a terminal:
dotnet run --project src/Penghou.Siming.Verify -- ledger.db --checkpoint checkpoint.json
The CLI also accepts --signed-checkpoint, --public-key, and --key-id.
It prints one JSON result to standard output, progress to standard error, and
returns 0 for valid, 1 for verification failure, 2 for invalid input, or
130 for cancellation. It opens the database through a strict read-only path,
performs no initialization or schema mutation, and verifies one stable SQLite
read snapshot while writers may continue under WAL.
Install
dotnet add package Penghou.Siming --prerelease
dotnet add package Penghou.Siming.Sqlite --prerelease
dotnet tool install --global Penghou.Siming.Verify --prerelease
Add Penghou.Siming.Cryptography only when detached Ed25519 checkpoint signing
is required. Provider authors can use Penghou.Siming.Testing to run the shared
behavioral conformance suite.
Build and publish
CI builds, checks formatting, runs all .NET tests, independently reproduces the
v1 ledger and v2 canonical-JSON vectors in Python, then restores, builds, and vulnerability-audits an
isolated consumer from the packed artifacts before uploading .nupkg and
.snupkg files.
Dispatch Publish qualified Siming graduation packages from the clean reviewed
main commit whose version is set in Directory.Build.props. The existing NuGet
trusted publisher and NUGET_USER secret remain the authorization mechanism.
The workflow packs once, verifies identity/source/hash, qualifies the same
artifacts on all three OSes, publishes those artifacts, then proves fresh
public packages and unchanged compiled consumers. Stable tags are created only
after public qualification; tags record provenance and do not republish.
See release qualification for exact gates.
Current status
The release target is 1.0.0 on .NET 8, following the qualified public
1.0.0-rc.1 and 0.1.0-preview.7 line. The
release notes and qualification evidence record final
publication status. The in-memory and
SQLite ledgers, provider conformance suite, canonical JSON v1 and v2 identities,
expected-head appends, bounded verification, detached Ed25519 checkpoints,
context-bound (epoch 2) and keyed hmac-sha256-v1 (epoch 3) ledger epochs, and
the verification CLI (checkpoint, signed-checkpoint, context, and HMAC key
flags) are implemented. Runnable API examples live in samples/ and run in CI.
Graduation freezes these contracts without adding capabilities. Native AOT
linking and performance work remain deferred. Guyabano, published Hongxian and
Marang paths are representative consumer probes, not full-application certification.
Samples
samples/Penghou.Siming.Samples is a runnable end-to-end tour: SQLite appends
with idempotency and pagination, checkpoint export/import/verification, signed
checkpoints, context-bound epoch-2 ledgers, and keyed epoch-3 ledgers with a
wrong-secret failure. Every scenario asserts its outcome:
dotnet run --project samples/Penghou.Siming.Samples -c Release
Repository layout
src/Penghou.Siming
src/Penghou.Siming.Sqlite
src/Penghou.Siming.Cryptography
src/Penghou.Siming.Testing
src/Penghou.Siming.Verify
samples/Penghou.Siming.Samples
tests/Penghou.Siming.Tests
tests/Penghou.Siming.Sqlite.Tests
docs
tools
vectors
Start with the implementation plan, then see the unfinished roadmap and persistence contract.
License
Apache-2.0
Copyright (c) 2026 Jenő Konrád László
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net8.0
- Penghou.Siming (>= 1.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 1.0.0 | 131 | 10/13/2026 |
| 1.0.0-rc.1 | 108 | 10/13/2026 |
| 0.1.0-preview.7 | 108 | 9/26/2026 |
| 0.1.0-preview.6 | 74 | 9/26/2026 |
| 0.1.0-preview.5 | 80 | 9/26/2026 |
| 0.1.0-preview.4 | 87 | 9/5/2026 |
| 0.1.0-preview.3 | 80 | 9/3/2026 |
| 0.1.0-preview.2 | 87 | 8/28/2026 |
| 0.1.0-preview.1 | 101 | 8/28/2026 |