VanguDeploymentConstructs

@zephytiju/vangu-constructs is the versioned TypeScript contract and standard construct library for immutable Vangu deployment packages. Package code is the authoring authority; the v1 manifest is deterministic evidence derived from that code and immutable build provenance.

The library owns only package declaration and composition contracts. It does not implement the Vangu execution workflow, target access, provider implementations, REST APIs, mutable discovery, or a parallel YAML/JSON authoring contract.

Target capabilities and compatibility

defineGenericCapability creates provider-neutral contracts. defineProviderCapability creates an explicitly provider-scoped key under provider/<provider>/...; packages still never select or install the adapter that implements it.

The target-side contract is published from @zephytiju/vangu-constructs/target. createTargetDescriptorV1 derives a canonical, deeply frozen descriptor and sha256 capability digest from an exact static adapter inventory. The descriptor contains only a stable target ID, monotonic revision, target-agent version, substrate class, direct-OCI artifact mode, bounded availability, approved adapter package coordinates, and capability contracts. Credentials, provider configuration, endpoints, Platform inventory, and live adapter values are not fields.

resolveTargetCompatibilityV1 is a pure pre-preview operation. It requires the target ID, revision, and capability digest snapshotted when execution intent was accepted. It rejects stale snapshots, incompatible target-agent versions, and missing or incompatible capabilities with the affected manifest path, and returns only the statically approved adapter IDs needed by the graph.

Standard application constructs

Package authors resolve ApplicationDeploymentRequirement from the bounded deployment context, then pass that capability to provider-neutral Pulumi components. The capability owns the target implementation; the public component API exposes no provider objects, credentials, raw state, target lifecycle, or dynamically selected adapters.

import {
  ApplicationDeploymentRequirement,
  ConfigurationBinding,
  defineDeploymentPackage,
  ImageService,
  Route,
  SecretBinding,
} from "@zephytiju/vangu-constructs";

export default defineDeploymentPackage({
  // package metadata omitted
  capabilities: { requires: [ApplicationDeploymentRequirement] },
  configure(ctx) {
    const runtime = ctx.capabilities.require(ApplicationDeploymentRequirement);
    const configuration = new ConfigurationBinding("orders-config", {
      runtime,
      reference: ctx.configurationReference("runtime-config"),
      delivery: { environmentVariable: "ORDERS_CONFIG" },
    });
    const secret = new SecretBinding("orders-signing-key", {
      runtime,
      reference: ctx.secretReference("signing-key"),
      delivery: { mountPath: "/var/run/secrets/orders/signing-key" },
    });
    const api = new ImageService("orders-api", {
      runtime,
      image: ctx.image("api"),
      port: 8080,
      configuration: [configuration],
      secrets: [secret],
    });
    const route = new Route("orders-route", {
      runtime,
      targetReference: api.serviceReference,
      protocol: "https",
      path: "/orders",
      exposure: "gateway",
    });
    return { outputs: { endpoint: route.endpoint } };
  },
});

Job, StorageRequest, and ApplicationBinding follow the same boundary. Every workload image is required to be digest-pinned before a target implementation is called. Configuration and secrets are opaque references; the components never accept their bytes.

Meridian storage integration

The ./meridian entry point imports the exact public @zephytiju/[email protected] contract. defineMeridianIntegration derives immutable Resource-requirement, schema, Operation, Engine-profile, Adapter, lifecycle, and runtime-config evidence. A Meridian-enabled package must also declare the released package version and registry integrity exported as MERIDIAN_CONSTRUCTS_*; missing or altered pins fail before preview.

MeridianStorageBinding consumes a typed MeridianBindingOutputV1 and generated meridian-config.v1 inside the Vangu-owned runtime boundary. Its workload-facing surface is limited to the logical Resource, Binding reference, approved profile fingerprint, typed capabilities, lifecycle evidence, config fingerprint, and the path selected by MERIDIAN_CONFIG. Engine endpoints, physical namespaces, Kafka topology, credentials, ACL material, and rendered configuration are intentionally absent from its public outputs.

Mandatory Policy Pack

The package includes a runnable Pulumi Policy Pack in policy-pack/ and reusable policies at @zephytiju/vangu-constructs/policy. All policies are mandatory and critical. They reject:

• mutable or unresolved images;
• floating dependencies or missing sha512 integrity;
• privileged, provider-specific, or dynamically selected capabilities;
• raw credentials, secret values, and encoded Secret payloads;
• cross-plane StackReference or raw state access; and
• dynamic providers, adapter discovery/downloads, and floating adapter packages.

After building the package, run the local pack with the standard Pulumi policy workflow from the policy-pack directory.

Package entry point

import { defineDeploymentPackage } from "@zephytiju/vangu-constructs";

export default defineDeploymentPackage({
  contractVersion: "v1",
  name: "orders-domain",
  version: "1.0.0",
  images: [
    {
      name: "api",
      reference:
        "ghcr.io/zephytiju/orders@sha256:<64 lowercase hex characters>",
    },
  ],
  compatibility: {
    constructs: "^1.0.0",
    core: "^1.0.0",
    targetAgent: "^1.0.0",
  },
  trust: "standard",
  configure(ctx) {
    return { outputs: { image: ctx.image("api") } };
  },
});

DeploymentContext exposes only an application/target identity, digest-pinned images, configuration and secret identifiers, approved capability/provider bindings, and typed package references. It has no credential, raw state, stack-discovery, network-discovery, or package-selection API.

Typed package references

Define shared references in a contract-only library:

