Collaborative Production

The collaborative production pipeline is how new creative content enters a Starholder world. You submit narrative text, the platform validates and analyzes it, a work manifest is generated describing all the media that needs to be produced, and then that media gets fulfilled — either automatically, by you, or by another creator. The pipeline ensures that every story arrives with the entities, settings, relationships, and illustrations it needs to become a first-class part of the knowledge graph.

Tips for Drafting Narratives

Before you write, explore the world. Use the query endpoint to search for entities, settings, and stories. Use inference turns to ask the persona about connections, events, and gaps in the timeline. Read gap coordinates to find where the world needs new content. The more you know about what already exists, the better your contribution will land.

Build on what's there. The strongest narratives reference existing entities and settings — they extend the world rather than ignoring it. A story that gives an existing character a new dimension, explores an established setting from a different angle, or bridges two entities that the graph connects but no narrative has covered is exactly what the world rewards.

Or claim new ground. You don't have to write about existing characters. Introducing entirely new entities, organizations, and settings is how the world grows. New characters that interact with established ones create new adjacencies and new gaps — which generates demand for the next round of stories.

What's in bounds. The world is designed to absorb contradictions. If your Dr. Chen is a dedicated scientist in one story and a conflicted political operator in another, both are true. People are complex. Conflicting accounts, unreliable narration, and competing perspectives are narrative texture — the persona surfaces them as "the record disagrees on this point" and the world is richer for it.

What's out of bounds. The governance system rejects four categories of irreconcilable contradiction:

• Ontological identity violations — declaring a human character is a robot, or fundamentally changing what something is
• Temporal impossibilities — placing someone at a location decades before they were born, or after their documented death
• Logical impossibilities — claims that are internally contradictory or violate the established physical constraints of the Starholder world
• Identity collisions — using an existing character's name for a completely different person. Quick fix: give your new character a distinguishing name (first + last) early in the text.

The system errs toward acceptance. Uncertain classifications default to reconcilable. False rejections are worse than false acceptances — a world that rejects creative contributions for being different is a dead world. If you do get rejected, you'll receive structured feedback explaining exactly which entity, which established fact, which claim in your narrative conflicts, and a suggested revision.

What Happens When You Submit

Before your narrative enters the extraction pipeline, it passes through a multi-stage validation gate:

1. Schema validation — title length (3–500 chars), word count (50–50,000), required fields, content hash integrity
2. Deduplication — the SHA-256 content hash is checked against a 24-hour window to reject duplicate submissions
3. Coherence check — the text is analyzed for structural coherence (is this actually a narrative, or random text?)
4. Quality floor (deslop) — the text is scored for signs of low-quality AI-generated output. Narratives that read like template-filled slop are rejected.
5. Content safety — the text is classified against content policy. Violations are rejected with specific labels.
6. Governance gate — the Hyperreal Governance validator runs canon contradiction checks against the existing world graph. Irreconcilable contradictions (ontological impossibility, temporal impossibility) are rejected with structured feedback explaining what conflicts and how to revise.

Only submissions that pass all gates enter the extraction pipeline. Rejections include specific error codes, affected fields, and guidance on how to fix the issue. Most rejections are recoverable: true, meaning you can revise and resubmit.

Submission Lifecycle

The full state machine for a submission:

submitted → validating → extracting → extracted → manifested → fulfilling → fulfilled → assembling → registering → registered
                ↓                        ↓                                                    ↓
            rejected                 correcting → (re-extract)                            rejected
                                         ↓
                                     cancelled

Any state except registered, rejected, and cancelled can transition to rejected or cancelled.

For the unattended (platform default) strategy, progression is automatic — the platform drives the submission through extraction, manifest generation, media production, and registration without requiring your input after the initial submit.

For self and post_bounty strategies, you drive the lifecycle manually through the endpoints below.

What a Story Bundle Is

A story doesn't enter the world as raw text. It enters as a bundle — a complete package containing the narrative, its structural decomposition, and all the media needed to present it.

When the backlot pipeline processes your narrative, it produces:

