@x12i/memorix-service 3.2.1 → 3.3.0

package/dist/magit/magit-pack-service.js

@@ -1,32 +1,95 @@
 /**
- * MagitPackService — server-only façade over @x12i/magit for pack versioning
- * and Magit 2.9+ FR package catalog (packPackageFR / list / fetch).
+ * MagitPackService — server-only façade over @x12i/magit for pack versioning.
+ * Phase 0–5: ensureRepo, saveVersion, history, diff, packAtCommit, publish, proposals.
+ *
+ * Package catalog (Magit 2.10+): flat FR-CPS when store env is unset; store-
+ * scoped when both MAGIT_PACKAGE_STORE_SELECTOR + MAGIT_PACKAGE_TYPE_ID are
+ * set. Selector is capability-like — never log it. Half-config fails closed.
+ * Store packages: pack/list/fetch + pullStore only (no Magit restore).
  */
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { MongoClient } from "mongodb";
-import { magit, listProposalLedgerEntries, isPatchsetError, isPackageCollisionError, createProgressReporter, labelDiff, } from "@x12i/magit";
+import { magit, listProposalLedgerEntries, isPatchsetError, createProgressReporter, labelDiff, redactStoreSelector, } from "@x12i/magit";
 import { checksumMetadataPack } from "@x12i/memorix-metadata-runtime";
-import { ServiceError } from "../errors.js";
+import { ServiceError, redactSecrets } from "../errors.js";
 import { isOrgRuntimeFolderSource, stripOrgRuntimeSourcesFromPack, } from "../org-sources.js";
-import { PACKAGE_CATALOG_ORG, } from "./package-catalog-bridge.js";
-import { MAGIT_AGENTS_COLLECTION, MAGIT_SEED_AGENT_ID, metadataPackToPackagePayload, packagePayloadToMetadataPack, packToPatchset, parseRecordId, parseSaveVersionIdempotencyKey, recordIdForDefinition, recordsToPack, } from "./pack-to-patchset.js";
+import { MAGIT_AGENTS_COLLECTION, MAGIT_SEED_AGENT_ID, packToPackagePayload, packToPatchset, packToDefinitionRecords, parseRecordId, parseSaveVersionIdempotencyKey, recordIdForDefinition, recordsToPack, packagePayloadToPack, } from "./pack-to-patchset.js";
 import { mergeProposalIntoPack, } from "./proposal-to-pack.js";
+// ---------------------------------------------------------------------------
+// Central package catalog (FR-CPS). Org-free — kind/id/version only. Distinct
+// from the org-scoped saveVersion/history/diff/packAtCommit API above, which
+// remains this environment's own live-metadata history.
+// ---------------------------------------------------------------------------
+/** Fixed local working directory for the shared package-catalog repo. Not an
+ *  org — purely a local disk key; the remote binding is the catalog tenant
+ *  (resolveMagitCatalogTenant), applied uniformly by ensureRepo. */
+const PACKAGE_CATALOG_LOCAL_DIR = "_package-catalog";
 /**
- * Magit storage auth is the Authix service token.
- * Prefers MAGIT_STORAGE_TOKEN_ENV, else MAGIT_TOKEN / AUTHIX_TOKEN when set.
+ * Any error surfaced from a catalog-flagged operation that isn't already a
+ * ServiceError or PatchsetError (both handled earlier in mapError, and
+ * neither indicates a reachability problem) is treated as central-storage
+ * unreachable — network/DNS failure, connection refused, and auth failure
+ * (missing/expired MAGIT_TOKEN) all leave the catalog equally unusable from
+ * an operator's "is Magit healthy" perspective, and the FR (§8's retirement)
+ * requires surfacing every one of them rather than silently falling back to
+ * local-only behaviour. The first line of the error message is kept as the
+ * classified reason for diagnostics.
  */
