SpiralistAI Per-Character Batch Identity Preservation: API Contract and Schema Specification

Full report

On this page

1. Executive Summary and Architectural Imperatives

The computational generation of expansive, highly specific adult fictional personas necessitates a strict, deterministic integration paradigm. Downstream consumers, specifically RogueIntelligence, orchestrate vast populations of simulated entities requiring exact per-character identity preservation. The primary challenge in generative systems lies in mitigating the probabilistic nature of underlying large language models (LLMs). When batch requests process identical or closely related persona seeds under shared systemic controls, the boundary between distinct character items often erodes, leading to a phenomenon known as identity drift or silent substitution. This research report establishes a definitive, implementation-ready API contract that systematically eliminates identity drift. The architecture ensures uncompromising preservation of identity constraints—specifically nomenclature, chronological age, and linguistic pronouns—across four distinct persona families: Regular Person, Psychosis, Espionage, and Espionage Psychosis. Furthermore, these constraints remain immutable across all runtime operational modes, including Assistant, NPC Character, and Game-NPC activation-detail contexts. To accomplish this, the contract standardizes error topologies utilizing RFC 9457 (Problem Details for HTTP APIs)1, formalizes fault-tolerant network operations via standardized idempotency headers3, enforces precise Unicode normalization techniques for string equivalence5, and implements the JSON Canonicalization Scheme (RFC 8785\) for immutable cryptographic fingerprinting7. The resulting specification is additive, securely extending existing ordered mixed-batch request structures without inventing divergent routing, ensuring that no generated persona silently mutates into another entity during network transit or asynchronous internal processing.

2. per-character-batch-api-contract.md

The operational lifecycle of a batch request within this architecture is strictly deterministic at the HTTP transport and payload mapping layers. The core directive is unambiguous mapping: every response item must map unambiguously to exactly one request item, leveraging a stable client-provided identifier.

2.1 Canonical Payload Terminology and Alias Handling

The canonical namespace for the collection of requested personas must be designated as items. In RESTful batch processing architectures, the term items accurately denotes a structured array of discrete resource representations submitted for parallel or sequential processing. Conversely, the term requests implies the tunneling of independent HTTP method envelopes (such as those seen in OData or GraphQL batching endpoints), which misrepresents the unified transactional context of persona generation. To maintain backward compatibility with legacy SpiralistAI integrations, legacy aliases such as requests must be supported through a strict first-non-empty precedence rule9. If a legacy client transmits the requests array while the items array is omitted or null, the system internally maps the payload to the canonical items structure. However, if a downstream consumer supplies both items and requests simultaneously within the same payload, the API must immediately reject the request with a 400 Bad Request status. Attempting to aggregate, merge, or arbitrarily prioritize concurrently populated alias fields introduces fatal non-deterministic behavior, violating the principle of unambiguous client intent11.

2.2 Client Identity Anchors and Batch Constraints

The integrity of the per-character batch relies entirely on the clientItemId. Every object within the input array must declare a unique clientItemId. The API interprets this value as an immutable correlation anchor. If the identifier is missing from any item, or if duplicate identifier values are detected within the same batch payload, the processing engine must halt immediately and reject the entire request with a 422 Unprocessable Entity response12. Partial execution is strictly forbidden when the identifying schema is compromised, as it destroys the downstream application's ability to map asynchronous results back to their origin context. The maximum safe batch size is mathematically bound by the latency tolerances of the generative pipeline and the constraints of the reverse proxies handling the HTTP connection lifecycle. A maximum ceiling of 1,000 items per request ensures that payloads do not trigger 413 Payload Too Large infrastructure limits while allowing sufficient throughput for RogueIntelligence's population requirements12. For highly expansive populations exceeding this ceiling, the client application must divide the entities across paged or chunked requests. Global ordering across these disparate requests is preserved by the sequential, chronological submission of Idempotency-Key headers, which act as temporal sequence markers alongside the client's internal database indices3.

2.3 Deterministic Seeds versus Explicit Identity Precedence

