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

5.6 KiB

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.