@awebai/oats 0.69.12 → 0.69.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +216 -178
- package/bin/oats.mjs +254 -201
- package/docs/capabilities.md +58 -13
- package/docs/configuration.md +63 -5
- package/docs/container.md +291 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +590 -55
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +84 -9
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +99 -32
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/release-notes/v0.69.15.md +444 -0
- package/docs/schedules.md +159 -5
- package/docs/servers.md +241 -7
- package/docs/souls-and-instances.md +223 -14
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +36 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +20 -5
- package/lib/command-flags.mjs +240 -0
- package/lib/core.mjs +1004 -633
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +145 -33
- package/lib/errors.mjs +3 -2
- package/lib/harness-token.mjs +110 -0
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +165 -14
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +114 -43
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/kernel-features.mjs +4 -1
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +4 -1
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +126 -31
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +239 -21
- package/lib/servers.mjs +161 -28
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +63 -56
- package/lib/session-seen.mjs +3 -14
- package/lib/start-env.mjs +13 -7
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +68 -10
- package/package-catalog.json +1 -1
- package/package.json +5 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/packages/record/README.md +56 -21
- package/packages/record/docs/capture-service.md +8 -5
- package/packages/record/docs/turn-record-sot.md +9 -0
- package/packages/record/lib/capture-health.mjs +6 -4
- package/packages/record/lib/capture-lock.mjs +31 -27
- package/packages/record/lib/capture-retained-scratch.mjs +4 -3
- package/packages/record/lib/capture-scratch.mjs +2 -1
- package/packages/record/lib/derived-state.mjs +4 -2
- package/packages/record/lib/index-db.mjs +4 -2
- package/packages/record/lib/lock-holder.mjs +21 -0
- package/packages/record/lib/private-files.mjs +18 -0
- package/packages/record/lib/process-identity.mjs +310 -0
- package/packages/record/lib/store.mjs +31 -25
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +93 -26
- package/lib/tmux-config.mjs +0 -35
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Knowledge and learning
|
|
2
|
+
|
|
3
|
+
How OATS agents keep what they learn, so that every new instance of a soul starts wiser than the last. This page describes our default approach, implemented by the official `oats.okf` knowledge capability. Other knowledge capabilities can adopt it, adapt it or work differently.
|
|
4
|
+
|
|
5
|
+
## Four kinds of value, four places
|
|
6
|
+
|
|
7
|
+
An experienced agent carries four kinds of value, and each belongs in a different place:
|
|
8
|
+
|
|
9
|
+
- **Reusable procedures and know-how** belong in skills and capabilities. How to run a release is a skill.
|
|
10
|
+
- **Lasting judgment and the larger picture** belong in the knowledge base. Why a release must verify the installed artifact is a lesson.
|
|
11
|
+
- **A detailed understanding of the current problem** belongs in the instance's working context.
|
|
12
|
+
- **Unfinished work and next steps** belong in the instance's own state. Which release check is still running is state.
|
|
13
|
+
|
|
14
|
+
Only the second goes into the knowledge base.
|
|
15
|
+
|
|
16
|
+
## Keep expertise, not a second description of the code
|
|
17
|
+
|
|
18
|
+
> **Knowledge is what makes an expert an expert in a subject or project. It is not a description of what lives in the code.**
|
|
19
|
+
|
|
20
|
+
A lesson is kept when both answers are yes:
|
|
21
|
+
|
|
22
|
+
1. Would a future instance of this soul act differently for knowing it?
|
|
23
|
+
2. Is it something the instance could not learn by simply reading the repository?
|
|
24
|
+
|
|
25
|
+
- **Kept:** decisions and their reasons, rejected alternatives, discoveries, research conclusions, design inspiration, and awareness of the larger situation.
|
|
26
|
+
- **Not kept:** code structure, file maps, ordinary task progress, or anything the repository already makes clear. A second copy of what the code says only grows stale.
|
|
27
|
+
|
|
28
|
+
## Souls divide the knowledge base
|
|
29
|
+
|
|
30
|
+
- The knowledge base is divided into areas, such as the release process, the kernel or the design system.
|
|
31
|
+
- Each area has exactly one owning soul. Its instances' lessons are proposed to that area, and other souls hand lessons for it to its owner. Keeping the base consistent is maintenance, done by a knowledge maintainer or a person.
|
|
32
|
+
- Other souls read an area when their work touches it, and link to it rather than copying it.
|
|
33
|
+
- So every agent starts with a well-defined context: the area its soul owns, and the few it reads. Every area lives in one place, owned by one kind of agent.
|
|
34
|
+
- Each instance of a soul keeps its own working context and state for its own piece of work.
|
|
35
|
+
- Adopting someone else's published soul does not send your learning back to its publisher.
|
|
36
|
+
|
|
37
|
+
## How learning flows
|
|
38
|
+
|
|
39
|
+
1. **Instances work and capture evidence.** Each one keeps notes on what it decided and discovered.
|
|
40
|
+
2. **An independent harvester judges what is worth keeping,** at set moments such as a pull request handed over or a task finished.
|
|
41
|
+
3. **The proposal is validated and delivered** through the knowledge base's acceptance process. For a Git-backed knowledge base that is a pull request, reviewed by a knowledge maintainer agent or a person.
|
|
42
|
+
4. **Future instances consult the accepted result.**
|
|
43
|
+
|
|
44
|
+
Working instances never rewrite the accepted knowledge base directly. An open pull request is not yet accepted knowledge, and a delivery receipt does not prove that a person approved it or that another instance has read it.
|
|
45
|
+
|
|
46
|
+
## Our default: oats.okf
|
|
47
|
+
|
|
48
|
+
- It uses **Open Knowledge Format**: readable Markdown concepts with metadata, links and history.
|
|
49
|
+
- A team shares its knowledge bases, one or more, divided among its souls as above.
|
|
50
|
+
- It needs explicit bindings and setup; not every step is automatic.
|
|
51
|
+
|
|
52
|
+
## Your own way
|
|
53
|
+
|
|
54
|
+
OATS provides the contracts, and the knowledge capability decides how knowledge works. With the right capability you can, for example:
|
|
55
|
+
|
|
56
|
+
- let new instances inherit a soul's accumulated expertise;
|
|
57
|
+
- let instances of one soul develop their own specialisations from a shared foundation;
|
|
58
|
+
- let a long-running instance keep its working understanding across many tasks;
|
|
59
|
+
- turn selected learning into shared knowledge after review.
|
|
60
|
+
|
|
61
|
+
A knowledge capability can organise knowledge per soul, per topic or per project, centrally or next to the soul definitions, as long as it actually supports the arrangement you choose. Messaging and tasks work the same way: OATS provides the contracts, and you choose how your team works through them.
|
|
62
|
+
|
|
63
|
+
## Expertise can evolve
|
|
64
|
+
|
|
65
|
+
- Souls can widen their scope, hand an area to a better-placed soul, merge, or split into more specialised souls.
|
|
66
|
+
- A deliberate split into new reusable specialisations is called **speciation**. A generalist that keeps handling UX work, for example, can give rise to a dedicated UX expert. The new expert owns the UX area, and the generalist consults it rather than duplicating it.
|
|
67
|
+
- These changes are proposed and reviewed. A busy period or a large pile of notes is not enough on its own, and no agent reshapes its own soul.
|
|
68
|
+
|
|
69
|
+
## Learn more
|
|
70
|
+
|
|
71
|
+
- [Knowledge, instances and evolving expertise](knowledge-theory.md): the full model, including long-running instances, harvesting, maintenance, hand-offs and cloning.
|
|
72
|
+
- [Knowledge operations](knowledge.md): how the knowledge capability is set up and run.
|
|
@@ -73,10 +73,19 @@
|
|
|
73
73
|
"additionalProperties": {
|
|
74
74
|
"oneOf": [
|
|
75
75
|
{ "type": "string" },
|
|
76
|
-
{ "type": "object", "additionalProperties": false, "required": ["fromEnv"], "properties": { "fromEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } }
|
|
76
|
+
{ "type": "object", "additionalProperties": false, "required": ["fromEnv"], "properties": { "fromEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } },
|
|
77
|
+
{ "type": "object", "additionalProperties": false, "required": ["fromFile"], "properties": { "fromFile": { "type": "string", "pattern": "^/[^\\u0000]*$" } } }
|
|
77
78
|
]
|
|
78
79
|
},
|
|
79
|
-
"
|
|
80
|
+
"allOf": [{ "properties": {
|
|
81
|
+
"HOME": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
82
|
+
"PATH": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
83
|
+
"CLAUDE_CONFIG_DIR": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
84
|
+
"CODEX_HOME": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
85
|
+
"PI_CODING_AGENT_DIR": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
86
|
+
"PI_CODING_AGENT_SESSION_DIR": { "not": { "type": "object", "required": ["fromFile"] } }
|
|
87
|
+
} }],
|
|
88
|
+
"description": "Environment for the harness. A string is a literal (non-secret by contract; still redacted in every answer). {fromEnv: NAME} is resolved from the execution host's environment at start time; the reference, never the value, is recorded. A missing reference refuses the start before anything stops. {fromFile: /absolute/path} reads a regular UTF-8 file of at most 64 KiB (source bytes including a final newline) on the execution host at every start, stripping one trailing LF or CRLF. NUL, missing, unreadable or nonregular files refuse with E_LAUNCH_ENV_MISSING. Both reference kinds are redacted and recorded only as keyed digests. fromFile is for credential values; directory selectors require a literal or fromEnv."
|
|
80
89
|
},
|
|
81
90
|
"model": { "type": "string", "minLength": 1, "description": "Model for this configuration's harness; overrides the soul default when this configuration is selected." },
|
|
82
91
|
"yolo": { "type": "boolean", "description": "Permission bypass for this configuration; overrides scope and soul defaults when selected." },
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,10 +9,10 @@ or workspace membership alone does not make a package official.
|
|
|
9
9
|
|
|
10
10
|
| package | release | capabilities | package souls |
|
|
11
11
|
|---|---|---|---|
|
|
12
|
-
| `oats.framework` | `oats-framework/v1.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.23.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
|
|
13
13
|
| `oats.okf` | `v5.8.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
14
|
| `oats.aweb` | `v1.37.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
|
|
15
|
-
| `oats.engineering` | `v1.18.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
15
|
+
| `oats.engineering` | `v1.18.0` (frozen: see Coordination templates) | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
16
16
|
| `oats.authoring` | `v1.0.3` | `oats.authoring` | |
|
|
17
17
|
| `oats.cloning` | `v1.1.0` | `oats.cloning` | `cloner` |
|
|
18
18
|
| `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
|
|
@@ -21,12 +21,46 @@ or workspace membership alone does not make a package official.
|
|
|
21
21
|
| `oats.machine` | `v0.1.1` | `oats.machine-care` | `steward`, `technician` |
|
|
22
22
|
|
|
23
23
|
Each package lives in its own `awebai/oats-*` repository except
|
|
24
|
-
`oats.framework`, whose payload root is `oats-package/` here. A capability
|
|
25
|
-
|
|
26
|
-
`oats.developer: { from: package }`
|
|
24
|
+
`oats.framework`, whose payload root is `oats-package/` here. A capability
|
|
25
|
+
written `{ from: package }` resolves through the workspace's lock, to the one
|
|
26
|
+
locked package whose capability list holds it: `oats.developer: { from: package }`
|
|
27
|
+
selects `oats.engineering` when that package is pinned and synced. Two locked
|
|
28
|
+
packages providing the same capability are refused with `E_PACKAGE_MISSING`,
|
|
29
|
+
which names both. The catalog's `capabilities` map records which official
|
|
30
|
+
package ships each capability (and a renamed capability's current name:
|
|
31
|
+
`oas.okf` is `oats.okf`); the kernel reads it only to pick a standalone
|
|
32
|
+
deployment's package (the one that ships `oats.core`). This catalog ships with
|
|
27
33
|
the CLI: an older installed CLI keeps its own copy, and a change here rewrites
|
|
28
34
|
no lock and adds nothing to an existing workspace.
|
|
29
35
|
|
|
36
|
+
## Coordination templates
|
|
37
|
+
|
|
38
|
+
OATS's coordination ships as templates, not packages: one for each way of
|
|
39
|
+
working, each in its own repository. An installed kernel's
|
|
40
|
+
copy of this catalog carries this section from the next kernel release; the
|
|
41
|
+
onboarding skills name the engineering template directly, so they work on an
|
|
42
|
+
older kernel too. A template is a
|
|
43
|
+
repository that a setup expert copies into a workspace's own capabilities and
|
|
44
|
+
adapts to the organisation by the repository's `ADAPTING.md`
|
|
45
|
+
(`/adapt-to-the-organisation`, in `oats.framework`); nobody pins it. Template
|
|
46
|
+
releases are tagged `template-v<version>`. Each copied capability records the
|
|
47
|
+
release it came from in its description, and the copy records it as a whole in
|
|
48
|
+
`capabilities/TEMPLATE-RELEASE`.
|
|
49
|
+
|
|
50
|
+
| Template | Latest release | Way of working |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| `oats-project/oats-engineering-coordination` | `template-v3.0.1` | Work that lands as pull requests: a dispatcher, a lead for each effort that builds a change itself or sends developers, whoever builds it iterating with a fresh reviewer each round, and a maintainer where a lane needs one. |
|
|
53
|
+
| `oats-project/oats-research-coordination` | `template-v2.0.0` | Work that ends in a finding or a report: a dispatcher, a research lead for each question that researches a single small angle itself or sends a researcher for each, and a verifier briefed to disprove, which checks the lead's own claims too. A report lands when the person who asked accepts it. |
|
|
54
|
+
| `oats-project/oats-scientific-research-coordination` | `template-v2.0.0` | Studies that end in claims a person is accountable for: a dispatcher, a study lead for each study, an analyst for each arm of a locked protocol, fresh study reviewers for the methods, an independent check, leakage and citations, and a record steward that locks protocols and keeps the study records. A claim lands when the scientist accepts it; one that leaves the group needs a check that isn't LLM judgement. |
|
|
55
|
+
|
|
56
|
+
The package `oats.engineering` is frozen at `v1.18.0`. Its entry and its four
|
|
57
|
+
aliases stay, so existing pins keep resolving, and its repository,
|
|
58
|
+
`oats-project/oats-engineering`, gets no further releases. The engineering
|
|
59
|
+
template that replaces it lives in its own repository, above; a workspace that
|
|
60
|
+
pins the package moves to it by the template's `ADAPTING.md` and the "From
|
|
61
|
+
v1.18.0" steps in its CHANGELOG. Open: retiring the entry and moving the
|
|
62
|
+
aliases, a later decision once no workspace we know of pins it.
|
|
63
|
+
|
|
30
64
|
## Find and use packages
|
|
31
65
|
|
|
32
66
|
- A workspace pins an official package by **bare version** in its
|
package/docs/packages.md
CHANGED
|
@@ -28,7 +28,11 @@ A Git repository **contains** a package at `oats-package/`:
|
|
|
28
28
|
```
|
|
29
29
|
|
|
30
30
|
`oats-package.json` must declare `package` and `capabilities` (a list of
|
|
31
|
-
directories relative to the package root, each holding an `oats.json`).
|
|
31
|
+
directories relative to the package root, each holding an `oats.json`). The
|
|
32
|
+
`package` must equal the `packages:` key the package is pinned under: a
|
|
33
|
+
package is locked under its own id, and its souls are named after it
|
|
34
|
+
(`<package>/<soul>`). `sync` refuses a pin whose manifest names another id
|
|
35
|
+
(`E_PACKAGE_INTEGRITY { why: "package-id" }`, see [`oats sync`](#oats-sync--the-one-command-for-the-common-path)). It may
|
|
32
36
|
also declare `souls`: soul directories the package ships, see
|
|
33
37
|
[Package souls](#package-souls). A
|
|
34
38
|
directory entry need not equal the capability's name
|
|
@@ -51,7 +55,7 @@ packages:
|
|
|
51
55
|
- **Bare version** (`v5.8.0`, `5.8.0`, `1.0.0-rc.1`): the id is looked up in
|
|
52
56
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
53
57
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
54
|
-
convention (`v5.8.0` or `oats-framework/v1.
|
|
58
|
+
convention (`v5.8.0` or `oats-framework/v1.23.0`) and the payload path. An id
|
|
55
59
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
56
60
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
57
61
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -74,7 +78,7 @@ members:
|
|
|
74
78
|
- git:github.com/acme/agents
|
|
75
79
|
- git:github.com/acme/platform
|
|
76
80
|
packages:
|
|
77
|
-
oats.framework: v1.
|
|
81
|
+
oats.framework: v1.23.0
|
|
78
82
|
oats.okf: v5.8.0
|
|
79
83
|
oats.aweb: v1.37.0
|
|
80
84
|
teams:
|
|
@@ -117,12 +121,29 @@ lock oats-lock.json
|
|
|
117
121
|
|
|
118
122
|
1. discovers the workspace over the remotes and confirms every member;
|
|
119
123
|
2. resolves each `packages:` entry to a commit (`observeRemote`), reads its
|
|
120
|
-
manifests,
|
|
121
|
-
|
|
124
|
+
manifests, checks that `oats-package.json` names the `packages:` key it is
|
|
125
|
+
pinned under, computes the **integrity** (content digest of the package
|
|
126
|
+
tree) and records `url`, `path`, `version`, `commit`, `integrity`,
|
|
127
|
+
`capabilities`. A manifest naming another package is refused before
|
|
128
|
+
anything is written: `E_PACKAGE_INTEGRITY { why: "package-id", id,
|
|
129
|
+
manifestPackage, commit }`, whose message names the line to write instead:
|
|
130
|
+
- a catalog version whose named package is in the catalog: `<named>: <the
|
|
131
|
+
same version>`;
|
|
132
|
+
- a catalog version whose named package is not: `<named>:
|
|
133
|
+
git:<the catalog entry's repo>@<the resolved tag>` (no line when the
|
|
134
|
+
catalog entry reads another `path` than `oats-package/`, which a `git:`
|
|
135
|
+
pin cannot reach);
|
|
136
|
+
- a `git:` pin: `<named>: <the same git: value>`.
|
|
137
|
+
|
|
138
|
+
The other way out is a version of the key's package whose manifest names
|
|
139
|
+
that key;
|
|
122
140
|
3. for an entry already locked at the same version/source/path: the commit must
|
|
123
141
|
be unchanged (else `E_PACKAGE_INTEGRITY` — "the tag moved; a version string
|
|
124
|
-
must change when its content does")
|
|
125
|
-
(`E_PACKAGE_INTEGRITY`)
|
|
142
|
+
must change when its content does"), the integrity must match
|
|
143
|
+
(`E_PACKAGE_INTEGRITY`), and the manifest must still name the key
|
|
144
|
+
(`why: "package-id"`, as in step 2: a lock an older kernel wrote under
|
|
145
|
+
another package's id is refused at the next sync; spawns from it keep
|
|
146
|
+
working until then);
|
|
126
147
|
4. writes `oats-lock.json` and reports the diff. Entries dropped from
|
|
127
148
|
`packages:` are dropped from the lock.
|
|
128
149
|
|
|
@@ -202,9 +223,12 @@ Member capabilities are trusted by membership; **a package is trusted by its
|
|
|
202
223
|
declaration in the workspace's `packages:`**. People declare a package only
|
|
203
224
|
when they trust it, so there is no second, per-version approval step. The lock is reproducibility, not approval: it pins
|
|
204
225
|
the exact commit and the content integrity, a moved tag or drifted content is
|
|
205
|
-
`E_PACKAGE_INTEGRITY`,
|
|
206
|
-
|
|
207
|
-
|
|
226
|
+
`E_PACKAGE_INTEGRITY`, a package pinned under another package's id is
|
|
227
|
+
`E_PACKAGE_INTEGRITY { why: "package-id" }` at sync, and at spawn the lock's
|
|
228
|
+
capability list must match what the package declares at the locked commit
|
|
229
|
+
(`E_PACKAGE_INTEGRITY { why: "capabilities" }`) and the package tree there must
|
|
230
|
+
digest to the lock's `integrity`
|
|
231
|
+
([The integrity check at spawn](#the-integrity-check-at-spawn)).
|
|
208
232
|
|
|
209
233
|
## Materialization from a package
|
|
210
234
|
|
|
@@ -217,6 +241,56 @@ against what the fetch reported; skills are copied to
|
|
|
217
241
|
`packages:` and syncing affects **only new spawns**; `oats status` shows a
|
|
218
242
|
running instance's package module as `moved` once the lock points elsewhere.
|
|
219
243
|
|
|
244
|
+
### The integrity check at spawn
|
|
245
|
+
|
|
246
|
+
A spawn copies a package's capabilities only when the package is the content
|
|
247
|
+
the lock records. For each package the soul composes a capability from, the
|
|
248
|
+
kernel digests the package tree (the lock entry's `path`) at the lock's
|
|
249
|
+
`commit`, as `oats sync` does, and compares the digest with the lock's
|
|
250
|
+
`integrity`.
|
|
251
|
+
|
|
252
|
+
- **When.** After the soul is resolved and before the spawn writes anything:
|
|
253
|
+
no soul copy, no worktree, no instance home. `oats spawn --preview` makes
|
|
254
|
+
the same check. `oats instance upgrade` makes it for each package it moves
|
|
255
|
+
a module to.
|
|
256
|
+
- **The refusal** is `E_PACKAGE_INTEGRITY` with `details: {package, version,
|
|
257
|
+
commit, expected, actual}`: `expected` is the lock's `integrity`, `actual`
|
|
258
|
+
the digest of the tree as this computer reads it. The message names the
|
|
259
|
+
package, the commit and both digests. Two things produce it: a lock whose
|
|
260
|
+
`commit` and `integrity` describe different content (a hand edit, a bad
|
|
261
|
+
merge), which is fixed by restoring the lock; and a copy of the
|
|
262
|
+
package in this computer's remote cache that changed after it was fetched,
|
|
263
|
+
which is fixed by removing the cache (`$OATS_REMOTE_CACHE`, default
|
|
264
|
+
`~/.cache/oats/remotes`).
|
|
265
|
+
- **Once per package version and computer.** A tree that matched is recorded
|
|
266
|
+
under the remote cache, in `.verified/`, one file per (repository key,
|
|
267
|
+
commit, path, integrity). The record also holds the state of the cached
|
|
268
|
+
repository the tree was read from: every file under it, by path, size,
|
|
269
|
+
mode, inode, modification time and status-change time. A later spawn
|
|
270
|
+
believes a record only when each of its fields is the one asked for and the
|
|
271
|
+
cached repository is still in that state, and then digests nothing. Any
|
|
272
|
+
file added, removed, replaced or rewritten there (a later fetch of the same
|
|
273
|
+
repository included) makes the next spawn digest the tree again. Nothing
|
|
274
|
+
is recorded when the cached repository changed while the tree was read (the
|
|
275
|
+
first fetch of the package's files): the next spawn digests it again. With
|
|
276
|
+
a missing or unreadable record the tree is digested, and a cached
|
|
277
|
+
repository that reads objects from outside itself (a symbolic link, an
|
|
278
|
+
alternates file) is digested every time. A record older than 30 days is
|
|
279
|
+
removed when the cache is next pruned. The records are the kernel's own and
|
|
280
|
+
no contract: deleting them only costs the next spawn a digest.
|
|
281
|
+
- **What a record does not see.**
|
|
282
|
+
- A change to the cached repository that leaves every file's size, mode,
|
|
283
|
+
inode and both times as they were. That takes writing to the disk under
|
|
284
|
+
the filesystem, setting the clock back, or, on a filesystem that keeps
|
|
285
|
+
times to the second, rewriting a file in place to the same size within
|
|
286
|
+
the second it was last changed.
|
|
287
|
+
- A record written by whoever changed the cache: both live in the same
|
|
288
|
+
directory, so the cache is as trusted as the account that owns it.
|
|
289
|
+
- What Git reads outside the cached repository: its own configuration and
|
|
290
|
+
environment.
|
|
291
|
+
- A change made between the check and the copy of the modules a moment
|
|
292
|
+
later in the same spawn.
|
|
293
|
+
|
|
220
294
|
## Package souls
|
|
221
295
|
|
|
222
296
|
A package may ship **souls** as well as capabilities. One pin in
|
|
@@ -273,7 +347,12 @@ oats-package/
|
|
|
273
347
|
{ id, version, commit, digest, path }` and the soul id `package:<id>#<soul>`;
|
|
274
348
|
in `oats status` the soul is `moved` once the package pin moves.
|
|
275
349
|
- **Disabled** by `oats-local.yaml` `souls.disabled` by its qualified or bare
|
|
276
|
-
name (`E_SOUL_DISABLED` at spawn).
|
|
350
|
+
name (`E_SOUL_DISABLED` at spawn). An entry is matched by name only, so an
|
|
351
|
+
entry naming a soul that no longer exists fails open: after a pin's removal
|
|
352
|
+
or rename, the soul it was meant to keep off spawns again under its new
|
|
353
|
+
name. After removing or renaming a pin, or a soul it provided, run
|
|
354
|
+
`oats doctor` and fix what it reports, and check `souls.disabled` by hand: an
|
|
355
|
+
older kernel's doctor doesn't report such an entry.
|
|
277
356
|
- **Trusted** as the package's capabilities are: declaring the package is the
|
|
278
357
|
trust decision.
|
|
279
358
|
|
|
@@ -353,11 +432,11 @@ A soul that names one of the package's capabilities with
|
|
|
353
432
|
"policy": "docs/official-catalog.md",
|
|
354
433
|
"packages": {
|
|
355
434
|
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.8.0", "path": "oats-package" },
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.
|
|
435
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.23.0", "path": "oats-package" }
|
|
357
436
|
}
|
|
358
437
|
}
|
|
359
438
|
```
|
|
360
439
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.
|
|
362
|
-
resolves to tag `oats-framework/v1.
|
|
440
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.23.0`
|
|
441
|
+
resolves to tag `oats-framework/v1.23.0`. Resolving through the catalog never
|
|
363
442
|
advances a lock by itself: `oats sync` does, and says so.
|
package/docs/release-lane.md
CHANGED
|
@@ -480,7 +480,8 @@ always records `release.status: pending`.
|
|
|
480
480
|
## Releasing `oats.framework`
|
|
481
481
|
|
|
482
482
|
The distribution package in `oats-package/` (`oats.core`, `oats.setup`,
|
|
483
|
-
`oats.onboarding`, `oats.
|
|
483
|
+
`oats.onboarding`, `oats.coordination-setup`, `oats.support`,
|
|
484
|
+
`oats.knowledge-theory`) is not published
|
|
484
485
|
by `release.yml` or by this lane. A deployment takes it from this repository at the tag
|
|
485
486
|
`oats-framework/v<version>`, through the catalog ref or its workspace pin. A
|
|
486
487
|
skill changed under `oats-package/` therefore reaches deployments only when
|