Generative architecture relies heavily on numerical seeds to anchor the latent space trajectory, ensuring that identical seeds produce identical narrative outputs15. However, a fundamental conflict arises when a deterministic seed contradicts explicit identity parameters supplied by the client. The API contract strictly dictates that explicit identity constraints—such as preferredName, age, or pronouns—supersede the latent determinism of the seed. If the seed ri-npc-001 inherently generates the persona of a forty-year-old male named "John", but the explicit request mandates the name "Aaliyah James Smith" with an age of 21, the generative engine must force the explicit constraints into the output. When a generated attribute fundamentally breaks the chronological reality requested by the client (for instance, an explicitly requested 18-year-old character generating a twenty-year military career history), the API must not silently alter the requested age to fix the biographical logic error. Instead, the API must fail the specific item due to a conflicting identity constraint. Preserving the exact requested age is non-negotiable; silent corrections undermine RogueIntelligence's precise demographic distribution mechanics.

2.4 Platform Safety Separation

The systemic injection of platform safety rules—such as content moderation blocks or structural safety overlays—must be rigorously decoupled from the persona's core architectural definition. The API specification explicitly forbids the inclusion of platform safety variables within the final .uai or .uaix file outputs. Integrating safety telemetry into these files permanently contaminates the persona's identity schema, blurring the line between the character's internal psychological directives and external corporate compliance mechanics. Platform safety enforcement functions strictly as an ephemeral transport-layer overlay; if safety parameters require the modification or suppression of an explicitly requested trait, the item generation must fail explicitly rather than quietly altering the persona to bypass the safety filter.

3. batch-request.schema.json

The formal JSON schema defines the precise boundaries of acceptable input. Every field is meticulously categorized to dictate its interaction with the cryptographic fingerprinting engine, its status as sensitive private data, and its eligibility for inclusion in the final exported persona file format.

The separation of metadata and transient infrastructural flags from the runtime fingerprint is a deliberate cryptographic design choice. If a client alters the outputFormats from .uai to .uaix, the underlying character semantics remain identical. Therefore, the fields that do not define the character's internal reality do not influence the runtimeFingerprint, allowing RogueIntelligence to cryptographically verify that the persona generated on Tuesday is mathematically identical to the persona generated on Friday, despite changes in requested output formatting or arbitrary metadata attached by intermediary message brokers15.

4. batch-response.schema.json

The response schema represents a significant departure from binary HTTP status models, leveraging the 207 Multi-Status paradigm originally popularized by WebDAV (RFC 4918\)17. When processing massive batches, an atomic success/failure mechanism generates unacceptable compute waste. If a batch contains 1,000 items and a semantic failure occurs on the final item, responding with a single 400 or 500 status code forces the client to discard 999 successfully generated personas12. The 207 Multi-Status response signals that the request was syntactically valid and processed, but the outcomes of individual sub-operations vary. The payload itself acts as an aggregated envelope of distinct HTTP transaction results18. The response envelope is strictly formatted to ensure full diagnostic visibility, reporting the exact normalization steps taken, the discrepancy between requested and resolved states, and the cryptographic proofs of execution.

Within the items array, every sub-object adheres to a rigid mapping schema:

5. batch-problem-catalog.json

Historically, API error handling has suffered from severe inconsistency, often relying on arbitrary HTTP status codes accompanied by unstructured, unpredictable text bodies. This approach forces client engineers to write fragile parsing logic that collapses when internal server messages change. To eliminate this friction, the batch problem catalog implements the "Problem Details for HTTP APIs" standard, transitioning from RFC 7807 to the refined RFC 94572. The Problem Details object enforces a standardized taxonomy. Every item failure within the 207 Multi-Status array must encapsulate an error object containing a URI type, a stable HTTP status, a localized title, an actionable detail explanation, and an instance correlating to a specific server log UUID1.

The downstream consumer utilizes the Retriable flag to determine automated recovery behavior. A globally unhandled exception mapping to 500 Internal Server Error implies an ephemeral resource constraint within the generative engine, making it safe to enqueue for a subsequent attempt. Conversely, a 422 Unprocessable Entity resulting from an identity substitution error indicates a fundamental impossibility within the prompt logic, rendering automated retries futile and computationally wasteful without human or procedural intervention2.

6. identity-preservation-rules.md

Identity preservation operates on a rigid "exact match or catastrophic fail" paradigm. Generative AI systems inherently attempt to smooth or normalize outputs to match the statistical peaks of their training distributions. For RogueIntelligence, this statistical smoothing acts as a data corruption mechanism. The API must guarantee that no persona silently morphs into another entity. If the downstream consumer requests the creation of preferredName: "Aaliyah James Smith", and the latent processing outputs the statistically more common Aaliyah Smith, the system is forbidden from merging the result. The engine must intercept the anomaly, compare the requestedIdentity node with the pending resolvedIdentity node, and register an err\_identity\_sub failure2. Repeated names across a batch do not instigate data merging. The API treats the clientItemId as the absolute boundary of a persona's existence. A single batch containing fifty items all named "John Smith" with distinct seeds will result in fifty completely disparate and isolated character sheets. Under no circumstances are request IDs, execution timestamps, or HTTP trace identifiers utilized as elements of the persona's identity. Identity is defined purely by the semantic variables supplied by the consumer, ensuring that generating the same persona across two different chronological timestamps yields mathematically identical character architectures, unpolluted by the metadata of the execution itself15.

