Skip to content

refactor(core): consolidate ownership and recoverable Author sync - #119

Closed
timhanlon wants to merge 231 commits into
devfrom
feat/author-sync-v5
Closed

timhanlon wants to merge 231 commits into
devfrom
feat/author-sync-v5

Conversation

@timhanlon

Copy link
Copy Markdown
Collaborator

SKIT's CLI workflows have accumulated Library state interpretation, filesystem writes, sync merging and protocol handling. This branch moves those responsibilities behind their owners and builds recoverable Author Workspace sync on the same foundation.

This is a broad architecture draft against dev, intended for review and discussion. It is not ready to merge.

Implemented

  • Library-owned planning/apply, installation, recovery and history, with captured revision checks and durable operation evidence.
  • Author Workspace and History owners, including interrupted first-connection recovery, structural merge conflicts and recoverable file/directory replacements.
  • Setup selection preserved through updates, passive discovery until approval, incomplete filesystem evidence retained, and owner-derived enable/disable outcomes.
  • Library sync merge, ancestry and device-selection derivation moved behind the Library boundary. First connections use an ordinary empty-base merge.
  • Registry-owned generated-client adapters, endpoint-specific failure classification and browser-login pending state. Request encoding is distinguished from response decoding; writes are not implicitly retried.
  • Source-specific fetching, shared archive preflight that rejects links before extraction, and ZIP-only Registry release downloads.
  • Owner-aligned feature modules and architecture checks. CLI shared/runtime imports now use explicit subpaths, and setup/usage consume Library read facts.

Still in progress

  • Remove the core root export and finish migrating raw Library state consumers in inventory, doctor and Author claims.
  • Close remaining private API leaks and finish the Library completion audit.
  • Complete unattended automatic Author sync, including edit-observation-time conflict policy and background behavior.
  • TUI work remains deferred. Author command modules are currently excluded from the executable CLI grammar.

Validation

Focused core/CLI tests, affected typechecks/builds, ownership/export checks and command smokes were run for the individual commits. Recovery and sync checks include real filesystem scenarios, interruptions and pinned-source restoration. Registry redirect/native probe tests were verified with local loopback access.

At the current head, the affected checks pass, command contracts are unchanged, bundled usage reads an absent Library without creating it, and the packed CLI passes isolated offline installation, runtime, public-story and declaration checks.

The full workspace suite has not been run for this draft. These are local results, not CI or deployed/live multi-device proof.

Add an executable architecture contract under architecture/:

- app.ts models every owner of persisted state and what stops existing.
- decisions.md records each decision with effect-grep corpus references.
- library.ts and library-results.ts declare Library's approved target API.

Enforcement:

- skit/owner-boundaries: code outside packages/skit/src/library/ may not
  import or re-export Library's private storage, writers or folder
  operations.
- skit/approved-services: a Context.Service or Context.Reference must be
  approved in architecture/boundaries.mjs.
- architecture/conformance/library.ts checks the real Library against its
  approved API: missing, extra and changed methods, and undeclared
  requirements. negative.ts proves those checks reject an added method,
  a missing method and an undeclared requirement.

Today's violations are recorded as debt, not approved, and the debt may
only shrink: tests fail on stale entries and the checks fail on new ones.
The root typecheck now includes the architecture project.
Sync.Remote leaves the platform and approved services; LibrarySync moves to workflows; the service rule is stated once in app.ts; drop stale DRAFT headers.
Adds a test that session writes from another site are refused.
AuthorHistory owns history capture, the engine store and sync bookmarks (v4, keyed by workspace and SKIT). Only prepareWrite issues write tickets; the recovered merge saves its own Writing and keeps reporting merged. Node 22 is dropped because it warns on stderr whenever node:sqlite loads (decisions.md A8).
Sync is a plain function over the two owners. History.Store and Sync.Remote are plain inputs, not services. Publish reads the connection once and fails NoRemoteHome. withLeaseReleased is removed: sync never retries.
withLibraryWriterLock takes an exclusive SQLite transaction on <home>/lock.sqlite instead of a pid@host .lock file, so a crashed SKIT never leaves the Library busy. Reentrancy, in-process queueing and fail-at-once are unchanged.
@timhanlon timhanlon closed this Nov 7, 2026
timhanlon added a commit that referenced this pull request Nov 7, 2026
SKIT's CLI and TUI callers currently coordinate Library state,
installation and recovery across frontend workflows. This change puts
those decisions behind the Library owner and gives Author Workspace sync
explicit workspace and history owners, so callers express intent through
reviewed operations.

