@omnitron-dev/omnitron 0.3.3 → 0.4.6

package/README.md

@@ -57,6 +57,101 @@ omnitron logs --status
 
 Ranked levels in the CLI are minimum severities. Use `--level unknown` for records without a recognized level, or specify the exact stored spelling of a custom level. In Console, the level chips and the custom-level selector match exact values in both live and historical logs. Share the main log view with one `level` URL parameter per selected level.
 
+## Pipelines pinned to installed releases
+
+A `kind: 'release'` step identifies a registered project, stack, application and
+immutable producer artifact. It executes a package-relative compiled JavaScript
+member using the verified resident owner's Node. It does not store a physical
+installation path, Node path or generated `PATH` in the pipeline definition.
+Changing the owner package can therefore create a different, correctly bound
+installation without changing the pipeline's ID, revision or run history.
+
+For a new caller running at the registered compiled launch entry, the existing
+runtime-origin API supplies the producer identity:
+
+```ts
+import { verifyInstalledRuntime } from '@omnitron-dev/omnitron/runtime';
+import type { PipelineDef } from '@omnitron-dev/omnitron/dto/services';
+
+const runtime = await verifyInstalledRuntime(new URL(import.meta.url));
+if (runtime.state !== 'verified') throw Error(runtime.reason);
+const definition: PipelineDef = {
+  name: 'publish-results',
+  steps: [{
+    name: 'publish',
+    kind: 'release',
+    target: {
+      project: 'research', stack: 'publication', app: 'publisher',
+      artifact: runtime.producer,
+      entry: 'dist/publish.mjs',
+    },
+    cwd: '/srv/research-operator',
+    env: { OPERATOR_ROOT: '/srv/research-operator' },
+    args: ['--checked'],
+    timeout: 180000,
+    retries: 0,
+  }],
+  triggers: [{ type: 'manual', config: {} }],
+};
+```
+
+`artifact` contains `releaseId`, `manifestSha256`, `artifactSha256`, `producerApp`,
+`projectCommit` and `frameworkCommit`. Imported artifacts retain their producer
+identity; the run records the selected consumer release separately. The entry may
+be another compiled member of that same verified closure. This does not change
+`verifyInstalledRuntime`'s stricter contract for the registered launch entry.
+Arguments are literal array elements, and parameters remain JSON in
+`OMNITRON_PARAMS`; no shell interpolation occurs.
+
+Use the existing administrator-only `OmnitronPipelines` API, or save the definition
+as JSON and use the ordinary CLI:
+
+```sh
+omnitron pipeline save publication.json
+omnitron pipeline run <pipeline-id>
+omnitron pipeline status <run-id> --output
+# An intentional definition change requires the reviewed current revision:
+omnitron pipeline save publication.json --id <pipeline-id> --expected-revision <sha256>
+```
+
+Console's Advanced JSON editor accepts the same definition. Opening and saving a
+release step preserves its target and arguments. Run details show each attempt's
+artifact, installed tree, actual executable/target, native owner lifetime, process
+ID and environment fingerprint; environment values are not copied into evidence.
+
+Prepare and select the immutable release through the ordinary stack release
+lifecycle first. Pipeline admission never installs dependencies, prepares a missing
+installation, changes selection, starts applications, or provisions infrastructure.
+Only independently owned local stacks are supported; remote targets explicitly
+refuse execution. Registration lifetime, release selection, declaration, environment,
+full frozen payload and native owner binding are checked again before every Xec
+attempt. This repeats full verification and may be expensive for large closures.
+The current operation keeps the admitted owner; it never retargets mid-run.
+
+`PATH`, `NODE_OPTIONS` and `NODE_PATH` cannot be set by the release step. The app's
+recorded resource-only Node options apply, while Node search paths are empty.
+Nonempty inherited or declared `LD_*` and `DYLD_*` loader controls are refused;
+Linux shared-library paths may only be derived from the verified closure. The
+working directory must be an absolute physical directory. Application output must
+be written outside the immutable installation.
+
+Xec owns output limits, retries, timeouts and cancellation. Backend handoff refuses
+active pipeline work. The owner proof is an observation, not an OS process lease:
+if execution starts and its binding cannot subsequently be confirmed, the attempt
+is marked `unconfirmed` and automatic retries are refused. Inspect effects before
+explicitly running again. Failed durable completion also makes an executed attempt
+unconfirmed. A daemon restart marks unfinished runs interrupted and their prepared
+or started attempts unconfirmed; missing spawn acknowledgement does not prove that
+effects never began. Completed attempts remain completed. Recovery never replays
+these runs or promises exactly-once execution.
+
+Existing frozen callers that compare absolute shell commands or generated `PATH`
+values do not acquire this contract automatically. A publication watcher using
+such comparisons requires a separately reviewed publication artifact and an
+explicit conditional update of its existing pipeline definition.
+This framework change neither rewrites that caller nor re-registers scientific
+experiments or results.
+
 ## Scoped backups
 
 `omnitron backup artifact storage-objects --project acme --stack prod --bucket uploads`
