@x12i/memorix-service 3.2.0 → 3.3.0

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

@@ -1,17 +1,96 @@
 /**
  * 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, 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 { MAGIT_AGENTS_COLLECTION, MAGIT_SEED_AGENT_ID, 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";
+/**
+ * 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.
+ */
+/** 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]: {
         docKey: "agentId",
@@ -40,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";
 }
@@ -92,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,8 +285,12 @@ export class MagitPackService {
             const configPath = join(repoRoot, ".magit", "config.json");
             if (!existsSync(configPath)) {
                 tick("ensureRepo.init", { orgId });
+                const isPackageCatalog = orgId === PACKAGE_CATALOG_LOCAL_DIR;
+                const repoName = isPackageCatalog
+                    ? resolveMagitCatalogRepoName()
+                    : `memorix-metadata-${orgId}`;
                 await repo.init({
-                    name: `memorix-metadata-${orgId}`,
+                    name: repoName,
                     driver: "transform",
                     urlEnv: this.cfg.mongoUrlEnv,
                     db: this.cfg.metadataDb,
@@ -140,9 +309,15 @@ export class MagitPackService {
                         process.env.MAGIT_STORAGE_URL?.trim() ||
                         "https://magit-storage.x12i.com",
                     storageTokenEnv: this.cfg.storageTokenEnv || "MAGIT_TOKEN",
-                    storageTenant: orgId,
+                    // 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: true,
+                    // 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);
@@ -153,6 +328,252 @@ export class MagitPackService {
             throw this.mapError(err, "failed to ensure Magit repo");
         }
     }
+    /**
+     * 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 ensureCatalogRepo() {
+        await this.ensureRepo(PACKAGE_CATALOG_LOCAL_DIR);
+        return magit.open({ repoRoot: this.repoRootFor(PACKAGE_CATALOG_LOCAL_DIR) });
+    }
+    /**
+     * 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 {
+            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
+                    ? {
+                        id: opts.actor.id,
+                        appId: store.publisher.appId,
+                    }
+                    : 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,
+                };
+            }
+            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,
+            };
+        }
+        catch (err) {
+            if (err instanceof ServiceError)
+                throw err;
+            throw this.mapError(err, "failed to pack package version", { catalog: true });
+        }
+    }
+    /**
+     * 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 {
+            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,
+                maxCount: filter?.maxCount,
+            });
+            this.catalogHealth = { reachable: true, reason: null };
+            return items;
+        }
+        catch (err) {
+            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 {
+            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: ref,
+            });
+            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) {
+            if (err instanceof ServiceError)
+                throw err;
+            throw this.mapError(err, "failed to compare package versions", {
+                catalog: true,
+            });
+        }
+    }
     async saveVersion(orgId, pack, opts) {
         const message = opts.message?.trim();
         if (!message) {
@@ -683,15 +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);
+        }
+        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);