Foundation.Data.Doublets.Cli 5.1.0

dotnet add package Foundation.Data.Doublets.Cli --version 5.1.0
                    
NuGet\Install-Package Foundation.Data.Doublets.Cli -Version 5.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Foundation.Data.Doublets.Cli" Version="5.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Foundation.Data.Doublets.Cli" Version="5.1.0" />
                    
Directory.Packages.props
<PackageReference Include="Foundation.Data.Doublets.Cli" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Foundation.Data.Doublets.Cli --version 5.1.0
                    
#r "nuget: Foundation.Data.Doublets.Cli, 5.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Foundation.Data.Doublets.Cli@5.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Foundation.Data.Doublets.Cli&version=5.1.0
                    
Install as a Cake Addin
#tool nuget:?package=Foundation.Data.Doublets.Cli&version=5.1.0
                    
Install as a Cake Tool

C# CI/CD Pipeline NuGet (clink) NuGet (library) GitHub Release

This directory contains the production .NET implementation, published as two NuGet packages from a shared source tree:

Package Project Install Use case
clink Foundation.Data.Doublets.Cli/ dotnet tool install --global clink Run the CLI without writing any C#.
Foundation.Data.Doublets.Cli Foundation.Data.Doublets.Cli.Library/ dotnet add package Foundation.Data.Doublets.Cli Embed the parser, query processors, decorators, named/pinned types, persistent transformation trigger decorator, and LiNo I/O in another .NET project.

The CLI csproj only contains Program.cs plus the System.CommandLine wiring; every reusable type lives in the library project so external apps can recreate or extend the CLI without re-implementing any of the internals.

Install

dotnet tool install --global clink

Update an existing installation:

dotnet tool update --global clink

To consume the library inside another .NET project:

dotnet add package Foundation.Data.Doublets.Cli

API documentation is generated by DocFX from the library's XML doc comments and is published to GitHub Pages alongside the Rust rustdoc site by .github/workflows/docs.yml.

Use

clink '() ((1 1))' --changes --after

The CLI exposes the complete command surface, including persistent transformation triggers with --always, --once, --never, --triggers, --triggers-file, and --embed-triggers. Each option is implemented in the public library, so other .NET applications can call into the same processors directly.

Quoted query references always resolve by name: "0" and "1" are names, while bare 1 is an address. This applies to definitions and restrictions as well as reference values. Use --auto-create-missing-references to create missing named points; strict queries require an existing name or a substitution definition.

Embedded callers can select unsigned addresses through AdvancedMixedQueryProcessor<T>. The existing AdvancedMixedQueryProcessor API, including its Options and Pattern types, remains available for uint. The selected implementation shares the same matching and mutation algorithms. For example, an existing row at the largest stored u64 identity can be queried with UInt128, keeping the wildcard outside that range:

using Foundation.Data.Doublets.Cli;
using Foundation.Data.Doublets.Cli.Engine;

var engine = new LinksEngine<UInt128>(new MemoryCommitLog());
using var session = engine.Begin();
UInt128 id = ulong.MaxValue;
session.EnsureCreated(id);
session.UpdateLink(id, id, id);
AdvancedMixedQueryProcessor<UInt128>.ProcessQuery(session,
    $"(({id}: {id} {id})) (({id}: {id} {id}))");