@@ -109,12 +204,16 @@ declaration. Preserve and qualify that declaration instead of relaxing its diges
 check or temporarily substituting files to obtain an admission receipt.
 
 The native `test/runtime/managed-backend.mjs` owner roundtrip accepts
-`--application-sdk /absolute/path/to/installed/@omnitron-dev/omnitron`.
-The independent consumer must also contain its matching Titan and Titan Storage.
+`--application-project /absolute/path/to/installed-consumer`
+and `--application-sdk-commit <full-sha>`.
+The consumer must directly resolve its matching Omnitron, Titan and Titan Storage.
+The full production dependency graphs must stay inside that consumer checkout
+(or its pnpm workspace); virtual-store siblings are included, external links are refused.
 Alongside the baseline → candidate → baseline service transition, this exercises
 one project's source and pinned-release stacks through the public project API:
 single and pooled bootstrap workers, source watch without restarting frozen workers,
-a second cold candidate start, retained release selection, and explicit refusal of
+a storage write/read from each worker in the application's directory, a second cold
+candidate start, retained release selection, and explicit refusal of
 a changed declaration. It verifies runtime bytes and entry change times after the
 applications run. All services, Git inputs and release archives belong to the private
 fixture; this does not establish cold readiness of real application registrations.
@@ -537,11 +636,78 @@ apply check the saved plan against the current scope immediately. PID ordering a
 identities and group membership are independently verified twice.
 
 For an isolated native owner roundtrip with real application workloads, pass
-`--application-sdk <installed-package>` and `--application-sdk-commit <full-sha>`
+`--application-project <installed-consumer>` and `--application-sdk-commit <full-sha>`
 to `test/runtime/managed-backend.mjs` alongside `--owner-roundtrip`. The fixture
-checks the package and its clean build stamp before creating services. Its result
+checks all required dependencies, their containment and the SDK's clean build stamp
+before creating services. Its result
 records the application's framework commit and the owner's commit and artifact hash.
 
