PitSeeder 4.2.10

PitSeeder

Terminal font

Font note: The pits help screen uses glyph icons from Nerd Fonts. Most Nerd Font-patched fonts render correctly in most terminal environments. Blink on iPadOS showed clipping and character-width problems with some choices; the tested solution was Blink's Jet Brains Mono Nerd Font stylesheet. See the RAIkeep terminal font guide for Blink, macOS, and Ubuntu setup.

PitSeeder change requests and release notes are centralized in the RAIkeep doc/ directory under PitSeeder_... filenames; they are not stored separately in this child repository.

PitSeeder uses the shared RAIkeep configured cloud-root contract: Dropbox, OneDrive, GoogleDrive, and ICloudDrive.

PitSeeder (pits) is a .NET command-line tool for working with JsonPit data stores. It can seed pits from JSON/JSON5 source files, export pits to JSON, and produce resolved WWWA exports where foreign key references are expanded inline.

Operational recovery-log guidance: PITS-AUDIT.md.

Within this repository, PitSeeder lives under RAIkeep/PitSeeder so it can build against the local JsonPit and OsLib sources before those packages are published.

4.2.10

• Adds --archive-events to pits maintain for explicit preview/apply compaction of loose recovery events.
• Preview reports the exact UTC-range archive and selected files without mutation; --apply creates the immutable archive directly inside the existing Events directory and retires only validated loose copies.
• pits audit transparently combines loose .event files and validated Events_*.zip archives with unchanged filters and ordering.
• Invalid or conflicting evidence is retained and reported; existing archives are never overwritten or replaced.
• Aligns fallback dependencies on JsonPit 4.2.10 and OsLibCore 4.2.10, and reports pits v4.2.10.
• Current release notes: PitSeeder_RELEASE_NOTES_4.2.10.md

4.2.9

• Implements accepted incident corrective action CR022 with maintenance-root validation before any Pit is constructed.
• Report-only and apply modes reject a missing root or a WWWA root containing no expected pits without creating directories or files.
• Partially populated WWWA roots report and skip missing pits without creating them.
• Large explicitly applied pruning/legacy-repair runs can trigger a CloudDrive mass-deletion confirmation for the obsolete artifacts reported by the command; review those counts before confirming the provider action.
• Aligns fallback dependencies on JsonPit 4.2.9 and OsLibCore 4.2.9, and reports pits v4.2.9.
• Current release notes: PitSeeder_RELEASE_NOTES_4.2.9.md
• Mandatory storage contract: Cloud-Storage-In-Place-Invariant.md

4.2.8

• Implements accepted CR021 pits maintain (<PitName> | --wwwa) with report-only default and explicit --apply.
• Adds machine-readable --json reporting, explicit aged process-window pruning, and explicit validated extensionless flag/event repair.
• Maintenance disposal does not republish retired changes.
• Aligns fallback dependencies on JsonPit 4.2.8 and OsLibCore 4.2.8, and reports pits v4.2.8.
• Current release notes: PitSeeder_RELEASE_NOTES_4.2.8.md

4.2.7

• Aligns PitSeeder with the coordinated seven-package RAIkeep 4.2.7 release implementing accepted CR020.
• Aligns fallback dependencies on JsonPit 4.2.7 and OsLibCore 4.2.7; pits behavior is unchanged.
• Reports pits v4.2.7 through the CLI version boundary.
• Current release notes: PitSeeder_RELEASE_NOTES_4.2.7.md

4.2.6

• Aligns PitSeeder with the coordinated seven-package RAIkeep 4.2.6 release implementing accepted CR019.
• Aligns fallback dependencies on JsonPit 4.2.6 and OsLibCore 4.2.6; pits behavior is unchanged.
• Reports pits v4.2.6 through the CLI version boundary.
• Current release notes: PitSeeder_RELEASE_NOTES_4.2.6.md

4.2.5

• Implements accepted CR017 with optional --at <timestamp> on single-pit and WWWA exports, for both --json and --out-dir.
• Requires an explicit Z or numeric UTC offset and projects JsonPit history inclusively through that instant.
• Emits the strict { "_export": { "at", "exported" }, "data": ... } envelope only when --at is supplied; existing exports retain their established root shape without it.
• Aligns fallback dependencies on JsonPit 4.2.5 and OsLibCore 4.2.5 and reports pits v4.2.5.
• Current release notes: PitSeeder_RELEASE_NOTES_4.2.5.md

4.2.4

• Aligns PitSeeder with the coordinated seven-package RAIkeep 4.2.4 release implementing accepted CR016.
• Preserves CR015 delete-property and delete-item behavior unchanged.
• Aligns fallback dependencies on JsonPit 4.2.4 and OsLibCore 4.2.4.
• 4.2.4 release notes: PitSeeder_RELEASE_NOTES_4.2.4.md

