linkedparticles-core 1.187.2__tar.gz → 1.190.0__tar.gz

{linkedparticles_core-1.187.2 → linkedparticles_core-1.190.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: linkedparticles-core
-Version: 1.187.2
+Version: 1.190.0
 Summary: Store-free client library for Particles: define, validate, serialize, and extract provenance-tracked belief particles
 Project-URL: Homepage, https://linkedparticles.org
 Project-URL: Documentation, https://docs.linkedparticles.org

{linkedparticles_core-1.187.2 → linkedparticles_core-1.190.0}/artifacts/schemas/context.jsonld

@@ -63,6 +63,8 @@
     "particleType": { "@id": "particles:particleType" },
     "assertionModality": { "@id": "particles:assertionModality" },
     "validUntil": { "@id": "psum:duration", "@type": "xsd:dateTime" },
+    "validFrom": { "@id": "particles:validFrom", "@type": "xsd:dateTime" },
+    "validKind": { "@id": "particles:validKind" },
     "supersedes": { "@id": "particles:supersedes", "@type": "@id" },
     "subjectIds": { "@id": "particles:subject", "@type": "@id", "@container": "@set" },
     "subjects": { "@id": "particles:subjects", "@container": "@list" },

{linkedparticles_core-1.187.2 → linkedparticles_core-1.190.0}/artifacts/schemas/interchange.schema.json

@@ -85,6 +85,8 @@
         },
         "uncertaintyKind": { "type": "string" },
         "validUntil": { "type": "string", "format": "date-time" },
+        "validFrom": { "type": "string", "format": "date-time" },
+        "validKind": { "type": "string", "enum": ["EVENT", "STATE"] },
         "supersedes": { "type": "string" },
         "basis": {
           "type": "object",

{linkedparticles_core-1.187.2 → linkedparticles_core-1.190.0}/artifacts/schemas/particle.schema.json

@@ -100,6 +100,16 @@
       "format": "date-time",
       "description": "Core: expiry for time-bounded claims (lazy query-time filter, §9.3)"
     },
+    "valid_from": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "Core: when the claim begins to hold in the world, the counterpart of valid_until; read by the window route (§9.3), never by reconciliation"
+    },
+    "valid_kind": {
+      "type": ["string", "null"],
+      "enum": ["EVENT", "STATE", null],
+      "description": "Core: how the world-time pair is read; EVENT is a moment (the point [valid_from, valid_from], never with a valid_until), STATE a span"
+    },
     "supersedes": {
       "type": ["string", "null"],
       "format": "uuid",

{linkedparticles_core-1.187.2 → linkedparticles_core-1.190.0}/artifacts/schemas/shacl/ParticleShape.ttl

@@ -112,6 +112,25 @@ particles:ParticleShape
         sh:message "assertion_modality, when present, must be FALSIFIABLE, EVALUATIVE, EXPERIENTIAL, or CONSTITUTIVE." ;
     ] ;
 
+    # validKind — optional reading of the world-time pair: EVENT is
+    # a moment, STATE a span. An EVENT never carries a validUntil — a
+    # cardinality across two properties the shape cannot express without a
+    # SPARQL constraint, so the Core model validator enforces it.
+    sh:property [
+        sh:path particles:validKind ;
+        sh:maxCount 1 ;
+        sh:datatype xsd:string ;
+        sh:in ( "EVENT" "STATE" ) ;
+        sh:message "valid_kind, when present, must be EVENT or STATE." ;
+    ] ;
+
+    sh:property [
+        sh:path particles:validFrom ;
+        sh:maxCount 1 ;
+        sh:datatype xsd:dateTime ;
+        sh:message "valid_from, when present, must be a single xsd:dateTime." ;
+    ] ;
+
     # canonicalForm — optional marker of which of the prose/structured pair is
     # the assertion; PROSE default. STRUCTURED additionally requires
     # a structuredClaim to be present — a cardinality the shape cannot express

{linkedparticles_core-1.187.2 → linkedparticles_core-1.190.0}/particles/config.py

