From fe9ad200c40950f742c1ebd75536c787758942de Mon Sep 17 00:00:00 2001 From: Dan Connolly Date: Thu, 8 Oct 2026 18:35:03 -0500 Subject: [PATCH] refactor(no-ambient-authority): rename from ocap-discipline Name the skill for what triggers it. Cite Wikipedia on capability-based security and ambient authority, and point newcomers to awesome-ocap. Co-Authored-By: Claude Opus 5.5 (1M context) --- io-between-turns/SKILL.md | 2 +- lazy-tdd/SKILL.md | 2 +- .../SKILL.md | 23 ++++++++++++++----- silent-failures-are-evil/SKILL.md | 2 +- 4 files changed, 20 insertions(+), 9 deletions(-) rename {ocap-discipline => no-ambient-authority}/SKILL.md (68%) diff --git a/io-between-turns/SKILL.md b/io-between-turns/SKILL.md index f1c2b55..924c619 100644 --- a/io-between-turns/SKILL.md +++ b/io-between-turns/SKILL.md @@ -47,7 +47,7 @@ paper.) ## see also -- [ocap-discipline](../ocap-discipline/SKILL.md): who gets to do I/O at +- [no-ambient-authority](../no-ambient-authority/SKILL.md): who gets to do I/O at all (authority passed in, not ambient); this skill is about *when*. - [silent-failures-are-evil](../silent-failures-are-evil/SKILL.md): an awaited I/O failure still needs a trace. diff --git a/lazy-tdd/SKILL.md b/lazy-tdd/SKILL.md index 7db4f04..952914e 100644 --- a/lazy-tdd/SKILL.md +++ b/lazy-tdd/SKILL.md @@ -46,5 +46,5 @@ amounts", not "fix for goof #3". If the goof can't reasonably be captured in an automated test (e.g. it lives in config, a one-off script, or untestable I/O with no seam), say so explicitly, explain why, and suggest the seam that would make it -testable (see [ocap-discipline](../ocap-discipline/SKILL.md) for +testable (see [no-ambient-authority](../no-ambient-authority/SKILL.md) for injecting I/O). Don't silently skip the debt. diff --git a/ocap-discipline/SKILL.md b/no-ambient-authority/SKILL.md similarity index 68% rename from ocap-discipline/SKILL.md rename to no-ambient-authority/SKILL.md index d8aba58..72478be 100644 --- a/ocap-discipline/SKILL.md +++ b/no-ambient-authority/SKILL.md @@ -1,6 +1,7 @@ --- -name: ocap-discipline -description: Use when writing or reviewing code whose functions touch I/O, clocks, random number generators, process.env, fetch, or filesystem; when someone says "ambient authority", "wash your mouth out", or "that function shouldn't reach for that"; when debating dependency injection or default-arg seams; when asked what OCap discipline is. Source: the Agoric wiki's OCap Discipline page. +name: no-ambient-authority +description: >- + Use when writing or reviewing code whose functions touch I/O, clocks, random number generators, process.env, fetch, or filesystem; when someone says "ambient authority", "wash your mouth out", or "that function shouldn't reach for that"; when debating dependency injection or default-arg seams; when asked what OCap discipline is. Source: the Agoric wiki's OCap Discipline page. --- # OCap Discipline @@ -10,14 +11,22 @@ condensed to working rules. ## the background, in three lines -Object-capability security = memory safety + encapsulation ("no +Object-capability security +([capability-based security](https://en.wikipedia.org/wiki/Capability-based_security)) += memory safety + encapsulation ("no reference to an object except: create it, be given it at creation, or receive it in a message") combined with **primitive effects only via references** — all world-touching primitives are embodied by objects, and *anything globally accessible is immutable data*. No `open(filename)` in the global namespace: converting a string to file access is like -casting an integer to a pointer. JavaScript doesn't enforce this; the -discipline is a convention (layerable via SES). +casting an integer to a pointer; that's +[ambient authority](https://en.wikipedia.org/wiki/Ambient_authority). +JavaScript doesn't enforce this; the discipline is a convention +(layerable via SES). + +New to object capabilities? Start with +[awesome-ocap](https://github.com/dckc/awesome-ocap), a curated list of +capability-based languages, systems, papers, and talks. ## the working rules (from the wiki) @@ -66,6 +75,8 @@ export const mintKey = (entropy: Entropy): string => b32(entropy(16)); - [OCap Discipline — Agoric wiki](https://github.com/Agoric/agoric-sdk/wiki/OCap-Discipline) (Miller, *Robust Composition* PhD thesis, 2006, is the deep source) -- [ambient authority — Wikipedia](https://en.wikipedia.org/wiki/Ambient_authority) +- [Ambient authority — Wikipedia](https://en.wikipedia.org/wiki/Ambient_authority) +- [Capability-based security — Wikipedia](https://en.wikipedia.org/wiki/Capability-based_security) +- [awesome-ocap: Awesome Object Capabilities and Capability-based Security](https://github.com/dckc/awesome-ocap) - in this workspace: `capsite/docs/webkeys.md` (URL-borne bearers), Agoric's eslit-based enforcement notes for contracts \ No newline at end of file diff --git a/silent-failures-are-evil/SKILL.md b/silent-failures-are-evil/SKILL.md index 7fd6147..5ce94ec 100644 --- a/silent-failures-are-evil/SKILL.md +++ b/silent-failures-are-evil/SKILL.md @@ -21,7 +21,7 @@ must leave a trace. - **Say only what you know.** When an API can't tell you the outcome, report what it did tell you ("offered", not "saved"). - **Make it testable.** Pass the logger in (see - [ocap-discipline](../ocap-discipline/SKILL.md)) so a test can assert + [no-ambient-authority](../no-ambient-authority/SKILL.md)) so a test can assert that the failure path logged; a discovered silent failure is a goof that owes a test ([lazy-tdd](../lazy-tdd/SKILL.md)).