Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .claude/skills/desktop-verification/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ This skill is how to use them; it restates neither.
| MCP Apps: `src/desktop/widgets/app/`, the sandbox proxy, `src-tauri/src/app_sandbox.rs` | `mcp-apps.mjs` |
| an app's review: reading it while the app's call or message waits (`appCall` and `stale()` in `gateway-source.ts`, the `callTool` and `sendMessage` routing in `dependencies.ts`), and who asks, and what, on the card or in the overview (`approval-request.tsx`, `gateway-views.ts`) | `app-review.mjs` |
| an agent's command in a review, including bidi (`said.tsx`, `ApprovalCommand`, the overview row) | `command-order.mjs` |
| a file an agent published, shown and saved: its card (`conversation/ui/published-files.tsx`), a held picture read back and verified (`ui/held-files.tsx`, `adapters/browser/held-file-urls.ts`, `ui/message-images.tsx`), where the transcript places it, and saving it (`saveFile` in `src/host/window.ts`, `src-tauri/src/saving/`) | `published-files.mjs --shots <dir>` |
| widths: approval card, composer (its thinking control too), column titles, Settings sidebar | `responsive.mjs --shots <dir>` |
| a Settings page: its masthead, tabs, the bar's title on scroll, search landing, its focus ring (`src/desktop/settings/ui/`) | `settings-page.mjs` |
| `index.html`'s load fallback, the panel's stage and window size | `load-fallback.mjs` |
Expand Down
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 3 additions & 2 deletions crates/nessa-client-core/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ name = "read_only_sync"
required-features = ["cli"]

[dependencies]
base64 = "0.22"
nessa-auth = { path = "../nessa-auth" }
nessa-protocol = { path = "../nessa-protocol" }
nessa-sdk = { path = "../nessa-sdk" }
Expand All @@ -27,6 +28,7 @@ nessa-local-storage = { path = "../nessa-local-storage" }
regex = "1"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sha2 = "0.10"
tokio = { version = "1", features = ["rt", "sync", "time", "net"] }
tracing = "0.1"
tungstenite = "0.29"
Expand All @@ -35,8 +37,7 @@ uuid = { version = "1", features = ["v4"] }
# The unmarked checkpoint fixture. A production build of this crate does not
# enable it.
nessa-sdk = { path = "../nessa-sdk", features = ["test-support"] }
# Existing cache corruption and private-key fixtures need these test-only values.
sha2 = "0.10"
# Existing private-key fixtures need this test-only value.
zeroize = "=1.9.0"
tempfile = "3"
tokio = { version = "1", features = ["macros", "rt-multi-thread", "test-util"] }
Expand Down
11 changes: 6 additions & 5 deletions crates/nessa-client-core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,15 +34,16 @@ cache policy/progress and reset ports/requests remain internal.
| Path | Responsibility |
| --- | --- |
| `src/pairing/client.rs` | Native enrollment, strict pinned status and retry, pending-state publication and one retained physical worker. Shared framing and enrollment socket policy come from `nessa-protocol::pairing`. |
| `src/read_only_sync/domain/` | Immutable attributed cache reset requests. |
| `src/read_only_sync/application/` | Cache policy and typed evidence, finite records/catalogue drivers, saved-read/reset/purge ports, protected connection policy and bounded watch loop. |
| `src/read_only_sync/domain/` | Immutable attributed cache reset requests; a held file named as the view names it, and its ranges. |
| `src/read_only_sync/application/` | Cache policy and typed evidence, finite records/catalogue drivers, saved-read/reset/purge ports, protected connection policy, bounded watch loop, and the held-file fetch (ranges, at least one asked every time, busy retries, size and digest before keeping). |
| `src/read_only_sync/infrastructure/cache/` | One private SQLite owner for catalogue values, physical records, SDK checkpoints, progress and purge/reset receipts. |
| `src/read_only_sync/infrastructure/gateway/` | Protected pinned session, codecs, sources, and operation deadline/cancellation adapter. Its post-I/O/first-cause policy differs from enrollment's phase/wake socket. |
| `src/read_only_sync/infrastructure/gateway/` | Protected pinned session, codecs, sources (`artifact.read` ranges included), and operation deadline/cancellation adapter. Its post-I/O/first-cause policy differs from enrollment's phase/wake socket. |
| `src/read_only_sync/infrastructure/held_file.rs` | The output and the `OUT.<key>.part` a fetch assembles in (keyed on conversation, digest, media type and size), held by one fetch at a time, re-read and checked from disk, synced and hard-linked at `OUT` (the link refuses anything there); an existing `OUT` looked at without following links. |
| `src/read_only_sync/entrypoint/` | Argument contract and JSON output over supplied handles. |
| `src/composition/` | Private profile, device/status admission, protected session and cache construction, independent wall/monotonic adapters, immutable command diagnostic facade, and executable input/output. |
| `src/composition/` | Private profile, device/status admission, protected session and cache construction, independent wall/monotonic adapters and the retry pause, `fetch` (an existing output answered before dialling, then one held file into its part), immutable command diagnostic facade, and executable input/output. |
| `examples/read_only_sync.rs` | Standalone executable using `composition::run_read_only_example`. |
| `tests/read_only_sync/` | Matching domain, application, gateway and private-cache boundary evidence, included by the library with `#[path]`. |
| `tests/composition/` | Private profile, code-input and command diagnostic evidence. Real authenticated online process tests remain in `nessa-server/tests/composition/read_only_online.rs`. |
| `tests/composition/` | Private profile, code-input, command diagnostic, and composed `fetch` (scripted native peer, real files) evidence. Real authenticated online process tests remain in `nessa-server/tests/composition/read_only_online.rs`. |