@@ -409,7 +409,9 @@ class ProviderSelection(BaseModel):
     """
 
     provider: str = "anthropic"
-    model: str = "claude-sonnet-4-6"
+    # The compiled default since 1.189.0, when it moved from claude-sonnet-4-6
+    # behind measurements registered before the runs.
+    model: str = "claude-sonnet-5-5"
 
 
 class OpenAICompatProviderConfig(BaseModel):
@@ -572,6 +574,27 @@ _LIST_PRICES_PER_MTOK: dict[str, tuple[float, float]] = {
 }
 
 
+# Measured estimate factors that ship for the compiled default and the model it
+# replaced, keyed like ``llm.price_per_mtok``. Characters per input
+# token follow the shipped convention: the old tokenizer's 4.0 rule of thumb
+# divided by the measured token ratio against claude-sonnet-4-6 (1.3437 on one
+# run's byte-identical extraction prompts, token-counting endpoint, 2026-10-13).
+# The output scale is relative to claude-sonnet-5, which the audit's per-call
+# figures were fitted on: claude-sonnet-5-5 wrote 59,760 output tokens on the
+# 2026-10 provider survey's 18 calls against claude-sonnet-5's 111,950 on the same
+# calls (0.534). The extraction figure is the memory benchmark's 6,700 scaled the
+# same way. The claude-sonnet-4-6 entries come from paired run
+# (docs/benchmarks/default-model-adr0317-2026-10-13.md).
+_SHIPPED_CHARS_PER_TOKEN: dict[str, float] = {"claude-sonnet-5-5": 2.98}
+_SHIPPED_OUTPUT_SCALE: dict[str, float] = {
+    "claude-sonnet-5-5": 0.534,
+    "claude-sonnet-4-6": 0.800,
+}
+_SHIPPED_EXTRACTION_OUTPUT_TOKENS: dict[str, int] = {
+    "claude-sonnet-5-5": 3_578,
+    "claude-sonnet-4-6": 5_363,
+}
+
 _T = TypeVar("_T")
 
 
@@ -591,6 +614,23 @@ def lookup_by_model(
     return None, None
 
 
+#: Every completion purpose, in the order the operator-facing lines print them.
+#: A literal here because config cannot import ``particles.llm``;
+#: tests/test_config.py pins it equal to ``particles.llm.LLMPurpose``.
+LLM_PURPOSES: tuple[str, ...] = (
+    "extraction",
+    "semantic_lint",
+    "verification",
+    "subject_resolution",
+    "query_response",
+    "synthesis",
+    "abstraction",
+    "benchmark",
+    "benchmark_answer",
+    "use_judge",
+)
+
+
 def _default_prices() -> dict[str, TokenPrice]:
     return {
         model: TokenPrice(input=inp, output=out)
@@ -603,9 +643,11 @@ class LLMConfig(BaseModel):
 
     ``default`` is the fallback pairing; each purpose may override it. The
     operator can thus route high-volume ``extraction`` to a cheap model while
-    keeping low-volume ``synthesis`` on a hosted one. All compiled defaults are
-    ``claude-sonnet-4-6`` so the out-of-the-box behaviour is unchanged from
-    before the port existed.
+    keeping low-volume ``synthesis`` on a hosted one. Every purpose falls back
+    to the compiled default, ``claude-sonnet-5-5`` since 1.189.0 (
+    ``claude-sonnet-4-6`` before), except ``use_judge``, which carries its own
+    compiled selection. ``particles config validate`` names the
+    default in force and where it came from.
 
     The legacy ``extraction.model`` / ``wiki.model`` keys are migrated into
     this section by ``_migrate_legacy_keys`` (``extraction.model`` →
@@ -712,6 +754,30 @@ class LLMConfig(BaseModel):
         override = getattr(self, purpose, None)
         return override if isinstance(override, ProviderSelection) else self.default
 
+    def selection_source(self, purpose: str) -> str:
+        """Where ``purpose``'s selection comes from, as an operator reads it.
+
+        ``"llm.<purpose>"`` when the configuration sets that purpose,
+        ``"compiled llm.<purpose>"`` for a purpose with its own compiled
+        selection that the configuration leaves alone (``use_judge``),
+        ``"llm.default"`` when the purpose falls back to a configured default,
+        and ``"compiled default"`` when nothing set it. ``"default"`` itself
+        reads as either of the last two.
+        """
+        if purpose != "default" and getattr(self, purpose, None) is not None:
+            if purpose in self.model_fields_set:
+                return f"llm.{purpose}"
+            return f"compiled llm.{purpose}"
+        return "llm.default" if "default" in self.model_fields_set else "compiled default"
+
+    def routed_elsewhere(self) -> dict[str, ProviderSelection]:
+        """The purposes whose selection differs from ``default``, in purpose order."""
+        return {
+            purpose: sel
+            for purpose in LLM_PURPOSES
+            if (sel := self.for_purpose(purpose)) != self.default
+        }
+
     @model_validator(mode="after")
     def _validate_provider_wiring(self) -> LLMConfig:
         """Fail dangling provider names / adapter kinds at config load.
