[cuibonobo]

Summary

Before this PR, installApp() refused a stale plan only by comparing against the plan object it was handed. A server shows the owner a plan in one request and applies it in a later one, holding only the manifest in between, so it had no way to say which plan the owner saw.

This gives install approval one primitive, with one comparison rule:

• installApp(manifest, { did, fingerprint }) replaces installApp(plan). It plans the manifest again for did and refuses with StackConflictError unless the result is the plan whose fingerprint it was given. An in-process caller passes plan.fingerprint; a server passes the one the owner saw. The options mirror planInstall(manifest, { did }).

• The fingerprint names the plan the owner saw, in canonical form. It's a SHA-256 over the plan as planInstall() reports it:

  • the manifest and the key;
  • the change lists and newKey;
  • linkedKeys;
  • the existing install's name, version and deleted state.

  The canonical form is the one core's other hashes use, as schemaHash does: a type by its id, name, migratesFrom and schemaHash, every list as a set, and keys in one fixed order. Two consequences:

  • no Record's version is hashed, so an edit no plan shows (the owner relabelling an _app card) leaves a pending approval standing;
  • a store that reorders keys gets the same fingerprint.

• One validator per list, used on every write of it.

  • validateActionList() covers an action list wherever one is written: grantType(), a _grant write, a manifest's requests and an _install write. It refuses an unknown or repeated action.
  • validateGrant(baseId, actions, path) covers a whole grant: an allowed family, the action list, and read companions for mutate verbs. It returns errors prefixed with where the grant sits; grantType() throws them.
  • validateRequests(requests, path) covers a list of requests: each a grant validateGrant() accepts, and each family requested once. Both a manifest and an _install Record use it. An _install's defines also refuses a version listed twice.
  • A manifest's refusals are reported together, each at its path (requests[i].actions[j]), the same way an _install write reports them.
  • A stored list is still read as a set, so a grant that reached storage with a repeat still matches.

• sha256Hex() is the one hashing helper inside @haverstack/core, shared by hashSchema(), planFingerprint() and MemoryAdapter's file IDs.

• InstallAppOptions is exported from @haverstack/core.

Spec

• docs/spec/apps.md:
  • § The _install record: its requests are held to a manifest's rules, and a repeated defines entry is refused.
  • § Plan, then apply:
    • "Nothing is applied that was not approved" is one rule: every apply names the plan it approves.
    • "A fingerprint names the plan the owner saw, in canonical form" lists what's hashed.
    • "A stale approval is a conflict" uses versioning.md's split between fixing your input and retrying after re-reading.
    • The refusal list now includes a family requested twice.
    • Residual: the plan-then-apply window inside installApp().
• docs/spec/access-control.md § Type-level grants: "actions is a set, written without repeats".
• docs/spec/wire-format.md § Installs: the 422 row names the refusals apps.md lists.

docs/spec/versioning.md is unchanged. Also updated: README.md, packages/core/README.md, and the apps.md example, all for the new signature.

Verification

pnpm run format:check, check:refs, lint, test, build and typecheck all pass.

Fingerprint (install.test.ts):

• changes with the manifest's name or version and with the key;
• unchanged when types, requests, actions or enum values are reordered, when keys are reordered inside a schema, or when manifest keys are reversed;
• relabelling the _app card leaves a pending approval valid;
• a stale fingerprint is refused and installs nothing, while a current one applies;
• an approval of one manifest won't apply another.

Validation:

• a manifest reports every refusal at once, each at its path;
• a repeated action is refused in a manifest (requests[0].actions[1]), in an _install write, in grantType() and in a _grant write;
• a family requested twice is refused in a manifest and in an _install write, and a version defined twice in an _install write;
• narrowing a request revokes the actions it drops;
• a stored grant naming an action twice is still withdrawn by revokeType().

The changeset is a minor on @haverstack/core.

Notes for reviewers

• Breaking for callers: installApp(plan) is gone. In-process callers write installApp(plan.manifest, { did: plan.did, fingerprint: plan.fingerprint }). No other package in this repo calls it.

• Newly refused writes:

  • a manifest requesting one family twice;
  • an action named twice in grantType(), a manifest, or an _install write;
  • a _grant Record write with an unknown or repeated action;
  • an _install write whose requests break the grant rules (including a mutate verb without its read companion), repeat a family, or repeat a defines version.

  Over the wire, POST /records now answers 422 for the record writes among these.

• Error paths: a refused manifest request is now reported at requests[i].… rather than at the grant's own actions[j] / baseId.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XRRrTNcLcf2TtfuL9wB8Z8

[changeset-bot]

🦋 Changeset detected

Latest commit: 993bd14

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
@haverstack/core	Minor
@haverstack/adapter-api	Patch
@haverstack/adapter-conformance	Patch
@haverstack/adapter-local	Patch
@haverstack/blob-adapter-disk	Patch
@haverstack/blob-adapter-s3	Patch
@haverstack/commons	Patch
@haverstack/record-adapter-do-sqlite	Patch
@haverstack/record-adapter-sqlite	Patch
@haverstack/wire-types	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR