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.
9.9 KiB
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:
asset:<type>:<name>
Examples:
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
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:

[Download the workbook](asset:xlsx:q1-budget)
Equivalent HTML examples are:
<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:
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:
/_/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
head_document_hashand every frozen dependency must be a lowercase, 64-character SHA-256.- Asset HEAD movement never changes existing Documents or Revisions.
- Revision save resolves all supported embedded Asset references or fails.
asset:is authoring identity;sha256:is delivery/storage identity.- A hash, Asset address, or Object UUID never grants access by itself.
- Cross-instance Asset resolution is forbidden without an explicit origin.
- 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 |