import type * as pulumi from "@pulumi/pulumi";
import {
  definePackageReference,
  providePackageReference,
  requirePackageReference,
} from "@zephytiju/vangu-constructs";

interface WorkerServiceV1 {
  readonly endpoint: pulumi.Output<string>;
}

export const WorkerServiceReference = definePackageReference<WorkerServiceV1>(
  "application/worker-service",
  "1.0.0",
);

export const WorkerRequirement = requirePackageReference(
  WorkerServiceReference,
  "^1.0.0",
);

// Provider package configure result:
providePackageReference(WorkerServiceReference, { endpoint });

// Consumer package configure callback:
const worker = ctx.packageReferences.require(WorkerRequirement);

Vangu Core calls composeDeploymentPackages before Pulumi preview. It rejects missing, duplicate, incompatible, and cyclic references before any package configure callback runs. After preflight, the resolver passes the exact provided object to the consumer. Pulumi Outputs are not serialized or reconstructed, so their dependency and lifecycle ownership remain intact.

Manifest evidence

generateDeploymentPackageManifest emits juntai.vangu/deployment-package-manifest/v1 with exact:

• image digests;
• requested/provided capability and package-reference contracts;
• constructs, Core, target-agent, and optional Node compatibility;
• trust tier;
• declared input/output schemas;
• dependency versions and integrity values; and
• source, builder, SBOM, and signature-bundle provenance.

Target descriptor evidence is defined by schemas/target-descriptor.v1.schema.json and juntai.vangu/target-descriptor/v1.

The schema is published at schemas/deployment-package-manifest.v1.schema.json; the OCI media type is application/vnd.juntai.vangu.deployment-package.v1. Live bindings, endpoints, provider objects, secret values, rendered configuration, and target-selected values are never manifest fields.

vangu-package CLI

The npm package installs vangu-package. The CLI loads the compiled package definition, derives the manifest from code, and fails closed before preview or publication when the content set, manifest, provenance, signature, compatibility contract, package-reference graph, capability requirements, or Policy Pack boundary is invalid.

The signing envelope binds all compiled program files, exact lockfiles, the SPDX/CycloneDX SBOM, and a normalized generated manifest. The final deterministic archive contains:

• package/ compiled program and lockfiles at their root-relative paths;
• evidence/deployment-package-manifest.v1.json;
• evidence/content-set.v1.json with exact sizes and SHA-256 digests;
• evidence/sbom.spdx.json;
• evidence/provenance.v1.json; and
• evidence/signature.bundle.v1.json with an Ed25519 detached signature.

Given identical source bytes, immutable inputs, provenance fields, and signing key, clean rebuilds are byte-identical. USTAR metadata and gzip time are fixed, paths and JSON keys are sorted, file modes are normalized, and mutable tags or floating inputs are rejected.

npm run fixtures:build

vangu-package sign \
  --root . \
  --definition fixture-dist/domain/domain-package.js \
  --program fixture-dist/domain \
  --lock package-lock.json \
  --sbom fixtures/package-sbom.spdx.json \
  --source-repository https://github.com/zephytiju/VanguDeploymentConstructs \
  --source-commit <40-character-commit> \
  --build-workflow .github/workflows/publish.yml \
  --build-run-id <immutable-build-id> \
  --builder-identity <workflow-identity> \
  --key <ed25519-private-key.pem> \
  --identity <workflow-identity> \
  --output domain-signature.json

vangu-package build \
  --root . \
  --definition fixture-dist/domain/domain-package.js \
  --program fixture-dist/domain \
  --lock package-lock.json \
  --sbom fixtures/package-sbom.spdx.json \
  --signature domain-signature.json \
  --source-repository https://github.com/zephytiju/VanguDeploymentConstructs \
  --source-commit <40-character-commit> \
  --build-workflow .github/workflows/publish.yml \
  --build-run-id <immutable-build-id> \
  --builder-identity <workflow-identity> \
  --output orders-domain.vangu.tgz

vangu-package verify --artifact orders-domain.vangu.tgz \
  --trusted-identity <workflow-identity> \
  --trusted-public-key <ed25519-public-key.pem>

preview accepts multiple --artifact values and validates their full signed contents before checking target versions, target capabilities, and the package-reference DAG. publish transfers the verified archive directly to an OCI registry with artifact type application/vnd.juntai.vangu.deployment-package.v1; it can use a collision-checked exact semantic version tag or publish by manifest digest only. retrieve requires the exact returned digest reference and re-verifies both OCI descriptors and package evidence.

Registry credentials are read only from VANGU_REGISTRY_USERNAME and VANGU_REGISTRY_PASSWORD; they are never accepted as manifest or archive inputs. Failures carry stable codes such as PACKAGE_MANIFEST_MISMATCH, PACKAGE_SIGNATURE_INVALID, PACKAGE_PROVENANCE_INVALID, PACKAGE_COMPATIBILITY_UNSUPPORTED, OCI_TAG_IMMUTABLE, and OCI_DIGEST_MISMATCH. Both OCI publication and retrieval require --trusted-identity and --trusted-public-key, preventing unsigned or self-asserted packages from crossing the registry boundary.

Fixtures and verification

fixtures/foundation-package.ts provides an application-scoped database binding, while fixtures/domain-package.ts consumes it without importing the foundation implementation.

npm ci --ignore-scripts
npm run check
npm run fixtures:build
npm audit --audit-level=high

The check gate covers formatting, strict TypeScript, lint, unit/negative tests, policy and preview conformance, coverage, domain/foundation fixture compilation, JSON-schema parity, declaration build, and npm artifact contents.

License

Apache License 2.0. See LICENSE and NOTICE.