4.2.3

• Implements accepted CR015 delete-property and delete-item commands.
• Aligns fallback dependencies on JsonPit 4.2.3 and OsLibCore 4.2.3.
• Retains the 4.2.1 Nerd Font glyphs, Blink guidance, and terminal clipping tolerance unchanged.
• Current release notes: PitSeeder_RELEASE_NOTES_4.2.3.md

4.2.1

• Uses glyphs embedded in JetBrainsMonoNLNerdFontPropo-Regular for cloud-provider and numbered help options, avoiding fallback-font width differences.
• Reserves two terminal cells at the end of help lines for renderers such as Blink.
• Continues to depend on JsonPit 4.2.0 and OsLibCore 4.2.0; no library package version changes are part of this CLI-only patch.
• Terminal setup guidance: TERMINAL_FONTS.md
• Current release notes: PitSeeder_RELEASE_NOTES_4.2.1.md

4.2.0

• Retains the command-first seed, export, and audit syntax introduced for CR006.
• Keeps established flat seed/export invocations working throughout 4.x; the legacy parser is scheduled for removal in 5.x.x.
• Moves the recent --events, --event-machine, and --event-level surface directly to audit, --machine, and --level without a legacy audit mode.
• Keeps PitSeeder last in the coordinated release order, immediately after ImgSeeder/iorg.
• Aligns fallback dependencies on JsonPit 4.2.0 and OsLibCore 4.2.0; no PitSeeder CLI behavior changes from 4.1.0.
• Release notes: PitSeeder_RELEASE_NOTES_4.2.0.md

Install

After the package is published to NuGet:

dotnet tool install --global PitSeeder

On macOS or Linux, a practical option is to install directly into a directory on your PATH:

sudo dotnet tool install PitSeeder --tool-path /usr/local/bin

To update:

sudo dotnet tool update PitSeeder --tool-path /usr/local/bin

CLI Reference

pits seed (<PitName> | --wwwa) --source <file-or-directory> [global options]
pits export (<PitName> | --wwwa) (--out-dir <dir> | --json) [--at <timestamp>] [global options]
pits audit (<PitName> | --wwwa) [--machine <filter>] [--level <severity>] [--json] [global options]
pits delete-property <PitName> <ItemId> <PropertyPath> [global options]
pits delete-item <PitName> <ItemId> [global options]
pits maintain (<PitName> | --wwwa) [--apply] [--archive-events] [--json] [global options]
  [--prune-process-flags --older-than <duration>] [--repair-legacy-extensions]

Global option	Description
-h, --help	Print all options with resolved paths
-v, --version	Print version info
-n, --nologo	Suppress the banner
-b, --debug	Enable debug output
-r, --pitroot	Root directory containing pits; when used with -c, this is relative to the configured cloud root
-c, --cloud	Cloud provider name (looks up root in ~/.config/RAIkeep.json5)
--retain-window	Keep this CLI process activity window until the normal timeout instead of releasing it on exit

--source belongs to seed; --out-dir and --at belong to export; --machine and --level belong to audit. --json is available on export, audit, and maintain. Run pits <command> --help for contextual help.

Maintain a pit

maintain is report-only unless --apply is present:

pits maintain Activity -r /path/to/pitroot --json
pits maintain Activity -r /path/to/pitroot --apply
pits maintain --wwwa -r /path/to/pitroot --apply

Ordinary apply reconciles valid changes, creates or preserves immutable cleanup receipts, and retires eligible pairs only after the grace and authority checks. Removing proven expired PID-specific process windows additionally requires --prune-process-flags --older-than <duration>. Repairing recognizable, content-valid extensionless process flags or recovery events additionally requires --repair-legacy-extensions. Unknown, malformed, live, master, and conflict files are retained.

One command can perform ordinary WWWA maintenance and explicit process-window pruning together:

pits maintain --wwwa -c OneDrive -r AIA \
  --apply \
  --prune-process-flags \
  --older-than 01:00:00 \
  --json

Do not follow this with a separate pits maintain --wwwa ... --apply; the combined invocation already merges changes, handles receipts, retires eligible pairs, and prunes eligible process flags.

Normal writable JsonPit construction with autoload: true also applies ordinary change/receipt maintenance when that instance obtains exact-master authority. This preserves the original "master opening performs cleanup" behavior, but it does not create a background timer: a receipt's ten-minute grace must have elapsed before a later opening or maintenance pass can delete its pair. A long-running service that opens each pit only once therefore needs a periodic maintenance call if it should retire eligible pairs without waiting for its next restart.

Process-flag pruning remains deliberately explicit and is never performed merely because a master opens a pit. --prune-process-flags currently requires --apply; ordinary report-only maintenance inventories active, released, and naturally expired flags, but does not preview the exact prune/defer decision. Recovery events are durable audit records and are not deleted by ordinary maintain. Their physical compaction is separately requested with --archive-events.