Queries edit this private session; publication still requires its explicit commit. Standard callbacks expose owned, read-only three-part lists, so later edits do not change retained observations. Read their parts through the list interface: the pinned upstream Link<UInt128> list helpers initialize default constants through reflection that does not support UInt128. Monotonic engine sessions preview queries over detached rows and names before reserving their allocation order. This avoids temporary create/delete probes; (() ((1 1))) creates the private point (1: 1 1) in a fresh session. Only real edits reach change callbacks. Preview failures preserve the cursor; a later missing-reference rejection or rollback can leave reserved address gaps. Explicit addresses use direct ensure rather than walking intervening identities. The reservation queue is allocated only when a query first reserves an address. Preview copies visible rows and executes the query before its real execution, so it adds a row snapshot and a second matching pass for this guarantee. Other stores keep their existing prediction through compatible interface defaults. Causal sessions expose session.QueryLinks as INamedTypesLinks<UInt128>. Pass that adapter to AdvancedMixedQueryProcessor<UInt128> to query the complete stored u64 range while staging in the caller's fresh address reservation. Even recreating a retained deletion at ulong.MaxValue preserves a lower fresh cursor. The adapter rejects reads and writes after preparation or disposal, including empty queries retained through an earlier adapter reference. Owned row callbacks and the session's finished diagnostics remain detached from subsequent edits.

Checked queries admit at most 1 MiB of original UTF-8 input, depth 64, 4096 syntax nodes/results, 16,384 bindings, 4 MiB of estimated binding storage and 1 MiB of decoded named change references. Admission previews precede real private edits and external callbacks. Bare negative and overflowing numbers reject; quoted or encoded numeric names stay names. Publication still requires session.Commit(token) and its existing final constraints and 64-edit batch admission.

LinksOperation<T>, LinksRestriction<T>, RemoteLinks<T> and the generic LinksServer.Serve/ExecuteRequest overloads share the standard protocol with selected unsigned addresses; the established uint APIs remain available. Serve session.QueryLinks to expose private causal edits through text and binary. LinksClient.QueryLossless(text) sends the explicit original-query envelope, retaining quoted numeric and special names. The peer must support that envelope; there is no fallback resend after an unknown outcome. Checked workers clamp raw text and binary decoding before canonical formatting. Request admission and query previews precede private edits; serving a session never publishes it. The query plan retains validation evidence and the unfinished physical query interchange work.

