vfs

var (
	// InvalidPath is returned for a name outside the fs.ValidPath grammar,
	// and by [ValidateWritePath] for the root itself.
	//
	// It is a REFUSAL rather than a cleanup. Normalising "../../etc/passwd"
	// into something safe is the single most reliable way to ship a
	// traversal bug: every normaliser is a small parser, every small parser
	// has a case its author did not think of, and the caller never learns
	// that the path it asked for is not the path it got.
	InvalidPath = errs.Static(CodeInvalidPath, "INVALID_PATH",
		"That path is not usable on this filesystem",
		"core/data/vfs: name violates fs.ValidPath (rooted, empty, backslash-separated, or carrying a . or .. element) or targets the root; refused, never normalised",
		0,
		65)

	// InvalidPermission is returned for a zero file mode, or one carrying
	// bits outside fs.ModePerm.
	//
	// ADR 0031's refusing half: any mode the SDK invented here would be
	// arbitrary. 0644 and 0600 differ by who may read the bytes, and the
	// caller is the only party that knows what the bytes are — so a zero is
	// read as "the field was never filled in", which it almost always is.
	InvalidPermission = errs.Static(CodeInvalidPermission, "INVALID_PERMISSION",
		"A file mode is required and must be a plain permission mode",
		"core/data/vfs: perm is zero (refused, never defaulted — ADR 0031) or carries bits outside fs.ModePerm such as setuid, setgid or sticky",
		0,
		78)

	// PathEscaped is returned when a lexically valid name resolved outside
	// the filesystem's root.
	//
	// fs.ValidPath cannot see this: every element of "link/secret" is legal,
	// and whether it leaves the tree depends on what "link" points at, which
	// is a runtime property of the filesystem and not of the string.
	PathEscaped = errs.Static(CodePathEscaped, "PATH_ESCAPED",
		"That path leaves the filesystem it was resolved against",
		"core/data/vfs: the name resolved outside the root — a symbolic link pointing away from the tree, or a traversal the kernel refused",
		0,
		77)

	// ReadFailed is returned when an open, stat or directory listing was
	// refused. The cause stays in the error chain, so a caller may still ask
	// errors.Is(err, fs.ErrNotExist) and get the answer io/fs would give.
	ReadFailed = errs.Static(CodeReadFailed, "READ_FAILED",
		"The filesystem could not read that path",
		"core/data/vfs: open, stat or readdir failed; the *fs.PathError cause is wrapped, not replaced, so errors.Is against fs.ErrNotExist still answers",
		0,
		74)

	// WriteFailed is returned when a create, write, mkdir or remove was
	// refused. Like [ReadFailed] it keeps the cause reachable.
	WriteFailed = errs.Static(CodeWriteFailed, "WRITE_FAILED",
		"The filesystem could not write that path",
		"core/data/vfs: create, write, mkdir or remove failed; the *fs.PathError cause is wrapped, not replaced",
		0,
		74)

	// PublishFailed is returned when an atomic publication did not complete.
	//
	// Its guarantee is the whole point of the domain and is asserted by a
	// test, not by this comment: on this error the bytes previously at the
	// name are unchanged and no temporary file survives. It is therefore
	// safe to retry, and safe to give up.
	PublishFailed = errs.Static(CodePublishFailed, "PUBLISH_FAILED",
		"The filesystem could not publish that file",
		"core/data/vfs: atomic publication aborted; the previous content is intact and the temporary was removed — the operation is safe to retry",
		0,
		74)

	// NotRegularFile is returned when a name exists and is not a regular
	// file. Writing it would replace a directory, a device or a socket, and
	// no caller has ever meant that by WriteFile.
	NotRegularFile = errs.Static(CodeNotRegularFile, "NOT_REGULAR_FILE",
		"That path already holds something other than a file",
		"core/data/vfs: the name resolves to a directory, device, socket or symlink; a write there would destroy an object of a different kind",
		0,
		65)

	// DirectoryNotEmpty is returned by Remove for a directory that still has
	// entries — POSIX ENOTEMPTY, made typed and made identical in both
	// implementations so a memory filesystem is a faithful double.
	DirectoryNotEmpty = errs.Static(CodeDirectoryNotEmpty, "DIRECTORY_NOT_EMPTY",
		"That directory still has entries in it",
		"core/data/vfs: Remove targets one file or one EMPTY directory; RemoveAll is the recursive call",
		0,
		65)

	// RootUnavailable is returned by NewOS when the root cannot be opened.
	//
	// It is a CONSTRUCTION-time refusal on purpose: a filesystem whose root
	// does not exist will fail every call it is ever given, and the useful
	// place to learn that is where the program is assembled, not on the first
	// request that happens to write something.
	RootUnavailable = errs.Static(CodeRootUnavailable, "ROOT_UNAVAILABLE",
		"The filesystem root could not be opened",
		"service/data/vfs: os.OpenRoot failed — the path is absent, is not a directory, or is not searchable by this process",
		0,
		78)

	// DirectorySyncFailed is returned when the rename succeeded and the
	// parent directory could not be flushed afterwards.
	//
	// It deliberately does NOT roll back. The rename has already happened, so
	// the new content is what every reader sees; undoing it would mean a
	// second non-atomic write to repair a durability problem, which is how a
	// good file gets replaced by a worse one. The caller is told exactly what
	// is true — published, not proven durable — and decides whether that is
	// acceptable for its data.
	DirectorySyncFailed = errs.Static(CodeDirectorySyncFailed, "DIRECTORY_SYNC_FAILED",
		"The file was published but the directory entry was not flushed",
		"service/data/vfs: fsync on the parent directory failed AFTER a successful rename; the content is visible and may not survive a power loss — deliberately not rolled back",
		0,
		74)
)