@@ -976,6 +1042,16 @@ class ModalityRegenerationConfig(BaseModel):
     commit_interval: int = Field(default=25, ge=1)
 
 
+class ValidityBackfillConfig(BaseModel):
+    """Defaults for ``particles validity``, the prose-date default for ``valid_from``.
+
+    The pass makes no model call, so it has no rate limit; ``commit_interval``
+    is how often it commits, so an interrupt costs seconds of work.
+    """
+
+    commit_interval: int = Field(default=200, ge=1)
+
+
 class ExtractionPolarityConfig(BaseModel):
     """LLM-semantic claim-polarity classification of candidates (cap. 1).
 
@@ -1777,6 +1853,10 @@ class SubjectsConfig(BaseModel):
     # claude-sonnet-4-6; on an ordinary-prose gold set, 0.898 to 0.918 against
     # 0.735, 45 of 49 names judged at about US$0.20 per 100 names, no correct
     # link lost on either (docs/benchmarks/subject-resolution-judge-2026-10-01.md).
+    # Re-measured 2026-10-13 on claude-sonnet-5-5, the compiled default since
+    # 1.189.0, at 7 hits: 1.000 on the suite and 0.939 on the ordinary-prose
+    # set, no correct link lost, at about US$0.09 and US$0.20 per 100 names
+    # (docs/benchmarks/default-model-adr0317-2026-10-13.md).
     # With no LLM key, an open breaker, or an unusable reply it takes the top
     # hit, so `top_hit` is also what an offline store gets. Set `top_hit` to
     # resolve with no model call at all.
@@ -3061,7 +3141,12 @@ class AuditConfig(BaseModel):
     # measured ~3,600 output tokens per memory-note call on claude-haiku-4-5
     # against ~6,700 on claude-sonnet-5, so routing ``llm.extraction`` to haiku
     # warrants an entry of about 0.55. A model with no entry is scaled by 1.
-    estimate_output_scale_by_model: dict[str, float] = Field(default_factory=dict)
+    # Ships with measured entries for the compiled default and the model it
+    # replaced (``_SHIPPED_OUTPUT_SCALE``); operator entries merge
+    # over them key by key.
+    estimate_output_scale_by_model: dict[str, float] = Field(
+        default_factory=lambda: dict(_SHIPPED_OUTPUT_SCALE)
+    )
     # Each call's output is taken to fall anywhere within this fraction of its
     # expected figure. The expected range runs from every call at (1 - spread)
     # to every call at (1 + spread), and a call whose output would pass
@@ -3108,6 +3193,14 @@ class AuditConfig(BaseModel):
     # Wall time per second reading: the measured runs read 22 flags in ~41 s.
     estimate_seconds_per_verification: float = Field(default=2.0, ge=0.0)
 
+    @field_validator("estimate_output_scale_by_model", mode="before")
+    @classmethod
+    def _merge_over_shipped_scales(cls, value: Any) -> Any:
+        """Operator entries replace the shipped ones key by key; the rest stay."""
+        if isinstance(value, dict):
+            return {**_SHIPPED_OUTPUT_SCALE, **value}
+        return value
+
     @field_validator("estimate_output_scale_by_model")
     @classmethod
     def _non_negative_output_scale(cls, value: dict[str, float]) -> dict[str, float]:
@@ -3524,8 +3617,10 @@ class MemoryBenchmarkConfig(BaseModel):
     # on claude-sonnet-5 but ~3.6k on claude-haiku-4-5 — so an arm routing
     # ``llm.extraction`` elsewhere is mis-estimated ~2x on the write side
     # without an entry here. The rendered estimate says which source it used.
+    # Ships with measured entries for the compiled default and the model it
+    # replaced; operator entries merge over them key by key.
     estimate_output_tokens_per_extraction_call_by_model: dict[str, int] = Field(
-        default_factory=dict
+        default_factory=lambda: dict(_SHIPPED_EXTRACTION_OUTPUT_TOKENS)
     )
     # Characters per input token — the factor the estimate and the pre-flight
     # context-window check divide prompt bytes by. The scalar is the classic
@@ -3536,8 +3631,30 @@ class MemoryBenchmarkConfig(BaseModel):
     # lookup as ``llm.price_per_mtok`` — is what keeps their input projection and
     # their window verdict honest. The write side is keyed on the extraction
     # model, the answer side and the window check on the answer model.
+    # The map ships one entry, for the compiled default, and the
+    # scalar stays the old tokenizer's 4.0, so a model with no entry (a local
+    # or OpenAI-compatible one included) keeps the factor it always had.
+    # Operator entries merge over the shipped one key by key.
     chars_per_token: float = Field(default=4.0, gt=0.0)
-    chars_per_token_by_model: dict[str, float] = Field(default_factory=dict)
+    chars_per_token_by_model: dict[str, float] = Field(
+        default_factory=lambda: dict(_SHIPPED_CHARS_PER_TOKEN)
+    )
+
+    @field_validator("estimate_output_tokens_per_extraction_call_by_model", mode="before")
+    @classmethod
+    def _merge_over_shipped_output_tokens(cls, value: Any) -> Any:
+        """Operator entries replace the shipped ones key by key; the rest stay."""
+        if isinstance(value, dict):
+            return {**_SHIPPED_EXTRACTION_OUTPUT_TOKENS, **value}
+        return value
+
+    @field_validator("chars_per_token_by_model", mode="before")
+    @classmethod
+    def _merge_over_shipped_chars_per_token(cls, value: Any) -> Any:
+        """Operator entries replace the shipped ones key by key; the rest stay."""
+        if isinstance(value, dict):
+            return {**_SHIPPED_CHARS_PER_TOKEN, **value}
+        return value
 
     @field_validator("estimate_output_tokens_per_extraction_call_by_model")
     @classmethod
@@ -3735,6 +3852,31 @@ class LeakageBenchmarkConfig(BaseModel):
     confirm_call_threshold: int = Field(default=50, ge=0)
 
 
+class UpdateGateBenchmarkConfig(BaseModel):
+    """The trip-versus-move case and the update-gate pair sets.
+
+    Run counts and safety margins only. The pipeline under test runs the
+    compiled defaults with every purpose pinned to the chosen model: nothing
+    here re-tunes extraction, reconciliation or consolidation. There is no
+    confirm threshold: every live run asks before its first call, because
+    neither suite has a free live path.
+    """
+
+    # The record's protocol (item 5): the bar is stated only when a
+    # run uses these counts.
+    move_runs: int = Field(default=3, ge=0)
+    trip_alone_runs: int = Field(default=2, ge=0)
+    # Samples per pair in the update-gate replay; the sets were registered at 3.
+    samples: int = Field(default=3, ge=1)
+    # The per-run ceiling --max-usd defaults to, as a multiple of a measured
+    # estimate (a profile or the 2026-10-12 record). An upper-bound estimate is
+    # already a ceiling and is used as is.
+    max_usd_multiplier: float = Field(default=4.0, ge=1.0)
+    # How long one run's child may take before it is stopped and reported
+    # incomplete. A live run took a few minutes on 2026-10-12.
+    run_timeout_seconds: float = Field(default=1800.0, gt=0.0)
+
+
 class BenchmarkConfig(BaseModel):
     """Benchmark-harness run persistence (family).
 
