Penghou.Hongxian 0.1.0-preview.5

Penghou.Hongxian

Penghou.Hongxian is a durable session kernel for work that unfolds across people, models, tools, workflow runs, retries, and process restarts.

A workflow engine knows what should execute. An artifact store knows what was produced. A memory system knows what has been retained. Hongxian supplies the missing temporal dimension: what belongs together, what happened, what changed, and how the work recovered.

It is designed for long-running human/AI applications that need more than a transient chat transcript but do not want a session framework to become another workflow engine.

Why Hongxian is different

• A session outlives a workflow run. One evolving effort can contain many executions, restarts, revisions, decisions, and external systems without treating any one provider's run ID as the identity of the work.
• History stays truthful. Events, failures, unusual conditions, recovery attempts, and verified receipts are append-only. Successful recovery adds new evidence; it never erases the failure that made recovery necessary.
• Authority is explicit. The ledger is authoritative history. SQLite projections are disposable read models that can be rebuilt. External systems remain authoritative for their own state.
• Retries are safe. Idempotency identities make ambiguous appends repeatable, while conflicting reuse is rejected instead of silently producing contradictory history.
• Cross-store work does not pretend to be one transaction. Cross-store participant receipts and forward reconciliation describe what actually committed across independent stores and what still needs attention.
• The core is provider-neutral. Workflow activities, model calls, tools, artifacts, and revisions are correlated through opaque references rather than dependencies on a particular orchestration or AI stack.
• Local sessions are real operational boundaries. Each session can own an independently verifiable SQLite ledger, making retention, export, inspection, and deletion boundaries understandable.
• Sensitive payload handling is deliberate. Callers classify payloads and choose to retain content, retain only its digest, or omit it before immutable evidence is written.

The result is a session that can answer not only “what is the current state?” but also “how did we get here, what evidence supports it, and what happened when something went wrong?”

How the pieces fit together

                         application policy
                                │
                                ▼
                    ┌───────────────────────┐
                    │  Penghou.Hongxian     │
                    │  session continuity   │
                    │  correlation/recovery │
                    └───────────┬───────────┘
                                │
              ┌─────────────────┼─────────────────┐
              ▼                 ▼                 ▼
       immutable evidence  rebuildable state  opaque references
       Penghou.Siming      SQLite projections external systems
                                               and artifacts

Hongxian deliberately composes focused components rather than absorbing their responsibilities:

This split keeps each authority independently useful. Hongxian does not copy a workflow database, turn every event into memory, store large artifacts, inspect a code graph, or invoke a model. It preserves the identities, causation, correlation, revisions, and receipts needed to understand how those systems participated in one session.

Packages

The core contracts do not require a workflow engine. Applications can attach any external execution system using a provider-qualified operation reference.

A small example

using System.Text.Json;
using Penghou.Hongxian;
using Penghou.Hongxian.Sqlite;

await using var sessions = new SimingSessionEventStore("sessions");
var sessionId = SessionId.New();

var created = await sessions.AppendAsync(new SessionEventRequest(
    sessionId,
    Participant: SessionParticipantAttribution.Human("laszlo", "example"),
    EventType: SessionEventTypes.SessionCreated,
    OccurredAt: DateTimeOffset.UtcNow,
    IdempotencyKey: $"session:{sessionId}:created"));

await sessions.AppendAsync(new SessionEventRequest(
    sessionId,
    Participant: SessionParticipantAttribution.Agent("planner", "example"),
    EventType: SessionEventTypes.ExecutionStarted,
    OccurredAt: DateTimeOffset.UtcNow,
    CausationId: created.EventId,
    CrossSystemRefs: new Dictionary<string, string>
    {
        ["provider"] = "my-workflow-engine",
        ["operation"] = "planning/42"
    },
    IdempotencyKey: "planning/42:started"));

var message = await sessions.AppendAsync(
    new SessionEventRequest(
        sessionId,
        Participant: SessionParticipantAttribution.Human("laszlo", "example"),
        EventType: SessionEventTypes.UserMessage,
        OccurredAt: DateTimeOffset.UtcNow,
        PayloadSchema: new SessionPayloadSchema("example.user-message", 1)),
    new { text = "Please add authentication" });

var payload = message.ReadPayload<JsonElement>();

var page = await sessions.ReadPageAsync(
    new SessionEventPageRequest(sessionId, Limit: 100));
var verifiedHead = await sessions.VerifyChainAsync(sessionId);

The same session can later attach another execution, record a failure, append a recovery plan and verified receipt, rebuild its projection, and prove the ordered ledger without rewriting the earlier history.

For applications using the standard local provider, HongxianSqliteStoreSet opens the complete, consistently configured surface from one root:

await using var hongxian = new HongxianSqliteStoreSet(
    new HongxianSqliteOptions { RootPath = "hongxian-data" });

