@amalgm/apps 0.1.2 → 0.1.3-preview.34176078280

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.
Files changed (3) hide show
  1. package/PURPOSE.md +30 -10
  2. package/README.md +27 -0
  3. package/package.json +38 -3
package/PURPOSE.md CHANGED
@@ -10,11 +10,11 @@ app keeps one stable identity while every deployment names an immutable
10
10
  release, failed deployments leave the last working release recoverable, and
11
11
  rollback means activating known bytes rather than rebuilding history.
12
12
 
13
- Amalgm Engine is the composition root for the complete Amalgm runtime. This
14
- repository owns the Apps product and its supervisor. Engine may run that
15
- product beside independently supervised Events, Realtime, and other products;
16
- it supplies identity, transport, and UI composition but does not absorb their
17
- domain supervisors or maintain a second app lifecycle implementation.
13
+ Amalgm Shell is the composition root for the complete Amalgm runtime. This
14
+ repository owns the Apps product and its supervisor. Shell composes that
15
+ product beside Files, Chat and other products through their public contracts;
16
+ it supplies identity, transport and machine adapters without absorbing their
17
+ domain supervisors or maintaining a second app lifecycle implementation.
18
18
 
19
19
  Runtime hosts may mount the Apps HTTP catalog, including its legacy Artifacts
20
20
  projection, without becoming lifecycle authorities. Catalog reads come from
@@ -32,7 +32,7 @@ the same Apps store as the SDK, CLI, and MCP surfaces.
32
32
  deployment.
33
33
  - The **Apps supervisor** is the sole lifecycle authority for apps in one
34
34
  Apps state directory.
35
- - A **product-service supervisor** is an optional outer Engine concern that
35
+ - A **product-service supervisor** is an optional outer Shell concern that
36
36
  observes whether the Apps product is available; it never supervises
37
37
  individual apps.
38
38
  - The **data directory** is stable writable storage for an app across
@@ -40,6 +40,26 @@ the same Apps store as the SDK, CLI, and MCP surfaces.
40
40
 
41
41
  ## Axioms
42
42
 
43
+ Consumer assembly derives exact same-branch dependency pins from the declared
44
+ package manifests and registry candidate records. One pending composition per
45
+ branch preserves human edits; complete consumer checks for the exact merge tree govern its
46
+ merge, and publication never implies installed adoption.
47
+
48
+ Managed package delivery starts from a clean, exact main or preview source
49
+ commit. The workflow occurrence supplies only its generated version and source
50
+ record; tests run against those candidate inputs before packing. Every native
51
+ gate and publication use that same tarball and integrity. A candidate tag makes
52
+ bytes available to release assembly; it never promotes an installed runtime.
53
+ Release tooling remains available inside each owner repository so a developer
54
+ or CI job never needs access to another private product repository.
55
+ Registry credentials are available only to the final protected publication job,
56
+ after every native examination proves the exact candidate bytes.
57
+ Native consumers install the archive as a dependency, so SDK development
58
+ dependencies never become an end-user installation requirement.
59
+ The repository token creates only its own dependency proposals and explicitly
60
+ dispatches checks and delivery; every admitted gate proves the actual checkout,
61
+ including the exact two-parent merge commit that becomes managed source.
62
+
43
63
  Managed releases bind to one exact published Core version and build from the
44
64
  locked dependency graph on the supported Node toolchain.
45
65
 
@@ -62,7 +82,7 @@ locked dependency graph on the supported Node toolchain.
62
82
  is derived from desired state, process state, health, and DNS connection.
63
83
  9. App code receives a stable data directory explicitly; writes made inside a
64
84
  deployment directory never become part of a release or a later deploy.
65
- 10. The SDK owns behavior. CLI, MCP, HTTP, and Engine integrations only adapt
85
+ 10. The SDK owns behavior. CLI, MCP, HTTP, and Shell integrations only adapt
66
86
  that public service.
67
87
  11. Apps stores tool identifiers as opaque references and never edits Toolbox,
68
88
  Agents, or another product. Any workflow spanning products has an explicit
@@ -71,7 +91,7 @@ locked dependency graph on the supported Node toolchain.
71
91
  crash or keep the hosted app alive by itself.
72
92
  13. The Apps supervisor belongs to this product in standalone and composed
73
93
  deployments; exactly one active Apps supervisor owns a state directory.
74
- 14. Engine composes product supervisors side by side. It may supervise the
94
+ 14. Shell composes product supervisors side by side. It may supervise the
75
95
  Apps product as one service, but it never reaches through that boundary to
76
96
  start, stop, adopt, or restart an individual app process.
77
97
  15. Supervisor state is scoped to its fault domain: an app failure changes
@@ -100,6 +120,6 @@ deployment. Rolling back selects an earlier successful release and appends a
100
120
  new deployment. Renaming changes only the app record. If validation or build
101
121
  fails, the running deployment is untouched. If the new process cannot start,
102
122
  the deployment is marked failed and the previous deployment is reactivated.
