Editing Corpus/Temporal (section)

= Temporal Model =

== Overview ==

Legal documents exist in time. Articles are versioned (valid_from/valid_until). Decisions are point-in-time events. The schema handles both with the same promoted columns.

== date and date_end semantics by kind ==

{| class="wikitable"
! kind !! date = !! date_end =
|-
| legislation (statute, versioned article) || valid_from (entry into force) || valid_until (repeal, amendment)
|-
| legislation (decree, regulation) || publication_date or entry_into_force || expiration (if any)
|-
| legislation (collective agreement) || filing_date or effective_date || expiration_date
|-
| legislation (guidance, circular) || publication_date || NULL (until superseded)
|-
| legislation (bill, debate) || publication_date || NULL
|-
| decision || decision_date || NULL
|-
| record (company) || creation_date || closure_date
|-
| record (person) || NULL || NULL
|-
| notice || publication_date || NULL
|-
| section || NULL || NULL
|-
| chunk || (inherited from parent) || NULL
|}

== Article versioning ==

Multiple versions of the same article = multiple documents with the same <code>tags.cid</code> (permanent article identity) and different date/date_end ranges.

<syntaxhighlight lang="sql">
-- Get the version of article 1147 CC in force on 2015-06-15
SELECT * FROM corpus.documents
WHERE tags->>'cid' = 'LEGISCTA000006136353'
  AND date <= '2015-06-15'
  AND (date_end IS NULL OR date_end > '2015-06-15')
ORDER BY date DESC LIMIT 1;
</syntaxhighlight>

<code>tags.cid</code> is the permanent identity (CID from LEGI XML, or equivalent). It survives renumbering. Article 1382 and article 1240 have different <code>id</code> values but the relationship is captured in <code>corpus.edges kind=replaces</code>.

== at_date in TagQuery ==

The reference resolver supports temporal queries via at_date:

<syntaxhighlight lang="python">
TagQuery(
    language="fr",
    kind="legislation",
    tag_filters=TagFilterSet.from_tags({"article_number": "1147", "code": "Code civil"}),
    at_date=date(2015, 6, 15),
)
</syntaxhighlight>

Translated to SQL:
<syntaxhighlight lang="sql">
WHERE language = 'fr'
  AND kind = 'legislation'
  AND tags @> '{"article_number": "1147", "code": "Code civil"}'
  AND date <= '2015-06-15'
  AND (date_end IS NULL OR date_end > '2015-06-15')
ORDER BY date DESC LIMIT 1
</syntaxhighlight>

== Non-Gregorian calendars ==

The <code>date</code> column always stores ISO/Gregorian dates. The original calendar representation is preserved in tags:

{| class="wikitable"
! Calendar !! Tag !! Example !! Used by
|-
| Islamic (Hijri) || tags.date_hijri || "1445-08-15" || SA, AE, other ME
|-
| Japanese imperial era || tags.date_era_jp || "R06" (Reiwa 6 = 2024) || JP
|-
| Taiwan ROC (Minguo) || tags.date_roc_tw || "112" (= 2023) || TW
|}

Conversion is done at ingestion time. The trigger and all queries use the ISO date column.

== Enforcement status ==

For versioned text documents, <code>tags.enforcement_status</code> tracks the legal force:

{| class="wikitable"
! Status !! Meaning
|-
| in_force || Currently applicable
|-
| deferred_enforcement || Not yet in force, will be on a future date
|-
| deferred_repeal || Currently in force, repeal scheduled for a future date
|-
| repealed || Explicitly repealed by a subsequent act
|-
| superseded || Historical version — a newer version of the same article exists
|-
| never_in_force || Modified before its effective date, never applied
|-
| expired || Lapsed by its own terms (sunset clause, fixed-duration text)
|-
| annulled || Struck down by a court (e.g. constitutional review) — typically retroactive
|-
| transferred || Content moved to a different article or location (renumbering)
|-
| denounced || Collective agreement repudiated by one of the parties
|-
| disjoined || Version split into multiple separate articles
|-
| conditional || In force only under a specific interpretation (constitutional reservation)
|-
| pending || Emergency decree or provisional measure awaiting ratification
|}

The boolean shortcut <code>tags.in_force</code> (true/false) enables simple filtering. Unlike <code>enforcement_status</code>, which is set once at ingest from the source data, <code>in_force</code> is dynamically recomputed by the <code>refresh_in_force</code> post-ingest job from the article's <code>date</code> and <code>date_end</code> columns. The two tags can therefore diverge over time:

* An article tagged <code>deferred_enforcement</code> becomes <code>in_force=true</code> once its effective <code>date</code> is in the past (the tag is not rewritten — only the boolean).
* An article tagged <code>deferred_repeal</code> becomes <code>in_force=false</code> once its <code>date_end</code> is in the past.
* An article tagged <code>in_force</code> becomes <code>in_force=false</code> if its <code>date</code> is in the future (rare — late-published versions).
* All other "not in force" states (<code>repealed</code>, <code>superseded</code>, <code>expired</code>, <code>annulled</code>, <code>transferred</code>, <code>denounced</code>, <code>never_in_force</code>, <code>disjoined</code>) are always <code>in_force=false</code>.

In short: <code>enforcement_status</code> answers "what is the legal lifecycle state of this version?", while <code>in_force</code> answers "is this version currently legally applicable?". Use <code>in_force</code> for filter queries, <code>enforcement_status</code> for display and warnings.

== Transitional provisions ==

When a reform includes transitional rules (e.g., the 2016 French contract law reform: contracts signed before Oct 1, 2016 governed by old law), these are modeled as:
* A separate document (the transitional provision article)
* With edges to both the old and new versions
* The knowledge graph (future) encodes transitional provisions as QUALIFY nodes that route to the correct version based on temporal context

[[Category:Corpus]]