Replaces #119. Compares `dev` at `6bc3bdeb7` with
`refactor/public-owner-apis` at `c67a74f45`.

## Ownership changes

- Library owns source imports, enable/disable planning, installed-file
changes, removal, setup execution, recovery, history and sync ancestry.
Reviewed plans capture the Library revision and filesystem evidence;
apply revalidates under the writer.
- Author Workspace owns registration, connection checkpoints and leased
workspace writes. Author History owns observations, content-addressed
revisions and sync/backup checkpoints, including interrupted first
connections and structural file/directory replacements.
- MachineSettings owns device settings and its recorded discovery-folder
inverse. The CLI still coordinates the Library and MachineSettings
portions of setup/undo.
- Registry adapters own protocol translation and credentials. Server
lifecycle code moves behind identity, Library and SKIT owners, with one
migration from the existing dev schema.
- Frontends use explicit core subpaths and command providers. Unused
exports and the obsolete routing helper are removed; required error
names remain available as types.

## Before/after call graphs

These condensed graphs omit rendering, low-level filesystem calls and
transport details.

```text
Before — 6bc3bde
CLI handlers / CLI library-application and workflows
├─ resolve configuration and construct operation services
├─ interpret Library state and resolve subjects/scopes
├─ coordinate enable/disable preview and apply
└─ coordinate setup, installed-file changes, recovery and history
   └─ core Library / LibraryStore / filesystem services

After — c67a74f
CLI command providers / TUI application
├─ construct one configured Library
├─ collect choices and render owner-supplied facts
├─ Library.planEnabled / plan → reviewed snapshot and file evidence
├─ Library.apply → writer, revalidation, recorded execution and recovery
└─ Library source/setup/sync operations → owner-held lifecycle
   └─ private store, installer, history and transport dependencies

Author workflows
├─ AuthorWorkspace lease → workspace identity, connection and file writes
├─ AuthorHistory → observations, revisions and durable checkpoints
└─ Registry adapter → authenticated remote revision protocol
```

Callers no longer open Library stores or writers or assemble
installation/recovery steps. Passive previews and interactive questions
stay outside writer scopes. Durable operation records add storage
complexity in exchange for replaying recorded decisions after
interruption.

## Compatibility and remaining scope

- Released local Library formats migrate through their historical
schemas into v12. The server upgrade preserves identity, releases and
Library data; legacy unreleased Draft content is discarded.
- CLI output contract compatibility against `dev` passes.
- Author command modules remain outside the executable CLI grammar. This
PR does not expose them as shipping commands or establish unattended
background sync.
- Runtime now requires Node `^24.22.1 || >=26.12.1`.

## Validation

Local macOS audit:
- Core: 1,079 tests passed, one skipped; eight initial loopback-related
failures passed outside the sandbox.
- CLI unit: 947 passed, three skipped; TUI: 44 passed.
- Server: 164 passed, including the dev-schema upgrade;
architecture/lint tests: 216 passed.
- Affected-package typechecks, CLI contract compatibility against dev,
CLI build, focused subprocess command smoke tests and isolated package
installation passed.

After the unused-export cleanup:
- `pnpm lint:unused` passes without baselines or exemptions.
- Core build, core/CLI/TUI/server typechecks, 42 focused tests,
affected-file Oxlint and diff whitespace checks pass.

The full workspace and end-to-end suites were not run for this audit.
These are local results; Linux CI and deployed/live multi-device
behavior remain unverified.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant