From ba176b63d5075a0cb837c0592ff5e422a6d30c09 Mon Sep 17 00:00:00 2001 From: Christopher Byrd Date: Tue, 17 Nov 2026 09:24:19 -0600 Subject: [PATCH 1/2] Home page: plain wording for a general reader Rewrite the home page opening in plain language: the problem first, then what REST:ACT lets a user do, then one paragraph naming the technology. "What it is for" moves ahead of the request demo and opens with why client code is wanted. The six-item mandatory-core grid, which no longer matched the draft's nine items, becomes four plain rules on how the server confines uploaded code, each linked to its draft section, with the full list left to /spec/. Fix limit claims that disagreed with the draft and restactd: a verb that runs past its wall-clock limit gets 504, not 408 (Security, Get started, restactd), and the compute limit is recommended, not required (Security, Compare, the /spec/ section gist). Part of #37 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012CEyiXRPrNfjwX3iEx99dw --- src/components/AnatomyDemo.astro | 4 +- src/lib/spec-map.ts | 2 +- src/pages/compare.mdx | 2 +- src/pages/index.astro | 90 +++++++++++++++++--------------- src/pages/restactd.astro | 2 +- src/pages/security.mdx | 4 +- src/pages/start.astro | 2 +- 7 files changed, 57 insertions(+), 49 deletions(-) diff --git a/src/components/AnatomyDemo.astro b/src/components/AnatomyDemo.astro index 5d55776..acb772e 100644 --- a/src/components/AnatomyDemo.astro +++ b/src/components/AnatomyDemo.astro @@ -40,7 +40,7 @@ const reqs: Req[] = [ { text: '/v1/notes/42', caption: 'object path: the noun', tone: 'ink', rule: 'line' }, ], kind: 'data', kindTone: 'soft', gist: 'The object’s data, a JSON document', - desc: 'Plain HTTP on the object path reads and writes its data. No verb runs, and a client that only does CRUD sees an ordinary REST API.', + desc: 'Plain HTTP on the object path reads and writes its data. No verb runs, so a client that only reads and writes data sees an ordinary REST API.', }, { method: 'GET', methodTone: 'sig', path: '/v1/notes/42:wordCount', short: 'function', @@ -50,7 +50,7 @@ const reqs: Req[] = [ { text: 'wordCount', caption: 'verb', tone: 'ink', rule: 'sig', lead: ':' }, ], kind: 'function', kindTone: 'sig', gist: 'Safe and cacheable', - desc: 'A function is called with GET. The host refuses any write it attempts, and a function may not call an action, so the response can be cached.', + desc: 'A function is called with GET. The server refuses any write it attempts, and a function may not call an action, so the response can be cached.', }, { method: 'POST', methodTone: 'act', path: '/v1/notes/42:archive', short: 'action', diff --git a/src/lib/spec-map.ts b/src/lib/spec-map.ts index 7d58e0f..4ba4c28 100644 --- a/src/lib/spec-map.ts +++ b/src/lib/spec-map.ts @@ -31,7 +31,7 @@ export const SECTION_MAP: Record = { tag: 'optional', }, capabilities: { gist: 'Layered host interfaces, deny by default; the guest contract and the read-only caller identity.', tag: 'core + optional' }, - limits: { gist: 'Wall-clock, compute and memory limits per invocation, answered with 504, 429 and 507.', tag: 'core' }, + limits: { gist: 'Wall-clock and memory limits per invocation, and a recommended compute limit, answered with 504, 507 and 429.', tag: 'core' }, composition: { gist: 'One verb calls another through the host, under a declared call graph and a shared budget.', tag: 'optional' }, authz: { gist: 'Authentication mechanisms, policy matchers, the simple profile, fixed ownership and the execution identity.', diff --git a/src/pages/compare.mdx b/src/pages/compare.mdx index 0a3057f..7627fd8 100644 --- a/src/pages/compare.mdx +++ b/src/pages/compare.mdx @@ -66,7 +66,7 @@ REST:ACT is a wire protocol for the clients of an API to upload components at ru Extism is a plug-in system built on WebAssembly. The host application defines an interface, and users or customers add logic by writing plug-ins against it. Extism supplies host SDKs for embedding that runtime in an application. -Both share the idea of letting a product's users extend it with their own code. The difference is the layer. Extism is a library that a product's developers embed, and they design the extension points. REST:ACT is a wire protocol, so any client of a compliant server can upload a verb over HTTP, and the server enforces time, compute and memory limits on it, runs it as the caller by default and lists it in its discovery document. +Both share the idea of letting a product's users extend it with their own code. The difference is the layer. Extism is a library that a product's developers embed, and they design the extension points. REST:ACT is a wire protocol, so any client of a compliant server can upload a verb over HTTP, and the server limits its time and memory, runs it as the caller by default and lists it in its discovery document. ## Cloudflare Workers for Platforms diff --git a/src/pages/index.astro b/src/pages/index.astro index 3b727c2..eed1b28 100644 --- a/src/pages/index.astro +++ b/src/pages/index.astro @@ -6,11 +6,12 @@ import ReaderGroups from '../components/ReaderGroups.astro'; import { term } from '../lib/term'; import { DRAFT, GITHUB, RESTACTD_DOCS, SITE } from '../site.config'; -/* The home page: a documentation hub. The draft's title, the one-line reason for the protocol and - the abstract open it, with one next step per reader. Then one object answers four requests, what - the protocol is for, the mandatory core, and one verb built, uploaded and called. It closes on the - reader-grouped links and a note on comments. The page sets the tagline in its opening, so the - tagline bar is off here. Copy sits up here, markup below. */ +/* The home page, written for a general technical reader first. The draft's title, the one-line + reason for the protocol and a plain introduction open it, with one next step per reader. Then + what the protocol is for, one object answering four requests, the rules that confine uploaded + code, and one verb built, uploaded and called. It closes on the reader-grouped links and a note on + comments. The page sets the tagline in its opening, so the tagline bar is off here. Copy sits up + here, markup below. */ const DRAFT_URL = '/spec/draft/'; @@ -26,9 +27,12 @@ const dek = { }, }; +/* Plain first, for a reader who has never met the protocol; the last paragraph names the technology + for the reader who wants it. */ const abstract = [ - 'REST:ACT is an HTTP protocol that lets the clients of an API add their own code to the server, within the permissions the server grants them. A client uploads a small program, called a verb, to a path in the server’s object tree, and anyone the server allows can call it with GET or POST.', - 'A verb is a WebAssembly component. It runs with the caller’s permissions, can use only the host interfaces it imports, and stops when it reaches its time, compute or memory limit.', + 'An API can do only what its developers built into it. When you need something it lacks, you ask them and wait, or you copy the data out and do the work somewhere else.', + 'REST:ACT lets an API’s users add the missing piece themselves, within the permissions the server grants them. A user, or an agent working for them, uploads a small program called a verb. From then on, anyone the server allows can run it with an ordinary web request.', + 'Each verb is a WebAssembly component. The server runs it in a sandbox with the permissions of whoever calls it, and stops it when it runs out of time or memory.', ]; /* One next step for each of the three readers, named as the reader groups at the close name them, @@ -42,7 +46,7 @@ const next = [ const demo = { heading: 'How the server reads a request', - lead: 'Four requests to the same note, notes/42. Select one to see how the server reads it.', + lead: 'A verb is called at the address of the thing it works on, after a colon. Here are four requests to one example note, notes/42. Select one to see what the server does with it.', }; const paths = { @@ -77,33 +81,38 @@ const paths = { const uses = { heading: 'What it is for', - lead: 'A few examples of what client-extensible APIs make possible:', + lead: 'Code-writing assistants have made small programs easy to write, even for people who are not programmers. Many of those programs are most useful running next to the data they work on, inside someone else’s service. For example:', items: [ - 'A user uploads a function that transforms rows in a database.', - 'A bot contributes a tool to a remote service.', - 'A social platform runs a profile owner’s code when other people interact with the profile.', - 'An interactive environment where participants write both the content and the programs.', + 'A user adds a function that reshapes rows in a database.', + 'A bot adds a tool to a service it works with.', + 'A social site runs a profile owner’s code when other people interact with the profile.', + 'A shared online world where the people in it write both the content and the programs.', ], - after: - 'The draft treats every uploaded verb as hostile. Execution is deny-by-default, resource-limited, and bounded by the caller’s own authority.', }; +/* The rules that confine uploaded code, in plain words. Each links the draft section it rests on; + the full mandatory core is on /spec/, where the build checks it against the draft. */ const core = { - heading: 'What a server must implement', - lead: 'A conformant server implements six things. Everything else in the draft is an optional feature, which the server lists in its discovery document.', + heading: 'How the server keeps uploaded code in check', + lead: 'The draft assumes that any uploaded verb could be hostile. A server does not try to judge the code. It confines whatever runs, under rules every conformant server follows.', items: [ - { name: 'Addressing and verb invocation', body: 'A colon separates the object path from the verb name, as in /v1/notes/42:wordCount.', href: `${DRAFT_URL}#addressing` }, - { name: 'Capability confinement', body: 'A verb reaches only the host interfaces it imports. The server refuses an upload that imports one it does not grant.', href: `${DRAFT_URL}#capabilities` }, - { name: 'Resource limits', body: 'Every call has wall-clock, compute and memory limits, answered with 504, 429 and 507.', href: `${DRAFT_URL}#limits` }, - { name: 'Runs as the caller', body: 'A verb acts with the caller’s authority, narrowed by what the verb declared and by the target’s policy.', href: `${DRAFT_URL}#exec-identity` }, - { name: 'Problem Details errors', body: 'Errors are RFC 9457 problem details carrying a restact_code.', href: `${DRAFT_URL}#errors` }, - { name: 'A discovery document', body: '/.well-known/restact lists the server’s features, limits and verbs.', href: `${DRAFT_URL}#discovery` }, + { name: 'A verb reaches only what it imports', body: 'A verb lists the host interfaces it needs, and the server refuses an upload that asks for one it does not allow. No verb gets raw network access.', href: `${DRAFT_URL}#capabilities` }, + { name: 'A verb runs as the caller', body: 'A verb can do nothing the person or program calling it could not do directly, and nothing it did not declare.', href: `${DRAFT_URL}#exec-identity` }, + { name: 'Every call has limits', body: 'A call that runs past its time limit ends with 504, and one that runs out of memory with 507. The draft also recommends a compute limit, answered with 429.', href: `${DRAFT_URL}#limits` }, + { name: 'Calls share one deadline', body: 'A verb that calls other verbs shares one deadline with them, so a chain of calls cannot stretch its time.', href: `${DRAFT_URL}#composition` }, ], + after: { + before: 'The', + spec: { label: 'specification overview', href: '/spec/' }, + middle: 'lists everything a conformant server must implement, and the', + security: { label: 'security model', href: '/security/' }, + after: 'explains each rule.', + }, }; const example = { heading: 'A verb, end to end', - lead: 'A Rust verb that counts words, built with plain cargo, uploaded with the draft’s reference deployment request, POST /v1/modules, and called with GET. The upload names notes/42:wordCount, so it creates the wordCount verb that the demo above calls. A local restactd without authentication lets a verb bind to an object that does not exist yet.', + lead: 'A Rust verb that counts words. It is built with cargo, uploaded with POST /v1/modules (the draft’s reference way to deploy a verb) and called with GET. The upload creates notes/42:wordCount, the verb the requests above call. On a local restactd with no sign-in, the note does not have to exist first.', needs: { server: { before: 'The commands need', link: { label: 'restactd', href: '/restactd/' }, after: 'running on localhost:8080.' }, how: { link: { label: 'Get started', href: '/start/' }, after: 'shows how.' }, @@ -167,14 +176,6 @@ const jsonLd = { -
-

{demo.heading}

-

- {split(demo.lead).map((x) => (x.code ? {x.t} : x.t))} -

- -
-

{uses.heading}

@@ -182,10 +183,17 @@ const jsonLd = {
    {uses.items.map((u) =>
  • {u}
  • )}
-

{uses.after}

+
+

{demo.heading}

+

+ {split(demo.lead).map((x) => (x.code ? {x.t} : x.t))} +

+ +
+

{core.heading}

@@ -201,6 +209,10 @@ const jsonLd = { )) } +

+ {core.after.before} {core.after.spec.label} {core.after.middle}{' '} + {core.after.security.label} {core.after.after} +

@@ -326,10 +338,10 @@ const jsonLd = { color: var(--ink-3); } - /* Core: a compact three-column list. */ + /* Core: four rules, read as two pairs. */ .core { display: grid; - grid-template-columns: repeat(3, minmax(0, 1fr)); + grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 56px; margin-top: 32px; font-variant-numeric: tabular-nums; @@ -347,7 +359,8 @@ const jsonLd = { max-width: 880px; margin-top: 32px; } - .more { + .more, + .core-after { margin-top: 24px; } @@ -361,11 +374,6 @@ const jsonLd = { color: var(--ink-3); } - @media (max-width: 1080px) { - .core { - grid-template-columns: repeat(2, minmax(0, 1fr)); - } - } @media (max-width: 720px) { .opening { padding-block: 40px 28px; diff --git a/src/pages/restactd.astro b/src/pages/restactd.astro index 9370f7b..de233e3 100644 --- a/src/pages/restactd.astro +++ b/src/pages/restactd.astro @@ -24,7 +24,7 @@ const facts: { term: string; html: string }[] = [ }, { term: 'Limits per call', - html: '200,000,000 fuel, 2 s and 32 MiB by default, answered with 429, 408 and 507. An operator sets the ceilings.', + html: '200,000,000 fuel, 2 s and 32 MiB by default, answered with 429, 504 and 507. An operator sets the ceilings.', }, { term: 'Storage', diff --git a/src/pages/security.mdx b/src/pages/security.mdx index 6ad85df..80d5d9a 100644 --- a/src/pages/security.mdx +++ b/src/pages/security.mdx @@ -36,7 +36,7 @@ Four rules apply to every verb, and a server that skips one is not conformant. 1. A verb is a WebAssembly component. Every verb runs as a WASI 0.2 component. A server may compile JavaScript or Python to a component at upload or run it through an interpreter component, under the same confinement and limits either way. [restactd](/restactd/) interprets, so nothing is compiled per upload. 2. A verb reaches only what it imports. The imports of the component are its capability manifest, and there is no ambient authority beyond them. A server answers `403` at upload for an interface it does not grant, and none of the standard interfaces opens a socket or a file. 3. A verb runs as the caller. A call can do what the caller could do directly and the verb declared, within the policy of the target. Its compute is charged to the caller. -4. A verb is metered. Wall-clock, compute and memory limits apply to every call, and a verb that calls other verbs shares one budget with them. +4. A verb is metered. Every call has a wall-clock limit and a memory limit, and the draft recommends a compute limit as well. A verb that calls other verbs shares one deadline with them, and one compute budget where the server counts compute. ### Capabilities are an import list @@ -85,7 +85,7 @@ A server enforces a wall-clock limit and a compute limit separately. Counting in | Limit | Status | restactd default | |---|---|---| -| Wall-clock time | `408` | 2 s | +| Wall-clock time | `504` | 2 s | | Compute (fuel) | `429` | 200,000,000 | | Memory | `507` | 32 MiB | diff --git a/src/pages/start.astro b/src/pages/start.astro index 4974728..e720d8a 100644 --- a/src/pages/start.astro +++ b/src/pages/start.astro @@ -204,7 +204,7 @@ const next = [

Watch a limit stop a verb

A verb that never returns is cut off. The default limits are 2 s of wall-clock time, 200,000,000 fuel and 32 MiB - of memory, and a breach returns 408, 429 or 507. + of memory, and a breach returns 504, 429 or 507.

From a78fd903dcd2729be88667d5690011c794ef2534 Mon Sep 17 00:00:00 2001 From: Christopher Byrd Date: Tue, 17 Nov 2026 09:32:13 -0600 Subject: [PATCH 2/2] Wording review fixes: runs-as-owner, optional composition, plainer leads From the text review: the runs-as-caller rule now says "by default" and names the owner opt-in the draft allows, since the page's own social-site example is that case. The shared deadline applies where a server lets verbs call each other on it, matching the draft's optional composition and its fresh budget across servers. The example lead names the second demo request and says authentication is off rather than "no sign-in". Security and Compare drop the last two places that stated the compute limit as required, and /llms.txt follows the new home-page opening. Part of #37 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012CEyiXRPrNfjwX3iEx99dw --- src/components/AnatomyDemo.astro | 2 +- src/pages/compare.mdx | 4 ++-- src/pages/index.astro | 18 +++++++++--------- src/pages/llms.txt.ts | 6 +++--- src/pages/security.mdx | 4 ++-- 5 files changed, 17 insertions(+), 17 deletions(-) diff --git a/src/components/AnatomyDemo.astro b/src/components/AnatomyDemo.astro index acb772e..998899f 100644 --- a/src/components/AnatomyDemo.astro +++ b/src/components/AnatomyDemo.astro @@ -40,7 +40,7 @@ const reqs: Req[] = [ { text: '/v1/notes/42', caption: 'object path: the noun', tone: 'ink', rule: 'line' }, ], kind: 'data', kindTone: 'soft', gist: 'The object’s data, a JSON document', - desc: 'Plain HTTP on the object path reads and writes its data. No verb runs, so a client that only reads and writes data sees an ordinary REST API.', + desc: 'Plain HTTP on the object path reads and writes its data. No verb is named, so a client that only reads and writes data sees an ordinary REST API.', }, { method: 'GET', methodTone: 'sig', path: '/v1/notes/42:wordCount', short: 'function', diff --git a/src/pages/compare.mdx b/src/pages/compare.mdx index 7627fd8..88e0881 100644 --- a/src/pages/compare.mdx +++ b/src/pages/compare.mdx @@ -66,7 +66,7 @@ REST:ACT is a wire protocol for the clients of an API to upload components at ru Extism is a plug-in system built on WebAssembly. The host application defines an interface, and users or customers add logic by writing plug-ins against it. Extism supplies host SDKs for embedding that runtime in an application. -Both share the idea of letting a product's users extend it with their own code. The difference is the layer. Extism is a library that a product's developers embed, and they design the extension points. REST:ACT is a wire protocol, so any client of a compliant server can upload a verb over HTTP, and the server limits its time and memory, runs it as the caller by default and lists it in its discovery document. +Both share the idea of letting a product's users extend it with their own code. The difference is the layer. Extism is a library that a product's developers embed, and they design the extension points. REST:ACT is a wire protocol, so any client a compliant server allows can upload a verb over HTTP, and the server limits its time and memory, runs it as the caller by default and lists it in its discovery document. ## Cloudflare Workers for Platforms @@ -78,7 +78,7 @@ It shares the multi-tenant goal and the idea that uploaded code is untrusted. In PostgREST serves a Postgres database over HTTP. A function in the exposed schema is callable under `/rpc`. A function that does not modify the database also runs under `GET`, and a request with a valid JWT switches the database session to the role named in the token, so the database decides what the caller may do. Supabase's REST API is PostgREST, and `rpc()` calls its database functions. Supabase recommends `security invoker`, the default, so a function runs with the caller's privileges. -This is the closest relative here. Read-only calls use `GET`, others use `POST`, and the code runs as the caller. PostgREST decides by function volatility: `GET` is always read-only, and `POST` is read-write only for volatile functions. REST:ACT separates a function from an action by declared kind, and a function is a cacheable `GET`. The functions there are SQL or other database code written by whoever administers the database, then exposed. A verb is uploaded at runtime by an API client, is not tied to a database, runs as a WebAssembly component under time, compute and memory limits, and works on the object it is bound to. +This is the closest relative here. Read-only calls use `GET`, others use `POST`, and the code runs as the caller. PostgREST decides by function volatility: `GET` is always read-only, and `POST` is read-write only for volatile functions. REST:ACT separates a function from an action by declared kind, and a function is a cacheable `GET`. The functions there are SQL or other database code written by whoever administers the database, then exposed. A verb is uploaded at runtime by an API client, is not tied to a database, runs as a WebAssembly component under time and memory limits, and works on the object it is bound to. ## Hasura actions diff --git a/src/pages/index.astro b/src/pages/index.astro index eed1b28..768c1da 100644 --- a/src/pages/index.astro +++ b/src/pages/index.astro @@ -32,7 +32,7 @@ const dek = { const abstract = [ 'An API can do only what its developers built into it. When you need something it lacks, you ask them and wait, or you copy the data out and do the work somewhere else.', 'REST:ACT lets an API’s users add the missing piece themselves, within the permissions the server grants them. A user, or an agent working for them, uploads a small program called a verb. From then on, anyone the server allows can run it with an ordinary web request.', - 'Each verb is a WebAssembly component. The server runs it in a sandbox with the permissions of whoever calls it, and stops it when it runs out of time or memory.', + 'Each verb is a WebAssembly component. The server runs it in a sandbox, by default with the permissions of whoever calls it, and stops it when it runs out of time or memory.', ]; /* One next step for each of the three readers, named as the reader groups at the close name them, @@ -46,7 +46,7 @@ const next = [ const demo = { heading: 'How the server reads a request', - lead: 'A verb is called at the address of the thing it works on, after a colon. Here are four requests to one example note, notes/42. Select one to see what the server does with it.', + lead: 'A verb’s address is the address of the thing it works on, then a colon and the verb’s name, as in notes/42:wordCount. Here are four requests to one example note, notes/42. Select one to see what the server does with it.', }; const paths = { @@ -86,7 +86,7 @@ const uses = { 'A user adds a function that reshapes rows in a database.', 'A bot adds a tool to a service it works with.', 'A social site runs a profile owner’s code when other people interact with the profile.', - 'A shared online world where the people in it write both the content and the programs.', + 'In a shared online world, the people in it write both the content and the programs.', ], }; @@ -94,12 +94,12 @@ const uses = { the full mandatory core is on /spec/, where the build checks it against the draft. */ const core = { heading: 'How the server keeps uploaded code in check', - lead: 'The draft assumes that any uploaded verb could be hostile. A server does not try to judge the code. It confines whatever runs, under rules every conformant server follows.', + lead: 'The draft assumes that any uploaded verb could be hostile. A server does not try to decide whether the code is safe. It confines whatever runs, under these rules.', items: [ - { name: 'A verb reaches only what it imports', body: 'A verb lists the host interfaces it needs, and the server refuses an upload that asks for one it does not allow. No verb gets raw network access.', href: `${DRAFT_URL}#capabilities` }, - { name: 'A verb runs as the caller', body: 'A verb can do nothing the person or program calling it could not do directly, and nothing it did not declare.', href: `${DRAFT_URL}#exec-identity` }, - { name: 'Every call has limits', body: 'A call that runs past its time limit ends with 504, and one that runs out of memory with 507. The draft also recommends a compute limit, answered with 429.', href: `${DRAFT_URL}#limits` }, - { name: 'Calls share one deadline', body: 'A verb that calls other verbs shares one deadline with them, so a chain of calls cannot stretch its time.', href: `${DRAFT_URL}#composition` }, + { name: 'A verb reaches only what it imports', body: 'A verb lists the server interfaces it needs, and the server refuses an upload that asks for one it does not allow. No verb gets raw network access.', href: `${DRAFT_URL}#capabilities` }, + { name: 'A verb runs as the caller', body: 'By default, a verb can do nothing the person or program calling it could not do directly, and nothing it did not declare. A server may let a verb’s owner lend it the owner’s permissions instead, and the verb’s description then says so.', href: `${DRAFT_URL}#exec-identity` }, + { name: 'Every call has limits', body: 'A call that runs past its time limit ends with HTTP status 504, and one that runs out of memory with 507. The draft also recommends a compute limit, answered with 429.', href: `${DRAFT_URL}#limits` }, + { name: 'Calls share one deadline', body: 'Where a server lets verbs call other verbs on it, they all share one deadline, so a chain of calls cannot run longer than the first call was allowed.', href: `${DRAFT_URL}#composition` }, ], after: { before: 'The', @@ -112,7 +112,7 @@ const core = { const example = { heading: 'A verb, end to end', - lead: 'A Rust verb that counts words. It is built with cargo, uploaded with POST /v1/modules (the draft’s reference way to deploy a verb) and called with GET. The upload creates notes/42:wordCount, the verb the requests above call. On a local restactd with no sign-in, the note does not have to exist first.', + lead: 'Here is a Rust verb that counts words. It is built with cargo, uploaded with POST /v1/modules (the draft’s reference way to deploy a verb) and called with GET. The upload creates notes/42:wordCount, the function in the second request above. With authentication off, as on a local restactd, the note does not have to exist first.', needs: { server: { before: 'The commands need', link: { label: 'restactd', href: '/restactd/' }, after: 'running on localhost:8080.' }, how: { link: { label: 'Get started', href: '/start/' }, after: 'shows how.' }, diff --git a/src/pages/llms.txt.ts b/src/pages/llms.txt.ts index 8537c1b..67799a3 100644 --- a/src/pages/llms.txt.ts +++ b/src/pages/llms.txt.ts @@ -3,7 +3,7 @@ import { DRAFT_FILE, SPECS_REPO } from '../lib/specmd'; import { DRAFT, GITHUB, RESTACTD_DOCS } from '../site.config'; // /llms.txt (llmstxt.org): a reading list for language models and the tools that feed them. The -// summary repeats the home page's abstract; the notes are short forms of each page's description. +// summary is a short form of the home page's opening; the notes are short forms of each page's description. // The draft's Markdown source is linked raw, since a model reads it more reliably than HTML. const raw = `${SPECS_REPO.replace('https://github.com/', 'https://raw.githubusercontent.com/')}/main/${DRAFT_FILE}`; @@ -11,9 +11,9 @@ export const GET: APIRoute = ({ site }) => { const u = (p: string) => new URL(p, site).href; const body = `# REST:ACT -> REST:ACT is an HTTP protocol that lets the clients of an API add their own code to the server, within the permissions the server grants them. A client uploads a small program, called a verb, to a path in the server's object tree, and anyone the server allows can call it with GET or POST. +> REST:ACT lets an API's users add the functions the API lacks, within the permissions the server grants them. A user, or an agent working for them, uploads a small program called a verb, and anyone the server allows can then run it with an ordinary GET or POST request. -A verb is a WebAssembly component. It runs with the caller's permissions, can use only the host interfaces it imports, and stops when it reaches its time, compute or memory limit. The protocol is specified in ${DRAFT.docname}, written as an Internet-Draft and not yet submitted to the IETF; it is not a standard. restactd is the reference server. +Each verb is a WebAssembly component. The server runs it in a sandbox, by default with the permissions of whoever calls it, lets it use only the interfaces it imports and the server allows, and stops it when it runs out of time or memory. The protocol is specified in ${DRAFT.docname}, written as an Internet-Draft and not yet submitted to the IETF; it is not a standard. restactd is the reference server. ## Specification diff --git a/src/pages/security.mdx b/src/pages/security.mdx index 80d5d9a..0e19a1b 100644 --- a/src/pages/security.mdx +++ b/src/pages/security.mdx @@ -36,7 +36,7 @@ Four rules apply to every verb, and a server that skips one is not conformant. 1. A verb is a WebAssembly component. Every verb runs as a WASI 0.2 component. A server may compile JavaScript or Python to a component at upload or run it through an interpreter component, under the same confinement and limits either way. [restactd](/restactd/) interprets, so nothing is compiled per upload. 2. A verb reaches only what it imports. The imports of the component are its capability manifest, and there is no ambient authority beyond them. A server answers `403` at upload for an interface it does not grant, and none of the standard interfaces opens a socket or a file. 3. A verb runs as the caller. A call can do what the caller could do directly and the verb declared, within the policy of the target. Its compute is charged to the caller. -4. A verb is metered. Every call has a wall-clock limit and a memory limit, and the draft recommends a compute limit as well. A verb that calls other verbs shares one deadline with them, and one compute budget where the server counts compute. +4. A verb is metered. Every call has a wall-clock limit and a memory limit, and the draft recommends a compute limit as well. A verb that calls other verbs shares one deadline with them and, where the server counts compute, one compute budget. ### Capabilities are an import list @@ -81,7 +81,7 @@ A function may not call an action, and may not write: `object.set` and `event.pu ## Resource limits -A server enforces a wall-clock limit and a compute limit separately. Counting instructions does not stop a verb that stalls without computing, and a timer alone is not deterministic. Each breach has its own status code. +The draft requires a wall-clock limit and recommends a separate compute limit. Counting instructions does not stop a verb that stalls without computing, and a timer alone is not deterministic. Each breach has its own status code. | Limit | Status | restactd default | |---|---|---|