@x12i/memorix-service 3.7.0 → 3.7.6

package/dist/openapi/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Memorix Service API",
-    "version": "3.7.0",
+    "version": "3.7.5",
     "description": "One versioned product API over accepted Memorix packages. Scope: orgId + agentIds[]. Headers x-memorix-org-id and x-memorix-agent-ids (comma-separated). MX-CALLER-01: every /api request requires x-memorix-caller (calling app id). Intelligence never auto-installs. Relationships /links is forbidden. IntegrationsRegistry (Stage −1) and RestrictedStore (FG-A3 dual-mode blob)."
   },
   "servers": [
@@ -1214,6 +1214,103 @@
         }
       }
     },
+    "/api/metadata/ensure": {
+      "post": {
+        "operationId": "metadataEnsure",
+        "summary": "Startup handshake: install declared pack only when missing or changed",
+        "description": "Client process start — declare OT/CT via a MetadataPack before the first content write. Same checksum → ready+noop. Missing/changed → install then ready. Do not invent types from POST /api/data/content.",
+        "tags": [
+          "Metadata"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "confirm",
+                  "pack"
+                ],
+                "properties": {
+                  "confirm": {
+                    "type": "boolean",
+                    "enum": [
+                      true
+                    ]
+                  },
+                  "pack": {
+                    "$ref": "#/components/schemas/MetadataPack"
+                  },
+                  "versionMessage": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Ensure result",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "ready",
+                    "installed",
+                    "noop"
+                  ],
+                  "properties": {
+                    "ready": {
+                      "type": "boolean"
+                    },
+                    "installed": {
+                      "type": "boolean"
+                    },
+                    "noop": {
+                      "type": "boolean"
+                    },
+                    "agentId": {
+                      "type": "string"
+                    },
+                    "checksum": {
+                      "type": "string"
+                    },
+                    "note": {
+                      "type": "string"
+                    },
+                    "result": {}
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request / confirmation required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/metadata/proposals/{id}/stage": {
       "post": {
         "operationId": "metadataStageProposal",
@@ -2160,7 +2257,15 @@
             "schema": {
               "type": "string"
             },
-            "description": "When set, get one record"
+            "description": "HTTP alias of recordId for exact get. Rejected if it conflicts with recordId."
+          },
+          {
+            "name": "recordId",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Preferred subject identity for exact get. Same as id."
           },
           {
             "name": "expandRelationships",
@@ -2365,6 +2470,16 @@
                     "written": {
                       "type": "boolean"
                     },
+                    "outcome": {
+                      "type": "string",
+                      "enum": [
+                        "created",
+                        "updated",
+                        "deduplicated",
+                        "conflict"
+                      ],
+                      "description": "Write outcome. HTTP does not always return written:true."
+                    },
                     "result": {
                       "type": "object",
                       "additionalProperties": true
@@ -2497,7 +2612,8 @@
                     "identifiers": {
                       "primary": {
                         "kind": "email",
-                        "value": "a@x.io"
+                        "value": "a@x.io",
+                        "issuer": "hr-src"
                       }
                     }
                   },
@@ -2514,6 +2630,357 @@
         }
       }
     },
+    "/api/data/publications": {
+      "post": {
+        "operationId": "dataCreatePublication",
+        "summary": "Create an immutable publication draft (operational, not Magit)",
+        "tags": [
+          "Data"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PublicationDraftRequest"
+              },
+              "example": {
+                "publicationId": "pub-1",
+                "members": [
+                  {
+                    "recordId": "W-1",
+                    "objectType": "widgets",
+                    "contentType": "raw",
+                    "revision": 1
+                  }
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Draft publication",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "scope": {
+                      "$ref": "#/components/schemas/MemorixScope"
+                    },
+                    "publication": {
+                      "$ref": "#/components/schemas/PublicationRecord"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Publication already exists",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                },
+                "example": {
+                  "error": {
+                    "code": "PUBLICATION_EXISTS",
+                    "message": "publication pub-1 already exists",
+                    "correlationId": "c1"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "operationId": "dataListPublications",
+        "summary": "List publications or return last-good committed publication",
+        "tags": [
+          "Data"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "status",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "draft",
+                "committed",
+                "superseded"
+              ]
+            }
+          },
+          {
+            "name": "lastGood",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "true"
+              ]
+            },
+            "description": "When true, return the last committed publication instead of a list."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Publications or last-good",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/data/publications/{publicationId}": {
+      "get": {
+        "operationId": "dataGetPublication",
+        "summary": "Get publication membership and completion status",
+        "tags": [
+          "Data"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "publicationId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Publication plus complete flag (true only when committed)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "scope": {
+                      "$ref": "#/components/schemas/MemorixScope"
+                    },
+                    "publication": {
+                      "$ref": "#/components/schemas/PublicationRecord"
+                    },
+                    "complete": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                },
+                "example": {
+                  "error": {
+                    "code": "PUBLICATION_NOT_FOUND",
+                    "message": "publication pub-1 not found",
+                    "correlationId": "c1"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/data/publications/{publicationId}/commit": {
+      "post": {
+        "operationId": "dataCommitPublication",
+        "summary": "Verify every member at the exact revision, then mark committed",
+        "description": "Missing or mismatched members fail the commit. Prior committed publication remains last-good. Matching generation labels in payloads is not a consistency proof.",
+        "tags": [
+          "Data"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "publicationId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Committed publication",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "scope": {
+                      "$ref": "#/components/schemas/MemorixScope"
+                    },
+                    "publication": {
+                      "$ref": "#/components/schemas/PublicationRecord"
+                    },
+                    "complete": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Member unavailable, not a draft, or mixed revision",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                },
+                "examples": {
+                  "memberUnavailable": {
+                    "value": {
+                      "error": {
+                        "code": "PUBLICATION_MEMBER_UNAVAILABLE",
+                        "message": "publication member is missing or revision mismatch",
+                        "correlationId": "c1"
+                      }
+                    }
+                  },
+                  "notDraft": {
+                    "value": {
+                      "error": {
+                        "code": "PUBLICATION_NOT_DRAFT",
+                        "message": "only draft publications can be committed",
+                        "correlationId": "c1"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/data/publications/{publicationId}/instances": {
+      "get": {
+        "operationId": "dataGetPublicationInstances",
+        "summary": "Retrieve pinned instances for a committed publication",
+        "description": "Fails closed if any member cannot be retrieved at the pinned revision. Live relationship expansion is the current graph; pinned evidence is only the manifest members.",
+        "tags": [
+          "Data"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "publicationId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Pinned instances",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Not committed or member unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                },
+                "example": {
+                  "error": {
+                    "code": "PUBLICATION_NOT_COMMITTED",
+                    "message": "only committed publications can be read as pinned instances",
+                    "correlationId": "c1"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/data/abstract": {
       "get": {
         "operationId": "dataGetAbstract",
@@ -2544,7 +3011,16 @@
             "in": "query",
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "HTTP alias of recordId. Rejected if it conflicts with recordId."
+          },
+          {
+            "name": "recordId",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Preferred subject identity for exact abstract get. Same as id."
           },
           {
             "name": "cursor",
@@ -4474,6 +4950,15 @@
           {
             "name": "id",
             "in": "query",
+            "description": "Deprecated alias of recordId",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "recordId",
+            "in": "query",
+            "description": "Org-wide subject identity (preferred)",
             "schema": {
               "type": "string"
             }
@@ -13067,6 +13552,100 @@
           }
         }
       },
+      "PublicationMember": {
+        "type": "object",
+        "required": [
+          "recordId",
+          "objectType",
+          "contentType",
+          "revision"
+        ],
+        "properties": {
+          "recordId": {
+            "type": "string"
+          },
+          "objectType": {
+            "type": "string"
+          },
+          "contentType": {
+            "type": "string"
+          },
+          "discriminator": {
+            "type": "string"
+          },
+          "revision": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "storageKey": {
+            "type": "string",
+            "description": "Internal Mongo storage key. Not subject identity."
+          }
+        }
+      },
+      "PublicationRecord": {
+        "type": "object",
+        "required": [
+          "publicationId",
+          "status",
+          "createdAt",
+          "members"
+        ],
+        "properties": {
+          "publicationId": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "draft",
+              "committed",
+              "superseded"
+            ]
+          },
+          "commitMarker": {
+            "type": "string"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "committedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "members": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PublicationMember"
+            }
+          },
+          "supersedes": {
+            "type": "string"
+          }
+        }
+      },
+      "PublicationDraftRequest": {
+        "type": "object",
+        "required": [
+          "members"
+        ],
+        "properties": {
+          "publicationId": {
+            "type": "string"
+          },
+          "members": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "$ref": "#/components/schemas/PublicationMember"
+            }
+          },
+          "supersedes": {
+            "type": "string"
+          }
+        }
+      },
       "ContentAddress": {
         "type": "object",
         "required": [
@@ -14042,6 +14621,7 @@
       },
       "ErrorEnvelope": {
         "type": "object",
+        "description": "Machine-readable error. Subject-model codes include WRITE_IDENTITY_ADOPTION, WRITE_IDENTITY_MISMATCH, WRITE_INTERFACE_BINDING, WRITE_DIRECTORY_INCONSISTENT, WRITE_STALE_REVISION, PUBLICATION_*, DIRECTORY_CONFLICT_*.",
         "required": [
           "error"
         ],
@@ -14069,6 +14649,13 @@
               }
             }
           }
+        },
+        "example": {
+          "error": {
+            "code": "WRITE_IDENTITY_ADOPTION",
+            "message": "recordId must not equal a source identifier value; use adoptedRecordId {issuer}/{kind}/{value}",
+            "correlationId": "c1"
+          }
         }
       },
       "ValidationDiagnostic": {

package/dist/operational-db.d.ts

@@ -0,0 +1,6 @@
+export declare function operationalDbName(orgId: string): string;
+/** True when a Mongo database name is this org's operational universe (V1 or V2). */
+export declare function isOperationalDbName(name: string): boolean;
+/** Strip operational suffix (V1 or V2) to recover orgId. */
+export declare function orgIdFromOperationalDbName(name: string): string | null;
+//# sourceMappingURL=operational-db.d.ts.map

package/dist/operational-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operational-db.d.ts","sourceRoot":"","sources":["../src/operational-db.ts"],"names":[],"mappings":"AAKA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIzD;AAED,4DAA4D;AAC5D,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQtE"}

package/dist/operational-db.js

@@ -0,0 +1,22 @@
+/**
+ * Org operational DB name — delegates to memorix-data (V1/V2 via MEMORIX_LAND_V2).
+ */
+import { databaseNameFor } from "@x12i/memorix-data";
+export function operationalDbName(orgId) {
+    return databaseNameFor(orgId, "operational");
+}
+/** True when a Mongo database name is this org's operational universe (V1 or V2). */
+export function isOperationalDbName(name) {
+    return (name.endsWith("_operational") || name.endsWith("-memorix-operational"));
+}
+/** Strip operational suffix (V1 or V2) to recover orgId. */
+export function orgIdFromOperationalDbName(name) {
+    if (name.endsWith("-memorix-operational")) {
+        return name.slice(0, -"-memorix-operational".length) || null;
+    }
+    if (name.endsWith("_operational")) {
+        return name.slice(0, -"_operational".length) || null;
+    }
+    return null;
+}
+//# sourceMappingURL=operational-db.js.map