Preview one pit’s event compaction without writing or deleting anything:

pits maintain Object -c OneDrive -r AIA --archive-events --json

Apply it, or compact all existing WWWA pits:

pits maintain Object -c OneDrive -r AIA \
  --apply --archive-events --json

pits maintain --wwwa -c OneDrive -r AIA \
  --apply --archive-events --json

The archive is named from the oldest and newest validated event timestamps in UTC, such as Events_20260804-0118_to_20260910-1643.zip. It is created directly inside the existing pit Events directory. There is no TempDir staging, directory replacement, archive overwrite, or extraction. Loose files are removed individually only after the archive validates their exact filenames and bytes. Corrupt files, collisions, and evidence that changes during the operation are retained and reported in Deferred or Failures.

Delete a nested property or item

delete-property interprets PropertyPath as a dot-delimited JSON path. It appends a tombstone without overwriting sibling properties:

pits delete-property Activity UC16_SavePits_DevSession What.Chat -c OneDrive -r AIA -n

delete-item appends the established item tombstone:

pits delete-item Object LegacyRecord -c OneDrive -r AIA -n

Both commands save before returning success, preserve append-only history, and release the normal process activity window. -n continues to mean --nologo; it does not suppress persistence.

When -c/--cloud is supplied, the provider must occur in Os.Config.DefaultCloudOrder and have a non-empty entry in Os.Config.Cloud. Having only a Cloud.<provider> path does not enable that provider for CLI use; matching is case-insensitive and the configured spelling is retained.

Events audit mode

pits audit <PitName> -r <root> reads the pit's durable recovery events from its Events child directory and its immutable Events_*.zip archives. It is strictly read-only: it opens no Pit, creates no process or master flag, merges nothing, and writes no audit event. With --json it emits the filtered events as a JSON array; otherwise output is human-readable and ordered deterministically by machine, UTC time, and event identity. Duplicate loose/archive copies are emitted once; conflicting identities cause a diagnostic and a nonzero command result without deleting either source.

For stage meanings, severity behavior, incident workflows, JSON fields, and practical jq reports, read the full pits audit operational manual.

pits audit Person -n -r /path/to/pitroot/ --level warning
pits audit Person -n -r /path/to/pitroot/ --json | jq '.[].Stage'

Use pits audit --wwwa to aggregate the four WWWA event directories. Legacy --events, --event-machine, and --event-level invocations fail with migration guidance rather than being silently reinterpreted.

4.x legacy transition

Existing flat seed/export invocations remain supported in 4.x, including -s, -e, positional pit names, direct .pit input, and WWWA seed/export. Command-first syntax is preferred for new scripts. The 5.x.x line will require subcommands.

Process-window lifecycle

Finite pits commands dispose their pits through JsonPit's durability boundary by default after normal completion and when execution unwinds through an exception: accepted fragments are exported as collision-safe change files before the process activity window is released. Ctrl+C and process exit also attempt this cleanup. Use --retain-window only when the prior timeout-based activity behavior is explicitly required.

Each invocation uses {MachineName}-pits-{PID}.flag. Release succeeds only while the flag content still identifies that OS process, and writes an expired epoch timestamp in place rather than deleting/recreating the OneDrive-backed file. Another process's activity flag cannot be released.

The process activity window is not the master writer ticket. A completed seed command retains its timed master ticket so stale API writers continue to fall back to change files; this preserves the existing overlapping-writer safety contract.

Features

Seed a single pit

Import a JSON5 file into a pit under the given pit root:

pits seed Person --source ./sample/Person.json5 -r ./output/

This creates ./output/Person/Person.pit.

Seed the WWWA set

Import all four WWWA files (Person, Object, Place, Activity) from a source directory:

pits seed --wwwa --source ./sample/ -r ./output/

Export a single pit to a file

pits export Person -r /path/to/pitroot/ --out-dir ~/export/

Writes ~/export/Person.json containing the projected current state of all items.

Export a single pit to stdout

pits export Person -n -r /path/to/pitroot/ --json

Output:

[
  {
    "Id": "Nomsa",
    "Name": "Nomsa Burkhardt",
    "Instruments": ["Voice", "Percussion", "Dance"],
    "Deleted": false,
    "Modified": "2026-04-06T04:06:10.349+00:00"
  },
  ...
]

Pipe to jq

Because --json writes to stdout, standard UNIX piping works (just add -n to suppress the banner):

pits export Person -n -r /path/to/pitroot/ --json | jq '.[] | select(.Id == "Nomsa") | .Instruments'

["Voice", "Percussion", "Dance"]

Export a point in time

