Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/tests/test_object_materialize.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
test_object_materialize.py · 41.8 KB · 935 lines
1"""Unit tests for object_materialize.py -- plan/vocabulary/61-materialize-spec.md.
2
3Mirrors tests/test_object_rollups.py's direct schema/record-fixture style:
4write a schema straight to data/schemas, create rows through object_records
5with base_dir=tmp_path and roots=[] (never touching the real packages/
6tree), then exercise object_materialize directly.
7
8End-to-end package/permission tests (admin-only materialize_definitions,
9the real dbbasic-package.json/manifest, HANDLES regeneration against the
10real installed materialize_seed.py) live in
11tests/test_app_materialize_package.py instead.
12"""
13import json
14
15import pytest
16
17import object_records
18import object_materialize
19import object_schemas
20
21
22def write_schema(data_dir, collection, fields, storage=None):
23 payload = {"name": collection, "fields": fields}
24 if storage:
25 payload["storage"] = storage
26 path = data_dir / "schemas" / f"{collection}.json"
27 path.parent.mkdir(parents=True, exist_ok=True)
28 path.write_text(json.dumps(payload))
29 return path
30
31
32FIN_RECURRING_FIELDS = [
33 {"name": "id"},
34 {"name": "name", "type": "text"},
35 {"name": "template_lines", "type": "textarea"},
36 {"name": "frequency", "type": "text"},
37 {"name": "next_run", "type": "date"},
38 {"name": "auto_post", "type": "boolean"},
39 {"name": "is_active", "type": "boolean"},
40 {"name": "created_at", "type": "datetime"},
41]
42
43FIN_JOURNALS_FIELDS = [
44 {"name": "id"},
45 {"name": "date", "type": "date"},
46 {"name": "description", "type": "text"},
47 {"name": "status", "type": "text"},
48 {"name": "reference", "type": "text"},
49 {"name": "currency", "type": "text"},
50 {"name": "generated_from", "type": "text"},
51]
52
53FIN_JOURNAL_LINES_FIELDS = [
54 {"name": "id"},
55 {"name": "journal_id", "type": "text"},
56 {"name": "account_id", "type": "text"},
57 {"name": "debit_cents", "type": "integer"},
58 {"name": "credit_cents", "type": "integer"},
59 {"name": "memo", "type": "text"},
60]
61
62PRODUCTS_FIELDS = [
63 {"name": "id"},
64 {"name": "name", "type": "text"},
65 {"name": "product_type", "type": "text"},
66 {"name": "purchase_date", "type": "date"},
67 {"name": "purchase_cost_cents", "type": "integer"},
68 {"name": "salvage_value_cents", "type": "integer"},
69 {"name": "useful_life_months", "type": "integer"},
70 {"name": "depreciation_method", "type": "text"},
71]
72
73TASKS_FIELDS = [
74 {"name": "id"},
75 {"name": "title", "type": "text"},
76 {"name": "description", "type": "textarea"},
77 {"name": "template_id", "type": "text", "relation": {"collection": "templates", "display_field": "name"}},
78 {"name": "generated_from", "type": "text"},
79]
80
81TEMPLATES_FIELDS = [
82 {"name": "id"},
83 {"name": "name", "type": "text"},
84 {"name": "default_values", "type": "textarea"},
85]
86
87
88def _make_fin_recurring(data_dir, rows):
89 write_schema(data_dir, "fin_recurring", FIN_RECURRING_FIELDS)
90 for row in rows:
91 object_records.create_collection_record("fin_recurring", row, base_dir=data_dir, roots=[])
92
93
94def _make_fin_journals(data_dir):
95 write_schema(data_dir, "fin_journals", FIN_JOURNALS_FIELDS)
96
97
98def _make_fin_journal_lines(data_dir):
99 write_schema(data_dir, "fin_journal_lines", FIN_JOURNAL_LINES_FIELDS, storage="append")
100
101
102def _make_products(data_dir, rows):
103 write_schema(data_dir, "products", PRODUCTS_FIELDS)
104 for row in rows:
105 object_records.create_collection_record("products", row, base_dir=data_dir, roots=[])
106
107
108def _make_tasks(data_dir, rows):
109 write_schema(data_dir, "tasks", TASKS_FIELDS)
110 for row in rows:
111 object_records.create_collection_record("tasks", row, base_dir=data_dir, roots=[])
112
113
114def _make_templates(data_dir, rows):
115 write_schema(data_dir, "templates", TEMPLATES_FIELDS)
116 for row in rows:
117 object_records.create_collection_record("templates", row, base_dir=data_dir, roots=[])
118
119
120def _recurring_definition(**overrides):
121 base = {
122 "id": "matgen_fin_recurring",
123 "name": "Recurring journal generation",
124 "source_collection": "fin_recurring",
125 "source_filter": json.dumps({"is_active": "true"}),
126 "trigger": json.dumps({
127 "mode": "scheduled",
128 "interval_seconds": 3600,
129 "period_field": "frequency",
130 "anchor_field": "next_run",
131 }),
132 "output_collection": "fin_journals",
133 "child_collection": "fin_journal_lines",
134 "child_source_field": "template_lines",
135 "child_link_field": "journal_id",
136 "idempotency_key": "matgen_{definition_id}_{source_id}_{period_start}",
137 "mapping": json.dumps({
138 "date": {"from_period": "period_start"},
139 "description": {"template": "Recurring: {source.name} ({period_label})"},
140 "status": {"if": {"source_field": "auto_post", "equals": True}, "then": "posted", "else": "draft"},
141 "reference": {"literal": ""},
142 "currency": {"literal": "USD"},
143 }),
144 "balance_check": json.dumps({"debit_field": "debit_cents", "credit_field": "credit_cents"}),
145 "last_run_at": "",
146 "actor": "daemon:materialize",
147 "enabled": "true",
148 "block": "false",
149 }
150 base.update(overrides)
151 return base
152
153
154def _depreciation_definition(**overrides):
155 base = {
156 "id": "matgen_depreciation",
157 "name": "Monthly depreciation",
158 "source_collection": "products",
159 "source_filter": json.dumps({"product_type": "asset"}),
160 "trigger": json.dumps({
161 "mode": "scheduled_fixed",
162 "interval_seconds": 3600,
163 "period_field": "monthly",
164 "start_field": "purchase_date",
165 "end_condition": {"periods_field": "useful_life_months"},
166 }),
167 "output_collection": "fin_journals",
168 "child_collection": "fin_journal_lines",
169 "child_link_field": "journal_id",
170 "idempotency_key": "matgen_{definition_id}_{source_id}_{period_start}",
171 "mapping": json.dumps({
172 "date": {"from_period": "period_start"},
173 "description": {"template": "Depreciation: {source.name} ({period_label})"},
174 "status": {"literal": "posted"},
175 "currency": {"literal": "USD"},
176 "amount": {"depreciation_amount": {
177 "method": "straight_line",
178 "cost_field": "purchase_cost_cents",
179 "salvage_field": "salvage_value_cents",
180 "life_field": "useful_life_months",
181 }},
182 }),
183 "balance_check": json.dumps({"debit_field": "debit_cents", "credit_field": "credit_cents"}),
184 "debit_account_id": "acct_expense",
185 "credit_account_id": "acct_accum_depr",
186 "last_run_at": "",
187 "actor": "daemon:materialize",
188 "enabled": "true",
189 "block": "false",
190 }
191 base.update(overrides)
192 return base
193
194
195def _creatework_definition(**overrides):
196 base = {
197 "id": "matgen_task_seed",
198 "name": "CreateWork seed",
199 "source_collection": "tasks",
200 "trigger": json.dumps({"mode": "event", "on": "record.created"}),
201 "output_collection": "tasks",
202 "idempotency_key": "{definition_id}_{source_id}",
203 "mapping": json.dumps({}),
204 "last_run_at": "",
205 "actor": "daemon:materialize",
206 "enabled": "true",
207 "block": "false",
208 }
209 base.update(overrides)
210 return base
211
212
213# --- parse_definition: happy paths --------------------------------------------------
214
215def test_parse_definition_scheduled_happy_path(tmp_path):
216 data_dir = tmp_path / "data"
217 _make_fin_recurring(data_dir, [])
218 _make_fin_journals(data_dir)
219 _make_fin_journal_lines(data_dir)
220
221 config = object_materialize.parse_definition(_recurring_definition(), base_dir=data_dir, roots=[])
222
223 assert config.definition_id == "matgen_fin_recurring"
224 assert config.trigger_mode == "scheduled"
225 assert config.anchor_field == "next_run"
226 assert config.frequency_field == "frequency"
227 assert config.output_collection == "fin_journals"
228 assert config.child_collection == "fin_journal_lines"
229 assert config.balance_check == {"debit_field": "debit_cents", "credit_field": "credit_cents"}
230 assert config.stamp_generated_from is True # fin_journals fixture declares generated_from
231
232
233def test_parse_definition_scheduled_fixed_happy_path(tmp_path):
234 data_dir = tmp_path / "data"
235 _make_products(data_dir, [])
236 _make_fin_journals(data_dir)
237 _make_fin_journal_lines(data_dir)
238
239 config = object_materialize.parse_definition(_depreciation_definition(), base_dir=data_dir, roots=[])
240
241 assert config.trigger_mode == "scheduled_fixed"
242 assert config.start_field == "purchase_date"
243 assert config.granularity == "monthly"
244 assert config.periods_field == "useful_life_months"
245 assert config.synthesized_amount_entry == {"depreciation_amount": {
246 "method": "straight_line",
247 "cost_field": "purchase_cost_cents",
248 "salvage_field": "salvage_value_cents",
249 "life_field": "useful_life_months",
250 }}
251 assert "amount" not in config.mapping # popped out for the synthesized shape
252 assert config.debit_account_id == "acct_expense"
253 assert config.credit_account_id == "acct_accum_depr"
254
255
256def test_parse_definition_event_happy_path(tmp_path):
257 data_dir = tmp_path / "data"
258 _make_tasks(data_dir, [])
259
260 config = object_materialize.parse_definition(_creatework_definition(), base_dir=data_dir, roots=[])
261
262 assert config.trigger_mode == "event"
263 assert config.output_collection == config.source_collection == "tasks"
264
265
266# --- parse_definition: validation --------------------------------------------------
267
268def test_parse_definition_rejects_missing_id(tmp_path):
269 data_dir = tmp_path / "data"
270 _make_fin_recurring(data_dir, [])
271 _make_fin_journals(data_dir)
272 _make_fin_journal_lines(data_dir)
273 with pytest.raises(object_materialize.DefinitionError, match="missing an id"):
274 object_materialize.parse_definition(_recurring_definition(id=""), base_dir=data_dir, roots=[])
275
276
277def test_parse_definition_rejects_missing_source_collection(tmp_path):
278 data_dir = tmp_path / "data"
279 with pytest.raises(object_materialize.DefinitionError, match="source_collection"):
280 object_materialize.parse_definition(_recurring_definition(source_collection=""), base_dir=data_dir, roots=[])
281
282
283def test_parse_definition_raises_missing_collection_error_for_unknown_source(tmp_path):
284 data_dir = tmp_path / "data"
285 with pytest.raises(object_materialize.MissingCollectionError) as excinfo:
286 object_materialize.parse_definition(
287 _recurring_definition(source_collection="no_such_collection"), base_dir=data_dir, roots=[],
288 )
289 assert excinfo.value.collection == "no_such_collection"
290 assert excinfo.value.role == "source"
291
292
293def test_parse_definition_raises_missing_collection_error_for_unknown_output(tmp_path):
294 data_dir = tmp_path / "data"
295 _make_fin_recurring(data_dir, [])
296 with pytest.raises(object_materialize.MissingCollectionError) as excinfo:
297 object_materialize.parse_definition(
298 _recurring_definition(output_collection="no_such_output"), base_dir=data_dir, roots=[],
299 )
300 assert excinfo.value.role == "output"
301
302
303def test_parse_definition_rejects_declining_depreciation_method(tmp_path):
304 data_dir = tmp_path / "data"
305 _make_products(data_dir, [])
306 _make_fin_journals(data_dir)
307 _make_fin_journal_lines(data_dir)
308 bad = _depreciation_definition(mapping=json.dumps({
309 "amount": {"depreciation_amount": {
310 "method": "declining", "cost_field": "purchase_cost_cents",
311 "salvage_field": "salvage_value_cents", "life_field": "useful_life_months",
312 }},
313 }))
314 with pytest.raises(object_materialize.DefinitionError, match="declining"):
315 object_materialize.parse_definition(bad, base_dir=data_dir, roots=[])
316
317
318def test_parse_definition_rejects_unrecognized_mapping_op(tmp_path):
319 data_dir = tmp_path / "data"
320 _make_fin_recurring(data_dir, [])
321 _make_fin_journals(data_dir)
322 _make_fin_journal_lines(data_dir)
323 bad = _recurring_definition(mapping=json.dumps({"status": {"whatever": "x"}}))
324 with pytest.raises(object_materialize.DefinitionError, match="unrecognized|must use one of"):
325 object_materialize.parse_definition(bad, base_dir=data_dir, roots=[])
326
327
328def test_parse_definition_requires_child_link_field_when_child_collection_set(tmp_path):
329 data_dir = tmp_path / "data"
330 _make_fin_recurring(data_dir, [])
331 _make_fin_journals(data_dir)
332 _make_fin_journal_lines(data_dir)
333 bad = _recurring_definition(child_link_field="")
334 with pytest.raises(object_materialize.DefinitionError, match="child_link_field"):
335 object_materialize.parse_definition(bad, base_dir=data_dir, roots=[])
336
337
338def test_parse_definition_synthesized_shape_requires_accounts(tmp_path):
339 data_dir = tmp_path / "data"
340 _make_products(data_dir, [])
341 _make_fin_journals(data_dir)
342 _make_fin_journal_lines(data_dir)
343 bad = _depreciation_definition(debit_account_id="", credit_account_id="")
344 with pytest.raises(object_materialize.DefinitionError, match="debit_account_id and credit_account_id"):
345 object_materialize.parse_definition(bad, base_dir=data_dir, roots=[])
346
347
348def test_parse_definition_stamp_generated_from_false_when_output_schema_lacks_field(tmp_path):
349 data_dir = tmp_path / "data"
350 _make_tasks(data_dir, [])
351 config = object_materialize.parse_definition(_creatework_definition(), base_dir=data_dir, roots=[])
352 # tasks fixture DOES declare generated_from in this test module -- use a
353 # bare schema without it to prove the opt-in behavior.
354 write_schema(data_dir, "tasks_bare", [{"name": "id"}, {"name": "title", "type": "text"}])
355 bare = _creatework_definition(id="matgen_bare", source_collection="tasks_bare", output_collection="tasks_bare")
356 config_bare = object_materialize.parse_definition(bare, base_dir=data_dir, roots=[])
357 assert config.stamp_generated_from is True
358 assert config_bare.stamp_generated_from is False
359
360
361# --- mapping vocabulary --------------------------------------------------
362
363def _period(start="2026-07-01", end="2026-08-01", label="2026-07", index=None, total=None):
364 from datetime import date
365 return object_materialize.Period(
366 start=date.fromisoformat(start), end=date.fromisoformat(end), label=label, index=index, total=total,
367 )
368
369
370def test_eval_entry_from_copies_source_field():
371 value = object_materialize._eval_entry(
372 "name", {"from": "name"}, source_row={"name": "Acme"}, period=None, definition_id="d1",
373 )
374 assert value == "Acme"
375
376
377def test_eval_entry_from_period_start_end_label():
378 period = _period()
379 assert object_materialize._eval_entry(
380 "date", {"from_period": "period_start"}, source_row={}, period=period, definition_id="d1",
381 ) == "2026-07-01"
382 assert object_materialize._eval_entry(
383 "date", {"from_period": "period_end"}, source_row={}, period=period, definition_id="d1",
384 ) == "2026-08-01"
385 assert object_materialize._eval_entry(
386 "date", {"from_period": "period_label"}, source_row={}, period=period, definition_id="d1",
387 ) == "2026-07"
388
389
390def test_eval_entry_from_period_requires_a_period():
391 with pytest.raises(object_materialize.DefinitionError, match="from_period"):
392 object_materialize._eval_entry(
393 "date", {"from_period": "period_start"}, source_row={}, period=None, definition_id="d1",
394 )
395
396
397def test_eval_entry_literal():
398 assert object_materialize._eval_entry(
399 "currency", {"literal": "USD"}, source_row={}, period=None, definition_id="d1",
400 ) == "USD"
401
402
403def test_eval_entry_template_interpolates_source_and_period_label():
404 period = _period()
405 value = object_materialize._eval_entry(
406 "description", {"template": "Recurring: {source.name} ({period_label})"},
407 source_row={"name": "Acme"}, period=period, definition_id="d1",
408 )
409 assert value == "Recurring: Acme (2026-07)"
410
411
412def test_eval_entry_template_rejects_unknown_placeholder():
413 with pytest.raises(object_materialize.DefinitionError, match="unknown placeholder"):
414 object_materialize._eval_entry(
415 "description", {"template": "{nonsense}"}, source_row={}, period=None, definition_id="d1",
416 )
417
418
419def test_eval_entry_if_resolves_true_and_false_branches():
420 entry = {"if": {"source_field": "auto_post", "equals": True}, "then": "posted", "else": "draft"}
421 assert object_materialize._eval_entry(
422 "status", entry, source_row={"auto_post": "true"}, period=None, definition_id="d1",
423 ) == "posted"
424 assert object_materialize._eval_entry(
425 "status", entry, source_row={"auto_post": "false"}, period=None, definition_id="d1",
426 ) == "draft"
427 assert object_materialize._eval_entry(
428 "status", entry, source_row={}, period=None, definition_id="d1",
429 ) == "draft"
430
431
432def test_validate_mapping_entry_if_requires_then_and_else():
433 with pytest.raises(object_materialize.DefinitionError, match="then.*else|'then' and 'else'"):
434 object_materialize._validate_mapping_entry(
435 "status", {"if": {"source_field": "x", "equals": "y"}, "then": "a"}, definition_id="d1",
436 )
437
438
439# --- straight-line depreciation, integer cents, remainder on final period ------
440
441def test_straight_line_split_computes_monthly_and_remainder():
442 op = {"cost_field": "cost", "salvage_field": "salvage", "life_field": "life"}
443 row = {"cost": "10000", "salvage": "1000", "life": "3"} # 9000 / 3 = 3000 exact
444 monthly, remainder = object_materialize._straight_line_split(op, row, definition_id="d1", field_name="amount")
445 assert monthly == 3000
446 assert remainder == 0
447
448
449def test_straight_line_split_remainder_lands_exactly_on_final_period():
450 op = {"cost_field": "cost", "salvage_field": "salvage", "life_field": "life"}
451 # depreciable = 10000 cents, life = 3 -> monthly = 3333, remainder = 1
452 row = {"cost": "10000", "salvage": "0", "life": "3"}
453 monthly, remainder = object_materialize._straight_line_split(op, row, definition_id="d1", field_name="amount")
454 assert monthly == 3333
455 assert remainder == 1
456 assert monthly * 3 + remainder == 10000 # exact, no truncation drift
457
458
459def test_eval_depreciation_books_monthly_except_final_period():
460 op = {"cost_field": "cost", "salvage_field": "salvage", "life_field": "life"}
461 row = {"cost": "10000", "salvage": "0", "life": "3"}
462 p1 = _period(index=1, total=3)
463 p2 = _period(index=2, total=3)
464 p3 = _period(index=3, total=3)
465 assert object_materialize._eval_depreciation(op, row, p1, definition_id="d1", field_name="amount") == "3333"
466 assert object_materialize._eval_depreciation(op, row, p2, definition_id="d1", field_name="amount") == "3333"
467 assert object_materialize._eval_depreciation(op, row, p3, definition_id="d1", field_name="amount") == "3334"
468
469
470def test_eval_depreciation_requires_a_capped_scheduled_fixed_period():
471 op = {"cost_field": "cost", "salvage_field": "salvage", "life_field": "life"}
472 with pytest.raises(object_materialize.DefinitionError, match="scheduled_fixed"):
473 object_materialize._eval_depreciation(op, {}, None, definition_id="d1", field_name="amount")
474 uncapped = _period(index=None, total=None)
475 with pytest.raises(object_materialize.DefinitionError, match="scheduled_fixed"):
476 object_materialize._eval_depreciation(op, {}, uncapped, definition_id="d1", field_name="amount")
477
478
479# --- period computation --------------------------------------------------
480
481def test_compute_scheduled_periods_monthly_generates_one_period_per_month():
482 from datetime import date
483 config = object_materialize.parse_definition # not used directly; build a minimal config via dataclass
484 cfg = object_materialize.MaterializeConfig(
485 definition_id="d1", name="d1", source_collection="fin_recurring", source_filter={},
486 trigger_mode="scheduled", trigger_interval_seconds=3600,
487 anchor_field="next_run", frequency_field="frequency",
488 start_field=None, granularity=None, periods_field=None,
489 output_collection="fin_journals", child_collection=None, child_source_field=None,
490 child_link_field=None, idempotency_key="{definition_id}_{source_id}_{period_start}",
491 mapping={}, balance_check=None, debit_account_id=None, credit_account_id=None,
492 synthesized_amount_entry=None, actor="daemon:materialize", enabled=True, block=False,
493 stamp_generated_from=False,
494 )
495 row = {"frequency": "monthly", "next_run": "2026-01-15"}
496 periods = object_materialize._compute_scheduled_periods(row, cfg, now=date(2026, 4, 20))
497 starts = [p.start.isoformat() for p in periods]
498 assert starts == ["2026-01-15", "2026-02-15", "2026-03-15", "2026-04-15"]
499 assert periods[0].label == "2026-01"
500 assert periods[0].index is None and periods[0].total is None
501
502
503def test_compute_scheduled_periods_daily_and_weekly_granularity():
504 from datetime import date
505 cfg = object_materialize.MaterializeConfig(
506 definition_id="d1", name="d1", source_collection="s", source_filter={},
507 trigger_mode="scheduled", trigger_interval_seconds=3600,
508 anchor_field="next_run", frequency_field="frequency",
509 start_field=None, granularity=None, periods_field=None,
510 output_collection="o", child_collection=None, child_source_field=None,
511 child_link_field=None, idempotency_key="k", mapping={}, balance_check=None,
512 debit_account_id=None, credit_account_id=None, synthesized_amount_entry=None,
513 actor="a", enabled=True, block=False, stamp_generated_from=False,
514 )
515 daily_row = {"frequency": "daily", "next_run": "2026-07-01"}
516 daily_periods = object_materialize._compute_scheduled_periods(daily_row, cfg, now=date(2026, 7, 3))
517 assert [p.start.isoformat() for p in daily_periods] == ["2026-07-01", "2026-07-02", "2026-07-03"]
518
519 weekly_row = {"frequency": "weekly", "next_run": "2026-07-01"}
520 weekly_periods = object_materialize._compute_scheduled_periods(weekly_row, cfg, now=date(2026, 7, 20))
521 assert [p.start.isoformat() for p in weekly_periods] == ["2026-07-01", "2026-07-08", "2026-07-15"]
522
523
524def test_compute_scheduled_fixed_periods_caps_at_useful_life_and_stops_at_now():
525 from datetime import date
526 cfg = object_materialize.MaterializeConfig(
527 definition_id="d1", name="d1", source_collection="products", source_filter={},
528 trigger_mode="scheduled_fixed", trigger_interval_seconds=3600,
529 anchor_field=None, frequency_field=None,
530 start_field="purchase_date", granularity="monthly", periods_field="useful_life_months",
531 output_collection="fin_journals", child_collection="fin_journal_lines", child_source_field=None,
532 child_link_field="journal_id", idempotency_key="k", mapping={}, balance_check=None,
533 debit_account_id="a1", credit_account_id="a2", synthesized_amount_entry={"depreciation_amount": {}},
534 actor="a", enabled=True, block=False, stamp_generated_from=False,
535 )
536 row = {"purchase_date": "2026-01-01", "useful_life_months": "3"}
537 periods = object_materialize._compute_scheduled_fixed_periods(row, cfg, now=date(2026, 12, 31))
538 assert [p.start.isoformat() for p in periods] == ["2026-01-01", "2026-02-01", "2026-03-01"]
539 assert [p.index for p in periods] == [1, 2, 3]
540 assert all(p.total == 3 for p in periods)
541
542 # now before the 3rd period -- only 2 periods due yet
543 partial = object_materialize._compute_scheduled_fixed_periods(row, cfg, now=date(2026, 2, 15))
544 assert [p.index for p in partial] == [1, 2]
545
546
547def test_month_advance_handles_day_overflow_correctly():
548 from datetime import date
549 assert object_materialize._add_months(date(2026, 1, 31), 1) == date(2026, 2, 28)
550 assert object_materialize._add_months(date(2024, 1, 31), 1) == date(2024, 2, 29) # leap year
551
552
553# --- generate_definition / generate_one: full worked examples ------------------
554
555def test_recurring_journal_generation_creates_header_and_lines(tmp_path):
556 data_dir = tmp_path / "data"
557 _make_fin_journals(data_dir)
558 _make_fin_journal_lines(data_dir)
559 template_lines = json.dumps([
560 {"account_id": "acct_cash", "debit_cents": 1000, "credit_cents": 0, "memo": "cash"},
561 {"account_id": "acct_rev", "debit_cents": 0, "credit_cents": 1000, "memo": "rev"},
562 ])
563 _make_fin_recurring(data_dir, [{
564 "id": "rec1", "name": "Rent", "template_lines": template_lines,
565 "frequency": "monthly", "next_run": "2026-06-01", "auto_post": "true", "is_active": "true",
566 }])
567
568 definition = _recurring_definition()
569 result = object_materialize.generate_definition(definition, base_dir=data_dir, roots=[], now=None)
570
571 # now defaults to current real time, far past 2026-06-01 -- at least one period generated
572 assert result["generated"] >= 1
573 assert result["errors"] == []
574
575 journals = object_records.read_collection_records("fin_journals", base_dir=data_dir, roots=[])
576 assert len(journals) >= 1
577 header = journals[0]
578 assert header["status"] == "posted" # auto_post true
579 assert header["currency"] == "USD"
580 assert header["description"].startswith("Recurring: Rent (")
581 assert json.loads(header["generated_from"])["definition_id"] == "matgen_fin_recurring"
582 assert json.loads(header["generated_from"])["source_id"] == "rec1"
583
584 lines = object_records.read_collection_records("fin_journal_lines", base_dir=data_dir, roots=[])
585 assert len(lines) == 2 * len(journals)
586 for line in lines:
587 assert line["journal_id"] == header["id"] or line["journal_id"] in {j["id"] for j in journals}
588
589
590def test_double_run_generates_no_duplicate(tmp_path):
591 data_dir = tmp_path / "data"
592 _make_fin_journals(data_dir)
593 _make_fin_journal_lines(data_dir)
594 template_lines = json.dumps([
595 {"account_id": "acct_cash", "debit_cents": 500, "credit_cents": 0},
596 {"account_id": "acct_rev", "debit_cents": 0, "credit_cents": 500},
597 ])
598 _make_fin_recurring(data_dir, [{
599 "id": "rec1", "name": "Rent", "template_lines": template_lines,
600 "frequency": "monthly", "next_run": "2020-01-01", "auto_post": "false", "is_active": "true",
601 }])
602 definition = _recurring_definition()
603
604 first = object_materialize.generate_definition(definition, base_dir=data_dir, roots=[])
605 assert first["generated"] > 0
606 journal_count_after_first = len(object_records.read_collection_records("fin_journals", base_dir=data_dir, roots=[]))
607 line_count_after_first = len(object_records.read_collection_records("fin_journal_lines", base_dir=data_dir, roots=[]))
608
609 second = object_materialize.generate_definition(definition, base_dir=data_dir, roots=[])
610 assert second["generated"] == 0
611 assert second["skipped_already_generated"] == first["generated"]
612
613 journal_count_after_second = len(object_records.read_collection_records("fin_journals", base_dir=data_dir, roots=[]))
614 line_count_after_second = len(object_records.read_collection_records("fin_journal_lines", base_dir=data_dir, roots=[]))
615 assert journal_count_after_second == journal_count_after_first
616 assert line_count_after_second == line_count_after_first
617
618
619def test_unbalanced_generation_writes_zero_rows(tmp_path):
620 data_dir = tmp_path / "data"
621 _make_fin_journals(data_dir)
622 _make_fin_journal_lines(data_dir)
623 unbalanced_lines = json.dumps([
624 {"account_id": "acct_cash", "debit_cents": 1000, "credit_cents": 0},
625 {"account_id": "acct_rev", "debit_cents": 0, "credit_cents": 999}, # off by one cent
626 ])
627 _make_fin_recurring(data_dir, [{
628 "id": "rec1", "name": "Bad", "template_lines": unbalanced_lines,
629 "frequency": "monthly", "next_run": "2020-01-01", "auto_post": "true", "is_active": "true",
630 }])
631 definition = _recurring_definition()
632
633 result = object_materialize.generate_definition(definition, base_dir=data_dir, roots=[])
634
635 assert result["generated"] == 0
636 assert len(result["errors"]) >= 1
637 assert "unbalanced" in result["errors"][0]["error"]
638
639 assert object_records.read_collection_records("fin_journals", base_dir=data_dir, roots=[]) == []
640 assert object_records.read_collection_records("fin_journal_lines", base_dir=data_dir, roots=[]) == []
641
642
643def test_child_first_header_last_ordering_and_crash_recovery(tmp_path):
644 """Simulate a crash between the last child write and the header write:
645 manually write only the child rows (as generate_one would, mid-flight),
646 confirm no header exists yet, then re-run the SAME generation and
647 confirm it re-writes the (idempotent, already-there) children without
648 error and completes by writing the header -- 61's Storage section's
649 exact recovery story.
650 """
651 data_dir = tmp_path / "data"
652 _make_fin_journals(data_dir)
653 _make_fin_journal_lines(data_dir)
654 template_lines = json.dumps([
655 {"account_id": "acct_cash", "debit_cents": 200, "credit_cents": 0},
656 {"account_id": "acct_rev", "debit_cents": 0, "credit_cents": 200},
657 ])
658 _make_fin_recurring(data_dir, [{
659 "id": "rec1", "name": "Crash test", "template_lines": template_lines,
660 "frequency": "monthly", "next_run": "2020-01-01", "auto_post": "true", "is_active": "true",
661 }])
662 definition = _recurring_definition()
663 config = object_materialize.parse_definition(definition, base_dir=data_dir, roots=[])
664
665 row = object_records.get_collection_record("fin_recurring", "rec1", base_dir=data_dir, roots=[])
666 from datetime import date
667 period = object_materialize.Period(
668 start=date(2020, 1, 1), end=date(2020, 2, 1), label="2020-01", index=None, total=None,
669 )
670 header_id = object_materialize._render_idempotency_key(config, source_row=row, period=period)
671
672 # Simulate the crash: write ONLY the children (as generate_one's first
673 # phase would), never the header.
674 child_rows = object_materialize._build_child_rows(config, source_row=row, header_id=header_id, period=period)
675 for child in child_rows:
676 object_records.create_collection_record(
677 "fin_journal_lines", child, base_dir=data_dir, roots=[], actor=config.actor,
678 )
679
680 assert object_records.read_collection_records("fin_journals", base_dir=data_dir, roots=[]) == []
681 orphans_before = object_records.read_collection_records("fin_journal_lines", base_dir=data_dir, roots=[])
682 assert len(orphans_before) == 2 # orphaned, headerless -- exactly 61's "accepted, bounded" failure mode
683
684 # Re-run the full generation -- must re-write the (now-duplicate-id)
685 # children harmlessly and complete by writing the header.
686 result = object_materialize.generate_one(config, row, period, base_dir=data_dir, roots=[])
687 assert result["status"] == "generated"
688 assert result["header_id"] == header_id
689
690 journals = object_records.read_collection_records("fin_journals", base_dir=data_dir, roots=[])
691 assert len(journals) == 1
692 assert journals[0]["id"] == header_id
693
694 lines = object_records.read_collection_records("fin_journal_lines", base_dir=data_dir, roots=[])
695 assert len(lines) == 2 # no duplicate lines despite the pre-existing orphans
696
697
698def test_depreciation_generation_books_straight_line_with_remainder_on_final_period(tmp_path):
699 data_dir = tmp_path / "data"
700 _make_fin_journals(data_dir)
701 _make_fin_journal_lines(data_dir)
702 _make_products(data_dir, [{
703 "id": "asset1", "name": "Laptop", "product_type": "asset",
704 "purchase_date": "2026-01-01", "purchase_cost_cents": "100000",
705 "salvage_value_cents": "0", "useful_life_months": "3",
706 "depreciation_method": "straight_line",
707 }])
708 definition = _depreciation_definition()
709
710 from datetime import date, datetime, timezone
711 now = datetime(2026, 4, 1, tzinfo=timezone.utc) # past all 3 periods
712 result = object_materialize.generate_definition(definition, base_dir=data_dir, roots=[], now=now)
713
714 assert result["generated"] == 3
715 assert result["errors"] == []
716
717 journals = object_records.read_collection_records("fin_journals", base_dir=data_dir, roots=[])
718 assert len(journals) == 3
719 lines = object_records.read_collection_records("fin_journal_lines", base_dir=data_dir, roots=[])
720 assert len(lines) == 6
721
722 # 100000 // 3 = 33333, remainder 1 -- final period books 33334.
723 amounts_by_journal = {}
724 for journal in journals:
725 journal_lines = [line for line in lines if line["journal_id"] == journal["id"]]
726 debit_line = next(line for line in journal_lines if int(line["debit_cents"]) > 0)
727 amounts_by_journal[journal["date"]] = int(debit_line["debit_cents"])
728
729 ordered = [amounts_by_journal[d] for d in sorted(amounts_by_journal)]
730 assert ordered == [33333, 33333, 33334]
731 assert sum(ordered) == 100000 # exact, no truncation drift
732
733 # Both lines of every journal carry the declared accounts.
734 for journal in journals:
735 journal_lines = [line for line in lines if line["journal_id"] == journal["id"]]
736 accounts = {line["account_id"] for line in journal_lines}
737 assert accounts == {"acct_expense", "acct_accum_depr"}
738
739
740def test_creatework_fills_only_empty_fields_via_mapping(tmp_path):
741 data_dir = tmp_path / "data"
742 _make_tasks(data_dir, [
743 {"id": "task1", "title": "Existing title", "description": "", "template_id": ""},
744 ])
745 definition = _creatework_definition(mapping=json.dumps({
746 "description": {"literal": "seeded description"},
747 "title": {"literal": "should never appear"},
748 }))
749 row = object_records.get_collection_record("tasks", "task1", base_dir=data_dir, roots=[])
750
751 config = object_materialize.parse_definition(definition, base_dir=data_dir, roots=[])
752 result = object_materialize.generate_one(config, row, None, base_dir=data_dir, roots=[])
753 assert result["status"] == "generated"
754
755 updated = object_records.get_collection_record("tasks", "task1", base_dir=data_dir, roots=[])
756 assert updated["title"] == "Existing title" # never clobbered -- already non-empty
757 assert updated["description"] == "seeded description" # filled -- was empty
758
759
760def test_creatework_applies_template_default_values_fill_only_if_empty(tmp_path):
761 data_dir = tmp_path / "data"
762 _make_templates(data_dir, [{
763 "id": "tmpl1", "name": "Onboarding", "default_values": json.dumps({
764 "description": "from template", "title": "should not overwrite",
765 }),
766 }])
767 _make_tasks(data_dir, [
768 {"id": "task1", "title": "My own title", "description": "", "template_id": "tmpl1"},
769 ])
770 definition = _creatework_definition(mapping=json.dumps({}))
771 row = object_records.get_collection_record("tasks", "task1", base_dir=data_dir, roots=[])
772
773 config = object_materialize.parse_definition(definition, base_dir=data_dir, roots=[])
774 result = object_materialize.generate_one(config, row, None, base_dir=data_dir, roots=[])
775 assert result["status"] == "generated"
776
777 updated = object_records.get_collection_record("tasks", "task1", base_dir=data_dir, roots=[])
778 assert updated["title"] == "My own title" # fill-only-if-empty -- never clobbered
779 assert updated["description"] == "from template" # filled from the template
780
781
782def test_creatework_second_run_is_a_noop(tmp_path):
783 data_dir = tmp_path / "data"
784 _make_tasks(data_dir, [{"id": "task1", "title": "T", "description": "", "template_id": ""}])
785 definition = _creatework_definition(mapping=json.dumps({"description": {"literal": "x"}}))
786 config = object_materialize.parse_definition(definition, base_dir=data_dir, roots=[])
787
788 row = object_records.get_collection_record("tasks", "task1", base_dir=data_dir, roots=[])
789 first = object_materialize.generate_one(config, row, None, base_dir=data_dir, roots=[])
790 assert first["status"] == "generated"
791
792 row = object_records.get_collection_record("tasks", "task1", base_dir=data_dir, roots=[])
793 second = object_materialize.generate_one(config, row, None, base_dir=data_dir, roots=[])
794 assert second["status"] == "skipped_already_generated"
795
796
797# --- per-row isolation --------------------------------------------------
798
799def test_generate_config_isolates_one_bad_row_from_others(tmp_path):
800 data_dir = tmp_path / "data"
801 _make_fin_journals(data_dir)
802 _make_fin_journal_lines(data_dir)
803 good_lines = json.dumps([
804 {"account_id": "acct_cash", "debit_cents": 100, "credit_cents": 0},
805 {"account_id": "acct_rev", "debit_cents": 0, "credit_cents": 100},
806 ])
807 _make_fin_recurring(data_dir, [
808 {"id": "bad", "name": "Bad row", "template_lines": "{not valid json",
809 "frequency": "monthly", "next_run": "2020-01-01", "auto_post": "true", "is_active": "true"},
810 {"id": "good", "name": "Good row", "template_lines": good_lines,
811 "frequency": "monthly", "next_run": "2020-01-01", "auto_post": "true", "is_active": "true"},
812 ])
813 definition = _recurring_definition()
814
815 result = object_materialize.generate_definition(definition, base_dir=data_dir, roots=[])
816
817 assert result["generated"] > 0 # the good row still generated
818 assert any(e["source_id"] == "bad" for e in result["errors"]) # the bad row is reported, isolated
819 journals = object_records.read_collection_records("fin_journals", base_dir=data_dir, roots=[])
820 assert all(json.loads(j["generated_from"])["source_id"] == "good" for j in journals)
821
822
823def test_generate_definition_raises_for_a_malformed_definition_itself(tmp_path):
824 """A malformed DEFINITION (not a bad row) raises -- the caller (daemon/
825 materialize_run) is responsible for that level of isolation, per
826 module docstring.
827 """
828 data_dir = tmp_path / "data"
829 with pytest.raises(object_materialize.DefinitionError):
830 object_materialize.generate_definition(
831 _recurring_definition(idempotency_key=""), base_dir=data_dir, roots=[],
832 )
833
834
835# --- flags --------------------------------------------------
836
837def test_materialize_pass_enabled_defaults_true_without_feature_flags_collection(tmp_path):
838 data_dir = tmp_path / "data"
839 assert object_materialize.materialize_pass_enabled(base_dir=data_dir) is True
840
841
842def test_materialize_pass_enabled_honors_off_flag(tmp_path):
843 data_dir = tmp_path / "data"
844 write_schema(data_dir, "feature_flags", [{"name": "id"}, {"name": "flag", "type": "text"}, {"name": "value", "type": "text"}])
845 object_records.create_collection_record(
846 "feature_flags", {"id": "f1", "flag": "materialize_enabled", "value": "off"}, base_dir=data_dir, roots=[],
847 )
848 assert object_materialize.materialize_pass_enabled(base_dir=data_dir) is False
849
850
851def test_is_definition_enabled_and_blocked_defaults():
852 assert object_materialize.is_definition_enabled({}) is True
853 assert object_materialize.is_definition_enabled({"enabled": "false"}) is False
854 assert object_materialize.is_definition_blocked({}) is False
855 assert object_materialize.is_definition_blocked({"block": "true"}) is True
856
857
858def test_is_definition_due_never_run_is_always_due():
859 assert object_materialize.is_definition_due({"id": "d1"}) is True
860
861
862def test_is_definition_due_respects_interval(tmp_path):
863 from datetime import datetime, timedelta, timezone
864 now = datetime.now(timezone.utc)
865 record = {
866 "id": "d1", "last_run_at": now.isoformat().replace("+00:00", "Z"),
867 "trigger": json.dumps({"mode": "scheduled", "interval_seconds": 3600, "period_field": "f", "anchor_field": "a"}),
868 }
869 assert object_materialize.is_definition_due(record, now=now + timedelta(seconds=10)) is False
870 assert object_materialize.is_definition_due(record, now=now + timedelta(hours=2)) is True
871
872
873# --- event-mode helpers --------------------------------------------------
874
875def test_event_definitions_for_collection_filters_by_mode_and_source(tmp_path):
876 data_dir = tmp_path / "data"
877 _make_tasks(data_dir, [])
878 write_schema(data_dir, "materialize_definitions", [
879 {"name": "id"}, {"name": "source_collection", "type": "text"},
880 {"name": "trigger", "type": "textarea"}, {"name": "enabled", "type": "boolean"},
881 {"name": "block", "type": "boolean"},
882 ])
883 object_records.create_collection_record(
884 "materialize_definitions", _creatework_definition(), base_dir=data_dir, roots=[], actor="tester",
885 )
886 object_records.create_collection_record(
887 "materialize_definitions",
888 {"id": "not_event", "source_collection": "tasks",
889 "trigger": json.dumps({"mode": "scheduled", "interval_seconds": 3600, "period_field": "f", "anchor_field": "a"}),
890 "enabled": "true", "block": "false"},
891 base_dir=data_dir, roots=[], actor="tester",
892 )
893
894 matches = object_materialize.event_definitions_for_collection("tasks", base_dir=data_dir, roots=[])
895 assert [m["id"] for m in matches] == ["matgen_task_seed"]
896
897
898def test_compute_event_handles_returns_sorted_distinct_events(tmp_path):
899 data_dir = tmp_path / "data"
900 write_schema(data_dir, "materialize_definitions", [
901 {"name": "id"}, {"name": "source_collection", "type": "text"},
902 {"name": "trigger", "type": "textarea"}, {"name": "enabled", "type": "boolean"},
903 {"name": "block", "type": "boolean"},
904 ])
905 object_records.create_collection_record(
906 "materialize_definitions",
907 _creatework_definition(id="d1", source_collection="tasks"),
908 base_dir=data_dir, roots=[], actor="tester",
909 )
910 object_records.create_collection_record(
911 "materialize_definitions",
912 _creatework_definition(id="d2", source_collection="deals"),
913 base_dir=data_dir, roots=[], actor="tester",
914 )
915 object_records.create_collection_record(
916 "materialize_definitions",
917 _creatework_definition(id="d3", source_collection="tasks", block="true"),
918 base_dir=data_dir, roots=[], actor="tester",
919 )
920
921 events = object_materialize.compute_event_handles(base_dir=data_dir, roots=[])
922 assert events == ["deals.record.created", "tasks.record.created"]
923
924
925def test_generate_one_event_rejects_non_event_definition(tmp_path):
926 data_dir = tmp_path / "data"
927 _make_fin_recurring(data_dir, [{
928 "id": "rec1", "name": "R", "template_lines": "[]", "frequency": "monthly",
929 "next_run": "2020-01-01", "auto_post": "false", "is_active": "true",
930 }])
931 _make_fin_journals(data_dir)
932 _make_fin_journal_lines(data_dir)
933 row = object_records.get_collection_record("fin_recurring", "rec1", base_dir=data_dir, roots=[])
934 with pytest.raises(object_materialize.DefinitionError, match="not an event-mode definition"):
935 object_materialize.generate_one_event(_recurring_definition(), row, base_dir=data_dir, roots=[])