Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions .machine_readable/contractiles/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@
:toc:
:sectnums:

This directory contains the canonical contractile templates for the
hyperpolymath estate. `rsr-template-repo` mirrors the standards master
structure; copy `.machine_readable/contractiles/` into a new repo to
establish a consistent operational, validation, trust, recovery,
aspiration, and service-automation framework.
This directory holds this repository's copy of the estate contractile set. It
follows the structure of the standards master, by way of `rsr-template-repo`
(the repository this one was minted from). The same set can be copied into
another repo to establish a consistent operational, validation, trust,
recovery, aspiration, and service-automation framework.

[IMPORTANT]
====
Expand Down
153 changes: 64 additions & 89 deletions docs/AI_INSTALLATION_GUIDE.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@
:toclevels: 3
:sectnums:

This guide is for an **AI agent** instantiating this template into a new
repository. A human following it will not be misled, but the ordering and the
warnings are written for an agent working non-interactively.
This guide is for an *AI agent* installing, using or verifying the Julia
package `CoprocessorRuntime.jl`. A human following it will not be misled; the
ordering and the warnings are written for an agent working non-interactively.

[[ai-implementation]]
== Implementation for an AI agent
Expand All @@ -16,118 +16,93 @@ warnings are written for an agent working non-interactively.

Read, in this order, before running anything:

. `*_chora.deed` (the repo deed) — the universal AI entry point at the repository root.
. `CLAUDE.md` — the generated arrival pack (estate doctrine + repo identity).
. `.machine_readable/descriptiles/STATE.a2ml` — current phase and completion.
. `*_chora.deed` (the repo deed) at the repository root.
. `CLAUDE.md` -- the generated arrival pack (estate doctrine and repo identity).
. `README.adoc` -- what the package is and is not.

Do not infer the repository's purpose from its name. If a fact is not written
down, record it as `UNASSIGNED` rather than inventing it.
Do not infer the package's capabilities from its name. It is a host-side
contract and evidence layer: it records launch semantics and does not run
accelerator kernels, select a backend, or prove CNO/OND. If a fact is not
written down, report it as unknown rather than inventing it.

=== 2. Obtain the template
=== 2. Install the package as a dependency

Always take the template from `origin/main`, never from a local working tree —
local checkouts across this estate are routinely stale or carry sweep debris.
The package is not in the Julia General registry. Install it by URL:

[source,bash]
[source,julia]
----
git clone https://github.com/hyperpolymath/rsr-template-repo.git my-project
cd my-project
rm -rf .git && git init
using Pkg
Pkg.add(url="https://github.com/hyperpolymath/CoprocessorRuntime.jl")
----

Alternatively, use GitHub's *Use this template* button, which produces a repo
with no git ancestry; `just repo-init` recovers the template tip via
`git ls-remote` and records it as the `parent-pin`.
It needs Julia 1.10 or later and has no dependencies of its own.
`AcceleratorGate.jl` is an optional weak dependency, also not in General; add it
by URL only if the `coprocessor_kind` mapping is wanted.

=== 3. Or work on a checkout

=== 3. Run the instantiation
When no revision is requested, take the repository from `origin/main`, never
from a stale local working tree. When a pull request or branch is named, check
out and test that revision instead.

[source,bash]
----
just repo-init # or: just repo-init <archetype>
git clone https://github.com/hyperpolymath/CoprocessorRuntime.jl.git
cd CoprocessorRuntime.jl
julia --project=. -e 'using Pkg; Pkg.test()'
----

`just repo-init` renders every `{{TOKEN}}` in the tree, derives the repository
identity, writes the provenance files, and removes the template-only
directories.
`Pkg.test()` runs Aqua and the case files in `test/cases`. On Julia 1.11 it
also runs `test/ext` in a subprocess, which fetches `AcceleratorGate` from
GitHub; on Julia 1.10 that step is recorded as one `Broken` test. Set
`COPROCESSORRUNTIME_SKIP_EXT_TESTS=1` to skip it (it is then also recorded as
one `Broken` test, not dropped).

[WARNING]
====
**Do not set `RSR_NON_INTERACTIVE=1`.** It stubs the shell builtin `read`
globally, which also disables the two `while read -r file` loops that drive
substitution. The result is an infinite loop that performs zero substitution —
it does not fail, it never terminates.