Add --at to either a single-pit or WWWA export. The timestamp must include Z or a numeric UTC offset. Projection is inclusive: changes timestamped exactly at the cutoff are included.

pits export Person -n -r /path/to/pitroot/ --json --at 2026-08-27T12:00:00Z

The output is strict JSON and gains an envelope only for an --at export:

{
  "_export": {
    "at": "2026-08-27T12:00:00.0000000Z",
    "exported": "2026-08-31T18:42:03.1234567Z"
  },
  "data": [
    { "Id": "Nomsa", "Name": "Nomsa Burkhardt" }
  ]
}

at is the requested historical cutoff. exported is when this invocation constructed the document from the history then available. It is not a distributed synchronization barrier. A later invocation with the same at can legitimately differ after a delayed or backdated change arrives.

Items that did not yet exist or were deleted at the cutoff are omitted. In a WWWA export, a missing projected target is absent from the lookup while the source reference remains safely unresolved; export does not rewrite it. The existing filenames (Person.json and wwwa.json) remain unchanged for --out-dir exports because provenance is inside the document.

Without --at, the established unwrapped array/object output remains unchanged. With --at, select through .data when piping:

pits export Person -n -r /path/to/pitroot/ --json \
  --at 2026-08-27T12:00:00+00:00 \
  | jq '.data[] | select(.Id == "Nomsa")'

Export all WWWA pits with resolved foreign keys

pits export --wwwa -r /path/to/pitroot/ --out-dir ~/export/

Writes ~/export/wwwa.json with all four pits merged into a single JSON object. Foreign key references in Who, What, Where, and Activity sections are resolved one level deep. Resolved wrappers dissolve and their contents are promoted to the item level; unresolved wrappers remain as-is.

For example, an Activity item with:

{
  "Who": { "Performer": "Nomsa" },
  "Where": { "Venue": "SDZSafariPark" }
}

becomes:

{
  "Performer": { "Id": "Nomsa", "Name": "Nomsa Burkhardt", "Instruments": ["Voice", "Percussion", "Dance"] },
  "Venue": { "Id": "SDZSafariPark", "Name": "San Diego Zoo Safari Park", "Homepage": "https://sdzsafaripark.org/" }
}

The same works with stdout:

pits export --wwwa -n -r /path/to/pitroot/ --json | jq '.Place[] | select((.Id | startswith("SD")) or (.Name | contains("Zoo"))) | {Id, Name}'

{
  "Id": "SanDiegoZoo",
  "Name": "San Diego Zoo"
}
{
  "Id": "SDZSafariPark",
  "Name": "San Diego Zoo Safari Park"
}

Cloud provider support

Use -c to look up a cloud storage root from ~/.config/RAIkeep.json5:

pits export Person -c OneDrive -r LiveAfricaStage --json

This resolves the cloud root from the config and appends the -r value as a provider-relative path. If OneDrive is configured as:

/Users/RSB/Library/CloudStorage/OneDrive/OneDriveData/

then these forms all resolve to the same pit root:

pits -c OneDrive -r LiveAfricaStage
pits -c OneDrive -r LiveAfricaStage/
pits -c OneDrive -r /LiveAfricaStage

Resolved pit root:

/Users/RSB/Library/CloudStorage/OneDrive/OneDriveData/LiveAfricaStage/

PitRoot inference

When -s points to a .pit file, the pit root is inferred automatically by stripping the canonical folder:

pits -s /cloud/RAIkeep/WwwaTests/Person/Person.pit --json

No -r needed.

Help with resolved paths

Pass -h with other parameters to see all paths fully resolved:

pits -h -n -r /cloud/RAIkeep/WwwaTests/

The help display shows which pits exist at the given root.

WWWA Data Model

WWWA stands for Who, What, Where, Activity. It is a convention for organizing data across four canonical pits:

Section keyword	Resolves against pit
Who	Person
What	Object
Where	Place
Activity	Activity

Items in any pit can reference items in other pits using these section keywords. The values are Ids that correspond to items in the target pit.

Build and Publish

• Coordinated release order: OsLibCore -> RaiUtils -> RaiImage -> RaiDiagram -> JsonPit -> ImgSeeder -> PitSeeder

When a matching tag is pushed from the RAIkeep repository, the GitHub Actions workflow at .github/workflows/publish-nuget.yaml now:

• publishes the PitSeeder NuGet tool package from PitSeeder/pits/pits.csproj
• builds self-contained single-file pits binaries for osx-arm64, osx-x64, linux-x64, and win-x64
• uploads those self-contained binaries as GitHub release assets on the matching tag

See BuildFromSource.md for:

• building from source
• building inside the RAIkeep workspace against local projects
• packing and publishing the NuGet tool
• publishing self-contained binaries for macOS, Ubuntu, and Windows

License

This project is licensed under the Apache 2.0 license. See LICENSE.