feat: app installs — manifests, the _install record, and POST /installs

[cuibonobo]

Summary

Closes #359. An app that holds its own key can now get its types into a stack in a single step that the owner reviews.

• _install@1 system type.

  • It stores what the owner approved, not the manifest the app shipped.
  • There is one install per appId, and appId is an immutable binding.
  • It can't be granted, and only the owner, acting alone, can write one.
  • It links to the _app cards it was installed for and the _grant records it produced, using relationship associations.
  • Its version history is the upgrade log.

• Stack.planInstall() → installApp() → uninstallApp().

  • What the plan reports:
    • new families and new versions;
    • typeChanges: every type it would define or redefine, commons types included;
    • requests added and removed;
    • requests on families the app doesn't own, with each family's owner;
    • linkedKeys: the keys already linked to the install.
  • What the plan refuses up front: any schema defineType() would refuse, a type listed twice, and a non-additive schema change. That means a manifest's types are written all or none.
  • Comparing requests: a request is compared by its family and the set of its actions, so repeating an action can't hide a dropped grant.
  • Applying: installApp() refuses a plan that's out of date, and works from a frozen copy of the manifest. It sets every linked key's grants to exactly what the manifest requests. Each linked key gets read on the install, and a key no longer linked loses it.
  • Empty plans: a plan that changes only name or version is not empty, so the owner still sees it.
  • Uninstalling revokes the install's grants and soft-deletes it. The app's data and its _app cards stay.

• Each family has one owner: the app whose appId is its namespace. An install may define commons types (org.haverstack/*) but never claims them. An app uses another app's family through a request, never by defining it.

• An installed app can migrate its own types. ScopedStack.commitMigration() admits the app when all of these hold:

  • both families are in its live install's namespace;
  • the target version is one the owner approved;
  • the app holds update-any through a grant made out to it directly;
  • the request comes from the app's own key, acting as itself.

  The new content goes through the file-reference check a create does. A soft-deleted record is refused until it's undeleted. migrateAll({ sweep: 'listed' }) returns { migrated, skipped }.

• POST /installs.

  • The body is { manifest }. The key being installed always comes from the session, never the body.
  • The server answers 202 pending (the request is queued and nothing is written to the stack) or 200 installed with the _install record.
  • Discovery advertises the endpoint with installs: { requests: true }.
  • New exports: APIAdapter.requestInstall(), parseInstallBody() and isPlanEmpty().

Out of scope: proving who publishes an app (signed manifests, publisher pinning, certified keys) moves to #404. An earlier revision of this PR prototyped it, and the last commit removes it. It came down mostly to trust on first use, it added a lot of edge cases, and it overlaps the deferred key-rotation design. apps.md describes the remaining appId risk and links to where it's deferred.

Spec

• New: docs/spec/apps.md, covering the _install record, who owns a family, plan-then-apply, migration by an installed app, uninstalling, and the wire request.
• New: docs/spec/wire-format.md § Installs, plus the installs field in Discovery.
• Updated:
  • access-control.md: _install can't be granted and is fenced; the commitMigration() exception.
  • data-model.md, identity.md § App, versioning.md, wire-format.md (Migration commit and Types), the docs/spec.md index, and README.md.
• Fixtures: installRequestFixtures and a discovery fixture in @haverstack/conformance-fixtures.

Verification

All six pre-push checks pass locally on the current head: format:check, check:refs, lint, test, build, typecheck.

• packages/core/tests/install.test.ts covers:
  • plan and apply, upgrades, multiple keys, and stale plans;
  • typeChanges, linkedKeys, and the frozen manifest;
  • plans that change only name or version;
  • comparing requests as sets of actions;
  • schema refusals at plan time;
  • namespace and commons rules;
  • field immutability and the write fence;
  • read access following linked keys;
  • uninstall and reinstall;
  • every refusal path for migration, including a soft-deleted record and a file reference the app can't read;
  • sweep: 'listed'.
• wire-body.test.ts covers parseInstallBody().
• adapter-api runs against the new fixtures, including the local refusal when discovery doesn't advertise installs.

Notes for reviewers

• The appId claim is a known residual risk. Any key can present a manifest under any appId. The plan shows the appId, newKey and linkedKeys, so the owner's review is the check. See apps.md § Who owns a family and Design: proving who publishes an app (signed manifests, publisher pinning, certified keys) #404.
• The owner's approval step isn't specified, on purpose. A server builds that UI on planInstall() / installApp(). Only the app's request is pinned.
• WIRE_PROTOCOL_VERSION stays 1.0. The changes only add things.
• Some server behavior isn't exercised here. There's no server in this repo, so the pending queue and the 403 for a delegated session are specified and pinned by fixtures but not run.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AdV1VbrMeuGtMoFiE31tqg

[changeset-bot]

🦋 Changeset detected

Latest commit: 26e2eac

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

This PR includes changesets to release 11 packages

Name	Type
@haverstack/core	Minor
@haverstack/wire-types	Minor
@haverstack/conformance-fixtures	Minor
@haverstack/adapter-api	Minor
@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

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