7. unicode-and-name-preservation.md

The preservation of explicit linguistic identity requires sophisticated management of string equivalence. Digital character encoding systems allow for multiple valid representations of the exact same visual character. Without standardized text normalization, an equality check between a requested name and a generated name will fail silently, leading to false positives in the identity preservation engine and persistent database duplication5. The Unicode Standard dictates multiple Normalization Forms to resolve encoding ambiguity. The API contract mandates the use of Normalization Form C (NFC) for all string parsing, storage, and matching algorithms6. NFC canonicalizes by decomposing characters and then recomposing them into the shortest possible precomposed characters (e.g., combining the base letter "e" and the combining acute accent into a single code point for "é")5. This is the optimal strategy for ensuring that a client's requested string mathematically matches the generated output string. Crucially, the API strictly forbids the application of Compatibility Decomposition forms (NFKC and NFKD) to any identity fields25. Compatibility normalization permanently alters text by collapsing distinct visual variants into a shared standard format. Applying NFKC would destructively alter native script names, collapse typographic ligatures (like folding "fi" into the distinct letters "f" and "i"), and completely override the typographic intent required by specialized Game-NPC text rendering engines5. The "exact" preservation of a name is therefore defined as a byte-exact match of the UTF-8 encoded string immediately following its mandatory NFC normalization15. Furthermore, while whitespace trimming (removing leading and trailing spaces) is acceptable to prevent parsing errors, all such structural adjustments must be transparently reported back to the client within the identityDifferences response array. This guarantees that RogueIntelligence is fully aware of any morphological changes, preventing discrepancies during cross-system database synchronizations.

8. batch-ordering-and-retry.md

Sequence stability and diagnostic retry behaviors are paramount when processing thousands of entities. The API strictly preserves the ordinal position of items. The length and index mapping of the returned items array must exactly match the inbound payload, irrespective of the variable processing speeds of the individual generation threads. The itemIndex property serves as an explicit mathematical verification of this order. When a batch is designated as partially successful via the 207 Multi-Status code12, the downstream consumer evaluates the Retriable status of the failed items. To execute a safe retry, the client extracts the failed items, constructs a new batch payload, and generates a new, distinct Idempotency-Key3. The clientItemId values remain unchanged. Because the original batch and the retry batch possess different Idempotency keys, the server processes the retry as a valid, intentional new request3. The consumer relies entirely on the stable clientItemId to map the newly successful generations back into the original demographic roster, seamlessly healing the population gaps. If the client mandates that a specific batch must execute without failure or not at all, they may invoke atomic mode via a top-level transactional flag. In atomic mode, a single 422 Unprocessable Entity or 500 Internal Server Error encountered on any item triggers a total operational rollback. The batch fails entirely, no partial records are committed, and the consumer receives a uniform error state, preventing fragmented relational datasets.

9. idempotency-and-fingerprinting.md

Network partitions, connection timeouts, and client-side processing delays inevitably cause duplicate request submissions. To prevent the erroneous generation of duplicate personas and the resulting exhaustion of computational resources, the contract requires strict adherence to draft-ietf-httpapi-idempotency-key-header-073. The consumer client generates a universally unique identifier (UUID V4) to serve as the idempotency key3. The API intercepts this key and checks its tenant-scoped cache. If the key exists and the attached payload fingerprint precisely matches the cached fingerprint, the API intercepts the generation logic and immediately returns the stored HTTP response. If the key is identified but the original transaction is still processing, the API safely rejects the duplicate with a 409 Conflict, preventing concurrent race conditions4. If a key is maliciously or accidentally reused with a completely different payload, a 422 Unprocessable Entity is thrown to highlight the integration error3. To prove generation provenance and ensure idempotency keys correctly map to immutable requests, the system implements the JSON Canonicalization Scheme (JCS) as outlined in RFC 87857. Standard JSON serializers are inherently non-deterministic; they routinely alter key ordering, object spacing, and internal number formatting8. JCS enforces a strict lexicographical sorting of keys, removes all insignificant whitespace, and formalizes number representations8. The resulting byte sequence is then hashed using SHA-25615. The client generates a requestFingerprint hash from the JCS-canonicalized input object. The server echoes this and generates a distinct runtimeFingerprint from the finalized persona output7. Crucially, volatile metadata—such as execution duration, internal processing timestamps, and varying HTTP headers—are explicitly excluded from the JCS input15. This architecture provides RogueIntelligence with a deterministic cryptographic proof: supplying exact payload [Figure omitted from source export] will infinitely and perpetually result in the generation of runtime fingerprint [Figure omitted from source export], ensuring deep auditability and reproducible character states without falsely promising that the generative pipeline operates exactly once per request.