@@ -3903,6 +4045,7 @@ class ParticlesConfig(BaseModel):
     extraction_stance: ExtractionStanceConfig = Field(default_factory=ExtractionStanceConfig)
     extraction_polarity: ExtractionPolarityConfig = Field(default_factory=ExtractionPolarityConfig)
     extraction_validity: ExtractionValidityConfig = Field(default_factory=ExtractionValidityConfig)
+    validity_backfill: ValidityBackfillConfig = Field(default_factory=ValidityBackfillConfig)
     extraction_vision: ExtractionVisionConfig = Field(default_factory=ExtractionVisionConfig)
     structured_claim: StructuredClaimConfig = Field(default_factory=StructuredClaimConfig)
     rdf: RdfConfig = Field(default_factory=RdfConfig)
@@ -3956,6 +4099,9 @@ class ParticlesConfig(BaseModel):
         default_factory=RelevanceFloorBenchmarkConfig
     )
     benchmark_leakage: LeakageBenchmarkConfig = Field(default_factory=LeakageBenchmarkConfig)
+    benchmark_update_gate: UpdateGateBenchmarkConfig = Field(
+        default_factory=UpdateGateBenchmarkConfig
+    )
     benchmark: BenchmarkConfig = Field(default_factory=BenchmarkConfig)
     refetch_floors: dict[str, int] = Field(default_factory=lambda: dict(_DEFAULT_REFETCH_FLOORS))
     local_refresh: LocalRefreshConfig = Field(default_factory=LocalRefreshConfig)
