Files
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

248 lines
9.9 KiB
Markdown

# Asset Model
## 1. Purpose
An Asset is a mutable authoring identity whose HEAD points to one immutable
Document. It represents continuity of editing for binary or application-native
material such as an image, DrawIO scene, Excalidraw scene, spreadsheet, slide
deck, audio file, or video file.
An Asset is not:
- a Semantic Path or a Viewer URL;
- a Page Revision;
- immutable historical truth;
- an authorization capability;
- a remote-instance address.
The identity layers remain distinct:
| Identity | Meaning | Mutable |
| --- | --- | --- |
| `asset:<type>:<name>` | Editable Asset identity and current HEAD | yes |
| `sha256:<hash>` | Exact immutable Document bytes | no |
| `rev:<uuid>` | Immutable Page Revision that may refer to Documents | no |
| `path:/...` | Domain-scoped semantic reachability | yes |
## 2. Address and scope
The canonical local address is:
```text
asset:<type>:<name>
```
Examples:
```text
asset:image:knowledge-city-logo
asset:drawio:network-core
asset:xlsx:q1-budget
```
`type` is a projection/editor hint, not trusted MIME metadata. `name` is the
stable authoring name. The complete address is Domain-local, case-sensitive,
and unique by `(domain_uuid, address)` in the `assets` table.
Asset authoring identity is Domain-scoped so separate Domains may independently
own `asset:image:logo`. Immutable Documents remain content-addressed and may be
deduplicated across Domains. A local `asset:` address must never be resolved on
another instance. A remote resource requires an absolute HTTPS URL and an
explicit federation or external-object contract.
## 3. Stored state
The current additive schema is:
| Column | Meaning |
| --- | --- |
| `domain_uuid` | Owning Domain; part of the composite primary key |
| `address` | Canonical `asset:` identity; part of the composite primary key |
| `object_uuid` | Stable Object UUID with kind `asset` |
| `head_document_hash` | Current immutable Document SHA-256; empty means no HEAD |
| `created_at_ms` | Asset creation time |
| `content_type` | Mutable MIME metadata for the current HEAD |
| `filename` | Mutable filename metadata for the current HEAD |
| `size_bytes` | Current HEAD byte length |
| `updated_at_ms` | Last HEAD update time |
The bytes are stored in the Document Store under their SHA-256. The Asset row
contains no duplicate body. Filename, MIME type, and size describe the mutable
HEAD but do not participate in Document identity. Immutable delivery uses
bounded content detection when historical metadata is unavailable.
## 4. State transitions
### Create or update HEAD
```text
input bytes
-> calculate SHA-256
-> atomically persist immutable Document
-> compare with Asset HEAD
-> create Asset or move HEAD
```
Writing identical bytes with unchanged MIME and filename is a no-op. Correcting
MIME or filename records a metadata/history update without changing the hash.
Moving HEAD never mutates or overwrites the
old Document. The local CLI currently implements this operation through
`put LOCAL asset:<type>:<name>` and `edit asset:<type>:<name>`.
Asset HEAD updates do not create Page Revisions. An old Document remains live
when a Page Revision has frozen a reference to it; otherwise it may become
garbage after it is no longer an Asset HEAD. Garbage collection must treat
current Asset HEADs and `revision_document_refs` as roots.
### Read
`view`, `cat`, and `get` resolve the Asset HEAD at operation time. These are
mutable reads and must not be used for reproducible rendering or historical
export. Reproducible consumers use the resolved `sha256:` identity.
### Delete
Administrator HTTP deletion removes the mutable Asset identity only; it does
not delete a Document still
referenced by a Revision, another Asset HEAD, export, or retention root.
Automatic retention and physical Document collection policy remain pending.
## 5. Revision save and freezing
A saved Page Revision must never use a live `asset:` dependency as its rendered
payload. It does retain the authoring address as provenance so a later edit can
resolve the then-current HEAD. For HTML payloads, the server resolves `asset:`
values at save time:
| Authoring input | Stored Revision |
| --- | --- |
| `asset-ref="asset:…"` | Retain `asset-ref`; add/update `immutable-ref="sha256:<hash>"` |
| `immutable-ref="asset:…"` | Normalize to retained `asset-ref` plus fixed `immutable-ref` |
| `src="asset:…"` | Fixed `src="/_/obj/sha256:<hash>"` plus `data-pageswiki-asset-src="asset:…"` |
| `href="asset:…"` | Fixed `href` plus `data-pageswiki-asset-href` provenance |
| `poster="asset:…"` | Fixed `poster` plus `data-pageswiki-asset-poster` provenance |
| `data="asset:…"` | Fixed `data` plus `data-pageswiki-asset-data` provenance |
Only HTML attribute values are transformed. Explanatory prose, code blocks,
and non-HTML payloads are not rewritten. A missing Asset or an Asset without a
valid HEAD rejects the save with `ErrEmbeddedAssetUnavailable`; silently
leaving a mutable dependency is forbidden.
On a later save, the provenance address is resolved again and the fixed hash is
updated to the current Asset HEAD. Merely viewing an old Revision never resolves
the mutable address and therefore remains reproducible.
### Authoring forms
Markdown may use ordinary resource and link syntax because compilation produces
the supported HTML attributes:
```markdown
![Knowledge City logo](asset:image:knowledge-city-logo)
[Download the workbook](asset:xlsx:q1-budget)
```
Equivalent HTML examples are:
```html
<img src="asset:image:knowledge-city-logo" alt="Knowledge City logo">
<a href="asset:xlsx:q1-budget">Download the workbook</a>
<video poster="asset:image:intro-poster">
<source src="asset:video:intro">
</video>
<embedded-object
kind="drawio"
asset-ref="asset:drawio:network-core">
</embedded-object>
```
`asset:` is accepted only in `asset-ref`, legacy `immutable-ref`, `src`, `href`,
`poster`, and `data`. CSS `url()`, `srcset`, inline scripts, arbitrary
`data-*` attributes, and plain text are not resolvers. They require a future
typed parser rather than unsafe textual replacement.
### Access surfaces
| Surface | Address | Semantics |
| --- | --- | --- |
| CLI authoring | `asset:<type>:<name>` | Mutable HEAD read/write in selected Domain |
| Administrator HEAD URL | `/v/raw/asset:<type>:<name>` | Resolves current HEAD on every request; private and non-canonical |
| HTML/Markdown authoring | `asset:<type>:<name>` | Resolved only while saving a Revision |
| Stored semantic reference | `asset-ref="asset:…"` | Provenance for later editing; never rendered directly |
| Stored immutable reference | `sha256:<hash>` | Exact dependency identity |
| Browser delivery | `/_/obj/sha256:<hash>` | Authorized immutable GET/HEAD/Range |
| Management API | `/_/api/v1/assets?address=asset:…` | Domain-admin metadata and mutation surface |
The mutable Asset URL is an authenticated administrator authoring projection;
it is never emitted into published Pages or historical Revisions. It uses a
private revalidation cache policy and reports both the Asset address and
resolved HEAD hash in response headers. Published Pages always load the frozen
Document URL.
Every frozen dependency is recorded as:
```text
revision_document_refs(revision_uuid, document_hash)
```
This relation is part of Revision truth. It enables dependency inspection,
authorization, export, and garbage-collection reachability without reparsing
historical HTML.
## 6. Delivery and authorization
Immutable bytes are delivered through:
```text
/_/obj/sha256:<hash>
```
Knowing a hash is not authorization. Delivery succeeds only when the Document
is either the body of, or a frozen dependency of, a Revision whose Object has a
readable Path in the current Domain. The response exposes Object, Revision, and
Document identities in the PagesWiki metadata headers and supports ETag, HEAD,
and byte ranges.
The current HEAD of a Domain Asset may also be inspected through the same
immutable URL by a Domain or Campus administrator, even before any Revision has
frozen it. This administrative exception is for Asset management and does not
make the mutable HEAD anonymously readable. Once frozen into a Page Revision,
ordinary access follows that Page's read authorization.
The trusted local CLI bypasses HTTP Capability evaluation and is controlled by
database and filesystem permissions. The administrator HTTP API is restricted
to Domain or Campus administrators and requires an Asset HEAD ETag for updates
and deletion, or `If-None-Match: *` for creation. It records immutable HEAD
history with actor identity. Moving this endpoint into the typed policy matrix
and general audit outbox remains pending. Last-writer-wins HTTP updates are not
accepted.
## 7. Consistency rules
1. `head_document_hash` and every frozen dependency must be a lowercase,
64-character SHA-256.
2. Asset HEAD movement never changes existing Documents or Revisions.
3. Revision save resolves all supported embedded Asset references or fails.
4. `asset:` is authoring identity; `sha256:` is delivery/storage identity.
5. A hash, Asset address, or Object UUID never grants access by itself.
6. Cross-instance Asset resolution is forbidden without an explicit origin.
7. GC must preserve Documents reachable from Revisions, frozen references,
current Asset HEADs, and configured retention roots.
## 8. Implementation status
| Capability | Status |
| --- | --- |
| Local CLI create/update/read/edit | active |
| Content-addressed Document persistence | active |
| HTML save-time freezing | active |
| Revision-to-Document dependency records | active |
| Authorized immutable HTTP delivery | active |
| Asset owner excluded from Zombie Object GC | active |
| Asset MIME/filename/size metadata | active |
| Administrator HTTP CRUD and ETag/CAS updates | active |
| Initial Domain Asset management UI | active |
| History/restore and dependency detail UI | active |
| Delete/retention UI and audit trail | designed, not implemented |
| Remote/federated Asset synchronization | not designed as implicit lookup |