X-01 · Create XBRL filing

SOP: SOP_XBRL_Filing.md §6 / Step 1.0 (S0 → DRAFT)Actors: XBRL Preparer (xbrl-preparer@spade.local) — holds MANAGE_XBRL_FILING. Pre-state: Client exists with XBRL_FILING in enabledProducts and a populated xbrlConfig. Post-state: XbrlFiling row in DRAFT. taxonomyVersion pinned and immutable. URL settles to /dashboard/xbrl/<filingId>.

0. Prerequisites

• Environment up per _shared/00-environment-setup.md.
• Anchor client: STELLAR (clientCode: STELLAR).
  • Existing seed: STELLAR has two filings — one in MAPPING_IN_PROGRESS (FY2024) and one in VALIDATION_FAILED (FY2023). To exercise the create flow, pick a period that does not yet exist (e.g. FY2025).
• Logged in as xbrl-preparer@spade.local.

1. Steps

1.1 Create the filing (Option A — Web UI)

1. Sidebar → XBRL Filings → New filing.
2. Pick STELLAR from the client dropdown.
3. Fill in:
   • Period start: 2025-01-01
   • Period end: 2025-12-31
   • Entry point: FULL_XBRL (defaults from Client.xbrlConfig.defaultEntryPoint)
   • Entity type: NON_LISTED_COMPANY_FULL (defaults from xbrlConfig.entityType)
   • Accounting standard: SFRS (defaults from xbrlConfig.accountingStandard)
   • Taxonomy version: acra_2026_v1 (defaults from xbrlConfig.taxonomyVersion) — pinned at create, immutable thereafter
   • Optional: link to an existing FsEngagement for the same client + period (Phase 3 cross-product path)
4. Submit.

1.2 Create the filing (Option B — API)

POST /ops/xbrl/filings
Content-Type: application/json
Authorization: Bearer <xbrl-preparer-jwt>

{
  "clientId": "<stellarClientId>",
  "periodStart": "2025-01-01",
  "periodEnd": "2025-12-31",
  "entryPoint": "FULL_XBRL",
  "entityType": "NON_LISTED_COMPANY_FULL",
  "accountingStandard": "SFRS",
  "taxonomyVersion": "acra_2026_v1"
}

The handler:

1. Asserts MANAGE_XBRL_FILING.
2. Asserts the client has XBRL_FILING in enabledProducts.
3. Asserts loadTaxonomy(version) does not throw — the version must exist in packages/xbrl/constitution/. Unknown versions raise XbrlUnknownTaxonomyVersionError (Rule 4).
4. Asserts periodStart < periodEnd.
5. Inserts XbrlFiling with status = DRAFT, versionNo = 1. taxonomyVersion is immutable after this point.
6. Emits AuditEvent xbrl.filing.created.

2. Verification

Database

SELECT id, period_start, period_end, entry_point, entity_type,
       accounting_standard, taxonomy_version, status, version_no
  FROM xbrl_filings
  WHERE client_id = '<stellarClientId>' AND period_end = '2025-12-31';
-- expect status = 'DRAFT', taxonomy_version = 'acra_2026_v1'

Audit log

Event type	Notes
xbrl.filing.created	actor + payload includes pinned taxonomyVersion

Status badge

Filing detail page shows DRAFT. The Upload source document CTA is enabled. Other tabs (Mappings / Validation / Exports) are visible but disabled.

3. Negative & edge cases

• Unknown taxonomy version — handler refuses with 400 Bad Request and reason: "unknown_taxonomy_version". This is the Rule 4 enforcement. Test: loadTaxonomy('made_up_version') raises XbrlUnknownTaxonomyVersionError in code.
• Client without XBRL enabled — 400 Bad Request with "Client does not have XBRL_FILING enabled."
• Caller without MANAGE_XBRL_FILING — 403 Forbidden. XBRL_PREPARER for FS cross-references (read-only) is rejected.
• periodEnd <= periodStart — 400 Bad Request.
• Attempt to update taxonomyVersion after creation — PATCH /ops/xbrl/filings/:id rejects the field; the server keeps the pinned version regardless of what the client sends.

Next

Proceed to X-02 · Upload source document, or to X-02b · Pull from FS engagement (Phase 3 cross-product).