@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/examples/oidc-login/provider/userinfo.aug.md

@@ -1,104 +1,22 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `userinfo.aug` specification
+# `userinfo.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`userinfo`](userinfo.aug.md#symbol-userinfo) handles `GET` `/provider/userinfo` returning `HttpResponse<Json>`.
+Plain handler results default to HTTP 200 unless another status is declared. HttpResponse values choose their own status. Unhandled request failures return HTTP 500 and cancel the request tasks.
 
 <a id="symbol-userinfo"></a>
+## `userinfo` · [source](userinfo.aug#L8)
 
-## `userinfo`
-
-[source](userinfo.aug#L7)
-
-**Inputs**
-
-- `authorization` (`optional string`) — read from the HTTP header; absent value becomes null.
-- `clock` ([`Clock`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock)) — injected; callers omit it.
-- `access` ([`ExpiringStore<AccessGrant>`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)) — injected; callers omit it.
-
-Returns: `HttpResponse<Json>`.
-
-Capabilities: [`clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now), [`access.get`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.get).
-
-Can fail with `TimeError`, `HttpError`. Callers must catch or propagate these errors.
-
-HTTP route: `GET` `/provider/userinfo`. Use status 200 when the handler returns a body; a returned HttpResponse can set its own status. An unhandled request failure returns status 500 and cancels its request tasks.
-
-**What it does**
-
-- Select the matching case for `authorization`:
-  - A null value, including omitted optional input:
-    - Continue without another operation.
-  - A present, non-null value, named `header`:
-    - Set `parts` to call `split` on `header` with `separator` = `" "`.
-    - If call `length` on `parts` equals `2`:
-      - Try these operations:
-        - If call `get` on `parts` with `index` = `0` equals `"Bearer"`:
-          - Set `token` to call `get` on `parts` with `index` = `1`.
-          - If call `isToken` on `token` with `min` = `43`; `max` = `43` is true:
-            - Select the matching case for call [`ExpiringStore.get`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.get) on `access` with `key` = `token`; `now` = call [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) on `clock`:
-              - A null value, including omitted optional input:
-                - Continue without another operation.
-              - A present, non-null value, named `grant`:
-                - Return call `HttpResponse` with `body` = call `Json` with `value` = call [`UserInfo`](contracts.aug.md#symbol-UserInfo) with `sub` = `subject` of `grant`; `name` = `name` of `grant`; `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders).
-      - If they fail with `IndexError`, name the failure `error` and recover:
-        - Continue without another operation.
-- Set `headers` to call `with` on call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) with `name` = `"www-authenticate"`; `value` = `"Bearer error=\"invalid_token\""`.
-- Return call `HttpResponse` with `body` = call `Json` with `value` = a map with `"error"` mapped to `"invalid_token"`; `status` = `401`; `headers` = `headers`.
-
-**Author documentation**
-
-The opaque access token is valid only at this provider. Missing, expired and malformed credentials receive the same response.
-
-## Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-### [`ExpiringStore`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)
-
-Capability interface from `august.memory`.
-
-- [`ExpiringStore.get`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.get) (`key`: `string`, `now`: `int`) → `optional T`.
-
-### [`Clock`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock)
-
-Capability interface from `august.time`.
-
-- [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) (no caller inputs) → `int`; can fail with `TimeError`.
-
-### [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders)
-
-Function from `common`.
-
-- [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) (no caller inputs) → `Headers`; can fail with `HttpError`.
-
-### [`AccessGrant`](contracts.aug.md#symbol-AccessGrant)
-
-Record from `contracts`.
-
-- Read `name` (`string`).
-- Read `subject` (`string`).
-
-### [`UserInfo`](contracts.aug.md#symbol-UserInfo)
-
-Record from `contracts`.
+`userinfo` handles `GET /provider/userinfo`. The opaque access token is valid only at this provider. Missing, expired and malformed credentials receive the same response.
 
