askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
materialize_definitions.json · 8.5 KB · 149 lines
| 1 | { |
| 2 | "name": "materialize_definitions", |
| 3 | "title": "Materialize Definitions", |
| 4 | "version": 1, |
| 5 | "description": "Declared generation jobs (plan/vocabulary/61-materialize-spec.md): one record per definition -- a source collection, an optional flat-equality filter, a trigger (scheduled/scheduled_fixed/event), an output collection (optionally with children), an idempotency_key template, and a mapping. The daemon's materialize pass (object_daemon.process_materializations, object_materialize.generate_config) generates due output; materialize_run (a slot button on this collection's own detail page) and materialize_seed (an event handler for event-mode definitions) call the identical per-source-row generation function. filter/trigger/mapping/balance_check are stored as JSON text -- this schema does not parse or validate their structure; object_materialize.parse_definition does that at generation time, same convention rollup_definitions uses for its own JSON-shaped fields. Admin-owned, full stop (see permissions/rules.json): a definition's mapping/trigger shape can generate financial records. debit_account_id/credit_account_id are this schema's own resolution of 61's Open Question on where depreciation's two posting accounts live -- on the definition record itself (fewest moving parts), only meaningful for the synthesized depreciation-lines shape (a child_collection with no child_source_field).", |
| 6 | "fields": [ |
| 7 | { |
| 8 | "name": "id" |
| 9 | }, |
| 10 | { |
| 11 | "name": "name", |
| 12 | "type": "text", |
| 13 | "required": true, |
| 14 | "label": "Name", |
| 15 | "help": "Human label, e.g. \"Recurring journal generation\".", |
| 16 | "validation": {"min_length": 1, "max_length": 200} |
| 17 | }, |
| 18 | { |
| 19 | "name": "source_collection", |
| 20 | "type": "text", |
| 21 | "required": true, |
| 22 | "label": "Source Collection", |
| 23 | "help": "Exactly one collection -- no joins. The materialize pass reads it outside row-level permissions (daemon posture), so it must already exist." |
| 24 | }, |
| 25 | { |
| 26 | "name": "source_filter", |
| 27 | "type": "textarea", |
| 28 | "label": "Source Filter (JSON)", |
| 29 | "help": "Optional flat {field: value} object, ANDed on equality -- e.g. {\"is_active\": true}. Blank means every row. Same flat-equality-only language as rollup_definitions.filter." |
| 30 | }, |
| 31 | { |
| 32 | "name": "trigger", |
| 33 | "type": "textarea", |
| 34 | "required": true, |
| 35 | "label": "Trigger (JSON)", |
| 36 | "help": "Exactly one of three shapes: {\"mode\": \"scheduled\", \"interval_seconds\": N, \"period_field\": <source row field naming its own frequency, e.g. \"frequency\">, \"anchor_field\": <source row date field>} for a per-row-frequency recurring job; {\"mode\": \"scheduled_fixed\", \"interval_seconds\": N, \"period_field\": <a FIXED granularity, e.g. \"monthly\">, \"start_field\": <source row date field>, \"end_condition\": {\"periods_field\": <source row integer field capping total periods>}} for a depreciation-shaped job; or {\"mode\": \"event\", \"on\": \"record.created\"} for CreateWork (requires DBBASIC_ENABLE_EVENT_HANDLERS; degrades to manual-only when unset). Manual run-now is always available regardless of mode." |
| 37 | }, |
| 38 | { |
| 39 | "name": "output_collection", |
| 40 | "type": "text", |
| 41 | "required": true, |
| 42 | "label": "Output Collection", |
| 43 | "help": "Where the generated top-level record lands -- an EXISTING, already-schema'd collection this package does not own. May equal source_collection (CreateWork: an in-place update, not a create)." |
| 44 | }, |
| 45 | { |
| 46 | "name": "child_collection", |
| 47 | "type": "text", |
| 48 | "label": "Child Collection", |
| 49 | "help": "Optional. Present only when the generated record has child rows (append-only postings, e.g. fin_journal_lines). Absent for a plain single-record generation (e.g. CreateWork)." |
| 50 | }, |
| 51 | { |
| 52 | "name": "child_source_field", |
| 53 | "type": "text", |
| 54 | "label": "Child Source Field", |
| 55 | "help": "Names the field on the SOURCE row holding the child line template data as a JSON list (e.g. fin_recurring.template_lines), parsed verbatim into child rows. Leave blank alongside a set child_collection for the synthesized depreciation-lines shape instead (see debit_account_id/credit_account_id below)." |
| 56 | }, |
| 57 | { |
| 58 | "name": "child_link_field", |
| 59 | "type": "text", |
| 60 | "label": "Child Link Field", |
| 61 | "help": "Names the FK field on each generated child row back to the generated parent (e.g. fin_journal_lines.journal_id). Required whenever child_collection is set." |
| 62 | }, |
| 63 | { |
| 64 | "name": "idempotency_key", |
| 65 | "type": "text", |
| 66 | "required": true, |
| 67 | "label": "Idempotency Key Template", |
| 68 | "help": "A template producing the DETERMINISTIC id of the generated top-level record: {definition_id}, {source_id}, and (scheduled/scheduled_fixed only) {period_start}, e.g. \"matgen_{definition_id}_{source_id}_{period_start}\". This key is the entire idempotency mechanism -- treat as effectively immutable once a definition has generated at least one record (operational guidance, not enforced, same posture as rollup_definitions' target_collection)." |
| 69 | }, |
| 70 | { |
| 71 | "name": "mapping", |
| 72 | "type": "textarea", |
| 73 | "required": true, |
| 74 | "label": "Mapping (JSON)", |
| 75 | "help": "One entry per output field, each a small closed vocabulary: {\"from\": <source field>}, {\"from_period\": \"period_start\"|\"period_end\"|\"period_label\"}, {\"literal\": <value>}, {\"template\": \"...{source.field}...{period_label}...\"}, {\"if\": {\"source_field\":..., \"equals\":...}, \"then\":..., \"else\":...}, or the depreciation-specific {\"depreciation_amount\": {\"method\": \"straight_line\", \"cost_field\":..., \"salvage_field\":..., \"life_field\":...}} (declining is rejected, not silently mis-computed). The synthesized depreciation-lines shape reserves the key \"amount\" for this last op." |
| 76 | }, |
| 77 | { |
| 78 | "name": "balance_check", |
| 79 | "type": "textarea", |
| 80 | "label": "Balance Check (JSON)", |
| 81 | "help": "Optional {\"debit_field\", \"credit_field\"} naming the child rows' amount fields. When present, generated children's debit/credit sums (exact integer cents) MUST be equal before ANY write happens -- zero rows land otherwise. Required for the synthesized depreciation-lines shape." |
| 82 | }, |
| 83 | { |
| 84 | "name": "debit_account_id", |
| 85 | "type": "text", |
| 86 | "label": "Debit Account (depreciation)", |
| 87 | "help": "Only meaningful for the synthesized depreciation-lines shape (child_collection set, child_source_field blank): the account debited each period (typically Depreciation Expense)." |
| 88 | }, |
| 89 | { |
| 90 | "name": "credit_account_id", |
| 91 | "type": "text", |
| 92 | "label": "Credit Account (depreciation)", |
| 93 | "help": "Only meaningful for the synthesized depreciation-lines shape: the account credited each period (typically Accumulated Depreciation)." |
| 94 | }, |
| 95 | { |
| 96 | "name": "actor", |
| 97 | "type": "text", |
| 98 | "label": "Actor", |
| 99 | "help": "Attribution string stamped on every write this definition's generations make. Defaults to \"daemon:materialize\" when blank; override for finer-grained audit filtering, e.g. \"daemon:materialize:depreciation\"." |
| 100 | }, |
| 101 | { |
| 102 | "name": "last_run_at", |
| 103 | "type": "datetime", |
| 104 | "read_only": true, |
| 105 | "label": "Last Run", |
| 106 | "help": "Server-set after a pass over this definition (whether or not it generated anything that pass). Freshness DISPLAY only -- the actual due-set is recomputed from first principles every pass, never trusted from this field." |
| 107 | }, |
| 108 | { |
| 109 | "name": "enabled", |
| 110 | "type": "boolean", |
| 111 | "default": "true", |
| 112 | "label": "Enabled", |
| 113 | "help": "Per-definition pause, independent of the instance-wide materialize_enabled flag. Resume any time without further thought." |
| 114 | }, |
| 115 | { |
| 116 | "name": "block", |
| 117 | "type": "boolean", |
| 118 | "default": "false", |
| 119 | "label": "Blocked", |
| 120 | "help": "The harder stop: refuses even materialize_run's manual path with a distinct error. For a definition an operator has identified as producing genuinely wrong output -- \"something is wrong here, don't run this even on purpose,\" unlike enabled: false's \"pause, resume later.\"" |
| 121 | } |
| 122 | ], |
| 123 | "forms": { |
| 124 | "default": { |
| 125 | "fields": [ |
| 126 | "name", |
| 127 | "source_collection", |
| 128 | "source_filter", |
| 129 | "trigger", |
| 130 | "output_collection", |
| 131 | "child_collection", |
| 132 | "child_source_field", |
| 133 | "child_link_field", |
| 134 | "idempotency_key", |
| 135 | "mapping", |
| 136 | "balance_check", |
| 137 | "debit_account_id", |
| 138 | "credit_account_id", |
| 139 | "actor", |
| 140 | "enabled", |
| 141 | "block" |
| 142 | ] |
| 143 | } |
| 144 | }, |
| 145 | "views": { |
| 146 | "list_mode": "table", |
| 147 | "list_fields": ["name", "source_collection", "output_collection", "enabled", "block", "last_run_at"] |
| 148 | } |
| 149 | } |