@x12i/memorix-package-seed

@x12i/memorix-package-seed

Package-owned Catalox seeding with mandatory agent identity, multi-agent replication, platform-core bootstrap, validated plane writers, and an atomic once-only ledger.

Catalox database routing

Seeding does not use MEMORIX_AGENT_ID / MEMORIX_CATALOX_DB for the destination database. The pack declares identity.agentId + targetAgentIds, and each destination is opened as:

import { getMemorixMetadataDatabaseName } from "@x12i/memorix-db-router";

const dbName = getMemorixMetadataDatabaseName(agentId); // `<agentId>-memorix-catalox`

Shared env requirements: MONGO_URI and Memorix app id (MEMORIX_APP_ID / descriptors resolution).

Install

npm install @x12i/memorix-package-seed

Pack layout

my-pack/
  package-seed.json
  package-seed.manifest.json
  pipeline-services.json          # optional
  abstraction-map.json            # optional
  pipeline-steps.json             # optional
  pipeline-definitions.json       # optional
  pipeline-templates.json         # optional
  inventory-agents.json           # optional
  artifacts/                      # authoring-only (e.g. entra mappings)

Staging packs live under .operational/package-seed-packs/ (MOVE-OUT vs STAY documented there).

API

import {
  createPackageSeeder,
  attachPlatformCoreBootstrap,
  ensureSeeded,
  loadManifestFromDir,
  runPackageSeedOnStart,
} from "@x12i/memorix-package-seed";

const seeder = createPackageSeeder(
  attachPlatformCoreBootstrap({
    seedsDir: new URL("./seeds", import.meta.url).pathname,
    mode: "strict", // strict | upgrade | force
  }),
);

try {
  const result = await seeder.ensureSeeded();
  // result.outcome: applied | skipped | conflict | failed
} finally {
  await seeder.close();
}

Startup helper (trusted package config only — never wire to arbitrary HTTP input):

PACKAGE_SEED_ON_START=1 PACKAGE_SEED_MODE=strict PACKAGE_SEED_STRICT=1

await runPackageSeedOnStart({ seedsDir: "./seeds" });

Modes

Mode	Behavior
strict (default)	same contentHash → skip; different → conflict
upgrade	re-apply when seedRevision changes; revision-not-bumped → conflict
force	always re-apply (ops)

Platform core

Before integration packs, ensurePlatformCoreSeeded(targetAgentId) applies @x12i/memorix-platform-core-seed into that agent’s Catalox DB (PACKAGE_SEED_PLATFORM_CORE_DIR or .operational/package-seed-packs/_platform-core).

Ledger + lease

• Ledger catalog: memorix-package-seed-ledger (Catalox native items)
• Atomic leases: Mongo collection memorix-package-seed-leases with fencing/heartbeat
• resetLedger removes ledger/lease state only (never seeded catalog data); requires PACKAGE_SEED_ALLOW_RESET=1, yes: true, actor, reason

CLI

npx memorix-package-seed validate --dir ./seeds
npx memorix-package-seed apply --dir ./seeds --mode strict
npx memorix-package-seed status --dir ./seeds
PACKAGE_SEED_ALLOW_RESET=1 npx memorix-package-seed reset-ledger \
  --dir ./seeds --target agent-firewall-topology --actor ops --reason migrate --yes

Exit codes: 0 ok/skipped, 1 failed, 2 validation/conflict, 3 status-not-found.

Security boundary

Seed roots and identities are trusted deployment configuration. Do not expose an HTTP endpoint that accepts arbitrary package/agent/file input.

Related

• @x12i/memorix-db-router — database name routing
• @x12i/memorix-pipeline-services / @x12i/memorix-pipeline-orchestrator — typed plane writers
• .operational/package-seed-packs/ — exported MOVE-OUT packs