+## Starting with existing infrastructure
+
+Runtime-only recovery uses the ordinary stack lifecycle with
+`--infrastructure preserve`. It requires existing, running resources whose
+native identities and specification match the resolved declaration. It cannot
+provision, recreate or restart infrastructure, run post-provision setup or
+framework database migrations, install a remote daemon, upload static content,
+or rewrite a node's infrastructure configuration. Application startup still runs
+the application itself; its readiness and application-owned startup hooks remain
+separate checks.
+
+Before the maintenance stop, prepare the selected release through
+`stack prepare-release` if necessary, load the intended project configuration,
+and review preservation for both the forward and rollback selections:
+
+```sh
+omnitron stack start acme prod --release <release-id> --infrastructure preserve --dry-run --json
+```
+
+The review reads existing resources and current cached bootstrap declarations;
+it does not import application code or install a release. A non-null `digest`
+requires every target to be verified. Native container IDs, restart generation,
+image identity, ownership, environment, ports, mounts, network, resource limits
+and health-check specification are checked against the desired plan. Extra or
+missing resources and changed presets require a separately approved reconcile.
+A changed historical spec-hash algorithm alone is not native drift. Mounted
+configuration needs a matching creation receipt because mount paths cannot prove
+which configuration bytes a running daemon consumed. Unverifiable configuration
+receipts, host-service identities or recipient capabilities remain explicit
+failures; they are never treated as a successful preservation review.
+
+After the separately planned application stop and runtime transition, start with
+the reviewed authority:
+
+```sh
+omnitron stack start acme prod --release <release-id> --infrastructure preserve --review <digest>
+```
+
+The daemon repeats release admission, installed provenance, declaration and
+environment fingerprinting, and native inspection before startup. It checks
+native identity again when adopting the existing resources. The digest binds
+the exact launch context: a changed owner, installation, release, configuration
+or resource requires a new inspection. A review made before a planned owner
+change does not certify that changed owner. Omitting `--review` makes the CLI
+obtain and submit a current review; supplying it additionally pins the previously
+inspected digest. No secret environment values are returned in review evidence.
+
+`stack stop --keep-infrastructure` persists the preservation restriction before
+stopping applications and drains infrastructure repair work. Subsequent ordinary
+and automatic starts cannot return to reconciliation. A successful preserve start
+retains read-only health observation; unhealthy or replaced resources are reported
+without repair. Handoff retains this authority. An operator must explicitly select
+`--infrastructure reconcile` to authorize normal provisioning, setup and migrations
+again. A new project registration does not inherit an old registration's authority.
+
+The operator RPC contract is `OmnitronProject.reviewStackStart({ project, stack,
+release?, workingTree?, infrastructure: 'preserve' })`, followed by
+`startStack({ project, stack, release?, workingTree?, infrastructure: 'preserve',
+review })`. The existing remote lifecycle forwards the resolved infrastructure
+through `OmnitronInfra.reviewStack` and `provisionStack` with the same preservation
+authority. Recipients must acknowledge protocol 1; an older node refuses recovery
+without a provisioning fallback. Existing project isolation, deployment operations
+and cluster authority checks continue to apply. `check-release` alone checks release
+admission; its historical build/test gates do not certify preservation or classic
+application startup compatibility.
+
 ## Standalone infrastructure
 
 `omnitron infra up`, `down` and `reset --yes` operate on containers declared
@@ -567,6 +733,121 @@ the backend cannot replace its capture mechanism without an owner maintenance wi
 
 ## Source development and installed releases
 
