fix(publisher): include update concurrency control in editorial manifest

This commit is contained in:
devops committed 2026-11-12 09:53:26 +00:00
1 parent 4d41a5bbf7
commit a9280459da
6 files changed
+442

No files matched your search

@@ -0,0 +1,272 @@
#!/usr/bin/env python3
"""Offline completeness gate, NOT medical/SEO approval or live verification.
No network, credentials, publisher-state operations or article mutations.
"""
import argparse
import hashlib
import json
from pathlib import Path
import re
from html.parser import HTMLParser
from urllib.parse import urlsplit
SOURCES = {
'admin': 'frontend/admin-panel/src/pages/Blogs.tsx',
'client': 'frontend/admin-panel/src/services/api.ts',
'controller': 'backend/src/admin/blogs.controller.ts',
'service': 'backend/src/admin/blogs.service.ts',
'schema': 'backend/prisma/schema.prisma',
}
SYSTEM = {'id', 'viewCount', 'createdAt', 'updatedAt'}
RELATIONS = {'author', 'category', 'tags', 'comments'}
DISPOSITIONS = {'verified_value', 'system_derived', 'not_applicable', 'evidence_unavailable_empty'}
def sha(path):
return hashlib.sha256(Path(path).read_bytes()).hexdigest()
def manifest(root):
root = Path(root)
sources = {k: {'path': v, 'sha256': sha(root / v)} for k, v in SOURCES.items()}
schema = (root / SOURCES['schema']).read_text()
block = re.search(r'model Blog\s*\{(.*?)\n\}', schema, re.S)
if not block:
raise ValueError('Blog model missing')
fields = {}
for line in block.group(1).splitlines():
m = re.match(r'\s*(\w+)\s+([\w\[\]?]+)', line)
if not m:
continue
name, typ = m.groups()
fields[name] = {'type': typ, 'kind': 'system' if name in SYSTEM else 'relation' if name in RELATIONS else 'scalar'}
# tagNames is a transport alias, not a Prisma field; do not send tags/tagIds.
fields['tagNames'] = {'type': 'String[]', 'kind': 'transport_alias', 'readback': 'tags[].name'}
fields['markContentUpdated'] = {'type': 'Boolean', 'kind': 'transport_control', 'readback': 'contentUpdatedAt'}
# Optional UPDATE concurrency precondition; never a persisted Blog scalar.
fields['expectedUpdatedAt'] = {'type': 'String', 'kind': 'transport_control', 'actions': ['UPDATE'], 'persisted': False}
for role, needles in {
'admin': ["api.post('/admin/blogs', payload)", 'tagNames', 'relatedBlogIds'],
'controller': ['@Controller("admin/blogs")', '@Get("tags")', '@Post()'],
'service': ['tagNames', 'connectOrCreate', 'relatedBlogIds', 'contentUpdatedAt'],
'client': ['axios'],
}.items():
text = (root / SOURCES[role]).read_text()
if any(n not in text for n in needles):
raise ValueError(f'{role} contract changed: review parser and manifest manually')
return {'scope': 'LOCAL_SOURCE_CONTRACT_NOT_DEPLOYMENT_PROOF', 'sources': sources, 'fields': fields}
class Links(HTMLParser):
def __init__(self):
super().__init__()
self.hrefs = set()
def handle_starttag(self, tag, attrs):
if tag == 'a':
href = dict(attrs).get('href', '')
u = urlsplit(href)
if (not u.netloc and href.startswith('/') and not href.startswith('//')) or u.netloc == 'canina.ir':
self.hrefs.add(href)
CITATION = re.compile(r'\[\s*([0-9۰-۹٠-٩]+(?:\s*[,،;؛–-]\s*[0-9۰-۹٠-٩]+)*)\s*\]')
class CitationHTML(HTMLParser):
def __init__(self):
super().__init__(convert_charrefs=True)
self.stack = []
self.anchors = []
self.raw = []
self.targets = {}
def handle_starttag(self, tag, attrs):
attrs = dict(attrs)
self.stack.append((tag, attrs))
if attrs.get('id'):
self.targets.setdefault(attrs['id'], set())
if tag == 'a':
self.anchors.append({'href': attrs.get('href', ''), 'text': ''})
attrs['_anchor'] = self.anchors[-1]
for _, parent in self.stack:
if parent.get('id'):
self.targets.setdefault(parent['id'], set()).add(attrs.get('href', ''))
if tag in {'br', 'img', 'hr', 'input', 'meta', 'link'}:
self.stack.pop()
def handle_endtag(self, tag):
for i in range(len(self.stack)-1, -1, -1):
if self.stack[i][0] == tag:
del self.stack[i:]
break
def handle_data(self, text):
anchors = [attrs['_anchor'] for _, attrs in self.stack if '_anchor' in attrs]
if anchors:
anchors[-1]['text'] += text
else:
self.raw.append(text)
def validate_citations(content, sources):
"""Map numeric inline anchors to retrieved source URLs; no network claims."""
parser = CitationHTML()
parser.feed(content)
errors = []
if CITATION.search(''.join(parser.raw)):
errors.append('citations: raw unlinked numbered bracket citation')
for anchor in parser.anchors:
for match in CITATION.finditer(anchor['text']):
numbers = re.split(r'\s*[,،;؛–-]\s*', match[1])
for number in numbers:
key = str(int(number))
source = sources.get(key, {})
url = source.get('url', '')
href = anchor['href']
if not (urlsplit(url).scheme in {'http', 'https'} and urlsplit(url).netloc and source.get('retrieved') is True):
errors.append('citations: missing retrieved source mapping ' + key)
elif href != url and not (href == '#ref-' + key and url in parser.targets.get('ref-' + key, set())):
errors.append('citations: anchor does not resolve to mapped source ' + key)
return errors
def validate(packet, root, base):
"""Errors are cumulative. Evidence assertions still require independent review."""
errors = []
def require(ok, message):
if not ok:
errors.append(message)
expected = manifest(root)
require(packet.get('manifest') == expected, 'current complete source-derived manifest/hash mismatch')
payload = packet.get('payload', {})
errors.extend(validate_citations(payload.get('content', ''), packet.get('citation_sources', {})))
action = packet.get('action')
require(action in {'NEW', 'UPDATE', 'READ_ONLY_ACCEPTANCE'}, 'explicit action required')
if action in {'UPDATE', 'READ_ONLY_ACCEPTANCE'}:
require(bool(packet.get('record_id')), 'existing-record action requires record_id')
fields = packet.get('field_dispositions', {})
require(set(fields) == set(expected['fields']), 'every manifest field/control needs exactly one disposition')
allowed = set(expected['fields']) - SYSTEM - RELATIONS
require(not (set(payload) - allowed), 'unknown/system/readback-only payload keys: ' + ','.join(sorted(set(payload) - allowed)))
for key, field in fields.items():
require(field.get('disposition') in DISPOSITIONS, f'{key}: invalid disposition')
require(bool(field.get('reason')), f'{key}: reason required')
require(bool(field.get('evidence')), f'{key}: evidence references required')
if field.get('disposition') == 'verified_value':
require('value' in field, f'{key}: verified_value needs explicit value')
if key in allowed:
require(key in payload, f'{key}: verified writable value must be in payload; omission needs explicit disposition')
if key in payload:
require(field.get('value') == payload[key], f'{key}: disposition value differs from payload')
if field.get('disposition') in {'not_applicable', 'evidence_unavailable_empty'} and key in payload:
require(payload[key] in (None, '', []), f'{key}: deliberately empty disposition has nonempty payload')
if expected['fields'].get(key, {}).get('kind') == 'transport_control':
require(field.get('disposition') != 'verified_value', f'{key}: transport control is not a fetched scalar; use an explicit no-mutation/system-derived disposition')
if key in SYSTEM:
require(field.get('disposition') == 'system_derived', f'{key}: must be system-derived, not authored')
evidence = packet.get('evidence', {})
for key, entry in evidence.items():
path = Path(base) / entry.get('path', '')
require(path.is_file(), f'{key}: missing evidence file')
if path.is_file():
require(sha(path) == entry.get('sha256'), f'{key}: evidence hash mismatch')
require(bool(entry.get('readAt')), f'{key}: evidence readAt required')
def refs(refs, context):
require(bool(refs) and all(ref in evidence for ref in refs), context + ': unresolved evidence references')
for key, field in fields.items():
refs(field.get('evidence', []), key)
refs(packet.get('artifact_evidence', []), 'immutable artifact')
# Acceptance must bind dispositions to actual saved authenticated JSON, not
# a reconstructed payload that invents absent relations or transport fields.
if action == 'READ_ONLY_ACCEPTANCE':
binding = packet.get('acceptance_readback', {})
ref = binding.get('evidence')
require(ref in evidence, 'acceptance_readback: authenticated record evidence required')
if ref in evidence:
try:
fetched = json.loads((Path(base) / evidence[ref]['path']).read_text())
require(fetched.get('status') == 200, 'acceptance_readback: authenticated 200 required')
record = fetched['body']['data']
require(record.get('id') == packet.get('record_id'), 'acceptance_readback: record identity mismatch')
for key, field in fields.items():
kind = expected['fields'].get(key, {}).get('kind')
if kind == 'transport_control':
require(key not in record, key + ': unexpected transport readback requires contract review')
continue
if key == 'tagNames':
actual = [tag['name'] for tag in record.get('tags', [])]
require(field.get('value') == actual, key + ': readback alias differs')
elif key not in record:
require(field.get('disposition') in {'not_applicable', 'evidence_unavailable_empty'}, key + ': absent from fetched record; cannot claim fetched/system-derived value')
require(field.get('value') in (None, '', []), key + ': absent fetched field must be explicitly empty')
else:
require(field.get('value') == record[key], key + ': disposition differs from actual authenticated record')
except (ValueError, OSError, KeyError, TypeError):
require(False, 'acceptance_readback: invalid authenticated record evidence')
# Bind reviewed article to exact payload bytes, not merely a nearby draft.
artifact = packet.get('artifact', {})
path = Path(base) / artifact.get('path', '')
require(path.is_file(), 'immutable payload artifact missing')
if path.is_file():
require(sha(path) == artifact.get('sha256'), 'immutable payload artifact hash mismatch')
try:
require(json.loads(path.read_text()) == payload, 'immutable artifact differs from payload')
except (ValueError, OSError):
require(False, 'immutable artifact is not payload JSON')
relations = packet.get('relations', {})
for key, value in [('authorId', payload.get('authorId')), ('categoryId', payload.get('categoryId'))]:
item = relations.get(key, {})
require(item.get('selected') == value, key + ': selection mismatch')
require(bool(item.get('reason')), key + ': attribution/category rationale missing')
refs(item.get('evidence', []), key + ' authenticated read')
require(item.get('authenticated') is True and item.get('status') == 200, key + ': authenticated 200 read required')
for key in ['tagNames', 'relatedBlogIds', 'relatedProductIds']:
item = relations.get(key, {})
selected = payload.get(key, [])
require(item.get('selected') == selected, key + ': selection mismatch')
require(bool(item.get('reason')), key + ': deliberate disposition required even when empty')
refs(item.get('evidence', []), key + ' inventory/destination review')
require(item.get('authenticated') is True and item.get('status') == 200, key + ': authenticated inventory read required')
require(item.get('inventory_complete') is True, key + ': complete inventory required')
require(isinstance(selected, list) and len(selected) == len(set(selected)), key + ': unique array required')
require(set(selected or []) <= set(item.get('available', [])), key + ': selection absent from verified inventory')
if key == 'relatedBlogIds':
require(packet.get('record_id') not in selected, 'self related-article forbidden')
parser = Links()
parser.feed(payload.get('content', ''))
links = packet.get('internal_links', {})
candidates = links.get('reviewed_destinations', [])
require(bool(candidates), 'contextual link destination shortlist not reviewed')
for item in candidates:
refs(item.get('evidence', []), 'destination ' + item.get('href', '?'))
require(bool(item.get('reason')), 'destination suitability/medical-safety rationale required')
require(item.get('identity_verified') is True and item.get('content_reviewed') is True, 'destination content/identity not verified (HTTP 200 insufficient)')
selected_links = links.get('selected', [])
require(set(selected_links) == parser.hrefs, 'contextual body links differ from reviewed selections')
suitable = {item.get('href') for item in candidates if item.get('suitable') is True}
require(set(selected_links) <= suitable, 'selected link has no suitable reviewed destination')
if not selected_links:
require(bool(links.get('zero_link_reason')) and links.get('disclose_in_report') is True, 'zero contextual links need justified exception and report disclosure')
require(not suitable, 'zero-link exception contradicts suitable destinations')
return errors
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('action', choices=['manifest', 'validate'])
parser.add_argument('--source-root', required=True)
parser.add_argument('--packet')
args = parser.parse_args()
if args.action == 'manifest':
print(json.dumps(manifest(args.source_root), ensure_ascii=False, indent=2))
return 0
if not args.packet:
parser.error('validate requires --packet')
path = Path(args.packet)
try:
errors = validate(json.loads(path.read_text()), args.source_root, path.parent)
except (ValueError, OSError, KeyError, TypeError, AttributeError) as exc:
errors = ['invalid/incomplete evidence packet: ' + str(exc)]
print(json.dumps({'result': 'EDITORIAL_EVIDENCE_FAILED' if errors else 'EDITORIAL_EVIDENCE_COMPLETE', 'errors': errors, 'not_approval': 'Independent RD/Vet, SEO/Editorial, final QA, current live identity/relations, backup and public browser verification still mandatory.'}, ensure_ascii=False, indent=2))
return 1 if errors else 0
if __name__ == '__main__':
raise SystemExit(main())
@@ -0,0 +1,145 @@
#!/usr/bin/env python3
"""Offline synthetic unit fixtures only: never publication evidence."""
import copy
import json
from pathlib import Path
import tempfile
import unittest
from editorial_evidence import manifest, sha, validate
# Frozen publisher-owned contract fixture; not deployment/publication evidence.
# Override explicitly when testing a maintained source checkout. Never depend on
# a deleted scratch worktree. All generated evidence remains in self.base.
import os
ROOT = os.environ.get('CANINA_EDITORIAL_TEST_SOURCE', str(
Path(__file__).parent / 'runs/20261104/content/source'))
class EditorialEvidenceTests(unittest.TestCase):
def setUp(self):
self.temp = tempfile.TemporaryDirectory(dir='/opt/data/cache/scratch')
self.addCleanup(self.temp.cleanup)
self.base = Path(self.temp.name)
self.m = manifest(ROOT)
self.payload = {'title': 'SYNTHETIC UNIT TEST ONLY', 'content': '<p>test</p>', 'authorId': 'test-author', 'categoryId': 'test-category', 'tagNames': [], 'relatedBlogIds': [], 'relatedProductIds': []}
(self.base / 'payload.json').write_text(json.dumps(self.payload))
self.packet = {
'action': 'NEW', 'manifest': self.m, 'payload': self.payload,
'artifact': {'path': 'payload.json', 'sha256': sha(self.base / 'payload.json')},
'artifact_evidence': ['test'],
'evidence': {'test': {'path': 'payload.json', 'sha256': sha(self.base / 'payload.json'), 'readAt': 'UNIT_TEST_NOT_A_LIVE_READ'}},
'field_dispositions': {k: {'disposition': 'system_derived' if v['kind'] == 'system' else 'verified_value' if k in self.payload else 'not_applicable', 'reason': 'synthetic unit fixture only', 'evidence': ['test'], 'value': self.payload.get(k)} for k, v in self.m['fields'].items()},
'relations': {k: {'selected': self.payload[k], 'reason': 'synthetic unit fixture only', 'evidence': ['test'], 'status': 200, 'authenticated': True, 'inventory_complete': True, 'available': []} for k in ['authorId', 'categoryId', 'tagNames', 'relatedBlogIds', 'relatedProductIds']},
'internal_links': {'reviewed_destinations': [{'href': '/blog/test', 'identity_verified': True, 'content_reviewed': True, 'suitable': False, 'reason': 'synthetic medically unsuitable destination', 'evidence': ['test']}], 'selected': [], 'zero_link_reason': 'reviewed destination unsuitable', 'disclose_in_report': True},
}
def sync_artifact(self):
(self.base / 'payload.json').write_text(json.dumps(self.payload))
digest = sha(self.base / 'payload.json')
self.packet['artifact']['sha256'] = digest
self.packet['evidence']['test']['sha256'] = digest
def errors(self):
return validate(self.packet, ROOT, self.base)
def test_transport_control_cannot_claim_fetched_value(self):
self.payload['markContentUpdated'] = False
self.packet['field_dispositions']['markContentUpdated'].update(disposition='verified_value', value=False)
self.sync_artifact()
self.assertTrue(any('transport control is not a fetched scalar' in e for e in self.errors()))
def test_acceptance_requires_readback_binding(self):
self.packet.update(action='READ_ONLY_ACCEPTANCE', record_id='test-id')
self.assertTrue(any('acceptance_readback' in e for e in self.errors()))
def test_acceptance_absent_comments_rejects_invented_include(self):
self.packet.update(action='READ_ONLY_ACCEPTANCE', record_id='test-id', acceptance_readback={'evidence':'readback'})
record = {'id':'test-id', 'tags':[]}
(self.base/'readback.json').write_text(json.dumps({'status':200,'body':{'data':record}}))
self.packet['evidence']['readback']={'path':'readback.json','sha256':sha(self.base/'readback.json'),'readAt':'SYNTHETIC_ONLY'}
self.packet['field_dispositions']['comments'].update(disposition='system_derived',value=None)
self.assertTrue(any('comments: absent from fetched record' in e for e in self.errors()))
def test_verified_value_requires_value(self):
del self.packet['field_dispositions']['title']['value']
self.assertTrue(any('explicit value' in e for e in self.errors()))
def test_omitted_verified_writable_value_rejected(self):
self.packet['field_dispositions']['ogImage']['disposition'] = 'verified_value'
self.assertTrue(any('must be in payload' in e for e in self.errors()))
def test_update_identity_required(self):
self.packet['action'] = 'UPDATE'
self.assertTrue(any('requires record_id' in e for e in self.errors()))
def test_related_membership_with_coherent_payload(self):
self.payload['relatedBlogIds'] = ['missing']
self.packet['relations']['relatedBlogIds']['selected'] = ['missing']
self.packet['field_dispositions']['relatedBlogIds']['value'] = ['missing']
self.sync_artifact()
self.assertTrue(any('absent from verified inventory' in e for e in self.errors()))
def test_valid_selected_body_link(self):
self.payload['content'] = '<a href="/blog/test">test</a>'
self.packet['field_dispositions']['content']['value'] = self.payload['content']
self.packet['internal_links']['selected'] = ['/blog/test']
self.packet['internal_links']['reviewed_destinations'][0]['suitable'] = True
self.sync_artifact()
self.assertEqual([], self.errors())
def test_missing_action_rejected(self):
del self.packet['action']
self.assertTrue(any('explicit action' in e for e in self.errors()))
def test_complete_structure_is_not_publication_approval(self):
self.assertEqual([], self.errors())
def test_manifest_includes_all_43_scalars_relations_controls(self):
self.assertIn('homeDisplayMode', self.m['fields'])
self.assertIn('comments', self.m['fields'])
self.assertIn('markContentUpdated', self.m['fields'])
self.assertIn('tagNames', self.m['fields'])
def test_acceptance_missing_manifest_is_rejected(self):
self.packet['manifest'] = {}
self.assertTrue(self.errors())
def test_missing_disposition_rejected(self):
del self.packet['field_dispositions']['ogImage']
self.assertTrue(self.errors())
def test_wrong_transport_tagIds_rejected(self):
self.payload['tagIds'] = []
self.assertTrue(any('payload keys' in e for e in self.errors()))
def test_unjustified_empty_taxonomy_rejected(self):
for key in ['tagNames', 'relatedBlogIds', 'relatedProductIds']:
packet = copy.deepcopy(self.packet)
self.packet['relations'][key]['reason'] = ''
self.assertTrue(self.errors())
self.packet = packet
def test_missing_authenticated_tag_inventory_rejected(self):
self.packet['relations']['tagNames']['authenticated'] = False
self.assertTrue(self.errors())
def test_nonexisting_related_id_rejected(self):
self.packet['relations']['relatedBlogIds']['selected'] = ['missing']
self.assertTrue(self.errors())
def test_automatic_cards_do_not_replace_body_links(self):
self.packet['internal_links'] = {}
self.assertTrue(self.errors())
def test_zero_link_disclosure_required(self):
self.packet['internal_links']['disclose_in_report'] = False
self.assertTrue(self.errors())
def test_reject_zero_when_suitable_destination_exists(self):
self.packet['internal_links']['reviewed_destinations'][0]['suitable'] = True
self.assertTrue(self.errors())
def test_http_success_not_identity(self):
self.packet['internal_links']['reviewed_destinations'][0]['identity_verified'] = False
self.assertTrue(self.errors())
def test_tampered_artifact_rejected(self):
(self.base / 'payload.json').write_text('{}')
self.assertTrue(self.errors())
def test_unreviewed_body_link_rejected(self):
self.payload['content'] = '<a href="/blog/unreviewed">test</a>'
self.assertTrue(any('contextual body links' in e for e in self.errors()))
def test_missing_evidence_rejected(self):
self.packet['evidence'] = {}
self.assertTrue(self.errors())
def test_false_and_null_are_values_not_missing(self):
self.payload['noIndex'] = False
self.payload['scheduledAt'] = None
for k in ['noIndex', 'scheduledAt']:
self.packet['field_dispositions'][k]['value'] = self.payload[k]
self.packet['field_dispositions'][k]['disposition'] = 'verified_value'
(self.base / 'payload.json').write_text(json.dumps(self.payload))
digest = sha(self.base / 'payload.json')
self.packet['artifact']['sha256'] = digest
self.packet['evidence']['test']['sha256'] = digest
self.assertEqual([], self.errors())
if __name__ == '__main__':
unittest.main(verbosity=2)
@@ -0,0 +1,16 @@
"""Offline regression only; never publication evidence."""
import os
import unittest
from editorial_evidence import manifest
class ManifestTransportTests(unittest.TestCase):
def test_update_only_expected_updated_at_is_explicit_request_control(self):
fields = manifest(os.environ['CANINA_EDITORIAL_TEST_SOURCE'])['fields']
self.assertIn('expectedUpdatedAt', fields)
self.assertEqual(fields['expectedUpdatedAt'], {
'type': 'String', 'kind': 'transport_control',
'actions': ['UPDATE'], 'persisted': False,
})
if __name__ == '__main__':
unittest.main()
@@ -0,0 +1 @@
Base: 4d41a5bbf70e9bf9f9ead2412822668998b2c2cf; clean detached isolated worktree. Publisher validator currently untracked in application repository; preserve exact live baseline before minimal fix. Graph hash 6a73473cee9e207543fdeeb668bea544f766200a1b16b8a3a9ce18d4e42e51af; graph is unbound navigation only. Direct source confirms transport control; no backend/frontend edits. Dependencies: manifest -> field dispositions -> validate -> independent QA. Existing push workflow deploys site and restarts bot, forbidden in this scope. Do not push develop through that workflow; report publisher-only release boundary to parent.
@@ -0,0 +1,3 @@
# Production publisher manifest repair
The complete Blog contract must include optional UPDATE-only expectedUpdatedAt. NEW must explicitly disposition it not applicable and omit it from its payload. Preserve request-only semantics and independent approvals. No site deployment, gateway restart, Stage publisher or shared skill modifications.
Acceptance: regression fails before fix and passes after; existing editorial tests pass. Activate only through an authorized publisher-only CI/CD route; current site deploy workflow is not acceptable.
@@ -0,0 +1,5 @@
1. Preserve live validator/test source unchanged in Git.
2. RED: exercise expectedUpdatedAt manifest completeness on exact archived/current source.
3. GREEN: minimal update-only request-control manifest fix; full isolated editorial suite.
4. Record source hash and tests; commit isolated change without triggering prohibited site deploy.
5. Publisher-only CI/CD deployment, source/runtime mapping and exact-hash SEO/final QA remain prerequisites to cron create.