@@ -4130,6 +4276,15 @@ _ENV_OVERRIDES: list[tuple[str, str, str]] = [
 ]
 
 
+def env_override_names() -> frozenset[str]:
+    """Every environment variable that overrides a config field.
+
+    A benchmark that runs the SDK in a child process with a private environment
+    removes these, so no override of the operator's reaches the run.
+    """
+    return frozenset(name for name, _section, _field in _ENV_OVERRIDES)
+
+
 # ---------------------------------------------------------------------------
 # Loader
 # ---------------------------------------------------------------------------

{linkedparticles_core-1.187.2 → linkedparticles_core-1.190.0}/particles/conformance/contract.py

@@ -103,6 +103,16 @@ CONTRACT: list[FieldContract] = [
     ),
     FieldContract("uncertainty_kind", FieldTier.OPTIONAL, "Extension A free-text label"),
     FieldContract("valid_until", FieldTier.OPTIONAL, "Time-bounded claims only"),
+    FieldContract(
+        "valid_from",
+        FieldTier.OPTIONAL,
+        "Claims with a stated world-time start; the window route's input",
+    ),
+    FieldContract(
+        "valid_kind",
+        FieldTier.OPTIONAL,
+        "EVENT (a moment) or STATE (a span); how valid_from and valid_until are read",
+    ),
     FieldContract("supersedes", FieldTier.OPTIONAL, "Set by reindex, not by extractors"),
     FieldContract(
         "tags",

{linkedparticles_core-1.187.2 → linkedparticles_core-1.190.0}/particles/core/schema.py

@@ -112,6 +112,19 @@ class AssertionModality(StrEnum):
     CONSTITUTIVE = "CONSTITUTIVE"  # a rule a document establishes ("a Particle MUST …")
 
 
+class ValidKind(StrEnum):
+    """How a claim's world-time interval is read.
+
+    An ``EVENT`` is a moment: its interval is the point ``[valid_from,
+    valid_from]``, and it never carries a ``valid_until``. A ``STATE`` is a
+    span from ``valid_from`` until it closes (its own ``valid_until``, or for a
+    retired claim the close rule), either end open.
+    """
+
+    EVENT = "EVENT"
+    STATE = "STATE"
+
+
 class ParticleType(StrEnum):
     CLAIM = "CLAIM"
     REVIEW = "REVIEW"  # human review annotation records
@@ -596,6 +609,14 @@ class Particle(BaseModel):
     # (revision chain). Kept in declaration order for serialization
     # stability.
     valid_until: datetime | None = None
+    # Core (§6.2): the world-time axis beside the assertion-time
+    # one. ``valid_from`` is when the claim begins to hold; ``valid_kind``
+    # says whether it is a moment (EVENT) or a span (STATE). Read-time
+    # material for the window route and nothing else: never an input to
+    # reconciliation, ranking, or confidence. How a value was set rides on
+    # ``properties`` (``extraction:valid_from_basis`` and its siblings).
+    valid_from: datetime | None = None
+    valid_kind: ValidKind | None = None
     supersedes: str | None = None
     # Extension A field — stored but not processed by Core logic
     basis: dict[str, Any] | None = None
@@ -667,6 +688,28 @@ class Particle(BaseModel):
             raise ValueError("canonical_form=STRUCTURED requires a structured_claim")
         return self
 
+    @model_validator(mode="after")
+    def _check_validity_interval(self) -> Particle:
+        """The world-time interval is well-formed.
+
+        A start after the end is no interval, and a moment has one end, so an
+        EVENT never carries a ``valid_until``.
+        """
+        if self.valid_from is not None and self.valid_until is not None:
+            start = (
+                self.valid_from if self.valid_from.tzinfo else self.valid_from.replace(tzinfo=UTC)
+            )
+            end = (
+                self.valid_until
+                if self.valid_until.tzinfo
+                else self.valid_until.replace(tzinfo=UTC)
+            )
+            if start > end:
+                raise ValueError("valid_from must not be after valid_until")
+        if self.valid_kind is ValidKind.EVENT and self.valid_until is not None:
+            raise ValueError("an EVENT is a moment and carries no valid_until")
+        return self
+
 
 def is_truth_apt(particle: Particle) -> bool:
     """Whether the engine should apply truth-semantics to this particle.
@@ -831,8 +874,9 @@ class ExtractorCalibration(BaseModel):
             pipeline applies the record only when the current extraction
             provider/model matches; on mismatch the particle falls back to
             ``calibration_source=EXTRACTOR_DIRECT``. ``None`` is a legacy record
-            (fitted before this key existed); it is treated as the historical
-            default ``anthropic:claude-sonnet-4-6``.
+            (fitted before this key existed); it is treated as
+            ``anthropic:claude-sonnet-4-6``, the compiled default before 1.189.0
+            and the model those records were fitted on.
         heldout_suite_id: Benchmark suite(s) whose recorded runs the fit was
             scored on out of sample, ``+``-joined like
             ``benchmark_suite_id``. ``None`` on a record persisted before the
@@ -1178,6 +1222,37 @@ class StructuralGroupBy(StrEnum):
     OBJECT = "object"
 
 
+class TimeWindow(BaseModel):
+    """An interval of world time a query asks about.
+
+    Either end may be open; a window with both ends equal is a point, the
+    ``--on`` form. Timezone-naive values are read as UTC, the store's
+    convention.
+    """
+
+    start: datetime | None = None
+    end: datetime | None = None
+
+    @model_validator(mode="after")
+    def _check_bounds(self) -> TimeWindow:
+        if self.start is None and self.end is None:
+            raise ValueError("a time window needs a start or an end")
+        # Naive values are read as UTC, the store's convention (the as_of
+        # validator does the same), so the two ends and the claims compare.
+        if self.start is not None and self.start.tzinfo is None:
+            self.start = self.start.replace(tzinfo=UTC)
+        if self.end is not None and self.end.tzinfo is None:
+            self.end = self.end.replace(tzinfo=UTC)
+        if self.start is not None and self.end is not None and self.start > self.end:
+            raise ValueError("a time window's start must not be after its end")
+        return self
+
+    @property
+    def is_point(self) -> bool:
+        """True for the ``--on`` form: both ends set and equal."""
+        return self.start is not None and self.end is not None and self.start == self.end
+
+
 class QueryRequest(BaseModel):
     # Bounded so an oversized question can't drive an arbitrarily large prompt
     # into the paid query-response completion (security review F6). 8192 chars is
@@ -1234,6 +1309,14 @@ class QueryRequest(BaseModel):
     # is rejected by the validator below (HTTP 422; CLI/MCP surface the
     # message).
     as_of: datetime | None = None
+    # the world-time window — select the claims that began in,
+    # or were in force during, this interval of world time. Unset (None) is
+    # byte-for-byte today's read. With a question it prefilters the candidate
+    # set before scoring and ``top_k``; without one it selects the
+    # deterministic listing ordered by ``valid_from``. Composes with
+    # ``as_of`` (world time, then believed-at-T visibility). A window read
+    # admits retired claims for the period they held.
+    window: TimeWindow | None = None
     # read through a project observer — only beliefs that are global
     # or were observed in this project are candidates. ``None`` (the default) is
     # the store-wide view, for which the read is byte-identical to before. The
@@ -1310,6 +1393,18 @@ class QueryRequest(BaseModel):
             or self.list_vocabulary
             or self.is_aggregate
             or (self.question is None and self.has_claim_filters)
+            or self.is_window_listing
+        )
+
+    @property
+    def is_window_listing(self) -> bool:
+        """True for the window listing: a window, no question, no claim filter
+        or aggregate. Ordered by ``valid_from``, no LLM call."""
+        return (
+            self.window is not None
+            and self.question is None
+            and not self.has_claim_filters
+            and not self.is_aggregate
         )
 
     @model_validator(mode="after")
@@ -1318,7 +1413,13 @@ class QueryRequest(BaseModel):
             raise ValueError(
                 "a query needs a question, a structural claim filter "
                 "(predicate / object_*), an aggregate (count / group_by), "
-                "list_predicates, or list_vocabulary"
+                "a time window, list_predicates, or list_vocabulary "
+                ""
+            )
+        if self.window is not None and (self.list_predicates or self.list_vocabulary):
+            raise ValueError(
+                "a time window selects claims; it does not combine with the "
+                "predicate or vocabulary listings"
             )
         if self.is_aggregate and self.question is not None:
             raise ValueError(
@@ -1537,6 +1638,63 @@ class AsOfNote(BaseModel):
     successor: AsOfSuccessor | None = None
 
 
+class WindowReading(StrEnum):
+    """Why a claim is in a world-time window.
+
+    ``BEGAN``: its ``valid_from`` lies in the window, whatever its kind; what
+    "what happened in the week" asks. ``IN_FORCE``: a STATE that started
+    before the window and had not closed. ``HELD_AT``: a STATE whose start is
+    unknown but which is known to hold at its anchor (basis ``as-of``), read as
+    in force from there. ``WITHIN``: a claim anchored to a coarse unit (an
+    EVENT somewhere in a month or a year, or a STATE spanning one) whose unit
+    intersects the window.
+    """
+
+    BEGAN = "BEGAN"
+    IN_FORCE = "IN_FORCE"
+    HELD_AT = "HELD_AT"
+    WITHIN = "WITHIN"
+
+
+class WindowHit(BaseModel):
+    """How one hit sits in the requested world-time window (§4).
+
+    A **response model, not particle substrate**: computed at read time,
+    never stored. ``closed_at`` and ``close_basis`` say when a STATE's
+    interval ended and which rule said so (its own ``valid_until``, its
+    successor's ``valid_from``, or its retirement instant); both None for an
+    open interval and for an EVENT. ``retired`` carries the note for
+    a retired claim admitted for the period it held. ``restates`` names the
+    retired original this hit stood in for.
+    """
+
+    reading: WindowReading
+    valid_from: datetime
+    # None for an unkinded claim, admitted under the ``BEGAN`` reading only.
+    valid_kind: ValidKind | None = None
+    closed_at: datetime | None = None
+    close_basis: Literal["valid_until", "successor", "retired_at"] | None = None
+    retired: AsOfNote | None = None
+    restates: str | None = None
+
+
+class WindowCoverage(BaseModel):
+    """What a window read could and could not judge.
+
+    Disclosure only. ``undated`` are candidates with no ``valid_from``;
+    ``unkinded`` carry a date but no kind and so match the ``BEGAN`` reading
+    only; ``retired_admitted`` is how many retired claims the window let in;
+    ``restated`` how many of those yielded to a successor in the set.
+    """
+
+    candidates: int
+    admitted: int
+    undated: int
+    unkinded: int
+    retired_admitted: int
+    restated: int
+
+
 class RelevanceNote(BaseModel):
     """The question-level relevance disclosure for a semantic query.
 
@@ -1873,6 +2031,16 @@ class QueryResponse(BaseModel):
     # reconstructible (rung 4). Born-retired rows are never counted. Always 0
     # on a normal query.
     as_of_excluded_undatable: int = 0
+    # echo of the request's world-time window; None on a read with
+    # no window.
+    window: TimeWindow | None = None
+    # per-result window readings, query-time only. Parallel to
+    # ``particles`` (``window_hits[i]`` annotates ``particles[i]``). Empty
+    # unless the request set ``window``.
+    window_hits: list[WindowHit | None] = Field(default_factory=list)
+    # what the window could and could not judge. None on a read
+    # with no window. Disclosure only.
+    window_coverage: WindowCoverage | None = None
     # set when the request named an ``observer_project``; None on a
     # store-wide read. Disclosure only.
     observer_scope: ObserverScopeNote | None = None