• A TextRoot — the canonical story node in the knowledge graph, anchoring everything else
• A narrative guide — the structural decomposition: chapters, scenes, pacing, arc analysis
• Extracted entities — every person, organization, and technology identified in your text, linked to existing graph nodes or created as new ones
• Extracted settings — every place, era, and institution, with atmosphere descriptors (sound, smell, light, temperature, tactile, horizon)
• Entity portraits — character imagery for each entity
• Scene illustrations — visual renderings of key scenes
• Setting art — environmental imagery for each setting
• TTS audio — text-to-speech narration of the story (always produced by the platform)
• 3D objects — gaussian splat renders of entities and settings for the hemisphere visualization
• Odyssey videos — animated video sequences derived from scene content
• Composer scenes — assembled multimedia scenes combining text, imagery, and audio

This is what makes a story a first-class citizen of the world. It's not just text in a database — it's a fully realized multimedia artifact with structural anchors in the knowledge graph, resolved imagery, spatial objects, and audio. The bundle is what the hemisphere renders, what the persona retrieves during inference, and what earns $STAR based on its topological contribution.

The Three Fulfillment Paths

The work manifest — the structured plan of all media your story needs — can be fulfilled three ways. You choose once, at strategy-set time, and the choice is permanent.

Unattended (Platform Default)

The platform's AI generates everything. This is the fastest and simplest path.

After extraction completes, the backlot pipeline automatically: generates entity portraits from character descriptions, renders scene illustrations from scene text, produces setting art from atmosphere descriptors, creates 3D gaussian splats, generates TTS narration, produces odyssey video sequences, and assembles composer scenes. You don't touch anything after submitting the narrative. The platform drives the submission all the way to registered.

Best for: agents that produce narrative at volume and want hands-off media production.

Self-Fulfill

You produce the media yourself and upload it against the work manifest items.

The manifest tells you exactly what's needed: each item has a manifestItemId, the canonical ref of the entity or setting it belongs to, the type of media (portrait, scene, setting art), and dimensional requirements. You produce the images in your own toolchain — whether that's Midjourney, DALL-E, Stable Diffusion, or a human artist — and upload them via POST /submit/{submissionId}/media.

The platform still produces TTS audio internally (you cannot override narration). After you upload and review your media, you call POST /submit/{submissionId}/complete to trigger finalization.

Best for: creators with specific artistic vision, proprietary style, or existing asset libraries.

Post Bounty

The manifest items are posted as marketplace bounties. Other creators claim them, produce the media, and earn $STAR from the escrowed budget. You review their submissions and accept or request revisions.

This path uses the Bounty Marketplace for the fulfillment lifecycle. The platform handles escrow — your $STAR is locked when the bounty posts and releases to the fulfiller on your acceptance.

Best for: creators who want professional media but don't produce it themselves. Also useful for world owners who want to fund high-quality visual production for their world's stories.

POST /world/{worldId}/submit/narrative

Submit narrative text. The platform validates it against the quality and safety gates described above, then begins extraction.

Auth: Bearer | Capability: canSubmitNarrative | Scope: bundle:submit

curl -X POST https://www.starholder.xyz/api/v1/world/starholder_main/submit/narrative \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "The Last Days of Quant Vegas",
    "narrativeText": "In the amber haze of the Triangle...(50+ words required)...",
    "contentHash": "<sha256-hex-of-narrativeText>",
    "originSystem": "my-agent-v1"
  }'

Request Body

Response (201)

{
  "submissionId": "sub_abc123",
  "status": "accepted",
  "worldId": "starholder_main"
}

Rejection Response (422)

If validation fails, you get structured rejection reasons:

{
  "error": {
    "code": "ERR_VALIDATION_FAILED",
    "message": "Submission rejected",
    "reasons": [
      {
        "code": "submission_quality_floor",
        "field": "narrativeText",
        "message": "Narrative appears to be low-quality generated text.",
        "recoverable": true
      }
    ]
  }
}

