Object Model

docs/object-model.md · 13489 B · source sha256 b6570e434a42

This document describes the conceptual object model urban-observatory is being developed around. It is a working hypothesis, not a schema. It names the interpretive chain and the supporting primitives the method reasons over, and explicitly defers schema-level decisions until prototype work has pressure-tested the model against real public-data conditions.

For the project's core concept, see implementation-intelligence.md. For methodology, see methodology.md. For repo-local architecture context, see architecture.md.

on this page

Interpretive chain

The validated interpretive chain for the method is:

Assumption → ImplementationSignal → ImplementationFinding → InterventionCandidate

This is a working hypothesis to be pressure-tested by prototype work, not final schema doctrine. The supporting primitives below remain useful regardless of which schema shape ultimately consumes the chain.

Assumption

A claim or premise embedded in a public plan, policy, inventory, program, APR, capital plan, infrastructure plan, or related document. The project tests assumptions for current plausibility under changing conditions.

The project's core move is testing whether assumptions embedded in plans still hold under changing real-world conditions. Assumption is the load-bearing interpretive primitive in v0 planning.

An Assumption is not necessarily tied to a single site or project. Manual chain extraction has pressure-tested the per-site framing and surfaced that some assumptions operate at scales other than the site. Assumptions may attach to:

  • a specific site (e.g., an opportunity-site capacity assumption);
  • a specific project (e.g., a project's delivery expectation);
  • a typology or corridor (e.g., expected redevelopment across a class of sites);
  • a program or policy (e.g., expected outcomes from a rezoning ordinance);
  • an aggregate strategy (e.g., total ADU / small-infill production assumed across many parcels at once).

The ontology should not force per-site framing on aggregate strategies. A residential parcel's individual capacity assumption may be effectively zero or fractional while the aggregate strategy that includes it carries meaningful weight. The chain should be able to test assumptions at the scale they were stated.

Prototype source contact has confirmed that a single interpretive case can carry per-site, per-project, and aggregate-level assumptions simultaneously; the per-scale hierarchy is operational, and collapsing to a single scale loses interpretive coherence.

ImplementationSignal

A public-data observation that bears on whether one or more assumptions remain supported, weakened, contradicted, or uncertain. A signal is source-anchored (cites a public document or dataset), assumption-anchored (only counts as evidence about a specific assumption), directional, and typed. A row in a permit database is not a signal; the interpretation that the row's content weakens or supports a specific assumption is the signal.

Signal aggregation. Multiple similar raw records may be summarized as one ImplementationSignal where they support the same interpretation about the same assumption — for example, a series of related permit records that collectively bear on a single assumption can be summarized as one signal rather than recorded as many separate signals. Source and provenance remain inspectable: the summary signal cites the underlying records. The choice between per-record signals and summary signals is operational and depends on whether the underlying records carry distinct interpretive force. The chain does not require one signal per raw row.

Candidate signal subtypes. Signal subtypes are operationally useful for categorizing signals but are not final schema doctrine in v0. Candidate subtypes — surfaced by grounding-note context and by manual chain extraction — include:

  • AdministrativeSignal — pipeline / planning / case-management activity.
  • PermitSignal — building-permit activity.
  • PipelineSignal — project-status changes.
  • MarketSignal — market-level indicators.
  • InfrastructureSignal — capital plan or infrastructure-capacity signals.
  • EnvironmentalSignal — environmental review or constraint signals.
  • ParticipatorySignal — public-input signals (per grounding-note v7; reserved by default in v0).
  • EnforcementPromptedSignal — permits or activity prompted by enforcement actions rather than voluntary market activity.
  • CurrentUseSignal — signals about the current operating use of a property (e.g., active commercial tenancy at a site flagged for residential redevelopment).
  • ProgrammaticTemporalSignal — signals about the implementation environment rather than the site (e.g., long approval cycles, citywide entitlement-stage stalls).

These subtypes are candidates, not final schema. Prototype source contact in v0 has operated against CurrentUseSignal and ProgrammaticTemporalSignal as load-bearing subtypes; both are retained. The list as a whole remains candidate-level and may consolidate, split, or be renamed as further prototype work accumulates.

ImplementationFinding

The interpretive synthesis produced by comparing one or more assumptions against implementation signals. A finding carries direction, confidence, possible intervention candidates, and source provenance. Findings are the project's primary interpretive artifact; the Housing Element Implementation Risk Brief is a curated presentation of findings (see report-outline.md).

Three-layer assessment treatment. The method operates with three distinct assessment layers; they are deliberately not collapsed into a single direction value:

  1. Signal-level direction. An ImplementationSignal's direction relative to the assumption it anchors to. Working vocabulary: supports / weakens / contradicts / uncertain.
  2. Matrix row-level assessment. The matrix row's reading of one document-claim against its supporting and weakening evidence (see the Living Implementation Consistency matrix in methodology.md). Working vocabulary: confirmed / weakened / contradicted / unresolved / not yet testable. This vocabulary aligns to the design-system-ASK Evidence State profile by reference (UO owns assignment; DS owns the role vocabulary/value-mapping/presentation contract); the explicit role mapping — including that contradicted is consumer-local, outside the current DS profile — is in methodology.md §Living Implementation Consistency matrix.
  3. Finding-level composite treatment. When the row assessments within a finding diverge — including across the temporally distinct surfaces noted in methodology.md — the finding-level reading is composite. The composite is explained in the finding's interpretation prose rather than forced into a single controlled value.

Prototype source contact has surfaced cases where a single direction value cannot capture the implementation condition cleanly — partial support and partial weakening can coexist within one finding, and surface-specific readings can diverge across inventory snapshot, entitlement event, rolling advancement, and completion. The row-level vocabulary has held across operator-side scratch extractions but is not yet expert-reviewed; the finding-level composite treatment is held as prose, not as schema, and no controlled enum is committed for it. Final controlled vocabularies remain deferred to later prototype work.

InterventionCandidate

A downstream, non-prescriptive option that could plausibly change the trajectory of a weakened or contradicted assumption. Candidates are surfaced, not endorsed. They are plural and actor-typed where possible. They are not recommendations.

Supporting primitives

The following remain essential supporting primitives but are not the conceptual center of the method:

  • OpportunitySite — a Housing Element opportunity site. Anchor object for the citywide signal-card pass.
  • HousingProject — a project in the citywide pipeline. Separate from OpportunitySite, linkable through relationship statuses.
  • PolicyProgram — a city or state policy or program relevant to Housing Element implementation.
  • InfrastructureDependency — an upstream constraint that affects what a site or project can deliver.
  • MarketSignal — a market-level indicator that bears on feasibility.
  • Constraint — a regulatory, environmental, or policy constraint on a site or project.
  • Outcome — an observed outcome (delivered units, withdrawn projects, abandoned entitlements).
  • Source — a public document or dataset cited as provenance. First-class.
  • Confidence — a reusable confidence value attached to signals, findings, and signal cards.

OpportunitySite and HousingProject are separate but linkable. The relationship between them can be:

  • direct_match — a HousingProject is clearly on a Housing Element opportunity site (same parcel).
  • nearby_or_related — a project is near or within the planning area of an opportunity site, but not at the same parcel.
  • citywide_context — a project is not tied to an opportunity site but helps interpret broader pipeline / delivery conditions.
  • inventory_only — a Housing Element opportunity site is present in the inventory but has no matched HousingProject. The site exists as an assumption surface; no project signal has yet materialized.

The four-status split protects against several failure modes: ignoring citywide pipeline reality, forcing false project-to-site matches, collapsing the method into parcel feasibility, and treating an unmatched inventory site as either silently absent or as having an implicit project relationship it does not have.

Output classifications and direction labels (not objects in v0)

The following appear in the method's vocabulary but are not top-level objects in v0:

  • ImplementationRisk — an output classification / classification field, not an object. Attached to a finding or a signal card; combines direction, confidence, and structural conditions into a quick-scan tier. Specific terms are deferred.
  • FeasibilityShift — a direction label describing change over time in feasibility at the aggregate, typology, or corridor level.
  • SiteViabilityDrift — a direction label describing per-site, per-assumption drift over time.

Promoting these to objects would duplicate ImplementationFinding's direction and confidence fields and would prematurely add overlapping "direction-of-change" classes. They are useful project vocabulary, not separate schema entities in v0.

Cautions against alternative centers

The method's coherence depends on keeping Assumption at the center. Specifically:

  • Do not make Site the core primitive — the project risks collapsing into parcel feasibility.
  • Do not make Intervention the core primitive — the project risks sounding prescriptive too early.
  • Do not make Constraint the core primitive — the project risks becoming a static constraint inventory rather than a continuously-interpretive system.

The core is assumptions under changing conditions.

What stays conceptual in v0

The object model is a working hypothesis at the level of named primitives and the interpretive chain. The following remain conceptual until prototype work — specifically, a manual sample extraction step on a small set of opportunity sites — has tested the model against real public-data shape:

  1. Field-level schema of Assumption and ImplementationSignal.
  2. The exact mechanism by which assumptions reference supporting objects.
  3. Controlled vocabularies (direction labels, risk tiers, confidence levels, signal types, finding directions, candidate actor types).
  4. Typology list (the categories of opportunity sites are not hard-coded before reviewing the actual inventory).
  5. Specific datasets within source tiers (see source-strategy.md).
  6. Cross-cutting finding and intervention-candidate mechanisms.
  7. Pattern summary representation (as object vs. as brief section).
  8. Confidence basis taxonomy.
  9. APR-augmentation companion mechanism (how findings relate structurally to APR sections).

If prototype work surfaces substantial revisions to several of these, the right response is to slim the object model down to the chain plus supporting primitives and accept that source-data pressure has done its job.

Posture

This object model is a working hypothesis. Repo-local schema files and runnable schema artifacts are deferred to later phases. The chain and the supporting primitives are named here because they are method-bearing; schema-shape decisions are deferred because they are data-shape decisions.

For per-concept field-level treatment (candidate fields, source / provenance requirements, and the relationship between objects, signal subtypes, classifications, and reporting surfaces), see data-dictionary.md. For the chain exercised once, end to end, on a single site-abstracted case, see method-appendix-worked-pattern.md.