103
- When composed into Engine, the same Apps supervisor makes those decisions.
104
- Engine sees the Apps product as available, degraded, or unavailable and can
123
+ When composed into Shell, the same Apps supervisor makes those decisions.
124
+ Shell sees the Apps product as available, degraded, or unavailable and can
105
125
  restart that product independently without becoming a second app supervisor.
package/README.md CHANGED
@@ -74,3 +74,30 @@ are defined in [docs/SUPERVISION.md](./docs/SUPERVISION.md).
74
74
  npm install
75
75
  npm run verify
76
76
  ```
77
+
78
+ ## Managed package delivery
79
+
80
+ Managed npm delivery uses `.github/workflows/publish-package.yml` after the
81
+ exact main/preview owner checks pass. The occurrence generates a unique
82
+ prerelease version and records its source SHA; it reruns the owner suite, packs
83
+ once, and installs that tarball on Linux, macOS and Windows before publication.
84
+ The `candidate-main`/`candidate-preview` tags are release-assembly inputs and
85
+ never select installed runtimes. `package.json` declares this owner's gates,
86
+ CLI probes, peer-only exports and lifecycle permissions. The standalone runner
87
+ under `scripts/release/` is intentionally copied across owners to preserve
88
+ private repository access boundaries. The final publish step uses the `NPM_TOKEN`
89
+ secret in the `npm-release` environment. Where npm trusted publishing is
90
+ configured for this repository's `publish-package.yml` and that environment,
91
+ the token can be omitted. Authentication does not replace native certification,
92
+ exact source records or artifact integrity; private source repositories do not
93
+ receive npm's public-source provenance.
94
+
95
+ Managed dependency reconciliation reads this owner’s declared manifests and
96
+ updates exact same-branch registry candidates in one pending composition PR per
97
+ branch. The repository token explicitly dispatches the owner checks. Every declared gate must
98
+ pass for the exact merge tree; an atomic expected-base update prevents merging
99
+ with untested concurrent source. Human additions or amendments are preserved.
100
+ The half-hour CI reconciliation recovers missed dispatch hints. Assembly runs
101
+ no dependency code or lifecycle hooks, and repeated owner checks do not publish
102
+ another candidate for unchanged source. Repository policy must allow GitHub Actions to create pull requests; no
103
+ cross-repository credential or paid auto-merge feature is required.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@amalgm/apps",
3
- "version": "0.1.2",
3
+ "version": "0.1.3-preview.34176078280",
4
4
  "description": "Local-first, versioned application deployment for Amalgm.",
5
5
  "license": "UNLICENSED",
6
6
  "private": false,
@@ -44,13 +44,19 @@
44
44
  "check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json && tsc -p tsconfig.test.json",
45
45
  "test": "tsx --test --test-concurrency=1 --test-timeout=30000 test/*.test.ts",
46
46
  "verify": "npm run check && npm run build && npm test",
47
- "prepack": "npm run build"
47
+ "prepack": "npm run build",
48
+ "release:admit": "node scripts/release/package.mjs admit",
49
+ "release:prepare": "node scripts/release/package.mjs prepare",
50
+ "release:examine": "node scripts/release/package.mjs examine",
51
+ "release:publish": "node scripts/release/package.mjs publish",
52
+ "release:compose": "node scripts/release/compose.mjs",
53
+ "test:release": "node --test scripts/release/*.test.mjs"
48
54
  },
49
55
  "engines": {
50
56
  "node": ">=24"
51
57
  },
52
58
  "dependencies": {
53
- "@amalgm/core": "0.4.7",
59
+ "@amalgm/core": "0.4.8-preview.34168975242",
54
60
  "@types/better-sqlite3": "^7.6.13",
55
61
  "@types/node": "^20.19.43",
56
62
  "better-sqlite3": "^12.6.2",
@@ -59,5 +65,34 @@
59
65
  "devDependencies": {
60
66
  "tsx": "^4.23.1",
61
67
  "typescript": "^5.9.3"
68
+ },
69
+ "amalgmRelease": {
70
+ "schema": 1,
71
+ "workflow": "verify.yml",
72
+ "jobs": [
73
+ "verify"
74
+ ],
75
+ "verify": "verify",
76
+ "cli": [
77
+ "amalgm-apps"
78
+ ]
79
+ },
80
+ "allowScripts": {
81
+ "better-sqlite3@12.11.1": true,
82
+ "esbuild@0.28.1": true,
83
+ "fsevents@2.3.3": false
84
+ },
85
+ "amalgmComposition": {
86
+ "schema": 1,
87
+ "manifests": [
88
+ "package.json"
89
+ ]
90
+ },
91
+ "gitHead": "dd2b26e5641ddcf1bed549a0bb5dcd1d2249e214",
92
+ "amalgmSource": {
93
+ "repository": "amalgm-inc/amalgm-apps",
94
+ "branch": "preview",
95
+ "commit": "dd2b26e5641ddcf1bed549a0bb5dcd1d2249e214",
96
+ "occurrence": "34176078280"
62
97
  }
63
98
  }