10. conformance-test-catalog.json

A rigorous suite of automated conformance tests acts as the continuous verification protocol for the API contract. These tests validate boundary logic, ensure the preservation of complex Unicode interactions, and certify the separation of platform safety mechanisms from persona architecture.

11. backward-compatibility-plan.md

As the API contract formalizes new schemas, legacy downstream applications must transition without abrupt service interruptions. The backward compatibility protocol leverages the HTTP standard for lifecycle management, utilizing the Deprecation header (RFC 9745\) and the Sunset header (RFC 8594\)29. When the API encounters an incoming payload utilizing legacy structures, such as the requests array alias instead of items, the routing layer transparently aggregates and maps the payload to the new standard using the established first-non-empty precedence rule. Concurrently, the API modifies its response headers. The Deprecation header is injected, utilizing a structured field date format to officially mark the operational pathway as deprecated, providing immediate observability to the client's automated metric trackers9. To establish a hard deadline for the migration, the Sunset header is attached, outputting an HTTP-date timestamp indicating the exact moment the legacy alias will become permanently unresponsive20. Standard practice dictates an active sunset window of no less than six months. Furthermore, the API provides an HTTP Link header populated with the rel="sunset" and rel="deprecation" relationship types, supplying a direct URL to the transition documentation9. This ensures that RogueIntelligence's integration teams receive continuous, programmatic advance warnings and the necessary guidance to update their client implementations well before the endpoints throw 410 Gone errors.

12. openapi-recommendations.md

Translating this intricate contract into an OpenAPI 3.1 specification demands precise structural definitions to ensure client-generation tools properly map the complex responses. The specification must explicitly model the 207 Multi-Status response type under the standard HTTP POST endpoint operation, detailing the aggregated array structure. The heterogeneous nature of the item-level error reporting requires the use of OpenAPI discriminator objects. The error property nested within the items array must be mapped to an abstract ProblemDetails schema, utilizing the type URI property as the discriminator to map the 19 distinct RFC 9457 error objects automatically for typed languages like TypeScript or Go2. Furthermore, the Idempotency-Key must be declared as a heavily recommended, structured request header within the OpenAPI parameters array. To support cryptographic expectations, the jsonSchemaDialect property must define a draft structure that mandates Unicode Normalization Form C for string parameters, preventing code generators from overlooking critical string equivalence protocols during SDK synthesis.

13. source-register.csv

The structural integrity of this API contract relies upon adherence to globally recognized Internet Engineering Task Force (IETF) and Unicode Consortium standards. The mapping of architectural features to their underlying source material guarantees interoperability and technical longevity.

Works cited

1. Charge your APIs Volume 19: Understanding Problem Details for HTTP APIs \- A Deep Dive into RFC 7807 and RFC 9457 \- codecentric AG, https://www.codecentric.de/en/knowledge-hub/blog/charge-your-apis-volume-19-understanding-problem-details-for-http-apis-a-deep-dive-into-rfc-7807-and-rfc-9457

2. Problem Details (RFC 9457): Doing API Errors Well \- Swagger, https://swagger.io/blog/problem-details-rfc9457-doing-api-errors-well/

3. draft-ietf-httpapi-idempotency-key-header-07, https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header

4. Announcing idempot-js: Idempotency Middleware for Node.js, Bun, and Deno | roderick.dk, https://roderick.dk/posts/2026-04-06-announcing-idempot-js/

5. Unicode Normalization: NFC, NFD, NFKC | theproductguy.in, https://theproductguy.in/blogs/unicode-normalizer-guide/

6. UAX \#15: Unicode Normalization Forms, https://unicode.org/reports/tr15/

7. The Vaara Receipt: A Recomputable Receipt Format for Decisions About Agent Actions, https://www.ietf.org/archive/id/draft-sirkkavaara-vaara-receipt-05.html

