feat(examples): Phase 2 schema — FX, allowance windows, filing timeline#360
Merged
Conversation
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
buremba
force-pushed
the
feat/world-model-companies
branch
from
81adb4a to
865a027
Compare
Adds the accretive entities the long-term world model needs to support
foreign income, materialized allowance budgeting, and proactive filing
deadlines. None of these break the v1 SA100 flow; they simply fill in
gaps the agent had to work around.
New entities:
- allowance_window — materialized accumulator per (tax_year, kind):
isa_subscription, dividend_allowance, personal_savings_allowance,
cgt_annual_exempt, pension_annual_allowance (with 3-year carry-
forward), property_income_allowance, trading_allowance,
personal_allowance (tapered).
- filing_obligation — one per required submission (SA100 paper, online,
balancing payment, POA1, POA2, CT600, VAT101, P11D). Carries due_date
and status so the agent can surface deadlines proactively.
- payment — HMRC payments in either direction (balancing, POA1, POA2,
corp_tax, vat, refund, penalty, interest). Distinct from generic
transactions because it ties to filing_obligation for reconciliation.
- tax_assessment — the computed tax position for one (tax_year,
subject) pair. source ∈ {agent_projection, hmrc_sa302,
hmrc_ct600_acknowledgement, manual} so we can compare HMRC's number
with our own.
New relationship types:
- accumulates_in (transaction|contribution → allowance_window)
- obligation_for (filing_obligation → tax_year, $member|company)
- assessment_for (tax_assessment → tax_year, $member|company)
- settles (payment → filing_obligation)
Field additions:
- transaction: native_amount + native_currency + fx_rate_to_gbp +
fx_rate_source for non-GBP transactions. Keeps both numbers + the
conversion source so HMRC-aligned auditing is possible.
- income_source: foreign_tax_paid + foreign_tax_currency +
withholding_jurisdiction + treaty_rate_applied for SA106 Foreign Tax
Credit Relief.
SOUL.md teaches:
- When and how to record FX (non-GBP transactions, which rate to use).
- How to maintain allowance_window accumulators on every relevant write.
- How to register filing_obligation + reconcile via tax_assessment
+ settle via payment.
40 model YAMLs total. All validate.
buremba
force-pushed
the
feat/phase2-schema
branch
from
ee35b5c to
85f9e29
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 2 of the world model. Accretive — doesn't break v1 SA100 flow, fills the gaps the agent had to work around.
New entities (4)
New relationship types (4)
`accumulates_in` (tx → allowance_window), `obligation_for` (filing_obligation → tax_year + subject), `assessment_for` (tax_assessment → tax_year + subject), `settles` (payment → filing_obligation).
Field additions
SOUL.md teaches the FX rule (HMRC monthly average as default), allowance-window maintenance on every relevant write, and filing-obligation/payment/tax_assessment usage.
Stacked on
`feat/world-model-companies` (#358).
Test plan
Follow-up
ASSEMBLY.md will need a small SA106 section update to use the new foreign-tax fields. I'll amend that branch after this lands.