+`omnitron sdk dev /path/to/omni --project-dir /path/to/project --stack dev`
+selects a local SDK and watches its source changes. First run
+`omnitron sdk init --project-dir /path/to/project` and commit its canonical pnpm
+hook. Init does not resolve or install registry dependencies. The consumer's
+workspace manifests declare the framework packages it uses with normal version
+dependencies; the SDK command selects their public packages and transitive
+runtime dependencies from a separate SDK checkout, then uses its normal Turbo
+build graph. A standalone Lumen or Prism consumer does not need an Omnitron
+application dependency. Use a complete, normally installed SDK workspace.
+The consumer must own its dependency directory. An external `node_modules`
+symlink is refused before installation; preserve that directory separately
+before migrating an ad hoc dependency setup to an SDK profile.
+The standard pnpm `virtualStoreDir` setting may point to a dedicated physical
+directory on another volume. For a thin local `node_modules` symlink graph with
+the package contents on that volume, use `nodeLinker: isolated`; a hoisted install
+keeps package contents in the consumer's modules directories. For example:
+
+```yaml
+# Consumer pnpm-workspace.yaml; use a separate store directory for each workspace.
+nodeLinker: isolated
+virtualStoreDir: /Volumes/AGI-Dev/work/my-project/virtual-store
+```
+
+The SDK preserves these pnpm settings. Registry verification compares the effective
+configuration with `.modules.yaml`, checks the physical modules/store paths,
+and matches installed lock entries and archive integrity to the distribution lock.
+The existing selection fingerprint includes the effective module settings, so an
+environment-resolved store change triggers the normal dependency switch as well.
+A redirected store, mismatched receipt, or framework import outside the admitted
+installation fails verification. This installation check does not replace the
+release builder's archive provenance checks.
+
+A new consumer can use unpublished SDK packages without a distribution lock.
+An existing lock may also predate newly declared packages. Development installation
+first runs pnpm's ordinary package-manager bootstrap. This may add or update the
+manager metadata document in root `pnpm-lock.yaml`; the SDK checks that the
+parsed application dependency document remains unchanged. On success it accepts
+that root lock as its baseline and writes the development dependency graph only
+under `.omnitron/dev-sdk`. A manager-only root lock is not a registry application
+lock. This one-time bootstrap lets subsequent ordinary `pnpm run build` and
+`pnpm exec` use the selected profile through the same hook without extra flags.
+`--no-watch` builds the selected graph once without starting a watcher; omit `--stack` for an
+unregistered build-only consumer.
+
+`omnitron sdk registry` explicitly restores a current frozen registry lock.
+It refuses an absent or stale lock before replacing the local selection. Once
+the dependencies are published, create a real distribution lock with
+`pnpm install --lockfile-only --config.ignore-pnpmfile=true`, review and commit
+it, then run `sdk registry`. A failed SDK switch restores the previous accepted
+SDK when possible. A failed first install without a verified registry baseline
+remains visibly incomplete; correct the cause and run `sdk dev` again. No
+registry lock or successful installation is invented for recovery. Releases
+continue to read committed inputs and enforce their existing provenance gates.
+If bootstrap or installation fails, the SDK restores the original root lock
+bytes or absence only while that file still matches the metadata it generated.
+It preserves concurrent edits and reports the conflict instead of overwriting them.
+
+The initial dependency switch requires the project's local source stacks to be stopped.
+The owner must advertise `applicationRuntimeResolution@1`: otherwise it can
+retain a previous package identity after pnpm replaces dependencies. Both SDK
+selection and restoration of registry dependencies refuse this owner before
+installing packages. Prepare and qualify an owner transition separately.
+SDK commands also require a fresh owner observation and a matching Node ABI,
+platform and architecture. Use the Node version reported by `omnitron status`;
+the SDK command passes its selected Node to package installation and builds.
+A different shell default must not silently produce incompatible native addons.
+
+`sdk status` checks the project's resolved imports, the SDK's transitive framework
+imports and selected package identities; the daemon's `status` reports
+the running backend and owner independently. Online applications or a source
+watcher alone do not establish that the project uses the current SDK. Leave
+`sdk dev` running to rebuild platform packages and refresh their watched
+consumers. Every `sdk dev --no-watch`, including an unchanged checkout path and
+package version, runs the normal Turbo build graph. Turbo decides which tasks
+are cached. After success, the SDK verifies imports and updates the same output
+checkpoint used by the watcher. Its `hashes` record successful SDK output;
+`applications` separately records each stack/application's acknowledged source
+generation, definition revision, directory and dependent build identity. A
+build-only command reports `Development SDK build ready` or `build is current`;
+it does not certify an application's loaded modules.
+
+With `--stack`, every pass reconciles the selected stack, including unchanged
+builds. This requires `sourceRefresh@1` on the owner. The CLI
+uses the same automatic restart path as source watching, bound to the observed
+application generation and definition revision. It never substitutes a manual
+restart when watching is disabled, a source is retargeted or a release is pinned.
+Every running application in the selected stack must have an active watcher;
+an excluded or unavailable watcher, starting application or missing owned handle
+is an explicit failure. Stopped applications receive no application receipt;
+their next online generation must be reconciled on the next `--stack` pass.
+Application receipts come from the owner's exact restart response and are reused
+only for the same generation, definition and dependent SDK output. A legacy
+build-only checkpoint or another stack's receipt cannot establish that.
+
+A failed build leaves the whole checkpoint unchanged. If a successful build is
+followed by a partial refresh failure, the checkpoint retains its build hashes
+and individually acknowledged applications; a retry refreshes the remaining
+bindings. The CLI reports `Development SDK refresh confirmed for <project>/<stack>`
+only after checking the final stack membership, application generations and
+watch policy. Before recording a receipt, it rechecks output digests under the
+existing short build lock; a concurrent output change is an explicit failure.
+Symlinks and other unsupported output entries are rejected. These checks record
+a build snapshot and process lifecycle acknowledgement, not byte attestation of
+future lazy imports or an application's HTTP readiness. Declared readiness
+probes provide the latter evidence.
+
+Build caches must include `.omnitron/dev-sdk/*.json` as inputs. For Turbo, add
+this glob to the project's `globalDependencies`. It binds cached tasks to the
+selected SDK and the successful build checkpoint, including declarations and
+static assets. The distribution lock alone cannot identify locally linked code.
+Application receipt changes also invalidate that consumer cache. The SDK watcher
+observes SDK source/build inputs, so writing these consumer receipts does not
+trigger another SDK build.
+These private files stay outside Git and are absent in clean registry builds.
+
 One owner can supervise development applications and installed releases together.
 Watch applies only to source entries allowed by the application and global watch
 policy. An installed entry (`releaseRoot`) never enters the source build pipeline