-export function resolveMagitStorageTokenEnv() {
-    const explicit = process.env.MAGIT_STORAGE_TOKEN_ENV?.trim();
-    if (explicit)
-        return explicit;
-    if (process.env.MAGIT_TOKEN?.trim())
-        return "MAGIT_TOKEN";
-    if (process.env.AUTHIX_TOKEN?.trim())
-        return "AUTHIX_TOKEN";
-    // Magit SDK default name — put the Authix service token here.
-    return "MAGIT_TOKEN";
+/** First line of an error, with Magit store-selector material redacted. */
+export function classifyCatalogUnreachable(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const first = message.split("\n")[0] ?? message;
+    return String(redactSecrets(redactStoreSelector(first)));
+}
+/**
+ * Pure record-level pack compare used for Mode A (immutable store payloads)
+ * and unit tests. Keys definitions by kind/id with stable JSON equality.
+ */
+export function diffMetadataPacks(agentId, from, to, fromPack, toPack) {
+    const before = new Map();
+    const after = new Map();
+    for (const r of packToDefinitionRecords(fromPack)) {
+        before.set(`${r.kind}/${r.id}`, {
+            kind: r.kind,
+            id: r.id,
+            body: r.definition,
+        });
+    }
+    for (const r of packToDefinitionRecords(toPack)) {
+        after.set(`${r.kind}/${r.id}`, {
+            kind: r.kind,
+            id: r.id,
+            body: r.definition,
+        });
+    }
+    const keys = new Set([...before.keys(), ...after.keys()]);
+    const changes = [];
+    for (const key of [...keys].sort()) {
+        const b = before.get(key);
+        const a = after.get(key);
+        if (!b && a) {
+            changes.push({ kind: a.kind, id: a.id, change: "added" });
+            continue;
+        }
+        if (b && !a) {
+            changes.push({ kind: b.kind, id: b.id, change: "removed" });
+            continue;
+        }
+        if (b && a) {
+            const fields = fieldDiffs(b.body, a.body);
+            if (fields?.length) {
+                changes.push({
+                    kind: a.kind,
+                    id: a.id,
+                    change: "changed",
+                    fields,
+                });
+            }
+        }
+    }
+    return { agentId, from, to, changes };
 }
 const MEMORIX_LENS = {
     [MAGIT_AGENTS_COLLECTION]: {
@@ -56,12 +119,93 @@ export function isMetadataMagitEnabled() {
     // Default-on when unset or any other truthy-ish value (including "1"/"true"/"on").
     return true;
 }
+/**
+ * `MAGIT_REPO_ROOT` is the parent of each repo's LOCAL working checkout / cache
+ * (per-org live-history repos and the shared package catalog repo alike). It is
+ * demoted, not removed, by the central-catalog cutover (X12-65): it no longer
+ * doubles as the catalog — that is central storage, bound via `storageTenant`
+ * (see `resolveMagitCatalogTenant`). This directory can be wiped and
+ * re-bootstrapped from central storage without data loss.
+ */
 export function resolveMagitRepoRootParent() {
     const fromEnv = process.env.MAGIT_REPO_ROOT?.trim();
     if (fromEnv)
         return fromEnv;
     return join(process.cwd(), ".tmp", "magit-repos");
 }
+/**
+ * Central Magit package-catalog tenant (FR-CPS-1). This is a fixed
+ * developer/solution scope for Memorix's own package storage — it must NEVER
+ * be a runtime `orgId`. Org only appears as a Restore install target, never as
+ * the catalog key. Default `"memorix"`.
+ */
+export function resolveMagitCatalogTenant() {
+    return process.env.MAGIT_CATALOG_TENANT?.trim() || "memorix";
+}
+/**
+ * Magit storage repo id for the central package catalog (FR-CPS). Defaults to
+ * `memorix-metadata-_package-catalog`. Override with MAGIT_CATALOG_REPO when the
+ * Authix token only grants a specific repo (e.g. `demo`).
+ */
+export function resolveMagitCatalogRepoName() {
+    return (process.env.MAGIT_CATALOG_REPO?.trim() ||
+        `memorix-metadata-${PACKAGE_CATALOG_LOCAL_DIR}`);
+}
+/**
+ * Env var *name* Magit uses to load the central-storage bearer token.
+ * Priority: MAGIT_STORAGE_TOKEN_ENV (explicit name) → AUTHIX_TOKEN if set → MAGIT_TOKEN.
+ */
+export function resolveMagitStorageTokenEnv() {
+    const explicit = process.env.MAGIT_STORAGE_TOKEN_ENV?.trim();
+    if (explicit)
+        return explicit;
+    if (process.env.AUTHIX_TOKEN?.trim())
+        return "AUTHIX_TOKEN";
+    return "MAGIT_TOKEN";
+}
+/**
+ * Magit 2.10 typed global store binding.
+ * - both MAGIT_PACKAGE_STORE_SELECTOR + MAGIT_PACKAGE_TYPE_ID → store path
+ * - neither → flat catalog (2.9 compatible)
+ * - only one set → fail closed (never half-use store APIs)
+ */
+export function resolveMagitTypedStoreConfig() {
+    const storeSelector = process.env.MAGIT_PACKAGE_STORE_SELECTOR?.trim() || "";
+    const packageTypeId = process.env.MAGIT_PACKAGE_TYPE_ID?.trim() || "";
+    if (!storeSelector && !packageTypeId)
+        return null;
+    if (!storeSelector || !packageTypeId) {
+        throw new ServiceError("VALIDATION", "MAGIT_PACKAGE_STORE_SELECTOR and MAGIT_PACKAGE_TYPE_ID must both be set for store-scoped packs, or both unset for the flat 2.9 catalog", 400);
+    }
+    const publisherId = process.env.MAGIT_PACKAGE_PUBLISHER_ID?.trim() || "memorix";
+    const publisherAppId = process.env.MAGIT_PACKAGE_PUBLISHER_APP_ID?.trim() || "memorix-service";
+    return {
+        storeSelector,
+        packageTypeId,
+        publisher: { id: publisherId, appId: publisherAppId || undefined },
+    };
+}
+/** Whether store env is configured (yes/no only — never selector values). */
+export function magitTypedStoreConfigured() {
+    try {
+        return resolveMagitTypedStoreConfig() != null;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether MAGIT_PACKAGE_TYPE_ID is set (safe to report; not a capability secret). */
+export function magitPackageTypeIdConfigured() {
+    return Boolean(process.env.MAGIT_PACKAGE_TYPE_ID?.trim());
+}
+/** Whether MAGIT_PACKAGE_STORE_SELECTOR is set (yes/no only — never the value). */
+export function magitStoreSelectorConfigured() {
+    return Boolean(process.env.MAGIT_PACKAGE_STORE_SELECTOR?.trim());
+}
+/** Structure language id for diagnostics when set. Never the store selector. */
+export function magitPackageTypeIdForDiagnostics() {
+    return process.env.MAGIT_PACKAGE_TYPE_ID?.trim() || null;
+}
 function isLiveRef(ref) {
     return ref === "live" || ref === "LIVE";
 }
@@ -108,9 +252,14 @@ function unwrapDefinitionBody(body) {
 export class MagitPackService {
     cfg;
     ensured = new Set();
+    catalogHealth = { reachable: null, reason: null };
     constructor(cfg) {
         this.cfg = cfg;
     }
+    /** Last-observed central package-catalog reachability (task 5 diagnostics). */
+    catalogHealthStatus() {
+        return this.catalogHealth;
+    }
     progress() {
         const log = this.cfg.log;
         createProgressReporter({ mode: "json" });
@@ -120,33 +269,10 @@ export class MagitPackService {
             },
         };
     }
-    storageTokenEnvName() {
-        return this.cfg.storageTokenEnv?.trim() || resolveMagitStorageTokenEnv();
-    }
-    storageUrl() {
-        return (this.cfg.storageUrl ||
-            process.env.MAGIT_STORAGE_URL?.trim() ||
-            "https://magit-storage.x12i.com");
-    }
-    /** True when Authix/Magit token is present for remote catalog push/pull. */
-    hasRemoteCatalog() {
-        const env = this.storageTokenEnvName();
-        return Boolean(process.env[env]?.trim());
-    }
     repoRootFor(orgId) {
         return join(this.cfg.repoRootParent, orgId);
     }
-    catalogRepoRoot() {
-        return this.repoRootFor(PACKAGE_CATALOG_ORG);
-    }
     async ensureRepo(orgId) {
-        await this.ensureRepoInternal(orgId, { catalog: false });
-    }
-    /** Dedicated Magit root for org-free package catalog (`packages/`). */
-    async ensureCatalogRepo() {
-        await this.ensureRepoInternal(PACKAGE_CATALOG_ORG, { catalog: true });
-    }
-    async ensureRepoInternal(orgId, opts) {
         if (this.ensured.has(orgId))
             return;
         const { tick } = this.progress();
@@ -158,14 +284,13 @@ export class MagitPackService {
             const repo = await magit.open({ repoRoot });
             const configPath = join(repoRoot, ".magit", "config.json");
             if (!existsSync(configPath)) {
-                tick("ensureRepo.init", { orgId, catalog: opts.catalog });
-                // Catalog: enable remote bootstrap when Authix/Magit token is set.
-                // Org versioning repos stay local-only (`skipRemoteBootstrap: true`).
-                const remote = opts.catalog && this.hasRemoteCatalog();
+                tick("ensureRepo.init", { orgId });
+                const isPackageCatalog = orgId === PACKAGE_CATALOG_LOCAL_DIR;
+                const repoName = isPackageCatalog
+                    ? resolveMagitCatalogRepoName()
+                    : `memorix-metadata-${orgId}`;
                 await repo.init({
-                    name: opts.catalog
-                        ? "memorix-package-catalog"
-                        : `memorix-metadata-${orgId}`,
+                    name: repoName,
                     driver: "transform",
                     urlEnv: this.cfg.mongoUrlEnv,
                     db: this.cfg.metadataDb,
@@ -180,11 +305,19 @@ export class MagitPackService {
                         encodingProfile: "current",
                     },
                     storageProvider: "x12i-http",
-                    storageUrl: this.storageUrl(),
-                    storageTokenEnv: this.storageTokenEnvName(),
-                    storageTenant: orgId,
+                    storageUrl: this.cfg.storageUrl ||
+                        process.env.MAGIT_STORAGE_URL?.trim() ||
+                        "https://magit-storage.x12i.com",
+                    storageTokenEnv: this.cfg.storageTokenEnv || "MAGIT_TOKEN",
+                    // FR-CPS-1: catalog tenant is a fixed developer/solution scope, never
+                    // the runtime org — `orgId` here only names this repo's LOCAL working
+                    // directory (see repoRootFor), not its central storage binding.
+                    storageTenant: resolveMagitCatalogTenant(),
                     environmentName: "draft",
-                    skipRemoteBootstrap: !remote,
+                    // FR-CPS-3: bootstrap/sync with central storage instead of staying
+                    // local-only. The interim §8 bridge (skipRemoteBootstrap: true) is
+                    // retired — no silent local-history fallback.
+                    skipRemoteBootstrap: false,
                 });
                 writeFileSync(join(repoRoot, ".magitignore"), MAGITIGNORE, "utf8");
                 await this.seedAgentsCollectionCommit(repo);
@@ -196,180 +329,249 @@ export class MagitPackService {
         }
     }
     /**
-     * Pull remote package catalog when Authix token is configured.
-     * `full: true` for fetch/restore so record objects for package contents exist.
+     * Open the shared central package-catalog repo (org-free). Opening the
+     * LOCAL repo directory can succeed even when central storage itself is
+     * unreachable (`repo.init` only warns on a failed remote bootstrap by
+     * default — see `strictRemote` — and `magit.open` is a local-only call), so
+     * this deliberately does NOT mark catalogHealth reachable; only an actual
+     * round-trip (pull/pack/list/fetch) that completes should do that.
      */
-    async syncCatalogPull(opts) {
-        await this.ensureCatalogRepo();
-        if (!this.hasRemoteCatalog())
-            return { remote: false };
-        const { tick } = this.progress();
-        try {
-            this.ensureMongoEnv();
-            const repo = await magit.open({ repoRoot: this.catalogRepoRoot() });
-            tick("catalog.pull", { full: Boolean(opts?.full) });
-            const result = await repo.pull({ full: Boolean(opts?.full) });
-            return { remote: true, downloaded: result.downloaded };
-        }
-        catch (err) {
-            // Local catalog still usable; surface via log only for soft pull failures.
-            this.cfg.log?.("[magit] catalog.pull failed", {
-                error: err instanceof Error ? err.message : String(err),
-            });
-            return { remote: true };
-        }
+    async ensureCatalogRepo() {
+        await this.ensureRepo(PACKAGE_CATALOG_LOCAL_DIR);
+        return magit.open({ repoRoot: this.repoRootFor(PACKAGE_CATALOG_LOCAL_DIR) });
     }
-    async syncCatalogPush() {
-        if (!this.hasRemoteCatalog())
-            return { remote: false };
-        await this.ensureCatalogRepo();
-        const { tick } = this.progress();
-        try {
-            this.ensureMongoEnv();
-            const repo = await magit.open({ repoRoot: this.catalogRepoRoot() });
-            tick("catalog.push", {});
-            const result = await repo.push();
-            return { remote: true, uploaded: result.uploaded };
-        }
-        catch (err) {
-            throw this.mapError(err, "failed to push package catalog");
-        }
-    }
-    /** Pack a MetadataPack into Magit packages/ (does not change live metadata). */
-    async packCatalogPackage(input) {
-        const kind = input.kind;
-        const id = input.id?.trim();
-        const message = input.message?.trim();
-        if (!id)
-            throw new ServiceError("VALIDATION", "id required", 400);
-        if (!message)
-            throw new ServiceError("VALIDATION", "message required", 400);
-        await this.ensureCatalogRepo();
+    /**
+     * Pack a payload into the central catalog (FR-CPS-4), or into the typed
+     * global store when MAGIT_PACKAGE_STORE_SELECTOR + MAGIT_PACKAGE_TYPE_ID are set.
+     *
+     * Flat: pull then packPackageFR without selector.
+     * Store: packPackageFR with selector/type/kind/publisher; do not full-tree pull.
+     */
+    async packPackage(opts) {
         const { tick } = this.progress();
         try {
-            this.ensureMongoEnv();
-            const clean = stripOrgRuntimeSourcesFromPack(input.pack);
-            const payload = metadataPackToPackagePayload(clean);
-            const repo = await magit.open({ repoRoot: this.catalogRepoRoot() });
-            tick("catalog.packPackageFR", { kind, id, mode: input.mode });
-            const mode = input.mode ??
-                (input.pins?.length ? "full" : "narrow");
-            const result = await repo.packPackageFR({
-                kind,
-                id,
-                message,
-                payload,
-                mode,
-                associations: input.associations
+            const store = resolveMagitTypedStoreConfig();
+            const repo = await this.ensureCatalogRepo();
+            const { payload } = packToPackagePayload(opts.pack);
+            tick("packPackage.start", {
+                kind: opts.kind,
+                id: opts.id,
+                storeScoped: Boolean(store),
+            });
+            if (store) {
+                const publisher = opts.actor?.id
                     ? {
-                        connectorIds: input.associations.connectorIds,
-                        serviceIds: input.associations.serviceIds,
+                        id: opts.actor.id,
+                        appId: store.publisher.appId,
                     }
-                    : undefined,
-                pins: input.pins,
-                actor: input.actor
-                    ? { id: input.actor.subject, email: undefined }
-                    : undefined,
-            });
-            // Pin catalog HEAD so subsequent pin packs / full agent packs share lineage.
-            if (!result.reused) {
-                this.pinPackTip(repo, result.version);
+                    : store.publisher;
+                const result = await repo.packPackageFR({
+                    storeSelector: store.storeSelector,
+                    packageTypeId: store.packageTypeId,
+                    kind: opts.kind,
+                    id: opts.id,
+                    message: opts.message,
+                    payload,
+                    associations: opts.associations,
+                    mode: opts.mode,
+                    publisher,
+                    actor: opts.actor,
+                });
+                // Magit 2.11+ throws when default publish fails; still bind health to
+                // published so clients and diagnostics stay honest if publish:false ever used.
+                const published = result.published === true;
+                if (published) {
+                    this.catalogHealth = { reachable: true, reason: null };
+                }
+                else {
+                    this.catalogHealth = {
+                        reachable: false,
+                        reason: "pack completed without remote publish (published=false)",
+                    };
+                }
+                tick("packPackage.done", {
+                    version: result.version,
+                    reused: result.reused,
+                    published,
+                    storeScoped: true,
+                });
+                return {
+                    version: result.version,
+                    checksum: result.checksum,
+                    reused: result.reused,
+                    published,
+                    storeId: result.storeId,
+                    packageTypeId: result.packageTypeId ?? store.packageTypeId,
+                };
             }
-            const push = await this.syncCatalogPush();
-            tick("catalog.packPackageFR.done", {
-                version: result.version,
-                reused: result.reused,
-                remote: push.remote,
+            await repo.pull();
+            const result = await repo.packPackageFR({
+                kind: opts.kind,
+                id: opts.id,
+                message: opts.message,
+                payload,
+                associations: opts.associations,
+                mode: opts.mode,
+                pins: opts.pins,
+                actor: opts.actor,
             });
+            this.catalogHealth = { reachable: true, reason: null };
+            tick("packPackage.done", { version: result.version, reused: result.reused });
             return {
                 version: result.version,
                 checksum: result.checksum,
                 reused: result.reused,
-                remote: push.remote,
             };
         }
         catch (err) {
-            if (isPackageCollisionError(err)) {
-                throw new ServiceError("VALIDATION", `package collision: ${err.message}`, 409);
-            }
-            throw this.mapError(err, "failed to pack package into Magit catalog");
+            if (err instanceof ServiceError)
+                throw err;
+            throw this.mapError(err, "failed to pack package version", { catalog: true });
         }
     }
-    async listCatalogPackages(filter) {
-        await this.ensureCatalogRepo();
-        const pull = await this.syncCatalogPull({ full: false });
+    /**
+     * List packages — flat catalog or store-scoped list (kind required on store path).
+     * Org-free: kind + id only; never a store selector from the client.
+     */
+    async listPackages(filter) {
         try {
-            this.ensureMongoEnv();
-            const repo = await magit.open({ repoRoot: this.catalogRepoRoot() });
+            const store = resolveMagitTypedStoreConfig();
+            const repo = await this.ensureCatalogRepo();
+            if (store) {
+                if (!filter?.kind) {
+                    throw new ServiceError("VALIDATION", "kind is required when Magit typed store is configured", 400);
+                }
+                await repo.pullStore({ storeSelector: store.storeSelector });
+                const items = await repo.listPackagesFR({
+                    storeSelector: store.storeSelector,
+                    packageTypeId: store.packageTypeId,
+                    kind: filter.kind,
+                    id: filter.id,
+                    publisher: filter.publisher,
+                    maxCount: filter.maxCount,
+                });
+                this.catalogHealth = { reachable: true, reason: null };
+                return items.map((item) => ({
+                    kind: item.kind,
+                    id: item.id,
+                    version: item.version,
+                    checksum: item.checksum,
+                    message: item.message,
+                    createdAt: item.createdAt,
+                    associations: item.associations,
+                    mode: item.mode,
+                    publisher: item.publisher,
+                }));
+            }
+            await repo.pull();
             const items = await repo.listPackagesFR({
                 kind: filter?.kind,
-                id: filter?.id?.trim() || undefined,
+                id: filter?.id,
                 maxCount: filter?.maxCount,
             });
-            const mapped = items
-                .filter((row) => {
-                const k = row.kind;
-                return k === "agent" || k === "connector" || k === "service";
-            })
-                .map((row) => ({
-                kind: row.kind,
-                id: row.id,
-                version: row.version,
-                commit: row.version,
-                checksum: row.checksum,
-                message: row.message,
-                createdAt: row.createdAt,
-                mode: row.mode,
-                associations: row.associations
-                    ? {
-                        connectorIds: [...(row.associations.connectorIds ?? [])].sort(),
-                        serviceIds: [...(row.associations.serviceIds ?? [])].sort(),
-                    }
-                    : undefined,
-            }));
-            return { items: mapped, remote: pull.remote };
+            this.catalogHealth = { reachable: true, reason: null };
+            return items;
         }
         catch (err) {
-            throw this.mapError(err, "failed to list Magit package catalog");
-        }
-    }
-    async fetchCatalogPackage(ref, preferredAgentId) {
-        const version = ref.version?.trim();
-        const id = ref.id?.trim();
-        if (!id)
-            throw new ServiceError("VALIDATION", "id required", 400);
-        if (!version)
-            throw new ServiceError("VALIDATION", "version required", 400);
-        await this.ensureCatalogRepo();
-        // Full pull so package contents + record bodies resolve after remote sync.
-        const pull = await this.syncCatalogPull({ full: true });
-        const { tick } = this.progress();
+            if (err instanceof ServiceError)
+                throw err;
+            throw this.mapError(err, "failed to list packages", { catalog: true });
+        }
+    }
+    /**
+     * Fetch a package version WITH its payload.
+     * Flat: full pull + fetchPackageFR(ref).
+     * Store: pullStore + fetchPackageFR({ storeSelector, packageTypeId, kind, id, version }).
+     * Restore remains product-side (install after fetch) — no Magit store restore.
+     */
+    async fetchPackage(ref) {
         try {
-            this.ensureMongoEnv();
-            const repo = await magit.open({ repoRoot: this.catalogRepoRoot() });
-            tick("catalog.fetchPackageFR", { kind: ref.kind, id, version });
-            const fetched = await repo.fetchPackageFR({
-                kind: ref.kind,
+            const store = resolveMagitTypedStoreConfig();
+            const repo = await this.ensureCatalogRepo();
+            if (store) {
+                await repo.pullStore({ storeSelector: store.storeSelector });
+                const fetched = await repo.fetchPackageFR({
+                    storeSelector: store.storeSelector,
+                    packageTypeId: store.packageTypeId,
+                    kind: ref.kind,
+                    id: ref.id,
+                    version: ref.version,
+                });
+                this.catalogHealth = { reachable: true, reason: null };
+                return {
+                    ref: {
+                        kind: fetched.kind,
+                        id: fetched.id,
+                        version: fetched.version,
+                    },
+                    checksum: fetched.checksum,
+                    payload: fetched.payload,
+                    associations: fetched.associations,
+                    publisher: fetched.publisher,
+                };
+            }
+            await repo.pull({ full: true });
+            const fetched = await repo.fetchPackageFR(ref);
+            this.catalogHealth = { reachable: true, reason: null };
+            return fetched;
+        }
+        catch (err) {
+            if (err instanceof ServiceError)
+                throw err;
+            throw this.mapError(err, "failed to fetch package version", { catalog: true });
+        }
+    }
+    /**
+     * Compare two package versions (or a version vs live/installed).
+     *
+     * Mode A (typed store): package versions are immutable store payloads, not
+     * catalog-repo commits. Fetch both refs (or accept an installed pack for the
+     * installed/live sentinel) and produce a record-level PackDiffResult.
+     *
+     * Mode B (flat FR-CPS): reuses the org-scoped commit diff against the
+     * catalog local repo. `sliceAgentId` is the catalog-internal record grouping
+     * packPackage embeds, not a runtime org.
+     */
+    async diffPackages(sliceAgentId, opts) {
+        const from = opts.from?.trim();
+        const to = opts.to?.trim();
+        if (!from || !to) {
+            throw new ServiceError("VALIDATION", "from and to required", 400);
+        }
+        const store = resolveMagitTypedStoreConfig();
+        if (!store) {
+            return this.diff(PACKAGE_CATALOG_LOCAL_DIR, sliceAgentId, { from, to });
+        }
+        const kind = opts.kind;
+        const id = opts.id?.trim();
+        if (!kind || !id) {
+            throw new ServiceError("VALIDATION", "kind and id required for typed-store package compare", 400);
+        }
+        const resolveSide = async (ref) => {
+            if (ref === "live" || ref === "LIVE" || ref === "installed") {
+                if (!opts.installedPack) {
+                    throw new ServiceError("VALIDATION", "installed package payload required when comparing against installed/live", 400);
+                }
+                return opts.installedPack;
+            }
+            const fetched = await this.fetchPackage({
+                kind: kind,
                 id,
-                version,
+                version: ref,
             });
-            const pack = stripOrgRuntimeSourcesFromPack(packagePayloadToMetadataPack(fetched.payload, preferredAgentId?.trim() ||
-                (ref.kind === "agent" ? id : undefined)));
-            return {
-                pack,
-                checksum: fetched.checksum,
-                version: fetched.ref.version,
-                associations: fetched.associations
-                    ? {
-                        connectorIds: [...(fetched.associations.connectorIds ?? [])].sort(),
-                        serviceIds: [...(fetched.associations.serviceIds ?? [])].sort(),
-                    }
-                    : undefined,
-                remote: pull.remote,
-            };
+            return packagePayloadToPack(sliceAgentId, fetched.payload);
+        };
+        try {
+            const fromPack = await resolveSide(from);
+            const toPack = await resolveSide(to);
+            return diffMetadataPacks(sliceAgentId, from, to, fromPack, toPack);
         }
         catch (err) {
-            throw this.mapError(err, "failed to fetch package from Magit catalog");
+            if (err instanceof ServiceError)
+                throw err;
+            throw this.mapError(err, "failed to compare package versions", {
+                catalog: true,
+            });
         }
     }
     async saveVersion(orgId, pack, opts) {
@@ -902,18 +1104,170 @@ export class MagitPackService {
             process.env[this.cfg.mongoUrlEnv] = this.cfg.mongoUri;
         }
     }
-    mapError(err, fallback) {
+    mapError(err, fallback, opts) {
         if (err instanceof ServiceError)
             return err;
         if (isPatchsetError(err)) {
-            return new ServiceError("VALIDATION", `${fallback}: ${err.message}`, 400);
+            const safe = String(redactSecrets(redactStoreSelector(err.message)));
+            return new ServiceError("VALIDATION", `${fallback}: ${safe}`, 400);
         }
-        if (isPackageCollisionError(err)) {
-            return new ServiceError("VALIDATION", `${fallback}: ${err.message}`, 409);
+        const raw = err instanceof Error ? err.message : String(err);
+        const message = String(redactSecrets(redactStoreSelector(raw)));
+        if (opts?.catalog) {
+            const reason = classifyCatalogUnreachable(err);
+            this.catalogHealth = { reachable: false, reason };
+            return new ServiceError("MAGIT_CATALOG_UNREACHABLE", `${fallback}: central package catalog is not reachable (${reason})`, 503);
         }
-        const message = err instanceof Error ? err.message : String(err);
         return new ServiceError("MAGIT_UNAVAILABLE", `${fallback}: ${message}`, 503);
     }
+    // -------------------------------------------------------------------------
+    // Catalog store administration (Magit 2.12.1 owner operations)
+    // -------------------------------------------------------------------------
+    /**
+     * Provision a typed global package store (create + pushStore + verify).
+     * Returns the selector EXACTLY ONCE — caller must write it to a secret store.
+     * Duplicate packageTypeId stores abort unless force=true.
+     */
+    async provisionTypedPackageStore(opts) {
+        const packageTypeId = opts?.packageTypeId?.trim() ||
+            process.env.MAGIT_PACKAGE_TYPE_ID?.trim() ||
+            "memorix.packages.v1";
+        const allowedKinds = opts?.allowedKinds && opts.allowedKinds.length > 0
+            ? opts.allowedKinds
+            : ["agent", "connector", "service", "agent-bundle"];
+        try {
+            const repo = await this.ensureCatalogRepo();
+            const existing = await repo.listStores();
+            const match = existing.find((s) => s.typeDescriptor?.packageTypeId === packageTypeId);
+            if (match && !opts?.force) {
+                throw new ServiceError("VALIDATION", `A store for packageTypeId=${packageTypeId} already exists (createdAt=${match.createdAt}). Pass force to create another, or use recover with an explicit storeId.`, 409);
+            }
+            const created = await repo.createGlobalStore({
+                packageTypeId,
+                allowedKinds,
+            });
+            const pushed = await repo.pushStore({
+                storeSelector: created.storeSelector,
+                packageTypeId: created.packageTypeId,
+            });
+            // Metadata-only verify (listStores never returns selectors).
+            await repo.listStores();
+            this.catalogHealth = { reachable: true, reason: null };
+            return {
+                storeId: created.storeId,
+                storeSelector: created.storeSelector,
+                packageTypeId: created.packageTypeId,
+                pushed: {
+                    uploaded: pushed.uploaded ?? 0,
+                    skipped: pushed.skipped ?? 0,
+                },
+                existingStoreCount: existing.length,
+            };
+        }
+        catch (err) {
+            if (err instanceof ServiceError)
+                throw err;
+            throw this.mapError(err, "failed to provision typed package store", {
+                catalog: true,
+            });
+        }
+    }
+    /**
+     * Verify configured catalog reachability (typed store via pullStore, or flat pull).
+     * Never prints selector/token values.
+     */
+    async verifyTypedPackageStore() {
+        try {
+            const store = resolveMagitTypedStoreConfig();
+            const repo = await this.ensureCatalogRepo();
+            if (store) {
+                await repo.pullStore({
+                    storeSelector: store.storeSelector,
+                    packageTypeId: store.packageTypeId,
+                });
+                this.catalogHealth = { reachable: true, reason: null };
+                return {
+                    ok: true,
+                    mode: "typed-store",
+                    packageTypeId: store.packageTypeId,
+                    reachable: true,
+                };
+            }
+            await repo.pull();
+            this.catalogHealth = { reachable: true, reason: null };
+            return {
+                ok: true,
+                mode: "flat",
+                packageTypeId: null,
+                reachable: true,
+            };
+        }
+        catch (err) {
+            if (err instanceof ServiceError)
+                throw err;
+            throw this.mapError(err, "failed to verify package catalog", {
+                catalog: true,
+            });
+        }
+    }
+    /**
+     * Owner recovery: mint a new selector for an existing storeId, then pushStore.
+     * The new selector is returned ONCE. storeId is sensitive — operators only.
+     */
+    async recoverStoreSelector(opts) {
+        const storeId = opts.storeId?.trim();
+        if (!storeId) {
+            throw new ServiceError("VALIDATION", "storeId required for recovery", 400);
+        }
+        try {
+            const repo = await this.ensureCatalogRepo();
+            const rotated = await repo.rotateStoreSelector({ storeId });
+            const pushed = await repo.pushStore({
+                storeSelector: rotated.storeSelector,
+                packageTypeId: rotated.packageTypeId,
+            });
+            this.catalogHealth = { reachable: true, reason: null };
+            return {
+                storeId: rotated.storeId,
+                storeSelector: rotated.storeSelector,
+                packageTypeId: rotated.packageTypeId,
+                pushed: {
+                    uploaded: pushed.uploaded ?? 0,
+                    skipped: pushed.skipped ?? 0,
+                },
+            };
+        }
+        catch (err) {
+            if (err instanceof ServiceError)
+                throw err;
+            throw this.mapError(err, "failed to recover store selector", {
+                catalog: true,
+            });
+        }
+    }
+    /**
+     * Owner inventory of stores (metadata only — never selectors).
+     */
+    async listPackageStores() {
+        try {
+            const repo = await this.ensureCatalogRepo();
+            const stores = await repo.listStores();
+            this.catalogHealth = { reachable: true, reason: null };
+            return stores.map((s) => ({
+                storeId: s.storeId,
+                packageTypeId: s.typeDescriptor.packageTypeId,
+                allowedKinds: [...(s.typeDescriptor.allowedKinds ?? [])],
+                createdAt: s.createdAt,
+            }));
+        }
+        catch (err) {
+            if (err instanceof ServiceError)
+                throw err;
+            throw this.mapError(err, "failed to list package stores", {
+                catalog: true,
+            });
+        }
+    }
 }
 export function createMagitPackService(cfg) {
     return new MagitPackService(cfg);