Files
pages/docs/design/path-mutation-integrity.md
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

95 lines
5.6 KiB
Markdown

# Recursive Path mutation integrity
Implemented 2026-09-14. This is a correctness boundary for semantic Path
rename, copy and unlink, not a change to the Address/URI identity model.
## Authorization and write protocol
1. Normalize absolute API Paths using the same whitespace and trailing-slash
rules as the Path store. Do not fold case, decode a second time, or interpret
`%`, `_` or `\` as patterns. Reject root mutations.
2. Obtain a server-side `PathMutationSnapshot` containing the normalized root,
Domain, recursive flag and exact ordered Path/Object bindings. Creation time
and primary-link metadata are included so a changed binding is not silently
overwritten.
3. Authorize each captured source Path and, for rename/copy, its computed
destination. The snapshot is an opaque in-process value, never JSON supplied
by a client. Permission failures disclose neither descendants nor preview
metadata. Preview results are taken from this same checked snapshot.
4. Begin a store transaction, enumerate with the identical predicate and compare
the whole binding set with the snapshot **before the first write**. Added,
removed or rebound descendants, and wrong Domain/root/recursive scopes,
reject the operation with HTTP 409. The client must start a fresh operation
to obtain fresh authorization; there is no unchecked automatic retry.
5. Keep revalidation and all writes inside the same SQLite transaction. A writer
that commits after revalidation invalidates a WAL read snapshot: SQLite
rejects its upgrade with `SQLITE_BUSY_SNAPSHOT`, also translated to 409.
After the first write the transaction holds SQLite's write lock. This is not
an assertion of equivalent isolation for a future database backend.
For multi-selection unlink, validate **all** selected scopes before removing
any binding. Overlapping scopes are deduplicated inside the transaction. No
Object, Revision or Document is deleted by unlink. Rename retains identity and
updates filename Revision metadata and City boundaries transactionally; copy
allocates independent Object/Revision identities while reusing content hashes.
Local trusted code and the administrative CLI can retain the existing unchecked
`RenamePathsInDomain` / `CopyPathsInDomain` entry points; these still use the
literal bounded enumerator and an atomic transaction. HTTP mutation handlers use
the `Checked` methods exclusively.
## Object purge is a separate authority boundary
`object/delete` remains a purge: it removes the Object, its Revisions and all
bindings, not just the current Path. Its HTTP handler now requires POST and a
4 KiB JSON body limit. A store-issued `ObjectDeletionSnapshot` enumerates **all**
bindings across Domains and rejects the request if any binding belongs to a
different Domain. Every local Path needs a delete grant; one allowed alias or
an Object-only grant cannot authorize deleting ungranted aliases. Unknown and
unbound Objects fail closed even for a Domain administrator, because the current
schema cannot prove Domain ownership without a binding.
The scoped purge revalidates the exact complete binding set in the purge
transaction. A newly added local/foreign alias, removal or rebinding invalidates
the operation with HTTP 409. Paths, tags, Revisions and the Object are deleted
atomically; immutable content-addressed Documents remain for separate retention/
garbage-collection policy. The old global `DeleteObject` store entry point is
retained for trusted local administrative callers, not HTTP. Tests cover mixed
local grants, shared/unknown/unbound Objects, late alias changes, rollback after
Path deletions and successful full purge while retaining the immutable Document.
## Bounded, literal enumeration
The Domain/Path index is queried using separate exact and descendant range arms:
`path = root` and `root + '/' <= path < root + '0'` with binary collation.
This preserves storage case sensitivity and treats SQL wildcard characters
literally. A lexical index order places parents before their descendants without
a full length sort. The root listing special case excludes the exact root from
the descendant arm to avoid duplicates. A query-plan regression checks index
range use and absence of a temporary sort.
One scope/mutation is limited to 10,000 bindings; the API additionally limits
unlink selections to 1,000 roots and caps cumulative authorization work at
10,000 captured bindings. Oversized operations return HTTP 413, never a partial
success. Split large trees into smaller independently authorized operations.
All mutation endpoints and rename previews require POST and cap JSON bodies at
1 MiB where applicable.
## Verification and remaining boundaries
Regression tests cover literal percent/underscore/backslash and case-different
neighbors, normalization, denied descendants and destinations, preview leakage,
second-connection additions/removals/rebinding between authorization and write,
the post-revalidation WAL race, wrong/forged snapshot scope, overlapping deletes,
size caps, index plans and rollback after an injected second write (including
copied Object/Revision rows).
This slice does not make authorization-policy updates and Path writes share one
transaction. Revocation between the final grant check and the write still needs
a policy-version precondition or a transaction-aware authorization service.
Copying an Object with a very long Revision history can also exceed an acceptable
interactive duration even with the binding cap; a durable authorized background
operation is a follow-up. Cross-Domain or unbound Object purge requires a future
explicit global administrative ownership/retention policy; it is not inferred
from a Domain-scoped request.