Independent renderer: HTTP v1, contract v8
The host authorizes the source revisions and supplies them to SevenMark. Before delivery, the host rechecks read access to the root and each used dependency. SevenMark has no database, object-storage, session, or Cedar credentials.
HTTP fields use snake_case. Namespace values are document, file, category, template, user, and site. The routes use /v1; the current payload contract is contract_version: 8. All source uses the current native grammar.
Build version
Every JSON response from /v1/analyze, /v1/analyze-bundle and /v1/render contains renderer_version. Every HTTP response, including health and error responses, has the X-SevenMark-Version header with the same value.
- A release image build sets the
SEVENMARK_BUILD_VERSIONbuild argument to its image tag, for example10.0.1. The value is fixed at compile time. - When the build argument is absent or empty, the value is the Cargo package version.
- The value must be a valid HTTP header value. Otherwise the build fails.
renderer_version identifies the build. contract_version identifies the wire contract. The host checks the expected renderer and keeps cached output from different builds apart.
Resource profile and reports
GET /v1/capabilities returns contract_version, renderer_version, profile_id, limits, and fixed_limits. Each typed limit has limit, unit, scope, configurable, and ceiling. Values use UTF-8 bytes, logical storage bytes, work units, counts, depths, milliseconds, tokens, or pixels. Logical storage is cumulative accounting; it is not process resident memory.
The profile ID is lowercase BLAKE3 over canonical public settings and build identity. It contains no credentials. The host pins one profile before cache lookup. The host sends that ID in X-SevenMark-Profile-Id on each POST. A supplied stale or duplicate profile header fails with 409 profile_mismatch before the server reads the body. Reload both services after a profile change.
Fixed CSS policy limits apply to each CSS block: css_input_bytes and css_output_bytes are 1,048,576 bytes; css_nesting_depth is 32 and css_rule_depth is 128. Selector-guard expansion charges the existing output limit before allocation. These values come from the sanitizer's actual defaults. Dropping a CSS block is recoverable: the renderer emits a warning and preserves safe document output. It does not report a request-wide budget failure.
Every successful processing response includes resource_report. A budget failure includes the same field next to error and request_id. A report has profile_id, renderer_version, source_hash, phase, status, metrics, and exceeded. Each metric has {limit, used, remaining}. Unmeasured usage and remaining values are null. The phase is admission, analyze, analyze_bundle, or render. Analyze reports are complete only when evaluation_complete is true; pending inputs and fact discovery are incomplete. Render success is complete. A budget error is exceeded and names its metric. Other failed processing is unavailable.
Root-source bytes, largest-source bytes, source-bundle bytes, parser logical storage, evaluation work, expansion, and accepted parser, expression, and evaluation depth peaks are measured when available. Expression depth includes both parser recursion and constructed expression height. The parser and evaluator share their request budgets across the root and approved included revisions. Separate preflight requests have separate budgets. Dependencies report the largest collection checked by a dependency guard, including authored include candidates. References report the largest collection size observed at this operation's existing reference guards, including supplied decision collections. Independent guards use a maximum, while a shared guard counts its combined collection. Prior measurements survive a bounded helper failure; they do not describe the full rejected collection. Remaining capacity is specific to the reported operation, not a guarantee that another preflight phase will admit additional references. Unavailable and missing references have equivalent public reports.
Rejected reservations do not increase accepted usage. An exceeded report can therefore have positive remaining work or storage. A timeout does not invent operation usage. request_timeout_ms measures the original request from admission through queueing, body reading, and processing, before response serialization. Cached reports retain that original time. Optional canonical projection reserves possible elapsed-counter decimal-width growth before choosing its HTML. Final response-byte admission remains exact. A host can measure the current preview round trip separately. Native response bytes stay null because the report is itself part of that response. The host can populate response_bytes from the original validated successful body length. It must enforce both byte limits and must not count the enriched JSON or a budget-error envelope. Internal request bytes stay null because that request can contain private approval metadata. Admission failures have no source hash when the body has not produced an approved source. Local editor storage and token usage come from the LSP, not from a native renderer request.
Operators configure parser storage with SEVENMARK_MAX_AST_BYTES, independently of SEVENMARK_MAX_EXPANSION_BYTES. Evaluation depth is configurable from 1 to 128 with SEVENMARK_MAX_EVAL_DEPTH. Parser nesting (16) and expression depth (128) remain fixed structural safety constraints. Fixed title, URL, path, and media policies are listed separately. Media policy includes 16 rendition candidates, 64 variant-key bytes, 4096 layout-width pixels, and 128 gutter pixels. Settings and reports use safe JavaScript integers. The portable source ceiling is 268,435,455 bytes (256 MiB minus one). This covers the existing UTF-16 index allocation as well as parser reservations on wasm32. The default remains 16 MiB. Operators can select 32, 64, or 128 MiB within the public ceiling. These bounds do not guarantee process resident memory. Local-editor storage and token ceilings also fit their WASM allocations.
The host supplies LSP initialization admission as initializationOptions.admission with optional max_source_bytes, max_ast_bytes, and max_semantic_tokens. The accepted complete profile is returned at capabilities.experimental.sevenmark.admission. Omitted values use producer defaults. Invalid supplied values fail initialization; they do not silently restore a hidden source cap. Browser parser and formatter exports also provide explicit *_with_limits entrypoints.
Analyze host source
POST /v1/analyze accepts {region_id,namespace,title,content,declaration_only?,evaluation_context?}. It returns the source metadata, evaluation_complete, and evaluation_context_required, with optional parameters, pending_inputs, reference_candidates, fact_requests, and used_facts. The source metadata is {contract_version,renderer_version,source_hash,includes,links,relations,redirect,user_mentions,excerpt,preview_image,external_links}. The response has contract_version: 8.
The analyzer evaluates local definitions and conditionals. It does not load included sources or check destination access. source_hash is lowercase BLAKE3 hex over the exact UTF-8 source bytes.
Set declaration_only: true when building a conservative dependency closure. This mode parses the source and validates input declarations, then returns declarations, required inputs and static document/URL candidates without executing defaults or the body. It reports evaluation_complete: false and evaluation_context_required: false, with empty active graphs, fact requests and used facts. An inactive template cannot trigger arithmetic errors or a clock/statistics request merely because its revision belongs to the closure. Malformed syntax still fails. The flag defaults to false and is omitted from ordinary requests.
includescontains unique direct include references.linkscontains the other unique direct references, including File uses, category membership, and redirect targets.relationscontains unique{target,kind}entries. The kinds arewiki_link,category_membership,include,file_use, andredirect_target.redirectcontains the first active host redirect reference, or null.user_mentionscontains unique canonical user UUIDs, including UUID v7.
The analyzer returns these sets in a stable order. A link to a category page is separate from category membership. Direct relations do not inherit links or categories from included sources. The host can use them for backlinks, category membership, and include usage.
user_mentions includes only active user mentions in the host source. Code, literal text, comments, editor notes, and inactive branches do not add targets. Analysis does not attribute included mentions to the host author. The host owns account eligibility, authorization, deduplication, and notification delivery.
Reference sets, relation entries, user mentions, and external links share max_references. Duplicate spellings of one user UUID consume one mention slot. When the lists need more than max_references slots, the request fails with 413 budget_exceeded. SevenMark does not return a truncated list.
External links
external_links contains {url} entries for every absolute external URL that the active host source can put into rendered HTML. The host can use the list to check link destinations, for example against a domain blocklist, without parsing markup. SevenMark computes the list after local definitions and conditionals. It does not load includes.
The list contains these URLs:
- A link target, for example
[[https://example.com/a | label]]. - A File media
#urlclick target, for example[[#url="https://example.com" || file:Logo.png]]. - The iframe source of external media. SevenMark builds it from fixed provider origins, for example
[[#youtube #id="abc"]]giveshttps://www.youtube.com/embed/abc. - An include argument whose whole text is an absolute URL, for example
{{{#include Card #homepage="https://example.com"}}}. Include arguments are host source, and a template can put an argument into a#urlparameter.
The renderer and the analyzer use one URL rule from sevenmark_spec. A URL is the trimmed authored text. It must start with http:// or https:// (ASCII case does not matter), hold at most 2048 UTF-8 bytes, and parse as a WHATWG URL with a host. The renderer emits no link for any other value, so the analyzer does not report it. A File media #url must also be a valid #url parameter value. A media #anchor fragment is not part of the entry.
Each entry is unique by exact text and appears once, at its first occurrence in document order. The analyzer does not normalize case, ports, or encoding. The host normalizes entries before it compares them.
The list does not contain these values:
- URLs in inactive branches, code, inline code, literal blocks, comments, editor notes, definitions, TeX, and CSS blocks.
- URLs in included sources. The host analyzes each included source separately.
- Prose text that contains a URL. A link needs link syntax.
- An include argument that holds a URL inside other text, or markup such as
[[https://...]]. Argument values are plain text, and a template cannot extract a URL from them or render their markup as a link. - A URL that a template assembles from more than one fragment, for example
#url="https://[var(host)]/path"inside the template. This limit is part of the contract.
Link-preview fields
excerpt and preview_image let a host show a link preview without a render request. SevenMark computes both from the active host source only, after local definitions and conditionals. It does not load or expand includes. Text and images from an included source, including a source that the host hides, cannot appear in these fields.
excerpt is plain text from the first prose paragraph. Without a prose paragraph, it is the text of the first list:
- A paragraph is a run of inline content. A blank line or a non-prose block ends it. The first paragraph with visible text is the excerpt.
- Headings, tables, lists, folds, quotes, code blocks, literal blocks, horizontal lines, block TeX, block-level includes and external media end a paragraph and add no text.
- An include or template call is block-level when its source lines contain nothing else except whitespace. This applies to a multi-line
{{{#include ...}}}too. - Any other include is inline. An inline include adds no text, and the paragraph continues. The authored whitespace around the include stays in effect: a space joins the text, one line break joins the next line, and a blank line ends the paragraph. For example,
대한민국의 {{{#include 틀}}} 수도는 서울이다gives대한민국의 수도는 서울이다.A{{{#include 틀}}}BgivesAB. - Include targets and include arguments never add text.
- Footnotes, File media, categories, definitions, CSS blocks, comments, editor notes, inline TeX, mentions, anchors, unresolved variables, time macros and parse errors add no text. A redirect document has an empty excerpt.
- Text styles, styled spans and ruby base text keep their text. A link keeps its display text. An unlabeled link keeps its authored named title, URL or anchor. An unlabeled UUID link adds no text.
- A local
#letvalue supplies typed expressions and conditions. - Each whitespace run becomes one space. Control characters are removed. The text has no leading or trailing whitespace.
- The excerpt holds at most 200 Unicode scalar values. A cut never splits an extended grapheme cluster. A cut excerpt drops trailing whitespace and ends with
…, so it holds at most 201 scalar values.
When the source has no prose paragraph, the excerpt uses a list:
- The list is the first list, in document order, whose top-level items have visible text. The search uses the same path as the paragraph search, so a list inside a table, fold or quote is not used.
- Each top-level item gives the text of its first paragraph, with the rules above. A nested list ends that text, so nested items add no text. Top-level items summarize a disambiguation-style page and keep the excerpt short.
- Items without visible text are left out. The other item texts are joined with a space,
·(U+00B7), and a space. - The same 200-value bound applies. A cut inside or directly after a separator moves to the start of that separator, so the excerpt never ends with
·. - Any prose paragraph wins over a list, also a paragraph after the list.
The excerpt is empty when the source has no prose paragraph and no list item with visible text.
preview_image is {target,alt} or null:
targetis the first valid File media reference ([[file:...]]) in document order. It is aDocumentReferenceand is also afile_userelation target.- The search skips includes and their arguments, inactive branches, code, literal blocks, comments, editor notes, definitions, TeX and CSS blocks. It searches inside tables, styled spans and other containers. A File description link (
[[:file:...]]) is not an image. altis the display text after|, with the same plain-text rules and length bound asexcerpt. It is null when the source gives no display text.
SevenMark does not check that the File exists, is an image or is readable. The host resolves and authorizes target for each reader.
Reference and decision types
A DocumentReference has one of two forms:
{ "kind": "id", "document_id": "019a0000-0000-7000-8000-000000000001" }{
"kind": "named",
"namespace": "document",
"parent_document_id": null,
"title": "Title"
}A named root reference has a null parent. A named child reference has a nonnil parent UUID. Titles allow at most 200 Unicode scalar values and 800 UTF-8 bytes. The host owns title normalization and lookup. See document reference syntax.
The host supplies an allowed decision with the resolved UUID, actual namespace, and current readable local title:
{
"target": {
"kind": "named",
"namespace": "template",
"parent_document_id": null,
"title": "Card"
},
"state": {
"kind": "allowed",
"document_id": "019a0000-0000-7000-8000-000000000002",
"namespace": "template",
"title": "Current Card"
}
}The host can supply missing when a target is absent in an authorized lookup scope. It supplies unavailable when the target or lookup scope is unreadable, or when it cannot disclose absence. Neither state carries a resolved identity, title, or path:
{
"target": {
"kind": "named",
"namespace": "document",
"parent_document_id": null,
"title": "Authored title"
},
"state": { "kind": "missing" }
}{
"target": {
"kind": "id",
"document_id": "019a0000-0000-7000-8000-000000000003"
},
"state": { "kind": "unavailable" }
}These internal decisions have identical public presentation. Ordinary wiki links keep only authored content and can use an optional host name lookup. Neither state approves media, includes, redirects, or link previews. See Unresolved links.
The host must authorize the namespace and any explicit parent before it approves a named lookup as missing. An unreadable parent does not become an absent child decision.
An ID reference cannot bind to a different UUID. A File media occurrence requires an actual File document. Category membership requires an actual Category document. A namespace mismatch makes that occurrence unavailable or invalid. An ordinary allowed link to the same UUID can remain navigable.
An allowed decision can also contain path_segments, the current titles from the root document to the target. The last segment equals title:
{
"kind": "allowed",
"document_id": "019a0000-0000-7000-8000-000000000002",
"namespace": "document",
"title": "음반",
"path_segments": ["AC/DC", "음반"]
}The field is optional. See Title path links.
Approved source bundle
POST /v1/render accepts this request shape:
{
"contract_version": 8,
"presentation": {"instance_id":"preview", "document_anchors":"instance"},
"region_id": "019a0000-0000-7000-8000-000000000001",
"root": {
"document_id": null,
"revision_id": null,
"parent_document_id": null,
"namespace": "document",
"title": "Preview",
"content": "Hello",
"source_hash": "<64 lowercase BLAKE3 hex characters>"
},
"dependencies": [],
"links": [],
"document_path_base": "/ko/w/",
"file_document_path_base": "/ko/file/",
"media": [],
"media_layout": {
"default_content_width_px": 1024,
"wide_content_width_px": 1096,
"horizontal_gutter_px": 16
}
}document_path_base and file_document_path_base are optional as a pair. See Title path links. source_range is optional and applies only to rendering. See Selected source preview.
media contains one {document_id,media} item for each public File rendition that the host approved. SevenMark checks every candidate URL against the configured SEVENMARK_MEDIA_PUBLIC_ORIGIN. The origin must be HTTPS and cannot contain a path, query, or fragment. A missing media item remains a private File reference. The HTML keeps its placeholder and same-origin host link. SevenMark never fetches or proxies media bytes.
The verified source metadata.format is one of jpeg, png, apng, gif, webp, avif, heic, bmp, tiff, jxl, svg, ico, qoi or pnm. This set matches Hirune Image 0.3.0. The host preserves the explicit animated fact, including an animation with one display frame. Every public candidate must still be sanitized image/webp; source SVG is never a candidate URL.
The host can approve a public File rendition for an ordinary File link as well as for an embed. SevenMark validates every supplied media item, including its identity, candidate geometry, and public URL. It only attaches an item to a File media occurrence that uses that document. A valid item that no media occurrence uses has no effect on the rendered output.
media_layout bounds the default and wide CSS content widths. SevenMark emits standard and wide sizes profiles for every media occurrence. It accounts for the authored pixel width when present, then caps the image to the selected content width and horizontal viewport gutters. Hosts can switch the image's sizes attribute when the viewer changes width mode.
For a preview, both root identity fields are null. Otherwise, document_id and revision_id must both be nonnil UUIDs. parent_document_id records the current source context; it is null for a root document.
Each dependency has the same source fields and requires document and revision UUIDs. SevenMark verifies every source hash. Each direct include requires an explicit decision, including allowed includes.
An allowed include selects a dependency by its approved UUID and exact revision. The decision's current namespace and title must match the dependency. The source namespace, title, and parent can differ from an authored named alias. Several aliases can select one source snapshot. Duplicate dependency UUIDs are invalid.
SevenMark does not find sources by title, namespace, parent, or alias. Includes compose transitively from the approved source closure. Each nested call uses the same evaluation budget and its own declared input scope.
Selected source preview
POST /v1/render accepts optional source_range: {start, end}. Both values are UTF-8 byte offsets in the complete root.content. The interval is half-open, and both offsets must fall on character boundaries. For example:
{ "source_range": { "start": 120, "end": 360 } }Omit the field to render the complete document. For a selected preview, keep root.content, its source_hash, dependencies, evaluation context, and link decisions for the complete candidate. The range changes presentation only. It does not reduce source, hash, budget, or approval checks and grants no authority.
SevenMark evaluates and transforms the complete candidate before selecting HTML. Heading paths, footnote numbers, named-footnote identities, and footnote flush state retain their full-document meaning. The returned HTML and outline contain the selected content. Referenced footnote definitions remain available when authored outside the range; their backlinks point to a visible selected reference. Global document CSS still applies. An include is selected by its outer host call, rather than dependency-local byte offsets. Included headings retain their source identity.
sections remains the complete host section-range metadata. Used dependencies, diagnostics, redirects, and used facts describe the complete candidate. An empty range retains the declared body root with no selected content and an empty outline. Analysis always covers the complete candidate. /v1/analyze-bundle rejects source_range and presentation; both fields belong only to rendering.
A range can clip source-backed plain text. It must not split a heading, code block, container, or generated content. Extra surrounding whitespace is valid. Invalid bounds, invalid UTF-8 boundaries, and a split indivisible node return HTTP 400 with code invalid_source_range and message The selected source range is invalid or splits an indivisible syntax node. For example, an edit that opens a block and closes it in a later unselected section returns this error instead of exposing that section. Validation occurs after complete transform and approval checks. Include source_range in the cache identity when caching selected HTML.
Host procedure
- Call
POST /v1/analyzefor the authorized host source. - Authorize each direct include.
- Add the exact approved source revision for each allowed include.
- Call
POST /v1/analyze-bundlewith that bundle and exactly the include decisions. - Resolve each returned reference under current host authority.
- Call
POST /v1/renderwith the bundle, complete decision set and checked presentation. - Recheck root and used-dependency read access before delivery.
/v1/analyze-bundle accepts the approved bundle fields. It rejects the render-only presentation and source_range fields. It returns {contract_version,renderer_version,source_hash,links,dependencies}. Its links are the remaining references after approved include expansion, argument substitution, and conditionals. This phase does not look up ordinary destinations.
The final render decision set is the union of the include decisions and the expanded reference decisions. Duplicate, missing, extra, or conflicting decisions are invalid. SevenMark has no global lookup or shared source cache.
Body presentation
Rendering requires presentation.instance_id: 1–64 ASCII letters, digits, underscores or hyphens. The host selects a stable identifier unique on the page. Use document_anchors: "canonical" only for the main article; use "instance" for previews, messages and other bodies. Render cache keys include presentation. Analysis cache keys do not include it.
Core emits one ordinary HTML .sevenmark root with data-sm-scope and data-sm-document-anchors, including empty selected previews. The response echoes the exact presentation. The runtime adopts this root and verifies its identity. The HTML library returns editor-note fragments with deterministic child roots <instance_id>.note-N. The HTTP response does not expose editor notes. The host must isolate application CSS from every body, including lazy styles. The host supplies the scoped body and its matching echoed presentation.
Named anchors publish sm-a-<lowercase UTF-8 hex>. Main outline headings keep s-1.2. Secondary bodies use sm-i-<hex(instance_id)>-<canonical ID> for both IDs and local links. Footnotes always use the instance namespace. Nested include islands use internal ID namespaces and share their actual containing CSS root. Cross-document fragments use canonical IDs. External URL fragments are unchanged. Footnotes share one body collection across include islands, so their references and deferred list entries keep the containing body's namespace in both modes. The host keeps the placement identifier stable; copied emitted footnote URLs retain that identity. A logical wiki fragment such as #fn1 still names an authored anchor, not numbered footnote 1. See the light DOM contract.
Render response
The response is {contract_version,renderer_version,presentation,html,outline,diagnostics,dependencies,sections,redirect}.
dependenciescontains sorted, unique{document_id,revision_id,source_hash}entries for the sources actually used.diagnosticsuses UTF-8 byte ranges. Its source ishost,dependencywith document/revision UUIDs, orsynthesized.- CSS selector/admission warnings use
SM_CSS_SELECTOR_REJECTED,SM_CSS_SYNTAX_OMITTED,SM_CSS_INPUT_LIMIT,SM_CSS_OUTPUT_LIMITorSM_CSS_NESTING_LIMIT. They are collected during the existing sanitizer pass. Included CSS reports a coarse host include-call range with sourcehost; this is not the dependency's physical CSS range. Repeated discovery of the same block deduplicates each warning code and host range. Existing static dependency diagnostics retain their physical dependency source and host projection. sectionscontains ranges in the root source.outlinecontains{id,path,level,title}entries.
Allowed links use /documents/<UUID> and data-sm-reference with a serialized ID reference. Without an authored label, the renderer uses the current allowed local title. A host can replace the UUID route with a title path; see Title path links.
Unresolved links
missing and unavailable ordinary wiki links have identical public output. They render as sm-link-invalid spans with authored display content. Without display content, the label uses the authored local title or UUID. Heading outline text follows the same rule. The unresolved wrapper contains no server-resolved title, path, document identity, href, data-sm-reference, or data-sm-media-reference.
An unresolved named link carries data-sm-unresolved-reference, an escaped JSON copy of its authored {kind:"named",namespace,parent_document_id,title}. data-sm-section holds an optional authored fragment. A host can supply the runtime's navigation.unresolvedDocumentHref({reference,section?}) callback to open its normal name lookup route. Preserve the exact namespace and parent scope and recheck access at that destination. Null, a blank string, an omitted callback, or an unsafe URL leaves the label without navigation. The runtime accepts only HTTP or HTTPS destinations and does not restore another route when the callback declines.
This authored lookup metadata does not disclose existence or grant a resolved UUID, hover preview, media request, or include. An unresolved UUID can remain in the authored label but has no unresolved name lookup route. Nested links do not get a second route. Separately authorized child content retains its own access rules. The host owns any document creation flow.
Missing and unavailable includes have the same unavailable status and expose no target label. Missing and unavailable File media emit no hydration identity. An unavailable explicit media #link does not gain an authored lookup route. Redirects remain null unless the host allowed their destination.
Title path links
The host can supply the current title path for each allowed destination with public ancestors. These paths are optional navigation hints. The renderer measures the complete UUID response. It admits canonical hrefs only when a conservative growth check fits the existing output-byte limit. Otherwise it retains the complete UUID result. This admission adds no title, path or URL limit. The renderer projects the hint set as one unit. A host that omits title path fields keeps UUID routes.
RenderRequest.document_path_baseis the root-relative base for non-File title paths, for example/ko/w/for the Korean edition.RenderRequest.file_document_path_baseis the root-relative base for File title paths, for example/ko/file/.- Both bases must be present or both absent, including requests with no title paths.
AnalyzeBundleRequestuses the same paired-presence rule. Each base starts and ends with/, does not start with//, holds at most 256 bytes, and contains only ASCII letters, digits,-,.,_,~and/. The existingdocument_path_base_bytesfixed limit applies separately to each base. Their serialized fields count toward the existing request-byte limit. LinkState.allowed.path_segmentsholds 1 to 33 titles from the root document to the target. Each segment follows the title limits, and the last segment equalstitle. A decision withpath_segmentsrequires both bases.- The host omits
path_segmentsfor a target without a public title path, for example a target under a hidden parent. That link keeps/documents/<UUID>.
File links use file_document_path_base followed by the encoded title path. All other links use document_path_base. Template, Category, User and Site links add template:, category:, user: or site: before the first encoded title. Document links normally have no prefix. If their first local title starts with one of document:, file:, template:, category:, user: or site:, they add document: first. These reserved prefixes are lowercase and case-sensitive. Template:Foo remains an ordinary Document title. The prefix is interpreted once, not recursively.
Site's host-configured display name does not enter this protocol. A Site title Policy uses /ko/w/site:Policy; a literal Document title site:Policy uses /ko/w/document:site%3APolicy. Both keep their approved UUID identities.
The renderer percent-encodes each local title and joins titles with /. A / inside a title becomes %2F; :, % and # become %3A, %25 and %23. Non-ASCII text uses UTF-8 percent-encoding. A host splits the raw path before it decodes each segment once, then interprets the first segment's prefix. Raw and percent-encoded colons have the same meaning after decoding. An authored anchor follows as a fragment.
For example, the decision above with an authored #Track list anchor gives /ko/w/AC%2FDC/%EC%9D%8C%EB%B0%98#sm-a-547261636b206c697374. A Template named Card gives /ko/w/template:Card; a File named Logo.png gives /ko/file/Logo.png. A Document whose local title is template:Foo gives /ko/w/document:template%3AFoo. A Document child named template:Foo under Parent gives /ko/w/Parent/template%3AFoo; only the first segment can select a namespace. URLs do not change the stored title, parent scope or UUID.
The rule applies to ordinary links, the default File media link, and a File media #link destination. data-sm-reference still contains the ID reference with the UUID, so browser runtimes and host adapters keep the stable identity. Projected anchors also carry the boolean data-sm-canonical marker. The runtime passes the approved href and canonical fragment to the host without another URL payload. UUID destinations use the host route builder. Invalid title path input returns 400 invalid_input.
The host owns these duties:
- Compute
path_segmentsfrom current titles in the same snapshot as the decision, and withhold it for a target whose ancestors are not public. - Bind cached HTML to the approved path snapshot,
document_path_baseandfile_document_path_base. A compact version witness can identify that snapshot without repeating paths in the cache key. Revalidate target access, ancestor titles, parent relationships and public visibility before reuse. A changed path or authority requires a new render.
Allowed Files emit placeholders with data-sm-media-reference. The browser runtime calls the host's resolveMedia adapter. That adapter rechecks access and readiness, then supplies a cookie-protected same-origin URL for converted image bytes. An unavailable File emits no hydration identity. An allowed image with an unavailable explicit link destination remains an image without that link.
Redirects
AnalyzeResponse.redirect preserves the authored DocumentReference. RenderResponse.redirect contains a resolved ID reference only when the host allowed the destination. An unavailable redirect returns null.
Both refer to the first active redirect in host source after local control flow. A redirect inside included source does not redirect the host document. The host uses this metadata to check access, bound chains, reject cycles, and decide whether to navigate. History, preview, and discussion views can display a render response without following its redirect.
Limits and lifecycle
| Limit | Default |
|---|---|
| Request body | 256 MiB |
| Each source | 16 MiB |
| Source bundle | 64 MiB |
| Dependencies | 1024 |
| References | 2048 |
| Parser AST, expanded content and values | 128 MiB |
| Typed evaluation work | 10,000,000 units |
| Complete JSON response | 256 MiB |
| Processing concurrency | Available CPU parallelism |
| Admitted HTTP requests | 64 |
| Elapsed request time | 60 seconds |
See .envs/.example/server.env for configuration. Expansion checks account for variable growth and repeated includes. SEVENMARK_CPU_CONCURRENCY overrides the processing concurrency when a deployment has an explicit CPU quota.
Requests wait for an HTTP slot and then a processing slot. A full slot pool does not reject the request. The service reads and decodes the body only after it owns a processing slot. That same slot stays with the native spawn_blocking job until it finishes. Waiting requests do not accumulate decoded source bundles. For example, with 64 HTTP slots and two processing slots, two requests can read or process their bodies while the other admitted requests wait without body reads. This bounds concurrent processing; it is not a global bound on native memory.
One HTTP deadline includes both slot waits, body reads, decoding, and rendering. When this deadline expires, the service returns 408. It does not start a new deadline after either wait.
The source budget accepts at least 4,000,000 Unicode scalar values, including four-byte characters. The HTTP budget also covers escaped JSON for that source. Bundle, expansion and response budgets are separate conditions. A source within its own byte budget can still exceed another budget after markup expansion. Response counting does not allocate a second JSON buffer. It checks acceptance after rendering and does not measure or cap peak native memory.
| Condition | HTTP status |
|---|---|
| Service shutting down | 503 |
| Budget exceeded | 413 |
| Invalid request envelope or approval provenance | 400 |
Invalid selected source range (invalid_source_range) | 400 |
| Request timeout | 408 |
A timeout ends the waiting response. It does not stop a running blocking task. That task holds its CPU permit until it finishes.
GET /health/live returns 204. GET /health/ready returns 204 while the service accepts work and 503 after shutdown starts. Health routes bypass admission. Shutdown first withdraws readiness, then drains HTTP responses and native work. It wakes requests still waiting for an HTTP slot with 503. Requests that already hold an HTTP slot continue within their existing deadline. Configure the process termination grace period to cover that deadline and any native work still running.
Responses include Cache-Control: no-store and a UUID X-Request-ID. The service preserves one valid nonnil request ID. It replaces invalid or duplicate IDs. Errors use {error:{code,message},request_id} with fixed codes and messages. Source text, dependency names, and parser diagnostics do not enter error or tracing output. Deploy the service inside the host's network boundary; the host supplies the authorization decisions.
Live display macros
Display macros emit inert, cacheable HTML placeholders. They do not need evaluation_context, request approved calculation facts, or change a template branch. The browser fills them after the host mounts or updates the body runtime.
[now], [date], [datetime], [age(...)], and [dday(...)] use one browser instant for each mount, update, or live-value refresh. The runtime formats them with its locale and optional timeZone; the default is the viewer's browser time zone. Age and D-day use calendar dates in that display zone. Their HTML keeps the authored target date, not the current date or clock value.
The host can call await handle.refreshLiveValues() to update clocks and statistics without remounting content. This preserves map canvases and fold state. Live refresh has separate cancellation, so an obsolete statistic response cannot overwrite a newer refresh. The runtime starts no automatic timers.
Statistic displays use a host-owned batch callback:
| Source | Display request |
|---|---|
[stat(document_count)] or [pagecount] | {"kind":"document_count","namespace":null} |
[stat(document_count, document)] or [pagecount(document)] | {"kind":"document_count","namespace":"document"} |
[stat(user_count)] | {"kind":"registered_user_count"} |
[stat(active_user_count, yesterday)] | {"kind":"active_user_count","period":"yesterday"} |
[stat(documents_created, yesterday, document)] | {"kind":"documents_created","period":"yesterday","namespace":"document"} |
[stat(active_user_count, 2026-11-01)] | {"kind":"active_user_count","period":{"date":"2026-11-01"}} |
[stat(documents_created, 2026-11-01, 2026-12-01, template)] | {"kind":"documents_created","period":{"range":{"from":"2026-11-01","until":"2026-12-01"}},"namespace":"template"} |
Periods are today, yesterday, {date:"YYYY-MM-DD"} or {range:{from:"YYYY-MM-DD",until:"YYYY-MM-DD"}}. Dates are valid Gregorian dates in years 0001 through 9999. A range includes its start and excludes its strictly later end. The runtime rejects unknown fields and invalid dates before calling the host. The host enforces its configurable maximum period. Optional namespaces serialize as null when omitted. V7 resolves a symbolic period at lookup time using its current site calendar and counting policy. The cached HTML does not contain yesterday's absolute dates. This site-calendar policy is separate from the viewer's display time zone.
The UI splits expanded requests into sequential HTTP batches of at most 32. Each batch has its own observation time. It validates each batch length and count before joining results, and cancels all remaining work on failure or abort. A failed refresh does not publish a partial set of counts.
Each statistic span has class="sm-statistic", an escaped JSON data-sm-statistic descriptor, and a dash fallback (—). The page-count shorthand also has sm-pagecount. The host supplies data.statistics:
statistics(
requests: readonly StatisticRequest[],
signal: AbortSignal,
): Promise<readonly (number | null)[]>;The runtime batches unique descriptors and expects one result per request in the same order. Results must be non-negative safe integers. Zero is a real value; null, missing adapters, invalid results, and failures retain the fallback. The runtime formats valid values with the viewer's locale. Updates and disposal cancel the work, and stale responses cannot modify a replaced body. The runtime does not choose an endpoint or make independent network requests; the adapter owns retrieval, authorization, and data freshness.
HTML caching is independent of live display-data caching. The host can reuse the same HTML while it refreshes the displayed statistics. Its data cache must account for the current site-calendar interval, aggregate version, and visibility. Public HTML must not contain private statistic values.
Native evaluation and approved site facts
All documents and templates use one typed language. Source does not contain a language-version directive. The wire contract is version 8; it describes the API, not a separate source dialect. /v1/analyze has no version selector.
The three endpoints accept optional evaluation_context for explicit native calculations. Pure arithmetic does not require it. Functions such as now(), today(), yesterday(), age(...), dday(...), and site.* read its fixed instant, IANA site time zone, and approved facts as needed. These values can select branches and compose template output, so they remain fixed across discovery and rendering. They are separate from the live display macros above. The evaluator does not read the operating-system clock, browser clock, or database.
{
"instant": "2026-11-02T00:00:00Z",
"timezone": "Asia/Seoul",
"facts": [
{
"request": { "kind": "document_count", "namespace": "document" },
"outcome": {
"state": "available",
"value": 1234,
"as_of": "2026-11-01T23:59:00Z",
"version": "public-documents-42",
"valid_until": "2026-11-02T00:05:00Z"
}
}
]
}Supported fact requests are:
document_count, with optionalnamespace.registered_user_count, for accounts under the host's global counting policy.active_user_count, withfromanduntilRFC 3339 instants.documents_created, withfrom,until, and optionalnamespace.
Periods are half-open: [from, until). Date-based requests convert calendar boundaries in the context's time zone to UTC. Yesterday can contain 23 or 25 hours. Document creation means an initial creation, not restoring or recreating the same document identity. The host owns aggregate visibility and counting policy. Existing public document counters can supply document_count.
An unavailable outcome has state: unavailable and reason: unsupported or temporarily_unavailable. It is distinct from an available value of zero. A missing or unavailable fact never becomes a fabricated value during rendering.
Analysis returns parameters with each root template input's name, canonical value_type, required flag, and source-exact default expression. Required inputs without arguments return evaluation_complete: false and ordered pending_inputs. SevenMark does not invent values or execute the template body. reference_candidates conservatively lists static references from all syntax branches. These candidates are separate from the active includes, links, and relations. The host can inspect template declarations and candidate permissions without claiming that an argument-dependent render has completed.
external_link_candidates is always present. It lists valid static external destinations from every branch, including a template that still needs required inputs. Code, literal blocks, comments and editor notes add no candidates. This list shares the reference budget with static document candidates. It does not execute expressions or predict a URL assembled from parameter fragments.
AnalyzeBundleResponse.external_links is always present and lists actual external destinations after approved include and typed argument expansion. It is empty when evaluation is incomplete. The host checks these URLs against its current blocklist before publication or rendering. This covers a template that builds https:// plus an input host name. The expanded URLs share the bundle's reference budget with document targets and used facts. Direct source external_links keeps its existing active-host meaning.
When an active calculation needs a fixed context and none was supplied, analysis returns HTTP 200 with evaluation_complete: false and evaluation_context_required: true. It returns no active graph or fact requests. Plain analysis retains input declarations and static reference candidates. The host supplies one approved fixed instant and site time zone, then repeats analysis. Ordinary content and live display widgets return evaluation_context_required: false without reading the clock or statistics.
Analysis stops at the first missing fact and returns evaluation_complete: false with fact_requests. Its active reference/relationship lists are empty and must not certify publication, backlinks, or authorization. Supply the approved result and repeat analysis with the same fixed instant, time zone, and source revisions. Further dependencies can require further rounds; the host bounds those rounds. These responses have evaluation_context_required: false because the context is already present. Malformed request envelopes remain HTTP 400 errors. Authored syntax and evaluation errors render locally as escaped red source with an error diagnostic; surrounding valid content still renders. Rendering requires the context and every reached fact; it fails instead of returning partial success.
Successful analysis returns evaluation_complete: true. Analysis and rendering return used_facts for the statistics actually read, with their request, version, as_of, and valid_until. Repeated reads use one supplied value and one manifest entry. Independently observed facts do not imply one database snapshot. A fact can be observed after the fixed language clock during discovery. Its expiry must follow both its observation and the fixed instant. The host rechecks real-time freshness before cache use or delivery.
Cache identity for evaluated output must include the renderer version, exact selected source revisions, typed input meanings, and the complete approved evaluation_context: its exact instant, time zone, and supplied fact identities, values, and freshness metadata. An empty used_facts list does not make a result context-independent: now() and calendar-only expressions can read the clock without reading a statistic. The host validates snapshot versions and real-time expiry and selects an explicit refresh policy for calculated time. Live placeholder hydration does not rerun these calculations or update their branch decisions. Current read authorization is a separate final check.
Roots support transitive includes from an approved static source closure. Supply each required revision and include decision; SevenMark does not fetch extra revisions independently. Only selected source revisions enter the used-dependency manifest. All included sources use the same native rules.
SEVENMARK_MAX_EVAL_WORK configures one budget for the render, including nested templates, expressions, iteration, helpers, and cached output. Bulk work is charged by processed data. Ten million units is the initial default, not a CPU-time guarantee. Existing source/bundle/reference/output guards remain. Parser construction, typed values, and expanded content use the expansion-byte setting; logical byte accounting is not process RSS. Parser syntax depth and execution depth are separate guards. No per-loop or per-function quota is added.
Map values produce validated native nodes. The browser runtime accepts a host-owned map adapter; it does not accept markup-authored tile URLs or scripts. The mapcn-svelte example shows Svelte mounting, ShadowRoot styles, explicit themes, and teardown. A location link remains available without a widget adapter. Provider configuration belongs to the UI host; aggregate queries and precomputation belong to V7. Track host implementation in V7 issue 593.
AI authoring reference
The documentation site serves /llms.txt as its entry point and /llms-full.txt as its complete native authoring reference. The portable SevenMark skill lives at .agents/skills/sevenmark/. The same deterministic generator writes the full site reference and the skill's language reference from canonical grammar pages and the evaluator's function registry. CI checks for drift. These files describe current markup; the host API remains documented here.
Host-denied external URLs
POST /v1/render accepts blocked_external_urls, a list of exact emitted HTTP or HTTPS URLs. The default is an empty list. Each URL must satisfy the external URL rules. The list cannot exceed the reference budget.
The host matches its rules against the completed bundle analysis. It sends the matching URLs with the same approved source bundle. SevenMark applies these negative decisions after include expansion and typed evaluation. A denied link keeps its authored label, or its URL when it has no label, as ordinary text. It has no navigation, link styling or policy warning. A denied File click target loses its navigation while the approved image remains. Denied provider embeds and maps use plain text fallbacks. The rest of the body renders normally. Source ranges and dependency provenance remain available. This is a presentation decision; source publication rules remain the host's responsibility. SevenMark 11.3.1 adds this field to contract 8. SevenMark 11.3.2 renders policy-denied occurrences as ordinary content. Invalid markup still uses local error nodes and diagnostics; resource exhaustion can refuse the whole render.