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.
248 lines
9.9 KiB
Markdown
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
|
|

|
|
[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 |
|