LiNo imports (--import, --in, --lino-input, and the library's LinoDatabaseInput.ImportText/ReadFromFile) validate the complete input before writing. Invalid input leaves existing links and names unchanged, without requiring --transactions.

LiNo import/export preserves backslashes literally in quoted names, including Windows paths and a backslash immediately before the closing delimiter. Names with newlines or both quote kinds export as the notation library's lossless ~1{UTF-8 hex} reference literals. See the import syntax and examples.

Optional Transactions and Version Control

Pass --transactions (or any flag in the family — --transactions-file, --commit-mode, --retention, --log) to record each Create/Update/Delete as a reversible transition in a sidecar doublets store. Pass --vc (or --vc-file, --branch, --branch-from, --checkout, --tag, --list-branches, --list-tags) to add a version-control layer over the recorded transitions log:

# Record reversible transitions into data.transitions.links
clink --db data.links --transactions --auto-create-missing-references '() ((1 1))'
clink --db data.links --log

# Branch and tag on top of the transitions log
clink --db data.links --vc --tag v1
clink --db data.links --vc --branch feature --branch-from 1
clink --db data.links --vc --list-branches

Tags accept name=sequence or name=existing-tag. For names containing =, the command uses the first delimiter whose complete suffix resolves. For example, after creating v1, --tag 'release=雪=part=v1' creates release=雪=part, and --tag 'alias=release=雪=part' creates an alias at the same point. Quote these arguments in the shell. The tag-name example checks both forms and checkout through repeated native command invocations.

BeginTransaction() / Commit() / Rollback() are also exposed on the library API for explicit batches. End-to-end demo scripts live in examples/transactions/ and examples/version-control/.

Serve Over TCP and Other IPC Transports

clink --db data.links --serve 127.0.0.1:7777                 # serve a database
clink --connect 127.0.0.1:7777 '() ((1 1))'                  # text protocol
clink --connect 127.0.0.1:7777 --protocol binary --arity 1.. # binary protocol, list all links

With --triplets, the server reads every request as triplets instead, as described in docs/TRIPLETS.md.

Every address is an endpoint of IPC transports v1, so the same server also listens on UDP, Unix sockets, named and anonymous pipes, FIFOs, shared memory, mapped files, files, signals, POSIX and System V message queues, mailslots, WM_COPYDATA or ALPC. --serve repeats, and --forward stacks a relay on top without opening a database:

clink --db data.links --serve 127.0.0.1:7777 --serve shm:/tmp/links   # two endpoints, one store
clink --serve udp:127.0.0.1:7778 --forward shm:/tmp/links              # a relay
clink --connect udp:127.0.0.1:7778 --protocol binary '() ((1 1))'
clink --connect 'exec:clink --db other.links --serve stdio' ''         # anonymous pipes

In the library, Foundation.Data.Doublets.Cli.Ipc connects, listens, relays and registers custom kinds, and LinksServer.ListenAll and LinksClient.ConnectEndpoint take any endpoint. See examples/ipc/.

In the library, LinksServer serves any INamedTypesLinks<uint>, and LinksClient queries a server through either TextLinoProtocol or BinaryLinoProtocol. The wire formats are described in docs/case-studies/issue-105. The binary links notation codec itself (LinksPacket, LinoMapping, LinoFormat, ArityRange, DecodeLimits, PacketReader) comes from the Link.Foundation.Links.Notation.Binary namespace of the Link.Foundation.Links.Notation package; ProtocolLimits bounds messages of both protocols.

Use as a library

Foundation.Data.Doublets.Cli.Library is usable as an embedded transactional store, not only as the code behind clink.

using Foundation.Data.Doublets.Cli;
// `CreateAndUpdate` and `Exists` are extension methods on `ILinks<T>`.
using Platform.Data;
using Platform.Data.Doublets;

// A `ulong`-addressed store; the CLI's own `uint` store is the
// non-generic `TransactionsDecorator`.
using var data = new NamedTypesDecorator<ulong>("db.links");
using var log = new NamedTypesDecorator<ulong>("db.transitions.links");
using var transactions = new TransactionsDecorator<ulong>(data, log);

using (var transaction = transactions.BeginTransaction())
{
    transactions.CreateAndUpdate(transactions.Constants.Null, transactions.Constants.Null);
    transaction.Commit();
}

A runnable version of this is examples/embedded-store/csharp (dotnet run --project examples/embedded-store/csharp).

  • Any address type. TransactionsDecorator<TLinkAddress> works over any INamedTypesLinks<TLinkAddress> whose address is an IUnsignedNumber<TLinkAddress>; the non-generic TransactionsDecorator stays behind as the uint specialisation the CLI uses. The transitions wire format writes addresses in decimal under the invariant culture, so it is identical across address types, and an address that does not fit the target type is rejected rather than silently truncated.
  • Crash recovery. Recovery runs when the decorator is constructed: committed-but-unapplied transitions are replayed and transitions that were never committed are rolled back, so an abandoned transaction leaves nothing behind after a reopen.
  • Multi-process access. LinksFileLock locks a <database>.lock sidecar, shared for readers and exclusive for writers, with a blocking Acquire and a non-blocking TryAcquire. StorageRevision.Of(path) / revision.HasChanged(path) answer "has anyone else written since I last looked?" without reparsing the database. The lock file path and the shared/exclusive semantics match the Rust storage::lock module, so both implementations can guard the same database.

Type hierarchy

TypesDecorator<TLinkAddress> wraps any ILinks<TLinkAddress> and keeps a type hierarchy with multiple inheritance in plain links (#148): the type of a link is its source, the root is (Type: Type Type), a sub-type is (S: T S), and an extra parent is a pair (p: S T2) marked by (m: Extends p). Its queries stop on cycles.

using var named = new NamedTypesDecorator<uint>("db.links");
var types = new TypesDecorator<uint>(named); // finds or creates Type and Extends
var doc = types.Define(types.Root);
var @public = types.Define(types.Root);
var note = types.Define(doc);
var news = types.Define(note, doc, @public);
var isPublic = types.IsA(types.Instance(news), @public); // true
var parents = types.ParentsOf(news); // [note, doc, public]

The class is not sealed and every member is virtual. Queries read the decorated links and writes go through the decorator, so a derived decorator that checks writes sees them. With new TypesDecorator<uint>(links, root, extends) the pinned types (1: 1 1), (2: 1 2), … are sub-types of root 1.

Triplets

TripletsOverDoublets<TLinkAddress> wraps any INamedTypesLinks<TLinkAddress> and keeps triplets (index: type from to) in its doublets (#151): a node (i: T 0 0) is (i: T i) and a link (i: T f t) is (i: T ((Pair f) t)), with the points Pair and Nothing found or created by name.

using var named = new NamedTypesDecorator<uint>("db.links");
var triplets = new TripletsOverDoublets<uint>(named);
var type = triplets.CreateTripletPoint();               // (type: type 0 0)
var person = triplets.CreateTriplet(type, 0, 0);
var alice = triplets.CreateTriplet(person, 0, 0);
var bob = triplets.CreateTriplet(person, 0, 0);
var knows = triplets.CreateTriplet(type, alice, bob);   // (knows: type alice bob)
triplets.UpdateTriplet(knows, type, bob, alice);        // the address stays
var fromBob = triplets.EachTriplet(TripletQuery<uint>.ByFrom(bob));
var deleted = triplets.DeleteTriplet(alice);            // alice and knows
TripletsQueryProcessor.ProcessQuery(triplets, $"(() (({type} {bob} {bob})))"); // a create
Console.Write(TripletsLino.Export(triplets));           // (index: type from to) lines

The class is not sealed and every member is virtual. See docs/TRIPLETS.md for the encoding and its costs.

Permissions

--permissions self|<rules.links> runs queries as --subject (an index or a name; a guest by default) and checks every read and write against rules stored as links (#149); see Permissions and examples/permissions. In the library:

using var data = new NamedTypesDecorator<uint>("data.links");
var markers = PermissionPolicy<uint>.EnsureMarkers(data, data);
PermissionPolicy<uint>.Allow(data, markers, PermissionAccess.Read, user, @public);
var policy = new PermissionPolicy<uint>(data, data); // or a rules store of its own
var alice = new PermissionsDecorator<uint>(data, policy, aliceLink);
// Reads skip what alice may not read; a forbidden write throws
// ForbiddenException ("Forbidden: update 14") and changes nothing.

A link alice may not refer to answers as a missing one and its name as an unknown one (#161). PermissionAccess.Reference grants the reference without the read; see the case study.

UndoableLinksDecorator<uint> (Begin, Commit, Rollback) makes a request atomic under the view, writes the store made on its own included. LinksServerOptions.Permissions, Subject and Authenticate give every connection of a LinksServer a session of its own (LinksSessions); (auth: token) answers (subject: i). Authenticate is any callback; LinksTokenTable keeps the tokens as links named after their SHA-256.

Composing networks

UnionLinksDecorator<uint> joins links networks into one, RemapLinksDecorator<uint> reads one under other addresses (OffsetAddressMap<uint>, AddressTable<uint> or any IAddressMap<uint>), and LinksExternalIds keeps the ids of other systems (UUIDs, URLs) as links (#149). None of them depends on permissions or on each other; a PermissionsDecorator over a union restricts every member, one under it a single member. See docs/COMPOSITION.md.

var union = new UnionLinksDecorator<uint>(client, new RemapLinksDecorator<uint>(server, new OffsetAddressMap<uint>(1u << 24)));
var draft = union.Create();              // in client, the primary member
union.Update(draft, serverNote, draft);  // may refer to the server's links
var owner = union.OwnerOf(draft);        // 0: the member that has the link
var alice = new PermissionsDecorator<uint>(union, new PermissionPolicy<uint>(union, union), aliceLink);

var ids = new LinksExternalIds(idsStore, "uuid");     // or the data itself
var link = ids.Ensure("6f1c...", data);               // bound, or a new point

Develop

dotnet restore
dotnet build --configuration Release
dotnet test --configuration Release

Release automation for this package lives in csharp/scripts/ and uses changesets from csharp/.changeset/.

The optional Foundation.Data.Doublets.Cli.Engine namespace exposes LinksEngine<T> sessions through the existing links and names API. Concurrency, isolation, immutable history, constraints and revision-log storage are selected at construction. See engine strategies for costs, file/replication ownership, guarantee limits and runnable examples. The existing bare links store remains available for cache workloads.

Select ConcurrencyControl.Pessimistic for overlapping sessions that reserve written addresses and immediately reject competing writes. It composes with the existing isolation and history options. See point-write ownership, retry rules and costs.

Any store can be kept as a cache with deadlines and a size limit. Any session can undo part of its work with savepoints. A running engine can be copied to an empty log with online backup. A damaged journal can be checked and repaired from its valid prefix or a replica.

TransactionsDecorator borrows its data and journal stores. Finish foreground operations, dispose the decorator, then dispose those stores. Shutdown() and Dispose() wait for the active asynchronous checkpoint to finish; concurrent shutdown callers all wait for the same completion. Persistence callbacks must return for shutdown to complete. Calls from active background callbacks (including Task.Run descendants), or while holding the decorator's storage lock, throw InvalidOperationException to prevent joining their own work. Cancelled queued checkpoint work and failed checkpoints remain recoverable from committed journal records on reopen. Shutdown does not dispose the borrowed stores.

When you own an entire facade graph, LinksFacadeDisposer.Dispose(outermost) releases borrowers before their dependencies. It joins transaction workers and finishes version transactions while their stores remain available. Nested cleanup shares cycle/duplicate detection and retains references detached during disposal. A borrower cleanup failure propagates before its dependencies close, allowing a retry. Calling TransactionsDecorator.Dispose() directly continues to leave its borrowed stores with the caller.

If version-transaction rollback fails during undo or persistence, the version facade retains that transaction and rejects branch, tag, checkout and new transaction operations. Retry the same transaction rollback or owner disposal; only a terminal transaction releases admission. A whole-graph cleanup failure therefore leaves the stores available for the same retry.

A commit can report a checkpoint error after the journal decision is durable. When IsCommitted is true, version transaction disposal, owner disposal and rollback finish that commit's branch metadata. They preserve the committed data. Failed metadata publication retains admission and rejects further writes until retry succeeds. Retried transition markers are idempotent, including when the original metadata write took effect before reporting an error.

Initial version history visits retained journal records. Gaps in sequence numbers do not create checkout targets, and the final signed sequence remains publishable before later writes are rejected as exhausted.

Version sidecars preserve delimiter text, Unicode, NUL and newline in branch, parent and tag names. New branch markers use a versioned encoding and ordinary legacy markers remain readable; see the marker protocol for compatibility and upgrade limits.

The optional Engine.PagedCommitLog stores ordered records as immutable native doublets pages without SQL. Its caller-owned IPageDevice can be a native FilePageDevice; select a positive page quota with the log constructor. Keep the device alive while using the engine. Explicit disposal reports uncertain close outcomes and preserves ownership fencing; it never flushes staged records. See native page guarantees, costs and examples.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
5.1.0 0 11/20/2026
4.0.6 115 10/24/2026
4.0.5 110 10/24/2026
4.0.4 97 10/24/2026
4.0.3 103 10/24/2026
4.0.2 102 10/15/2026
4.0.1 122 10/15/2026
4.0.0 94 10/7/2026
3.2.0 110 10/5/2026
3.1.0 134 8/29/2026
3.0.0 129 8/29/2026
2.6.0 128 8/18/2026
2.5.0 155 5/15/2026