var session = await hongxian.SessionStore.CreateAsync("project", "workspace/1");
await hongxian.CatalogEvidence.DispatchPendingAsync();

var audit = await hongxian.ConsistencyAudit.InspectAsync(session.Id);

The store set exposes both concrete SQLite implementations and the provider-neutral event, projection, catalog, lease, operation, and inspection interfaces. It is composition convenience, not a service locator or a new authority boundary.

Callers that need immediate delivery visibility can use ISessionEventDeliveryStore.AppendWithDeliveryAsync. Its result separates the authoritative ledger commit from Applied, Lagging, or NotConfigured projection delivery. The consistency audit later correlates the verified ledger head, projection cursor, catalog version, incomplete operations, participant failures, evidence outboxes, and the best-known decision lease. The audit is intentionally a non-atomic diagnostic snapshot and never claims a distributed transaction.

Typed and JsonElement appends first become a JSON tree, then the SQLite provider uses Siming's canonical JSON contract. Object-property order, insignificant whitespace, and equivalent JSON number spelling therefore do not change payload identity. DigestOnly records the canonical JSON digest without content; Omit records neither content nor a digest, so omitted values cannot participate in content-based idempotency. Application payload schemas are versioned separately from the Hongxian envelope and SQLite schema. Registered upcasters transform payloads only while reading or projecting and never rewrite immutable ledger history.

Experience projection and recall

Hongxian now includes a provider-neutral experience model derived from verified session evidence. ExperienceEntity and ExperienceRelation retain temporal validity, provenance, and evidence references. The projector advances through explicit checkpoints, applies effects idempotently, and can rebuild a derived projection without changing the authoritative Siming streams.

Recall is capability-aware and bounded. Exact lookup, relation traversal, and lexical search return freshness, truncation, degradation, unsupported-feature, and checkpoint metadata rather than silently changing query meaning. The core ships an in-memory reference provider; Penghou.Hongxian.LatticeDb supplies the first durable graph and BM25 implementation.

The experience graph is a disposable read model. It does not turn remembered claims into facts, replace ledger verification, or authorize an action. A consumer can trace recalled material back to the evidence that produced it and decide how much authority that evidence deserves.

Architectural boundaries

Hongxian records facts and coordination evidence. Applications still decide what those facts mean and what should happen next.

Participant attribution is a structured, immutable host claim: kind, provider, stable opaque subject, and an optional display-name snapshot. It makes events usefully attributable across humans, agents, models, tools, and systems without pretending to authenticate them. Public IDs and external-operation references round-trip as stable JSON strings and support Parse, TryParse, and span formatting. Portable bounds are exposed through SessionContractLimits and enforced before event, catalog, recovery, or cross-store persistence.

Hongxian does not:

• schedule or restart workflow steps;
• choose a domain recovery action;
• authenticate participants or authorize commands;
• store source code, model transcripts, or large artifacts;
• interpret code graphs or memory;
• roll back independent external systems;
• claim that a projection is authoritative history.

Participant attribution and occurrence time are host-supplied claims. The ledger's commit time is the authoritative audit clock. If an append commits but a projection update fails, the result is projection lag—not permission to append the event again as though nothing happened.

Status and direction

Hongxian 0.1.0-preview.3 (release candidate) targets .NET 10. The session kernel, SQLite provider, recovery and reconciliation contracts, verified experience projector, in-memory experience provider, and initial LatticeDB provider are implemented. The LatticeDB package remains a checkpoint: packed-consumer isolation and the full supported-platform matrix are still being completed. Package-backed Guyabano integration, richer bounded queries, participant collaboration, and cross-domain validation remain roadmap work.

See the architecture for authority and failure semantics, and the roadmap for current milestones and stability criteria.

Build

dotnet build Penghou.Hongxian.slnx --configuration Release
dotnet test Penghou.Hongxian.slnx --configuration Release --no-build
dotnet run --project samples/Penghou.Hongxian.Example

Security model

Hash chaining makes changes to an existing ledger detectable, but an attacker with full storage access could replace the entire ledger. Trusted checkpoints or external anchoring are required to detect rollback or wholesale replacement. Hongxian preserves participant claims and provenance; it does not authenticate them.

Applications should keep secrets and unrestricted model transcripts out of the session ledger, store large content in its authoritative system, and record bounded references and digests instead.

SQLite schemas are versioned independently for the catalog, projections, and cross-store operation store. Upgrades are serialized and transactional, and a library version refuses to open a component written by a newer schema. The host is responsible for backing up authoritative catalog, operation, outbox, and ledger files before upgrading. Projections are rebuildable; the other stores are not. Migration from the first preview discards old decision-lease rows because their GUID tokens cannot provide the fencing guarantee of the current monotonic token contract.

License

Apache-2.0

Copyright (c) 2026 Jenő Konrád László