Files
pages/docs/design/asset-model.md
T
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

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:

![Knowledge City logo](asset:image:knowledge-city-logo)
[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

  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