@@ -574,7 +855,16 @@ or either watcher, even when development mode is enabled. Launch receipts and
 artifact integrity still determine whether an installed executable is trusted;
 setting `releaseRoot` does not grant that trust.
 
-Enabling watch reconciles edits made while watch was disabled. Disabling watch
+The owner derives both watcher inventories from its actual application handles,
+including classic applications added by registered projects after daemon startup.
+A classic source subscription survives its internal child replacement, so edits
+received during startup are processed after the current restart. Explicit stop,
+redefinition, retirement and watch-policy changes revoke pending source events.
+
+Enabling bootstrap watch rebuilds changes made while it was disabled. Enabling
+classic watch subscribes to subsequent filesystem changes; it does not infer
+past edits. Use `sdk dev --stack` to build and confirm changed SDK output.
+Disabling watch
 awaits disposal and cancels queued automatic restarts. A restart already stopping an
 application may finish when only global watching is disabled. Explicitly
 redefining that application revokes its pending restart, including an identical

package/bin/{pnpmfile-sdk.mjs → pnpmfile-sdk.js}

@@ -6,6 +6,18 @@ import { fileURLToPath } from 'node:url';
 const root = fs.realpathSync(path.dirname(fileURLToPath(import.meta.url)));
 const profileDirectory = path.join(root, '.omnitron', 'dev-sdk');
 
+// Shared with the SDK selector: a directory must contain the actual public
+// framework package, not an alias, a private workspace or an unversioned stub.
+export function frameworkPackage(name, directory, expectedVersion) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(directory, 'package.json'), 'utf8'));
+  if (!/^@omnitron-dev\/[a-z0-9-]+$/.test(name) || manifest.name !== name || manifest.private ||
+      typeof manifest.version !== 'string' ||
+      !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?(?:\+[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?$/.test(manifest.version) ||
+      expectedVersion !== undefined && manifest.version !== expectedVersion)
+    throw Error('Invalid Omnitron SDK package identity for ' + name);
+  return manifest;
+}
+
 export function developmentPackages() {
   let profile;
   try {
@@ -20,6 +32,7 @@ export function developmentPackages() {
     if (!/^@omnitron-dev\/[a-z0-9-]+$/.test(name) || !path.isAbsolute(directory) ||
         !directory.startsWith(profile.source + path.sep) || fs.realpathSync(directory) !== directory)
       throw Error('Invalid Omnitron SDK package location for ' + name);
+    frameworkPackage(name, directory, profile.versions?.[name]);
   }
   return profile.links;
 }
@@ -28,7 +41,12 @@ export const hooks = {
   updateConfig(config) {
     const links = Object.entries(developmentPackages());
     if (!links.length) return config;
-    const overrides = { ...config.overrides };
+    // pnpm resolves workspace overrides from lockfileDir. Importers keep their own base.
+    const overrides = Object.fromEntries(Object.entries(config.overrides ?? {}).map(([selector, specifier]) => {
+      const local = typeof specifier === 'string' && /^(file:|link:)(.+)$/.exec(specifier);
+      if (!local || path.isAbsolute(local[2])) return [selector, specifier];
+      return [selector, local[1] + path.resolve(root, local[2]).split(path.sep).join('/')];
+    }));
     for (const [name, directory] of links) overrides[name] = 'link:' + directory;
     return { ...config, lockfileDir: profileDirectory, overrides };
   },

package/bin/sdk.d.ts

@@ -0,0 +1,19 @@
+export interface DevelopmentSdkStatus {
+  mode: 'development' | 'registry';
+  verifiedImports: number;
+  source?: string;
+  distributionLock?: 'present' | 'absent' | 'manager-only';
+  distributionLockChanged?: boolean;
+}
+export interface DevelopmentSdkProfile {
+  schema: 1;
+  root: string;
+  source: string;
+  links: Record<string, string>;
+  lockSha256?: string | null;
+  versions?: Record<string, string>;
+  inputSha256?: string;
+}
+export function sdkCommand(args: string[]): Promise<void>;
+export function inspectSdk(projectDirectory?: string): Promise<DevelopmentSdkStatus>;
+export function watchSdk(profile: DevelopmentSdkProfile, stack: string | undefined, signal: AbortSignal): Promise<void>;