subsync

Documentation

Overview

Package subsync materialises a versioned config bundle into a repo byte-for-byte (epic:scoped-sync, order:5). It is pure filesystem mechanism — no HTTP, no git — so the client transport (internal/hosted) and the CLI verbs (satelle sync config deploy/pull) layer on top and stay testable separately.

This is the git-agnostic successor to the removed project-substrate backup (25c79c3): scoped sync walks the area dirs directly rather than git-ls-files, and Restore writes the bytes a deploy pulls back. The byte-exact writer and the safe-path + exclusion guard are the only pieces reused from the old code.

Index

• func ExcludedLocal(p string) bool
• type File
• type FileError
  • func (e FileError) Error() string
• type Result
  • func Restore(dataDir string, files []File) (Result, error)
  • func (r Result) Err() error

Functions

func ExcludedLocal

func ExcludedLocal(p string) bool

ExcludedLocal reports whether a server-relative path is one Restore will never write, so a caller can skip it before spending a fetch (sty_0fd04503). Restore remains the enforcement point; this is only an early-out.

Returns false when the path fails cleanRel (absolute, "..", empty, …): those are Restore hard-errors, not skips — pre-filtering them would swallow the escape guard.

Types

type File

type File struct {
	Path    string
	Content []byte
}

File is one byte-exact restore target: a server-relative path under the data dir (forward slashes, no leading ".satelle/", e.g. "skills/my-skill.md", "agents.toml", "constitution.md", "tasks/tsk_x.md") and its verbatim bytes.

type FileError

type FileError struct {
	Path string
	Err  error
}

FileError is one file Restore could not write, with the reason.

func (FileError) Error

func (e FileError) Error() string

type Result

type Result struct {
	Written int
	// Skipped holds the server-relative paths that excludedLocal refused.
	// Empty when nothing was skipped. Paths are never written to disk.
	Skipped []string
	// Failed holds files Restore WANTED to write and could not — a filesystem
	// condition, not policy. Deliberately distinct from Skipped: an operator
	// reading "skipped" learns something routine happened, and a real failure
	// must never be reported that way. A non-empty Failed is not an error by
	// itself; each caller decides (a cursor-driven pull continues, a deliberate
	// single-file or whole-partition write fails).
	Failed []FileError
}

Result is Restore's outcome: how many files were written, which excluded (local-only) paths were skipped rather than applied (sty_84f14ace), and which files could not be written at all (sty_4c3729e7).

func Restore

func Restore(dataDir string, files []File) (Result, error)

Restore writes files under <dataDir>, each byte-for-byte, parent dirs created, overwriting any existing file at the same path. dataDir is the repo's resolved .satelle data dir (the workspace-config root the server paths are relative to).

THREE outcomes per file, and they are not interchangeable:

• Unsafe paths (escape dataDir via cleanRel) still HARD-ERROR. That is the escape guard; a manifest that names one is hostile or corrupt.
• Excluded (local-only) paths are SKIPPED and listed in Result.Skipped — never written — so a corrupt manifest cannot drop a satelle.db over a live one, while a batch carrying legitimate files can still complete and advance a pull cursor (sty_84f14ace).
• A file that cannot be WRITTEN is recorded in Result.Failed and the batch CONTINUES (sty_4c3729e7). Returning on the first write failure wedged the documents pull permanently: the cursor save sits after that return, so every later pull re-fetched the same batch and failed on the same file.

Mode: an existing destination keeps its current permissions, a new one is created 0o644, and a file whose content carries the `generated: satelle` frontmatter marker is forced to 0o444 — the mode the OKF materializer writes its views with. See writeRestored for why a read-only destination is replaced rather than refused.

func (Result) Err

func (r Result) Err() error

Err joins the failures into one error, or nil when there are none. Callers for which a partial restore is a failure (config deploy, single-file publish) use this so their loud behaviour is preserved.