8. Determinism: Why Consistent Encodings Matter \- The CBOR, dCBOR, and Gordian Envelope Book, https://cborbook.com/part\_2/determinism.html

9. How to Create API Deprecation Headers \- OneUptime, https://oneuptime.com/blog/post/2026-01-30-api-deprecation-headers/view

10. Understanding The HTTP Deprecation Header \- Zuplo, https://zuplo.com/learning-center/http-deprecation-header

11. Handling API Errors the Right Way: Understanding ProblemDetails in ASP.NET Core Web API | by Aseem | Medium, https://medium.com/@aseem2372005/handling-api-errors-the-right-way-understanding-problemdetails-in-asp-net-core-web-api-e3f7d404672c

12. How to Handle Partial Success in Bulk API Operations \- OneUptime, https://oneuptime.com/blog/post/2026-02-02-rest-bulk-api-partial-success/view

13. What are applicable scenarios in using HTTP status 207 in REST API? \- Stack Overflow, https://stackoverflow.com/questions/30571489/what-are-applicable-scenarios-in-using-http-status-207-in-rest-api

14. Errors : Guide : ShootProof for Developers, https://developer.shootproof.com/guide/errors/

15. ERC-8257: Agent Tool Registry \- Ethereum Improvement Proposals, https://eips.ethereum.org/EIPS/eip-8257

16. Deterministic AI Governance \- Intelligent Analyst, https://intelligentanalyst.com/protocol/iavp/v1

17. 207 Multi-Status \- HTTP \- MDN Web Docs \- Mozilla, https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/207

18. 207 Multi-Status \- HTTP status code explained \- HTTP.DEV, https://http.dev/207

19. What HTTP status code to return if multiple actions finish with different statuses?, https://softwareengineering.stackexchange.com/questions/329596/what-http-status-code-to-return-if-multiple-actions-finish-with-different-status

20. Sunset \- Expert Guide to HTTP headers, https://http.dev/sunset

21. Error handling Error details · NationalBankBelgium/REST-API-Design-Guide Wiki \- GitHub, https://github.com/NationalBankBelgium/REST-API-Design-Guide/wiki/Error-handling-Error-details

22. Problem Details for HTTP APIs \- IETF, https://www.ietf.org/archive/id/draft-ietf-httpapi-rfc7807bis-07.html

23. What are applicable scenarios in using HTTP status 207 in REST API? \- Stack Overflow, http://stackoverflow.com/questions/30571489/what-are-applicable-scenarios-in-using-http-status-207-in-rest-api/30572347

24. Unicode equivalence \- Wikipedia, https://en.wikipedia.org/wiki/Unicode\_equivalence

25. UAX \#15: Unicode Normalization Forms, https://www.unicode.org/L2/L2011/11292-tr15-34.pdf

26. Unicode Normalization Forms \- Perldoc Browser \- Perl.org, https://perldoc.perl.org/Unicode::Normalize

27. The Idempotency-Key HTTP Header Field \- IETF, https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-01.html

28. draft-idempotency-header-01 \- IETF Datatracker, https://datatracker.ietf.org/doc/html/draft-idempotency-header-01

29. RFC 8594 \- The Sunset HTTP Header Field \- IETF Datatracker, https://datatracker.ietf.org/doc/html/rfc8594

30. proposal:OpenAPI 3.3 Proposal: API-Level Deprecation & Sunset Support \#5193 \- GitHub, https://github.com/OAI/OpenAPI-Specification/discussions/5193

31. We built a Spring Boot starter that automates API deprecation with RFC-compliant headers, 410 Gone enforcement, and metrics : r/SpringBoot \- Reddit, https://www.reddit.com/r/SpringBoot/comments/1te5w57/we\_built\_a\_spring\_boot\_starter\_that\_automates\_api/

32. System Interface Description REPO | Europe's Rail, https://rail-research.europa.eu/wp-content/uploads/2026/06/SPT2-CONEMP\_TCCS\_Service\_Function\_Configuration\_\_SFC\_\_L5\_System\_Interface\_Description\_REPO.pdf

33. Unicode Normalization Forms, https://docs.mojolicious.org/Unicode/Normalize

34. The Idempotency-Key HTTP Header Field \- IETF Datatracker, https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/

35. Idempotency \- What is an Idempotent REST API? \- REST API Tutorial, https://restfulapi.net/idempotent-rest-apis/