-- Construct with `sub`: `string`, `name`: `string` → [`UserInfo`](contracts.aug.md#symbol-UserInfo).
+It takes `authorization` as `optional string` from the HTTP header. It gets `clock` ([`Clock`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock)) and `access` ([`ExpiringStore<AccessGrant>`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore)) from dependency injection. Omitted optional inputs are null. It can also raise `HttpError` and `TimeError`.
 
-## Built-in operations used by this file
+If `authorization` is null, it continues without an operation. If `authorization` is not null, using `header` for it sets `parts` to `header.split` with `separator` `" "`. If the number of elements in `parts` equals `2`, if the item at index `0` in `parts` equals `"Bearer"`, it sets `token` to the item at index `1` in `parts`. If `token` is a URL-safe ASCII token with `43` to `43` characters, if [`access.get`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore.get) with `key` from `token` and `now` from [`clock.now`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock.now) is null, it continues without an operation.
 
-- `Headers.with` (`name`: `string`, `value`: `string`) → `Headers`: Return new headers with one additional validated field. Header names ignore case; duplicate values remain separate. Can fail with `HttpError`.
-- `List<string>.get` (`index`: `int`) → `string`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
-- `List<string>.length` (no inputs) → `int`: Read the number of elements.
-- `string.isToken` (`min`: `int`, `max`: `int`) → `bool`: Require an ASCII RFC 3986 unreserved token with a bounded length.
-- `string.split` (`separator`: `string`) → `List<string>`: Split at an exact separator, preserving empty parts.
+If [`access.get`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore.get) with `key` from `token` and `now` from [`clock.now`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock.now) is not null, using `grant` for it returns HTTP 200 with a `Json` with `value` from an [`UserInfo`](contracts.aug.md#symbol-UserInfo) with `sub` from `grant.subject` and `grant.name` and [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) headers. If this work raises `IndexError`, it continues without an operation. It sets `headers` to [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) with the header `"www-authenticate"` set to `"Bearer error=\"invalid_token\""`. It returns HTTP 401 with a `Json` with `value` from a map with `"error"` mapped to `"invalid_token"` and `headers` headers.
 
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+## Dependencies
 
-## Shared language rules
+It uses [`ExpiringStore`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore) ([`get`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore.get)) from `memory`. It uses [`Clock`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock) ([`now`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock.now)) from `time`. It uses [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) from `common`. It uses [`AccessGrant`](contracts.aug.md#symbol-AccessGrant) (`name` and `subject`) and [`UserInfo`](contracts.aug.md#symbol-UserInfo) from `contracts`.
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/oidc-login/provider/views.aug

@@ -1,6 +1,7 @@
+// aug-spec: "views.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Page from common
 /** A server form with a checked HTTP action. The browser submits to the provider endpoint. */
-ProviderLogin(string requestId, string csrf, string message, HttpAction submit) returns Html:
+ProviderLogin(string requestId, string csrf, string message, HttpAction submit) :
     return <Page title="Sign in with the August provider">
         <p>{message}</p>
         <p style="background:#f3f5f9;padding:12px;border-radius:8px">Demo account: <strong>ada</strong> · password <strong>august-demo</strong></p>
@@ -14,5 +15,5 @@ ProviderLogin(string requestId, string csrf, string message, HttpAction submit)
         <p style="font-size:14px;color:#677189">The provider and app run in the same executable. Authorization codes still travel through the OpenID Connect protocol.</p>
     </Page>
 
-ProviderFailure(string message) returns Html:
+ProviderFailure(string message) :
     return <Page title="Sign-in could not continue"><p>{message}</p><a href="/login/start">Start a new sign-in</a></Page>

package/examples/oidc-login/provider/views.aug.md

@@ -1,63 +1,19 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `views.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`ProviderLogin`](views.aug.md#symbol-ProviderLogin) is a function returning `Html`.
-- [`ProviderFailure`](views.aug.md#symbol-ProviderFailure) is a function returning `Html`.
+# `views.aug`
 
 <a id="symbol-ProviderLogin"></a>
+## `ProviderLogin` · [source](views.aug#L4)
 
-## `ProviderLogin`
-
-[source](views.aug#L3)
-
-**Inputs**
-
-- `requestId` (`string`) — required labeled input.
-- `csrf` (`string`) — required labeled input.
-- `message` (`string`) — required labeled input.
-- `submit` (`HttpAction`) — required labeled input.
+A server form with a checked HTTP action. The browser submits to the provider endpoint. It takes `requestId`, `csrf`, and `message` as strings and `submit` as `HttpAction`.
 
-Returns: `Html`.
-
-**What it does**
-
-- Return the server component [`Page`](../common/views.aug.md#symbol-Page) with `title` = `"Sign in with the August provider"` containing the HTML element `p` containing `message` (rendered on the server with embedded text escaped), the HTML element `p` with `style` = `"background:#f3f5f9;padding:12px;border-radius:8px"` containing `Demo account: `, the HTML element `strong` containing `ada` (rendered on the server with embedded text escaped), ` · password `, the HTML element `strong` containing `august-demo` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `form` with `method` = `"post"`, `action` = `"/provider/login"`, `onSubmit` = `submit` containing the HTML element `input` with `type` = `"hidden"`, `name` = `"request_id"`, `value` = `requestId` (rendered on the server with embedded text escaped), the HTML element `input` with `type` = `"hidden"`, `name` = `"csrf"`, `value` = `csrf` (rendered on the server with embedded text escaped), the HTML element `p` containing the HTML element `label` with `for` = `"username"` containing `Username` (rendered on the server with embedded text escaped), the HTML element `br` (rendered on the server with embedded text escaped), the HTML element `input` with `id` = `"username"`, `name` = `"username"`, `autocomplete` = `"username"`, `value` = `"ada"`, `maxlength` = `"64"`, `required` = `true`, `style` = `"padding:10px;width:90%"` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `p` containing the HTML element `label` with `for` = `"password"` containing `Password` (rendered on the server with embedded text escaped), the HTML element `br` (rendered on the server with embedded text escaped), the HTML element `input` with `id` = `"password"`, `type` = `"password"`, `name` = `"password"`, `autocomplete` = `"current-password"`, `maxlength` = `"256"`, `required` = `true`, `style` = `"padding:10px;width:90%"` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `button` with `type` = `"submit"`, `style` = `"padding:12px 20px;border:0;border-radius:9px;background:#4852d7;color:white;font:inherit"` containing `Sign in and return to the app` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `p` with `style` = `"font-size:14px;color:#677189"` containing `The provider and app run in the same executable. Authorization codes still travel through the OpenID Connect protocol.` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped).
-
-**Author documentation**
-
-A server form with a checked HTTP action. The browser submits to the provider endpoint.
+It returns the server component [`Page`](../common/views.aug.md#symbol-Page) with `title` = `"Sign in with the August provider"` containing a paragraph containing `message` with escaped text, a paragraph with `style` = `"background:#f3f5f9;padding:12px;border-radius:8px"` containing `Demo account: `, the HTML element `strong` containing `ada` with escaped text, ` · password `, the HTML element `strong` containing `august-demo` with escaped text with escaped text, the HTML element `form` with `method` = `"post"`, `action` = `"/provider/login"`, `onSubmit` = `submit` containing the HTML element `input` with `type` = `"hidden"`, `name` = `"request_id"`, `value` = `requestId` with escaped text, the HTML element `input` with `type` = `"hidden"`, `name` = `"csrf"`, `value` = `csrf` with escaped text, a paragraph containing the HTML element `label` with `for` = `"username"` containing `Username` with escaped text, the HTML element `br` with escaped text, the HTML element `input` with `id` = `"username"`, `name` = `"username"`, `autocomplete` = `"username"`, `value` = `"ada"`, `maxlength` = `"64"`, `required` = `true`, `style` = `"padding:10px;width:90%"` with escaped text with escaped text, a paragraph containing the HTML element `label` with `for` = `"password"` containing `Password` with escaped text, the HTML element `br` with escaped text, the HTML element `input` with `id` = `"password"`, `type` = `"password"`, `name` = `"password"`, `autocomplete` = `"current-password"`, `maxlength` = `"256"`, `required` = `true`, `style` = `"padding:10px;width:90%"` with escaped text with escaped text, a button with `type` = `"submit"`, `style` = `"padding:12px 20px;border:0;border-radius:9px;background:#4852d7;color:white;font:inherit"` containing `Sign in and return to the app` with escaped text with escaped text, a paragraph with `style` = `"font-size:14px;color:#677189"` containing `The provider and app run in the same executable. Authorization codes still travel through the OpenID Connect protocol.` with escaped text with escaped text.
 
 <a id="symbol-ProviderFailure"></a>
+## `ProviderFailure` · [source](views.aug#L18)
 
-## `ProviderFailure`
-
-[source](views.aug#L17)
-
-**Inputs**
-
-- `message` (`string`) — required labeled input.
-
-Returns: `Html`.
-
-**What it does**
-
-- Return the server component [`Page`](../common/views.aug.md#symbol-Page) with `title` = `"Sign-in could not continue"` containing the HTML element `p` containing `message` (rendered on the server with embedded text escaped), the HTML element `a` with `href` = `"/login/start"` containing `Start a new sign-in` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped).
-
-## Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-### [`Page`](../common/views.aug.md#symbol-Page)
-
-Function from `common`.
-
-- [`Page`](../common/views.aug.md#symbol-Page) (`title`: `string`, `children`: `List<Html>`) → `Html`.
+It takes `message` as a string. It returns the server component [`Page`](../common/views.aug.md#symbol-Page) with `title` = `"Sign-in could not continue"` containing a paragraph containing `message` with escaped text, a link with `href` = `"/login/start"` containing `Start a new sign-in` with escaped text with escaped text.
 
-## Shared language rules
+## Dependencies
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`Page`](../common/views.aug.md#symbol-Page) from `common`.

package/examples/ownership/.aug-spec/manifest.json

@@ -4,5 +4,5 @@
     "counter.aug.md",
     "main.aug.md"
   ],
-  "digest": "963a9ed380d8c2dcd5cb2f8545a9ace3770b304d6bb172d08a25283afc8b72a7"
+  "digest": "3ccf0836702f9d499e94848e741d62d26cd91dcd1fe1e6fd0cc7fbdc339a7579"
 }

package/examples/ownership/counter.aug

@@ -1,10 +1,11 @@
+// aug-spec: "counter.aug.md" explains this file. Read it before changes; refresh with aug spec.
 Counter(mutable int value) implements ICounter {
-    increment() changes self {
+    increment() {
         borrow self {
             value = value + 1
         }
     }
-    read() returns int {
+    read() {
         return value
     }
 }

package/examples/ownership/counter.aug.md

@@ -1,85 +1,31 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `counter.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`Counter`](counter.aug.md#symbol-Counter) is a class implementing `ICounter`.
-- [`ICounter`](counter.aug.md#symbol-ICounter) is an interface.
+# `counter.aug`
 
 <a id="symbol-Counter"></a>
+## `Counter` · class · [source](counter.aug#L2)
 
-## `Counter`
-
-[source](counter.aug#L1)
-
-Behavioral class.
-
-Satisfies [`ICounter`](counter.aug.md#symbol-ICounter).
-
-**Inputs**
-
-- `value` (`int`) — required labeled input — stored as `value` and mutable.
+It implements [`ICounter`](counter.aug.md#symbol-ICounter). It takes `value` as an integer, kept mutable.
 
 <a id="symbol-Counter.increment"></a>
+### `Counter.increment` · [source](counter.aug#L3)
 
-### `Counter.increment`
-
-[source](counter.aug#L2)
-
-Returns: no value.
-
-May change: `self`.
-
-**What it does**
-
-- Grant exclusive mutable access to `self` for this block, then end the borrow:
-  - Set `value` to `value` plus `1`.
+It may change `self`. With temporary permission to change `self`, it increases `value` by `1`.
 
 <a id="symbol-Counter.read"></a>
+### `Counter.read` · [source](counter.aug#L8)
 
-### `Counter.read`
-
-[source](counter.aug#L7)
-
-Returns: `int`.
-
-**What it does**
-
-- Return `value`.
+It returns `value`.
 
 <a id="symbol-ICounter"></a>
-
-## `ICounter`
-
-[source](counter.aug#L11)
-
-Interface.
+## `ICounter` · interface · [source](counter.aug#L12)
 
 <a id="symbol-ICounter.increment"></a>
+### `ICounter.increment` · [source](counter.aug#L13)
 
-### `ICounter.increment`
-
-[source](counter.aug#L12)
-
-Returns: no value.
-
-May change: `self`.
-
-Interface contract. A selected implementation supplies the behavior.
+It may change `self`.
 
 <a id="symbol-ICounter.read"></a>
+### `ICounter.read` · [source](counter.aug#L14)
 
-### `ICounter.read`
-
-[source](counter.aug#L13)
-
-Returns: `int`.
-
-Interface contract. A selected implementation supplies the behavior.
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It returns `int`.

package/examples/ownership/main.aug

@@ -1,3 +1,4 @@
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Counter from counter
 own Counter counter = Counter(value=1)
 counter.increment()

package/examples/ownership/main.aug.md

@@ -1,38 +1,13 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `main.aug` specification
+# `main.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+## Startup
 
-## In this file
+It sets `counter` of type [`Counter`](counter.aug.md#symbol-Counter) to a [`Counter`](counter.aug.md#symbol-Counter) with `value` `1`. `counter` of type [`Counter`](counter.aug.md#symbol-Counter) owns this value. It calls [`counter.increment`](counter.aug.md#symbol-Counter.increment). It prints [`counter.read`](counter.aug.md#symbol-Counter.read).
 
-- Run 3 other startup steps in source order.
+## Dependencies
 
-## Startup, in source order
+It uses [`Counter`](counter.aug.md#symbol-Counter) ([`increment`](counter.aug.md#symbol-Counter.increment) and [`read`](counter.aug.md#symbol-Counter.read)) from `counter`.
 
-- Set `counter` of type [`Counter`](counter.aug.md#symbol-Counter) to call [`Counter`](counter.aug.md#symbol-Counter) with `value` = `1`.
-- This variable owns the value.
-- Call [`Counter.increment`](counter.aug.md#symbol-Counter.increment) on `counter`.
-- Call `print` with `value` = call [`Counter.read`](counter.aug.md#symbol-Counter.read) on `counter`.
-
-## Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-### [`Counter`](counter.aug.md#symbol-Counter)
-
-Class from `counter`.
-
-- Construct with `value`: `int` → [`Counter`](counter.aug.md#symbol-Counter).
-- [`Counter.increment`](counter.aug.md#symbol-Counter.increment) (no caller inputs) → `void`; changes `self`.
-- [`Counter.read`](counter.aug.md#symbol-Counter.read) (no caller inputs) → `int`.
-
-## Built-in operations used by this file
-
-- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
-
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/ownership-transfer/.aug-spec/august/0.21.0/io/contracts.aug

@@ -0,0 +1,37 @@
+// Generated by aug spec. This is a copy of the installed dependency source.
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+/** Permission to write to a console, provided by an explicitly selected adapter. */
+capability Console:
+    /** Write one line of text. @param value Text to display. */
+    write<T>(T value) uses Console.write
+
+/** The native standard-output adapter. Construction performs no output. */
+SystemConsole() implements Console:
+    write<T>(T value):
+        print(value=value)
+
+/** Read UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileReader:
+    /** Read text. @param path File path. @throws FileError The file could not be read. */
+    read(string path) returns string uses FileReader.read unless FileError
+
+/** Write UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileWriter:
+    /** Write text. @param path File path. @param content Text. @throws FileError Writing failed. */
+    write(string path, string content) uses FileWriter.write unless FileError
+
+/** Native files. Operations are explicit; construction opens no files. */
+LocalFiles() implements FileReader, FileWriter:
+    read(string path) :
+        return read_file(path=path)
+    write(string path, string content) :
+        write_file(path=path, content=content)
+
+/** Read command-line input through an explicit dependency. */
+capability Arguments:
+    read() returns List<string> uses Arguments.read
+
+/** Native command-line arguments. */
+ProcessArguments() implements Arguments:
+    read() :
+        return arguments()

package/examples/ownership-transfer/.aug-spec/august/0.21.0/io/contracts.aug.md

@@ -0,0 +1,82 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `contracts.aug`
+
+<a id="symbol-Console"></a>
+## `Console` · capability interface · [source](contracts.aug#L4)
+
+Permission to write to a console, provided by an explicitly selected adapter.
+
+<a id="symbol-Console.write"></a>
+### `Console.write` · [source](contracts.aug#L6)
+
+Write one line of text. The type parameters are `T`. It takes `value` as `T` (Text to display). It can call [`Console.write`](contracts.aug.md#symbol-Console.write).
+
+<a id="symbol-SystemConsole"></a>
+## `SystemConsole` · class · [source](contracts.aug#L9)
+
+The native standard-output adapter. Construction performs no output. It implements [`Console`](contracts.aug.md#symbol-Console).
+
+<a id="symbol-SystemConsole.write"></a>
+### `SystemConsole.write` · [source](contracts.aug#L10)
+
+Write one line of text. The type parameters are `T`. It takes `value` as `T` (Text to display). It prints `value`.
+
+<a id="symbol-FileReader"></a>
+## `FileReader` · capability interface · [source](contracts.aug#L14)
+
+Read UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileReader.read"></a>
+### `FileReader.read` · [source](contracts.aug#L16)
+
+Read text. It takes `path` as a string (File path).
+
+It returns `string`. It can call [`FileReader.read`](contracts.aug.md#symbol-FileReader.read). Failures can raise `FileError` (The file could not be read).
+
+<a id="symbol-FileWriter"></a>
+## `FileWriter` · capability interface · [source](contracts.aug#L19)
+
+Write UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileWriter.write"></a>
+### `FileWriter.write` · [source](contracts.aug#L21)
+
+Write text. It takes `path` as a string (File path) and `content` as a string (Text). It can call [`FileWriter.write`](contracts.aug.md#symbol-FileWriter.write). Failures can raise `FileError` (Writing failed).
+
+<a id="symbol-LocalFiles"></a>
+## `LocalFiles` · class · [source](contracts.aug#L24)
+
+Native files. Operations are explicit; construction opens no files. It implements [`FileReader`](contracts.aug.md#symbol-FileReader) and [`FileWriter`](contracts.aug.md#symbol-FileWriter).
+
+<a id="symbol-LocalFiles.read"></a>
+### `LocalFiles.read` · [source](contracts.aug#L25)
+
+Read text. It takes `path` as a string (File path). Failures can raise `FileError` (The file could not be read). It returns `read_file` with `path`.
+
+<a id="symbol-LocalFiles.write"></a>
+### `LocalFiles.write` · [source](contracts.aug#L27)
+
+Write text. It takes `path` as a string (File path) and `content` as a string (Text). Failures can raise `FileError` (Writing failed). It calls `write_file` with `path` and `content`.
+
+<a id="symbol-Arguments"></a>
+## `Arguments` · capability interface · [source](contracts.aug#L31)
+
+Read command-line input through an explicit dependency.
+
+<a id="symbol-Arguments.read"></a>
+### `Arguments.read` · [source](contracts.aug#L32)
+
+It returns `List<string>`. It can call [`Arguments.read`](contracts.aug.md#symbol-Arguments.read).
+
+<a id="symbol-ProcessArguments"></a>
+## `ProcessArguments` · class · [source](contracts.aug#L35)
+
+Native command-line arguments. It implements [`Arguments`](contracts.aug.md#symbol-Arguments).
+
+<a id="symbol-ProcessArguments.read"></a>
+### `ProcessArguments.read` · [source](contracts.aug#L36)
+
+It returns `arguments`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/ownership-transfer/.aug-spec/manifest.json

@@ -1,10 +1,10 @@
 {
   "format": 1,
   "files": [
-    ".aug-spec/august/0.19.0/io/contracts.aug",
-    ".aug-spec/august/0.19.0/io/contracts.aug.md",
+    ".aug-spec/august/0.21.0/io/contracts.aug",
+    ".aug-spec/august/0.21.0/io/contracts.aug.md",
     "main.aug.md",
     "resource.aug.md"
   ],
-  "digest": "0647bd67edecc9f86adc5dfccefbfac3fb6aa5d23e2e010c4bb4e657d37bb259"
+  "digest": "b280d365f556538b71dc053ac6be0f2eee02eb87d72f228ebcc02ab357ece4ab"
 }

package/examples/ownership-transfer/main.aug

@@ -1,3 +1,4 @@
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console and SystemConsole from august.io
 implement Console with SystemConsole
 import Resource from resource

package/examples/ownership-transfer/main.aug.md

@@ -1,63 +1,19 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `main.aug` specification
+# `main.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+## Providers
 
-## In this file
+`Console` is provided by [`SystemConsole`](.aug-spec/august/0.21.0/io/contracts.aug.md#symbol-SystemConsole). The same instance is shared.
 
-- Register 1 dependency provider before startup.
-- Run 4 other startup steps in source order.
+## Startup
 
-## Dependency providers
+It gets `first` of type [`Resource`](resource.aug.md#symbol-Resource) from [`make`](resource.aug.md#symbol-make). `first` of type [`Resource`](resource.aug.md#symbol-Resource) owns this value. It calls [`consume`](resource.aug.md#symbol-consume) with `value` from `first` using injected `Console` for `console`. It gets `second` of type [`Resource`](resource.aug.md#symbol-Resource) from [`make`](resource.aug.md#symbol-make).
 
-Register these providers before startup. Their declaration order does not set initialization order; shared instances initialize in dependency order.
+`second` of type [`Resource`](resource.aug.md#symbol-Resource) owns this value. It prints `"end of main"`.
 
-- Provide [`SystemConsole`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-SystemConsole) when `Console` is requested. Reuse one instance.
+## Dependencies
 
-## Startup, in source order
+It uses [`SystemConsole`](.aug-spec/august/0.21.0/io/contracts.aug.md#symbol-SystemConsole) from `august.io`. It uses [`Resource`](resource.aug.md#symbol-Resource), [`consume`](resource.aug.md#symbol-consume), and [`make`](resource.aug.md#symbol-make) from `resource`.
 
-- Set `first` of type [`Resource`](resource.aug.md#symbol-Resource) to call [`make`](resource.aug.md#symbol-make).
-- This variable owns the value.
-- Call [`consume`](resource.aug.md#symbol-consume) with `value` = `first`; inject `console` from `Console`.
-- Set `second` of type [`Resource`](resource.aug.md#symbol-Resource) to call [`make`](resource.aug.md#symbol-make).
-- This variable owns the value.
-- Call `print` with `value` = `"end of main"`.
-
-## Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-### [`SystemConsole`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-SystemConsole)
-
-Class from `august.io`.
-
-Used as a type or provider.
-
-### [`Resource`](resource.aug.md#symbol-Resource)
-
-Class from `resource`.
-
-Used as a type or provider.
-
-### [`consume`](resource.aug.md#symbol-consume)
-
-Function from `resource`.
-
-- [`consume`](resource.aug.md#symbol-consume) (`value`: [`Resource`](resource.aug.md#symbol-Resource)) → `void`; inject `console`: [`Console`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console); uses [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
-
-### [`make`](resource.aug.md#symbol-make)
-
-Function from `resource`.
-
-- [`make`](resource.aug.md#symbol-make) (no caller inputs) → [`Resource`](resource.aug.md#symbol-Resource).
-
-## Built-in operations used by this file
-
-- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
-
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/ownership-transfer/resource.aug

@@ -1,3 +1,4 @@
+// aug-spec: "resource.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console from august.io
 Resource() implements IResource {
     drop() {
@@ -11,6 +12,6 @@ make() returns own Resource {
     own Resource value = Resource()
     return value
 }
-consume(resolve Console console, own Resource value) uses Console.write {
+consume(resolve Console console, own Resource value) {
     console.write(value="consumed")
 }