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
<PackageReference Include="Foundation.Data.Doublets.Cli" Version="5.1.0" />
<PackageVersion Include="Foundation.Data.Doublets.Cli" Version="5.1.0" />
<PackageReference Include="Foundation.Data.Doublets.Cli" />
paket add Foundation.Data.Doublets.Cli --version 5.1.0
#r "nuget: Foundation.Data.Doublets.Cli, 5.1.0"
#:package Foundation.Data.Doublets.Cli@5.1.0
#addin nuget:?package=Foundation.Data.Doublets.Cli&version=5.1.0
#tool nuget:?package=Foundation.Data.Doublets.Cli&version=5.1.0
clink C# Package
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 anyINamedTypesLinks<TLinkAddress>whose address is anIUnsignedNumber<TLinkAddress>; the non-genericTransactionsDecoratorstays behind as theuintspecialisation 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.
LinksFileLocklocks a<database>.locksidecar, shared for readers and exclusive for writers, with a blockingAcquireand a non-blockingTryAcquire.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 Ruststorage::lockmodule, 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 | Versions 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. |
-
net10.0
- Link.Foundation.Links.Notation (>= 0.31.1)
- Platform.Data (>= 0.16.1)
- Platform.Data.Doublets (>= 1.0.0)
- Platform.Data.Doublets.Sequences (>= 0.6.5)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.