Drive it non-interactively by **piping answers to stdin** instead. Real `read`
stays intact, so the data loops work.
====

The prompts, in order, are:

[cols="1,3",options="header"]
|===
| # | Prompt

| 1 | Project name
| 2 | Repository slug — validated against `^[a-z0-9]+(-[a-z0-9]+)*$`; no capitals, spaces or underscores (it must be a valid Guix package name)
| 3 | Owner
| 4 | Author full name
| 5 | Author email
| 6 | Author organisation
| 7 | Previous/alternate email
| 8 | Project description
| 9 | Forge domain
| 10 | Security email
| 11 | Conduct email
| 12 | Project type
| 13 | Website URL (blank = default)
| 14 | OpenSSF Best Practices ID (blank = none)
| 15 | Service name (blank = default)
| 16 | Primary port (blank = 8080)
| 17 | Container registry (blank = default)
| 18 | Proceed? — answer `y`
|===

[IMPORTANT]
====
Prompts 15–17 are gated on the presence of the container directory, **not** on
the project type. The template always ships one, so they always fire. Supplying
only 15 answers makes `read` hit EOF, which returns 1 and kills the recipe under
`set -e`.
Running the tests on Julia 1.11 writes `test/ext/Manifest.toml`, and
`--project=.` use writes a root `Manifest.toml`. Both are listed in
`.gitignore`; do not force-add them. Use a scratch copy and a scratch
`JULIA_DEPOT_PATH` if the working tree must stay clean.
====

=== 4. Verify the result

[source,bash]
[source,julia]
----
just --list # every recipe resolves (imports are silent on failure)
just check-root-shape # root matches the allowlist
bash scripts/check-no-placeholders.sh .
just verify
using CoprocessorRuntime
s = open_session(GPUKind())
r = issue_receipt(s; warrant = WarrantOnly, claim = "planned")
@assert !host_may_claim(r)
close_session!(s)
----

A successful instantiation leaves **no** `{{TOKEN}}` anywhere in the tree, and
removes the template-only directories from the minted repository. If
`scripts/validate-template.sh` or the end-to-end instantiation test are still
present, the repository was not cured — they are the clearest single marker of
an un-instantiated repo.
A correct install loads without error and the assertion passes. See
`QUICKSTART.adoc` for a longer first run and its expected output.

=== 5. What not to claim

* Do not report a CNO or OND claim as proved. Status is `:unproved` or
`:model_checked`.
* Do not report a receipt as host knowledge unless `host_may_claim` is true.
* Do not treat `Idris`, `Zig` or other files under `src/interface/` as the
Julia API; that seam is not wired to this package (`src/README.adoc`).

== Privacy

This template performs no telemetry and transmits nothing during installation.
The package performs no telemetry and makes no network requests: `src/` and
`ext/` contain no network or file I/O.

Note what instantiation *records*, all of it locally and in your own git history:
What does touch the network is installation and testing, not the package:

* The identity you supply at prompts 3–7 (owner, author name, both email
addresses, organisation) is written into source headers, `CITATION.cff`,
`.mailmap`, `CODEOWNERS` and the security contact. Treat the alternate email
as published data.
* `just repo-init` runs `git ls-remote` against the template's forge to resolve
the parent pin. This is a single outbound request; when it is unavailable the
pin is recorded as `UNASSIGNED` rather than guessed.
* The clade UUID is *derived*, never allocated:
`uuidgen --sha1 --namespace @url --name "<forge>/<owner>/<repo>"`. It is a
function of the repository's name, so renaming the repository changes it and
registries must be regenerated rather than string-swapped.
* `Pkg.add(url=...)` and `git clone` fetch from GitHub.
* `Pkg.test()` on any supported Julia needs the Aqua test dependency
(`[extras]` and `[targets]` in `Project.toml`). With an empty depot, even on
Julia 1.10, where the extension tests are skipped, it can download Aqua and
the General registry data needed to resolve it.
* `Pkg.test()` on Julia 1.11 also fetches `AcceleratorGate.jl` from GitHub at
the commit pinned in `test/ext/Project.toml`, and may update the Julia General
registry.

If you are an agent acting on someone else's behalf, do not invent identity
values to satisfy a prompt. Leave them `UNASSIGNED` and report the gap.
Do not invent identity values (owner, author, email) when editing files; report
a gap instead.
Loading
Loading