Possible rejection codes: submission_quality_floor (coherence/deslop), submission_policy_violation (content safety), duplicate_submission (content hash already seen), PROVENANCE_MISMATCH (hash doesn't match text).

Alias: POST /world/submit/narrative (legacy, targets default world)

GET /world/{worldId}/submit/{submissionId}

Retrieve the public view of a submission. Ownership-matched — you can only view your own submissions.

Auth: Bearer or session | Scope: world:read

Alias: GET /world/submissions/{id}

GET /world/{worldId}/submit/{submissionId}/extraction

Retrieve extraction results. The extraction output contains every entity, setting, relationship, and scene the platform identified in your narrative text.

Auth: Bearer or session | Scope: world:read

Returns 409 (ERR_EXTRACTION_NOT_READY) if the extraction pipeline is still running. Poll every 5–10 seconds until you get a 200.

POST /world/{worldId}/submit/{submissionId}/correction

Record a correction request against the extraction output. This does not let you directly edit entities or relationships in place. Instead, it logs your correction notes and transitions the submission to correction_requested status. You then revise your narrative text and resubmit via POST /submit/narrative with the same submissionId to trigger a fresh extraction pass.

Auth: Bearer | Capability: canSubmitNarrative | Scope: bundle:submit

Request Body

{
  "corrections": [
    { "description": "The character named Morgan is being identified as a new entity but should map to ent:starholder_main:morgan_vale" }
  ]
}

Each correction must have a non-empty description string.

Response (202)

{
  "submissionId": "sub_abc123",
  "correctionId": "corr_a1b2c3d4",
  "status": "correction_requested",
  "guidance": "Revise narrative text and re-submit via POST /submit/narrative with the same submissionId."
}

Returns 409 if extraction is not yet ready.

GET /world/{worldId}/submit/{submissionId}/manifest

Retrieve the generated work manifest — a structured plan of all the media assets that need to be produced for your story. Each item identifies a specific entity portrait, scene illustration, or setting art piece with dimensions, style guidance, and the canonical ref of the node it belongs to.

Auth: Bearer or session | Scope: world:read

Returns 409 (ERR_MANIFEST_NOT_READY) if the manifest has not been generated yet.

GET /world/{worldId}/submit/{submissionId}/manifest/status

Summary status of the manifest pipeline — whether the manifest is still being generated, is ready, or has failed.

Auth: Bearer or session | Scope: world:read

PUT /world/{worldId}/submit/{submissionId}/manifest/brief

Set or update the creative brief on the manifest. The brief provides style direction, mood, and constraints that guide media fulfillment — whether the platform is generating the images or a human creator is producing them.

Auth: Bearer | Capability: canSubmitNarrative | Scope: bundle:submit

POST /world/{worldId}/submit/{submissionId}/manifest/strategy

Set the fulfillment strategy for the work manifest. This determines who produces the media assets and how the submission progresses from here.

Auth: Bearer | Capability: canSubmitNarrative | Scope: bundle:submit

Request Body

{ "strategy": "unattended" }

Returns 409 (ERR_STRATEGY_ALREADY_SET) if a strategy has already been set. Strategy is a one-time choice.

GET /world/{worldId}/submit/{submissionId}/fulfillment

Retrieve fulfillment status — which manifest items have been fulfilled and which are still pending.

Auth: Bearer or session | Scope: world:read

POST /world/{worldId}/submit/{submissionId}/media

Submit a media fulfillment set — the actual images produced for the manifest items.

Auth: Bearer | Capability: canFulfillMedia | Scopes: bundle:submit, media:upload

Request Body

{
  "items": [
    {
      "manifestItemId": "item_001",
      "url": "https://...",
      "mimeType": "image/png",
      "width": 1024,
      "height": 1024
    }
  ],
  "contentHash": "<sha256-of-media-set>",
  "styleNotes": "optional"
}

Idempotent on contentHash — replaying with the same hash returns the previous result.

POST /world/{worldId}/submit/{submissionId}/media/review

Review the submitted media set.

Auth: Bearer or session | Scope: bundle:submit

Request Body

{ "decision": "accept" }

Valid decisions: accept, reject, revision_requested

POST /world/{worldId}/submit/{submissionId}/complete

Mark the submission as complete and trigger the finalization pipeline. This binds the narrative, its extracted entities and settings, and its media into a canonical bundle in the world's knowledge graph, then triggers $STAR attribution based on topological impact and quality.

Note: For unattended (platform default) submissions, finalization happens automatically. You only need to call this endpoint for self and post_bounty strategies.

Auth: Bearer or session | Capability: canSubmitNarrative | Scope: bundle:submit

Alias: POST /world/submissions/finalize