The deterministic five-mode saved-output race is
`tests/read_only_sync/infrastructure/saved_output.rs`. It uses the existing
Expand Down
12 changes: 10 additions & 2 deletions crates/nessa-client-core/src/composition/clock.rs
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
//! Executable clock adapters. Authentication/cache wall time and socket elapsed time
//! have separate ports and separate meanings.
//! have separate ports and separate meanings. `ThreadPause` waits between
//! retries of a busy held-file range.
use crate::read_only_sync::application::held_file::Pause;
use nessa_auth::application::ports::Clock as WallClock;
use nessa_protocol::clock::Clock;
use std::time::{Instant, SystemTime, UNIX_EPOCH};
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
pub(super) struct SystemClock;
impl WallClock for SystemClock {
fn unix_milliseconds(&self) -> u64 {
Expand All @@ -24,3 +26,9 @@ impl Clock for MonotonicClock {
self.0.elapsed().as_millis().min(u64::MAX as u128) as u64
}
}
pub(super) struct ThreadPause;
impl Pause for ThreadPause {
fn pause(&self, delay: Duration) {
std::thread::sleep(delay);
}
}
90 changes: 90 additions & 0 deletions crates/nessa-client-core/src/composition/fetch.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
//! Composition of `fetch`: the output checked before anything is dialled,
//! then one held file fetched over the admitted connection into the files
//! beside its output, and the one JSON line.
//!
//! ```text
//! kept: output's name has no room for a part --> refused, nothing dialled
//! output there? --is the file--> success, nothing dialled
//! --is not-------> refused, left alone
//! --absent-------> (status, connect) --> fetch
//! fetch: fetch_held_file(connection, pause, disk files) --> line
//! --gateway refusal--> recheck asks the pinned status if it names authority
//! ```
//! Arrows are calls in order. `online` admits the run and supplies the
//! connection, the recheck and the enrollment evidence.
use crate::read_only_sync::application::held_file::{
fetch_held_file, kept_output, FetchCause, FetchFailure, FetchProgress, FileStep,
HeldFileSource, Pause,
};
use crate::read_only_sync::application::{device::asks_status, GatewayError};
use crate::read_only_sync::domain::HeldFile;
use crate::read_only_sync::entrypoint::held_file::write_fetch;
use crate::read_only_sync::entrypoint::CommandError;
use crate::read_only_sync::infrastructure::held_file::DiskFiles;
use serde_json::{json, Value};
use std::io::Write;
use std::path::Path;

/// The answer when `out` already decides the command: it is the file
/// (success), or it is something else, or it cannot be read, or it has no
/// room for a part beside it (refused). `None` when there is no output, so
/// the file is to be fetched. Nothing was dialled, so `recheck` is `null`.
pub(super) fn kept(
file: &HeldFile,
out: &Path,
output: &mut dyn Write,
) -> Option<Result<(), CommandError>> {
let result = match DiskFiles::new(out, file) {
Ok(mut files) => kept_output(&mut files, file).transpose()?,
Err(step) => Err(refused(step)),
};
Some(write_fetch(
file,
result,
false,
json!({"recheck":null}),
output,
))
}

fn refused(step: FileStep) -> FetchFailure {
FetchFailure {
cause: FetchCause::File(step),
progress: FetchProgress::default(),
}
}

/// Fetch `file` into `out` over `source`. `recheck` asks the pinned status
/// again, and is called only for a gateway failure that names this device's
/// authority (`asks_status`); every other report carries `null`.
pub(super) fn fetch(
source: &mut dyn HeldFileSource,
pause: &dyn Pause,
file: &HeldFile,
out: &Path,
recheck: &dyn Fn(GatewayError) -> Value,
enrollment: Value,
output: &mut dyn Write,
) -> Result<(), CommandError> {
let result = DiskFiles::new(out, file)
.map_err(refused)
.and_then(|mut files| fetch_held_file(source, pause, &mut files, file));
let recheck = match &result {
Err(FetchFailure {
cause: FetchCause::Gateway(failure),
..
}) if asks_status(*failure) => recheck(*failure),
_ => Value::Null,
};
write_fetch(
file,
result,
true,
json!({"enrollment":enrollment,"recheck":recheck}),
output,
)
}

#[cfg(test)]
#[path = "../../tests/composition/read_only_fetch.rs"]
mod tests;
3 changes: 2 additions & 1 deletion crates/nessa-client-core/src/composition/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,11 @@
//! the bounded private profile: the device's private state directory and gateway
//! address. `device` pairs and reads the pinned enrollment status. `online` admits each run by that status, then
//! consumes the protected session, its facades and finite drivers before JSON
//! presentation.
//! presentation. `fetch` keeps one held file beside its output.
mod clock;
mod device;
pub(crate) mod error;
mod fetch;
mod online;
mod profile;
use crate::composition::clock::SystemClock;
Expand Down
37 changes: 35 additions & 2 deletions crates/nessa-client-core/src/composition/online.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,15 @@
//! ```
//! `watch` holds the same session for its bounded loop: registration, then
//! one finite records pass per operation, each from the durable checkpoint.
//! `fetch` holds it for one held file, one `artifact.read` range per
//! operation, into the part beside its output; it opens no cache, and an
//! output already there is answered before the profile is opened (`fetch`).
//! Arrows are calls in order (design rows PC1–PC6). No read happens without a
//! fresh Active status, and nothing is purged without a Terminal one.
use super::device::{self, client_failure, pinned, status_json, Device};
use super::fetch;
use super::profile::{Profile, ProfileError};
use crate::composition::clock::{MonotonicClock, SystemClock};
use crate::composition::clock::{MonotonicClock, SystemClock, ThreadPause};
use crate::read_only_sync::application::device::{
asks_status, CachePurges, PinnedStatus, PurgeBeforeEnd, PurgeReceipt,
};
Expand All @@ -23,6 +27,7 @@ use crate::read_only_sync::application::watch::{
use crate::read_only_sync::application::{
CacheError, CachePolicy, Cancellation, GatewayError, GatewayPolicy,
};
use crate::read_only_sync::domain::HeldFile;
use crate::read_only_sync::entrypoint::watch::WatchLines;
use crate::read_only_sync::entrypoint::{online, Command, CommandError};
use crate::read_only_sync::infrastructure::cache::ReadOnlyCache;
Expand Down Expand Up @@ -138,12 +143,21 @@ pub(super) fn execute(
let profile_path = match command {
Command::Records { profile, .. }
| Command::Catalogue { profile, .. }
| Command::Watch { profile, .. } => profile,
| Command::Watch { profile, .. }
| Command::Fetch { profile, .. } => profile,
_ => return Err(CommandError::Arguments),
};
// The output, when it is there already, answers before anything is opened
// or dialled.
if let Command::Fetch { file, out, .. } = command {
if let Some(answer) = fetch::kept(file, out, output) {
return answer;
}
}
let operation = match command {
Command::Records { .. } => "records",
Command::Watch { .. } => "watch",
Command::Fetch { .. } => "fetch",
_ => "catalogue",
};
let paired = match open_paired(profile_path, policy) {
Expand Down Expand Up @@ -240,6 +254,7 @@ pub(super) fn execute(
max_passes,
..
} => run.watch(conversation.clone(), *pages, *max_passes, output),
Command::Fetch { file, out, .. } => run.fetch(file, out, output),
_ => Err(CommandError::Arguments),
}
}
Expand Down Expand Up @@ -465,6 +480,24 @@ impl Run<'_> {
};
lines.end(end, recheck)
}
/// One held file into the part beside `out`, kept as `out` once verified.
fn fetch(
mut self,
file: &HeldFile,
out: &Path,
output: &mut dyn Write,
) -> Result<(), CommandError> {
let paired = self.paired;
fetch::fetch(
&mut self.connection,
&ThreadPause,
file,
out,
&|failure| recheck(paired, failure),
self.enrollment,
output,
)
}
fn catalogue(self, pages: usize, output: &mut dyn Write) -> Result<(), CommandError> {
let mut source = self.connection.catalogue(
self.receiver.clone(),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
//! the record may go, so a device never forgets a receiver whose data it still
//! holds. A refusal, a timeout, a closed connection or an unreadable status
//! ends nothing and purges nothing (design rows PC2–PC5).
use super::{CacheError, GatewayError};
use super::{CacheError, GatewayError, HeldFileRefusal};
use nessa_auth::{
application::pairing::{
ClientPendingStore, DeviceCredential, PendingEnrollment, PrivateKeyMaterial,
Expand Down Expand Up @@ -165,6 +165,7 @@ pub(crate) fn asks_status(error: GatewayError) -> bool {
| ChangeWatchErrorCode::WrongReceiver
| ChangeWatchErrorCode::StaleEpoch
)
| GatewayError::HeldFile(HeldFileRefusal::Unauthorized | HeldFileRefusal::Forbidden)
)
}

Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
use nessa_protocol::product_contract::generated::{
CatalogueReadErrorCode, ChangeWatchErrorCode, RecordReadErrorCode, SessionCloseReason,
CatalogueReadErrorCode, ChangeWatchErrorCode, ConversationErrorCode, RecordReadErrorCode,
SessionCloseReason,
};
use std::io::{Read, Result as IoResult, Write};
use std::net::SocketAddr;
Expand Down Expand Up @@ -91,6 +92,20 @@ pub(crate) enum GatewayError {
Catalogue(CatalogueReadErrorCode),
/// The gateway refused a change-watch request with its typed code.
Watch(ChangeWatchErrorCode),
/// The gateway refused one `artifact.read` range with its typed code.
HeldFile(HeldFileRefusal),
}

/// How the gateway refuses an `artifact.read` range: a conversation code, or
/// the socket's own access refusals, which are no conversation code.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum HeldFileRefusal {
/// The gateway does not know `artifact.read`: it is older than held-file
/// reads. Its `unknown_method` is never a `Conversation` code here.
UnknownMethod,
Conversation(ConversationErrorCode),
Forbidden,
Unauthorized,
}

/// One driver attempt's consumed evidence; no durable authentication decision.
Expand Down
Loading
Loading